node-red-contrib-knx-ultimate 6.1.1 → 6.2.1

package/nodes/locales/es/knxUltimateAI.json

@@ -2,12 +2,19 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
-      "capture": "Capture",
-      "storage": "Historial y Resumen",
-      "detection": "Deteccion y Alertas",
+      "groupAssistant": "Asistente IA",
+      "groupChatHome": "Conversaciones y hogar",
+      "groupKnxAnalysis": "Análisis del tráfico KNX",
+      "quickSetup": "Configurar el asistente",
+      "capture": "Telegramas del bus",
+      "storage": "Historial y resúmenes KNX",
+      "detection": "Anomalías y patrones",
       "llmConnection": "Conexion del Asistente IA",
-      "llmContext": "Contexto del Asistente IA",
-      "advanced": "Ajustes Avanzados"
+      "llmContext": "Conocimiento y contexto IA",
+      "chatAdapter": "Canales de chat",
+      "homeIntelligence": "Hogar proactivo y memoria",
+      "homeIntelligenceAdvanced": "Ajustes proactivos avanzados",
+      "advanced": "Proveedor y límites"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +46,36 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "Incluir inventario del proyecto Node-RED",
+      "llmAllowKnxCommands": "Permitir que la IA lea estados KNX y controle actuadores",
+      "llmRequireCommandConfirmation": "Pedir confirmación antes de enviar comandos KNX",
+      "chatAdapterPreset": "Preajuste del adaptador",
+      "chatInputCode": "Mapeo de entrada (chat → KNX AI)",
+      "chatOutputCode": "Mapeo de salida (KNX AI → chat)",
+      "proactiveEnabled": "Activar notificaciones domésticas proactivas",
+      "proactiveRecipient": "Destinatario principal / ID de chat",
+      "proactiveOpenMinutes": "Avisar tras permanecer abierto (minutos)",
+      "proactiveCooldownMinutes": "Espera antes de repetir (minutos)",
+      "proactiveQuietStart": "Inicio de horas silenciosas",
+      "proactiveQuietEnd": "Fin de horas silenciosas",
+      "homeMemoryMaxKb": "Tamaño máximo de memoria del hogar (KB)",
+      "aiEducation": "Educación IA (gestionada por el usuario)",
       "llmIncludeDocsSnippets": "Include documentation snippets (help/README/examples)",
       "llmDocsLanguage": "Docs language"
     },
     "outputs": {
       "summary": "Resumen/Estadísticas",
       "anomalies": "Anomalías",
-      "assistant": "Asistente IA"
+      "assistant": "Asistente IA",
+      "knxCommands": "Operaciones KNX"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "OpenAI-compatible (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (local, beta)"
+      },
+      "chatAdapter": {
+        "none": "Sin adaptador"
       }
     },
     "messages": {
@@ -61,13 +85,20 @@
       "installedOllamaModel": "Ollama model installed",
       "installOllamaModelFailed": "Failed to install Ollama model",
       "ollamaInstallSteps": "1) Open the model library and copy the model name (for example llama3.1). 2) Put the name in the Model field and click Install it.",
-      "ollamaStartedAuto": "Ollama server started automatically."
+      "ollamaStartedAuto": "Ollama server started automatically.",
+      "chatAdapterIntro": "Elige un preajuste para insertar su código de mapeo de entrada y salida. La lista se carga desde el archivo de adaptadores de chat incluido; el código generado sigue siendo editable.",
+      "chatAdapterCodeHelp": "Los mapeos se ejecutan de forma síncrona. Devuelve msg para continuar o ningún valor para descartarlo. Los errores se capturan y notifican sin detener Node-RED.",
+      "homeIntelligenceIntro": "El nodo crea un modelo ETS semántico multilingüe y puede avisar al chat cuando una persiana, ventana o puerta reconocida con suficiente fiabilidad permanece abierta. Nunca envía por sí solo un comando KNX.",
+      "aiEducationHelp": "Solo el usuario puede editar esta sección. La IA la lee como una instrucción autoritativa, pero la memoria aprendida nunca puede sobrescribirla. Máximo 16.000 caracteres.",
+      "homeMemoryLimitHelp": "La memoria Markdown se reescribe atómicamente cada 15 minutos y siempre queda limitada entre 64 y 1.024 KB. Las observaciones antiguas se eliminan antes que los hábitos y los objetos semánticos."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",
       "llmApiKey": "Paste API key (starts with sk-)",
       "llmModel": "e.g. gpt-4o-mini",
-      "llmSystemPrompt": "Optional. Leave empty for default."
+      "llmSystemPrompt": "Optional. Leave empty for default.",
+      "proactiveRecipient": "Opcional: ID de chat de Telegram; si no, se recuerda la última sesión de chat",
+      "aiEducation": "Ejemplo: no avisarme entre las 23:00 y las 07:00. La persiana del despacho puede quedar abierta de noche."
     },
     "sidebar": {
       "ui": {

package/nodes/locales/fr/knxUltimateAI.html

@@ -1,18 +1,82 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 Ce nœud écoute **tous les télégrammes KNX** du gateway KNX Ultimate sélectionné, produit des statistiques de trafic, détecte des anomalies et peut interroger un LLM de façon optionnelle.
 
+L'éditeur utilise trois sections principales en accordéon : **Assistant IA** contient la configuration, les connaissances/le contexte et les limites du fournisseur ; **Conversations et maison** contient les canaux de chat, la maison proactive et la mémoire limitée ; **Analyse du trafic KNX** contient les télégrammes du bus, l'historique/les résumés et les anomalies/motifs. L'ouverture d'une section principale affiche ensemble toutes ses options. Les identifiants et valeurs enregistrés restent inchangés.
+
 ## Sorties
 1. **Résumé/Stats** (`msg.payload` JSON)
 2. **Anomalies** (`msg.payload` JSON)
 3. **Assistant IA** (`msg.payload` texte, avec `msg.summary`)
+4. **Opérations KNX** (un message Universal Mode par lecture ou écriture validée)
+
+Chaque message émis par les sorties 3 et 4 contient également une copie du message d'entrée original dans `msg.inputMessage`. Le payload, le topic, les métadonnées du chat et toutes les autres propriétés d'entrée restent ainsi disponibles pour les nœuds suivants. Les erreurs de clonage ou d'envoi sont interceptées et signalées sans se propager au runtime Node-RED.
 
 ## Commandes (entrée)
 Envoyez `msg.topic` :
 - `summary` (ou vide) : envoie le résumé immédiatement
-- `reset` : vide l'historique/compteurs internes
+- `reset` : efface l'historique, les compteurs et la mémoire domestique apprise ; l'Éducation de l'IA reste inchangée
 - `ask` : envoie une question au LLM configuré
+- `confirm` / `cancel` : confirme ou annule les commandes KNX en attente sans rappeler le LLM
+- `clear_chat` : efface la mémoire de conversation de la session courante
+
+Pour `ask`, mettez la question dans `msg.prompt` (recommandé), `msg.payload` (chaîne), ou les champs Telegram courants `msg.payload.content` / `msg.payload.text`.
+
+Lorsque le contrôle KNX est activé, les échanges récents sont conservés en RAM par `msg.knxAi.sessionId`, `msg.sessionId` ou ID de chat Telegram détecté. Reliez la sortie 3 au nœud d'envoi du chat et la sortie 4 à un nœud KNX Ultimate en **mode universel**. Avec la confirmation active, la première réponse affiche GA, DPT et payload sans émettre d’écriture ; la même session doit répondre `CONFIRMER` ou `ANNULER` dans les 5 minutes. Une nouvelle demande remplace tout plan précédent. Chaque commande confirmée contient `msg.destination`, `msg.dpt`, `msg.payload` et `msg.event = "GroupValue_Write"`.
+Pour les écritures DPT 1.xxx, les équivalents sûrs produits par l’IA `true`/`false`, `1`/`0` et `on`/`off` sont normalisés en véritables booléens avant la validation locale et la sortie.
+
+### Lectures KNX actualisées
+Lorsque l’utilisateur demande explicitement un état actuel ou actualisé, l’IA peut interroger les objets exacts du catalogue ETS importé, y compris les objets d’état et autres objets en lecture seule. La sortie 4 émet `msg.destination`, `msg.dpt`, `msg.event = "GroupValue_Read"` et `msg.readstatus = true`. Le nœud attend jusqu’à 6 secondes chaque `GroupValue_Response` ou écriture récente, puis renvoie les valeurs décodées sur la sortie 3 et les détails dans `msg.knxAi.readResults`. Les lectures ne nécessitent jamais de confirmation et ne sont jamais transformées en écritures.
+
+### Demande de confirmation pour les boutons du chat
+Lorsqu'un plan est en attente, la sortie 3 contient `msg.knxAi.confirmationRequest`. L'objet comprend `required`, `status`, `sessionId`, `expiresAt`, `commandCount` et deux éléments dans `actions`. Utilisez `action.label` comme texte du bouton Telegram, `action.callbackData` comme callback et renvoyez `action.message` à KNX AI pour confirmer ou annuler sans saisir de texte.
+
+### Préréglages d’adaptateur de chat
+L’onglet **Adaptateurs de chat** charge ses mappages sélectionnables depuis `resources/KNXAIChatAdapterMappings.js`. Le choix d’un préréglage insère deux mappages JavaScript synchrones et modifiables dans des zones de texte pleine largeur : un avant le traitement de l’entrée par KNX AI et un avant l’émission sur la sortie 3. Renvoyez `msg` pour continuer ou aucune valeur pour écarter le message. Les erreurs de syntaxe et d’exécution sont interceptées et signalées sans arrêter Node-RED.
+
+Le préréglage inclus **windkh/node-red-contrib-telegrambot** suit le contrat receiver/sender du paquet. Connectez directement un `telegram receiver` à KNX AI et la sortie 3 à un `telegram sender`. Pour les boutons de confirmation inline, connectez aussi un `telegram event` configuré pour `callback_query` à la même entrée KNX AI. Le mappage d’entrée extrait `msg.payload.content`, `msg.payload.chatId` et la langue Telegram. Le mappage de sortie crée `msg.payload.chatId`, `type` et `content`, puis ajoute `options.reply_markup` depuis `msg.knxAi.confirmationRequest` lorsqu’une écriture attend confirmation. Le paquet Telegram reste une dépendance optionnelle distincte.
+
+## Intelligence domestique proactive et mémoire limitée
+La sous-section **Maison proactive et mémoire** de **Conversations et maison** active les notifications proactives sur choix de l’utilisateur. À partir de la hiérarchie ETS, des noms, rôles et DPT, le nœud crée un modèle sémantique déterministe pour les volets, fenêtres, portes, éclairages, températures, climat, présence et alarmes avec des termes italiens, anglais, allemands, français, espagnols et chinois. Le premier détecteur proactif surveille uniquement les états hors commande de volets/fenêtres/portes reconnus avec une fiabilité suffisante. Après la durée d’ouverture configurée et hors heures silencieuses, la sortie 3 émet un message localisé avec `msg.knxAi.type = "proactive_notification"`. Il n’émet jamais sur la sortie 4 et ne modifie jamais KNX de façon autonome ; une demande ultérieure de l’utilisateur passe toujours par la validation et la confirmation normales.
+
+La dernière session de chat est mémorisée comme propriétaire, ou **Destinataire principal / ID de chat** permet de la définir explicitement. Un `msg.inputMessage` synthétique conserve le destinataire afin que l’adaptateur Telegram puisse envoyer une notification spontanée. Le délai de répétition et la limite de trois notifications proactives par heure évitent les rafales.
+
+La référence apprise est chargée au démarrage depuis `<userDir>/knxai/memory/knxai-home-memory-<node-id>.md`, réécrite atomiquement toutes les 15 minutes et strictement limitée entre 64 et 1 024 Ko configurables (256 Ko par défaut). Elle conserve au maximum 120 observations importantes, 80 habitudes agrégées, 80 notifications et 300 objets ETS sémantiques, jamais un flux illimité de télégrammes bruts. Les éléments anciens et moins prioritaires sont supprimés en premier. **Éducation IA** est limitée à 16 000 caractères et provient toujours de la configuration du nœud : l’IA peut la lire comme une consigne faisant autorité, mais ne peut ni la modifier ni l’écraser. Si cette Éducation est présente mais que le LLM ne peut pas l’évaluer, la notification candidate est supprimée plutôt que de risquer de la contredire.
+
+## Exemple pratique de configuration
+Cet exemple crée un assistant concis qui signale les ouvertures importantes, tout en acceptant que le volet du bureau reste ouvert :
+
+| Champ de l’éditeur | Valeur d’exemple | Résultat |
+|---|---|---|
+| **Activer les notifications domestiques proactives** (`proactiveEnabled`) | activé | Le nœud évalue les états ouverts de volet/fenêtre/porte reconnus avec fiabilité. |
+| **Destinataire principal / ID de chat** (`proactiveRecipient`) | `123456789` | Les messages spontanés vont vers ce chat ; laissez vide pour mémoriser la dernière session Ask. |
+| **Notifier après ouverture** (`proactiveOpenMinutes`) | `120` | Une notification potentielle est évaluée après deux heures. |
+| **Début / fin des heures silencieuses** | `23:00` / `07:00` | Aucun message proactif n’est émis pendant la nuit. |
+| **Délai de répétition** (`proactiveCooldownMinutes`) | `360` | Le même objet ne peut pas notifier à nouveau pendant six heures. |
+| **Taille maximale du fichier mémoire** (`homeMemoryMaxKb`) | `256` | La référence Markdown de ce nœud reste sous 256 Ko. |
+
+Exemple pour **Éducation IA** (`aiEducation`) :
+
+```text
+Appelle-moi Alex et réponds dans la même langue que moi.
+Réponds brièvement, sauf si je demande des détails techniques.
+Le volet du bureau peut rester ouvert le jour : ne m’envoie pas de notification.
+Préviens-moi lorsqu’un autre volet, une fenêtre ou une porte reste ouvert anormalement longtemps.
+Si « lumière du salon » est ambigu, demande-moi quel éclairage je veux dire.
+N’affirme jamais qu’un actionneur a changé avant confirmation par un objet d’état KNX.
+```
+
+Avec ces réglages, la sortie 3 peut émettre une `proactive_notification` localisée après 120 minutes pour le volet du salon, tandis que l’Éducation supprime la notification du volet du bureau. Si Alex demande ensuite de fermer le volet du salon, KNX AI prépare la commande ETS exacte, mais conserve la validation et la confirmation normales avant la sortie 4.
+
+Utilisez des hiérarchies et noms d’objet ETS explicites, avec des rôles état/commande corrects. L’Éducation personnalise les décisions et la formulation, mais ne peut ni inventer une adresse de groupe, ni changer un DPT, ni contourner la validation KNX.
 
-Pour `ask`, mettez la question dans `msg.prompt` (recommandé) ou `msg.payload` (chaîne).
+## Workflow rapide : contrôle KNX
+1. Importez le CSV ETS dans la passerelle et configurez le fournisseur, le modèle et les identifiants LLM.
+2. Activez **Assistant LLM** et **lecture des états KNX et commande des actionneurs** ; laissez la confirmation activée.
+3. Connectez l'entrée du chat à KNX AI en conservant un identifiant de session/chat stable.
+4. Connectez la sortie 3 à la réponse du chat et la sortie 4 à KNX Ultimate en **mode universel**.
+5. L'utilisateur envoie une demande ; les états actuels sont lus immédiatement, tandis que les écritures affichent d'abord GA, DPT et valeur sans écrire sur le bus.
+6. Dans les 5 minutes, le même chat répond exactement `CONFIRMER` ou `ANNULER`.
+7. Seul `CONFIRMER` revalide et émet les commandes sur la sortie 4 ; vérifiez l'exécution avec une GA d'état KNX.
 
 ## Champs de configuration
 Voici tous les champs tels qu'affichés dans l'éditeur KNX AI.
@@ -53,7 +117,20 @@ Voici tous les champs tels qu'affichés dans l'éditeur KNX AI.
 - **Endpoint URL** : URL endpoint chat/completions.
 - **API key** : clé API (non requise avec Ollama local).
 - **Model** : ID/nom du modèle.
+- **Compatibilité du modèle de chat** : le modèle sélectionné doit prendre en charge l'endpoint Chat Completions configuré. Les anciens modèles réservés aux completions, comme `gpt-3.5-turbo-instruct`, sont exclus lors de l'actualisation de la liste. Si le fournisseur refuse une valeur de température personnalisée ou le paramètre de limite de tokens, KNX AI réessaie en supprimant ou remplaçant uniquement le champ incompatible.
 - **System prompt** : instruction système globale pour l'analyse KNX (Advanced).
+- **Autoriser l’IA à lire les états KNX et commander les actionneurs** : active la sortie 4 et reste désactivé par défaut. Les objets exacts du catalogue ETS peuvent être lus ; seules les écritures vers des objets classés `command` sont acceptées. Les opérations inconnues, avec DPT discordant, invalides ou trop nombreuses, ainsi que les écritures vers des objets d'état ou neutres, sont rejetées localement.
+- **Demander confirmation avant d’envoyer les commandes KNX** : activé par défaut. Affiche d'abord les modifications validées et n'émet aucune commande tant que la même session de chat ne les confirme pas. Lorsque des commandes attendent une confirmation, la réponse ajoute toujours les instructions exactes de confirmation ou d'annulation dans la langue de la demande courante. Les commandes sont à nouveau validées juste avant la sortie.
+- **Préréglage d’adaptateur** : charge une paire de mappages entrée/sortie depuis le fichier d’adaptateurs de chat fourni. La sélection remplace volontairement les deux zones de texte ; le code reste ensuite modifiable.
+- **Mappage d’entrée (chat → KNX AI)** : JavaScript synchrone exécuté avant le traitement de la commande d’entrée.
+- **Mappage de sortie (KNX AI → chat)** : JavaScript synchrone appliqué uniquement aux messages de la sortie 3.
+- **Activer les notifications domestiques proactives** : détecteur optionnel des états ouverts de volet/fenêtre/porte reconnus de façon fiable ; il n'écrit jamais de manière autonome sur KNX.
+- **Destinataire principal / ID de chat** : destination facultative des messages spontanés ; sinon la dernière session Ask est mémorisée.
+- **Notifier après ouverture (minutes)** : seuil de durée avant d'envisager une notification proactive.
+- **Début / fin des heures silencieuses** : intervalle quotidien pendant lequel les messages proactifs sont supprimés.
+- **Éducation de l’IA** : consignes autoritaires gérées uniquement par l'utilisateur, lues par l'IA et jamais modifiées.
+- **Délai de répétition (minutes)** : intervalle minimal avant qu'un même objet puisse notifier à nouveau.
+- **Taille maximale du fichier mémoire domestique (KB)** : limite stricte de 64 à 1 024 KB ; 256 KB par défaut.
 - Si l'archive disque est active, **Ask** l'utilise par défaut : les dates/plages explicites sont respectées, sinon l'assistant cherche sur les dernières 24 heures plus les événements RAM courants.
 - **Include raw payload hex** : inclut le payload hex brut dans le prompt.
 - **Inclure l'inventaire du projet Node-RED** : inclut dans le prompt l'inventaire de tout le projet Node-RED, avec les nœuds KNX et d'autres nœuds utiles comme function/change/inject/template lorsqu'ils contiennent de la logique KNX ou des adresses de groupe.
@@ -84,5 +161,5 @@ Voici tous les champs tels qu'affichés dans l'éditeur KNX AI.
 - Si Node-RED tourne dans Docker, utiliser `host.docker.internal` au lieu de `localhost` dans l'endpoint.
 
 ## Note sécurité
-Si le LLM est activé, le contexte trafic KNX peut être envoyé à l'endpoint configuré. Pour un usage strictement on-premise, utilisez un provider local.
+Si le LLM est activé, le contexte trafic KNX peut être envoyé à l'endpoint configuré. Pour un usage strictement on-premise, utilisez un provider local. Une commande émise en sortie 4 a passé la validation locale et a été transmise au flow, sans prouver son exécution par l'actionneur. Utilisez une GA d'état KNX pour la confirmation.
 </script>

package/nodes/locales/fr/knxUltimateAI.json

@@ -2,12 +2,19 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
-      "capture": "Capture",
-      "storage": "Historique et Resume",
-      "detection": "Detection et Alertes",
+      "groupAssistant": "Assistant IA",
+      "groupChatHome": "Conversations et maison",
+      "groupKnxAnalysis": "Analyse du trafic KNX",
+      "quickSetup": "Configurer l'assistant",
+      "capture": "Télégrammes du bus",
+      "storage": "Historique et résumés KNX",
+      "detection": "Anomalies et motifs",
       "llmConnection": "Connexion Assistant IA",
-      "llmContext": "Contexte Assistant IA",
-      "advanced": "Reglages Avances"
+      "llmContext": "Connaissances et contexte IA",
+      "chatAdapter": "Canaux de chat",
+      "homeIntelligence": "Maison proactive et mémoire",
+      "homeIntelligenceAdvanced": "Paramètres proactifs avancés",
+      "advanced": "Fournisseur et limites"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +46,36 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "Inclure l'inventaire du projet Node-RED",
+      "llmAllowKnxCommands": "Autoriser l’IA à lire les états KNX et commander les actionneurs",
+      "llmRequireCommandConfirmation": "Demander confirmation avant d’envoyer les commandes KNX",
+      "chatAdapterPreset": "Préréglage d’adaptateur",
+      "chatInputCode": "Mappage d’entrée (chat → KNX AI)",
+      "chatOutputCode": "Mappage de sortie (KNX AI → chat)",
+      "proactiveEnabled": "Activer les notifications domestiques proactives",
+      "proactiveRecipient": "Destinataire principal / ID de chat",
+      "proactiveOpenMinutes": "Notifier après ouverture (minutes)",
+      "proactiveCooldownMinutes": "Délai avant répétition (minutes)",
+      "proactiveQuietStart": "Début des heures silencieuses",
+      "proactiveQuietEnd": "Fin des heures silencieuses",
+      "homeMemoryMaxKb": "Taille maximale de la mémoire maison (Ko)",
+      "aiEducation": "Éducation IA (gérée par l'utilisateur)",
       "llmIncludeDocsSnippets": "Include documentation snippets (help/README/examples)",
       "llmDocsLanguage": "Docs language"
     },
     "outputs": {
       "summary": "Résumé/Stats",
       "anomalies": "Anomalies",
-      "assistant": "Assistant IA"
+      "assistant": "Assistant IA",
+      "knxCommands": "Opérations KNX"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "OpenAI-compatible (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (local, beta)"
+      },
+      "chatAdapter": {
+        "none": "Aucun adaptateur"
       }
     },
     "messages": {
@@ -61,13 +85,20 @@
       "installedOllamaModel": "Ollama model installed",
       "installOllamaModelFailed": "Failed to install Ollama model",
       "ollamaInstallSteps": "1) Open the model library and copy the model name (for example llama3.1). 2) Put the name in the Model field and click Install it.",
-      "ollamaStartedAuto": "Ollama server started automatically."
+      "ollamaStartedAuto": "Ollama server started automatically.",
+      "chatAdapterIntro": "Choisissez un préréglage pour insérer son code de mappage d’entrée et de sortie. La liste est chargée depuis le fichier d’adaptateurs de chat fourni ; le code généré reste modifiable.",
+      "chatAdapterCodeHelp": "Les mappages s’exécutent de façon synchrone. Renvoyez msg pour continuer ou aucune valeur pour l’écarter. Les erreurs sont interceptées et signalées sans arrêter Node-RED.",
+      "homeIntelligenceIntro": "Le nœud crée un modèle ETS sémantique multilingue et peut avertir le chat lorsqu'un volet, une fenêtre ou une porte reconnu avec suffisamment de fiabilité reste ouvert. Il n'envoie jamais de commande KNX de manière autonome.",
+      "aiEducationHelp": "Seul l'utilisateur peut modifier cette section. L'IA la lit comme une consigne faisant autorité, mais la mémoire apprise ne peut jamais l'écraser. Maximum 16 000 caractères.",
+      "homeMemoryLimitHelp": "La mémoire Markdown est réécrite atomiquement toutes les 15 minutes et reste toujours limitée entre 64 et 1 024 Ko. Les anciennes observations sont supprimées avant les habitudes et les objets sémantiques."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",
       "llmApiKey": "Paste API key (starts with sk-)",
       "llmModel": "e.g. gpt-4o-mini",
-      "llmSystemPrompt": "Optional. Leave empty for default."
+      "llmSystemPrompt": "Optional. Leave empty for default.",
+      "proactiveRecipient": "Facultatif : ID de chat Telegram ; sinon la dernière session de chat est mémorisée",
+      "aiEducation": "Exemple : ne pas me notifier entre 23:00 et 07:00. Le volet du bureau peut rester ouvert la nuit."
     },
     "sidebar": {
       "ui": {

package/nodes/locales/it/knxUltimateAI.html

@@ -1,18 +1,86 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 Questo nodo ascolta **tutti i telegrammi KNX** dal gateway KNX Ultimate selezionato, costruisce statistiche di traffico, rileva anomalie e può interrogare opzionalmente un LLM.
 
+L'editor usa tre sezioni principali ad accordion: **Assistente AI** contiene configurazione, conoscenza/contesto, provider e limiti; **Conversazioni e casa** contiene canali chat, casa proattiva e memoria limitata; **Analisi traffico KNX** contiene telegrammi dal bus, storico/riepiloghi e anomalie/pattern. Aprendo una sezione principale vengono mostrate insieme tutte le opzioni relative. ID e valori salvati dei campi restano invariati.
+
 ## Output
 1. **Summary/Statistiche** (`msg.payload` JSON)
 2. **Anomalie** (`msg.payload` JSON)
 3. **Assistente AI** (`msg.payload` testo, con `msg.summary`)
+4. **Operazioni KNX** (un messaggio Universal Mode per ogni lettura o scrittura validata)
+
+Ogni messaggio emesso dalle uscite 3 e 4 contiene anche una copia del messaggio originale in ingresso in `msg.inputMessage`. In questo modo payload, topic, metadati della chat e qualsiasi altra proprietà di ingresso restano disponibili per i nodi successivi. Gli errori di clonazione o di invio vengono intercettati e segnalati senza propagarsi al runtime di Node-RED.
 
 ## Comandi (input)
 Invia `msg.topic`:
 - `summary` (o vuoto): emette subito la summary
-- `reset`: azzera storico e contatori interni
+- `reset`: azzera storico, contatori e memoria domestica appresa; Educazione AI resta invariata
 - `ask`: invia una domanda all'LLM configurato
+- `confirm` / `cancel`: conferma o annulla i comandi KNX in attesa senza richiamare l'LLM
+- `clear_chat`: azzera la memoria della conversazione per la sessione corrente
+
+Per `ask`, passa la domanda in `msg.prompt` (consigliato), in `msg.payload` (stringa), oppure nei comuni campi Telegram `msg.payload.content` / `msg.payload.text`.
+
+Quando il controllo KNX è abilitato, i turni recenti sono conservati in RAM per `msg.knxAi.sessionId`, `msg.sessionId` o per il chat ID Telegram rilevato. Collega l'uscita 3 al nodo di risposta della chat e l'uscita 4 a un nodo KNX Ultimate configurato in **Modalità Universale**. Con la conferma attiva, la prima risposta mostra GA, DPT e payload delle scritture senza emetterle; la stessa sessione deve poi rispondere `CONFERMA`/`ANNULLA` entro 5 minuti. Una nuova richiesta sostituisce l'eventuale piano precedente. Ogni comando confermato contiene `msg.destination`, `msg.dpt`, `msg.payload` e `msg.event = "GroupValue_Write"`.
+Per le scritture DPT 1.xxx, gli equivalenti sicuri prodotti dall'AI `true`/`false`, `1`/`0` e `on`/`off` vengono normalizzati in un vero booleano prima della validazione locale e dell'uscita.
+
+### Letture KNX aggiornate
+Quando l'utente chiede esplicitamente uno stato attuale o aggiornato, l'AI può interrogare gli oggetti esatti del catalogo ETS importato, compresi gli oggetti di stato e di sola lettura. L'uscita 4 emette `msg.destination`, `msg.dpt`, `msg.event = "GroupValue_Read"` e `msg.readstatus = true`. Il nodo attende fino a 6 secondi ogni `GroupValue_Response` o scrittura fresca, poi restituisce i valori decodificati sull'uscita 3 e i dettagli in `msg.knxAi.readResults`. Le letture non richiedono mai conferma e non vengono mai trasformate in scritture.
+
+### Richiesta di conferma per pulsanti chat
+Quando un piano è in attesa, l'uscita 3 contiene `msg.knxAi.confirmationRequest`. L'oggetto include `required`, `status`, `sessionId`, `expiresAt`, `commandCount` e due elementi in `actions`. Usa `action.label` per il testo del pulsante Telegram, `action.callbackData` per il callback e reinvia `action.message` al nodo KNX AI per confermare o annullare senza digitare testo.
+
+### Preset adattatori chat
+La tab **Adattatori chat** carica le mappature selezionabili da `resources/KNXAIChatAdapterMappings.js`. Scegliendo un preset vengono inserite due mappature JavaScript sincrone e modificabili in caselle di testo a larghezza piena: una eseguita prima che KNX AI elabori l'ingresso e una prima dell'emissione sull'uscita 3. Restituisci `msg` per continuare oppure nessun valore per scartare il messaggio. Errori di sintassi o esecuzione vengono intercettati e segnalati senza arrestare Node-RED.
+
+Il preset incluso **windkh/node-red-contrib-telegrambot** segue il contratto receiver/sender del pacchetto. Collega direttamente un `telegram receiver` a KNX AI e l'uscita 3 direttamente a un `telegram sender`; per usare i pulsanti inline di conferma, collega allo stesso ingresso KNX AI anche un `telegram event` configurato come `callback_query`. La mappatura d'ingresso estrae `msg.payload.content`, `msg.payload.chatId` e la lingua Telegram. Quella d'uscita crea i campi richiesti `msg.payload.chatId`, `type` e `content`, aggiungendo `options.reply_markup` da `msg.knxAi.confirmationRequest` quando una scrittura attende conferma. Il pacchetto Telegram resta una dipendenza opzionale separata.
+
+## Intelligenza domestica proattiva e memoria limitata
+La sottosezione **Casa proattiva e memoria** dentro **Conversazioni e casa** abilita le notifiche proattive su scelta dell'utente. Da gerarchia ETS, nomi, ruoli e DPT, il nodo crea un modello semantico deterministico per persiane, finestre, porte, luci, temperatura, clima, presenza e allarmi usando termini italiani, inglesi, tedeschi, francesi, spagnoli e cinesi. Il primo rilevatore proattivo osserva soltanto stati non di comando di persiane/finestre/porte riconosciuti con sufficiente affidabilità. Dopo il tempo di apertura configurato e fuori dalle ore silenziose, l'uscita 3 emette un messaggio localizzato con `msg.knxAi.type = "proactive_notification"`. Non emette mai l'uscita 4 e non modifica autonomamente KNX; un'eventuale richiesta successiva dell'utente passa sempre dalla normale validazione e conferma.
+
+L'ultima sessione chat viene ricordata come proprietario, oppure **Destinatario principale / chat ID** consente di impostarla esplicitamente. Un `msg.inputMessage` sintetico conserva il destinatario affinché l'adattatore Telegram possa inviare una notifica spontanea. Il cooldown e il limite di tre notifiche proattive all'ora evitano messaggi ripetuti.
+
+Il riferimento appreso viene caricato all'avvio da `<userDir>/knxai/memory/knxai-home-memory-<node-id>.md`, riscritto atomicamente ogni 15 minuti e limitato rigidamente tra 64 e 1.024 KB configurabili (256 KB per default). Conserva al massimo 120 osservazioni significative, 80 abitudini aggregate, 80 notifiche e 300 oggetti ETS semantici, mai un flusso illimitato di telegrammi raw. Gli elementi vecchi e meno importanti vengono eliminati per primi. **Educazione AI** è limitata a 16.000 caratteri e proviene sempre dalla configurazione del nodo: l'AI può leggerla come istruzione autorevole, ma non può modificarla o sovrascriverla. Se l'Educazione è presente ma l'LLM non riesce a valutarla, la notifica candidata viene soppressa invece di rischiare di contraddirla.
+
+## Esempio pratico di configurazione
+Questo esempio crea un assistente conciso che avvisa il proprietario delle aperture importanti, ma accetta che la persiana dello studio possa rimanere aperta:
+
+| Campo dell'editor | Valore di esempio | Risultato |
+|---|---|---|
+| **Abilita notifiche domestiche proattive** (`proactiveEnabled`) | attivo | Il nodo valuta gli stati aperti di persiane, finestre e porte riconosciuti con affidabilità. |
+| **Destinatario principale / chat ID** (`proactiveRecipient`) | `123456789` | I messaggi spontanei vengono inviati a questa chat. Lascia vuoto per ricordare l'ultima sessione Ask. |
+| **Avvisa dopo apertura** (`proactiveOpenMinutes`) | `120` | Dopo due ore viene valutata una possibile notifica. |
+| **Inizio / fine ore silenziose** | `23:00` / `07:00` | Durante la notte non vengono emessi messaggi proattivi. |
+| **Intervallo prima di ripetere** (`proactiveCooldownMinutes`) | `360` | Lo stesso oggetto non può generare un altro avviso per sei ore. |
+| **Dimensione massima memoria casa** (`homeMemoryMaxKb`) | `256` | Il riferimento Markdown del singolo nodo non può superare 256 KB. |
+
+Esempio per **Educazione AI** (`aiEducation`):
+
+```text
+Chiamami Massimo e rispondi nella stessa lingua che uso.
+Mantieni le risposte brevi, salvo quando chiedo dettagli tecnici.
+La persiana dello studio può restare aperta durante il giorno: non avvisarmi.
+Avvisami quando un'altra persiana, finestra o porta rimane aperta insolitamente a lungo.
+Quando "luce soggiorno" è ambiguo, chiedimi quale luce intendo.
+Non dire mai che un attuatore è cambiato finché un oggetto di stato KNX non lo conferma.
+```
+
+Con queste impostazioni:
+
+1. Se lo stato della persiana del soggiorno rimane aperto per 120 minuti fuori dalle ore silenziose, l'uscita 3 può emettere una `proactive_notification` localizzata.
+2. Se rimane aperta la persiana dello studio, l'LLM legge l'Educazione e sopprime quella notifica candidata.
+3. Se Massimo chiede poi di chiudere la persiana del soggiorno, KNX AI prepara il comando ETS esatto e applica comunque la normale validazione e conferma prima dell'uscita 4.
+
+Usa gerarchie e nomi oggetto ETS descrittivi, con ruoli di stato/comando corretti. L'Educazione può personalizzare decisioni e formulazione, ma non può autorizzare un group address inventato, cambiare un DPT o aggirare la validazione KNX.
 
-Per `ask`, passa la domanda in `msg.prompt` (consigliato) oppure in `msg.payload` (stringa).
+## Workflow rapido: controllo KNX
+1. Importa il CSV ETS nel gateway e configura provider, modello e credenziali LLM.
+2. Abilita **Assistente LLM** e **lettura stati e controllo attuatori KNX**; lascia attiva la conferma.
+3. Collega l'ingresso della chat al nodo KNX AI mantenendo un ID sessione/chat stabile.
+4. Collega l'uscita 3 alla risposta della chat e l'uscita 4 a KNX Ultimate in **Modalità Universale**.
+5. L'utente invia una richiesta; gli stati aggiornati vengono letti subito, mentre per le scritture l'AI mostra prima GA, DPT e valore senza scrivere sul bus.
+6. Entro 5 minuti, la stessa chat risponde esattamente `CONFERMA` oppure `ANNULLA`.
+7. Solo `CONFERMA` rivalida ed emette i comandi sull'uscita 4; verifica l'esecuzione tramite una GA di stato.
 
 ## Campi di configurazione
 Di seguito sono elencati tutti i campi presenti nell'editor del nodo KNX AI.
@@ -53,7 +121,20 @@ Di seguito sono elencati tutti i campi presenti nell'editor del nodo KNX AI.
 - **URL endpoint**: URL endpoint chat/completions.
 - **API key**: chiave API (non necessaria con Ollama locale).
 - **Modello**: ID/nome modello.
+- **Compatibilità modello chat**: il modello selezionato deve supportare l'endpoint Chat Completions configurato. I modelli legacy disponibili solo tramite completions, come `gpt-3.5-turbo-instruct`, vengono esclusi quando si aggiorna la lista. Se il provider rifiuta un valore personalizzato di temperature o il parametro del limite token, KNX AI riprova rimuovendo o sostituendo soltanto il campo incompatibile.
 - **Prompt di sistema**: istruzione globale del comportamento analisi KNX (Advanced).
+- **Consenti all'AI di leggere stati KNX e comandare attuatori**: abilita l'uscita 4 ed è disattivato per default. Gli oggetti esatti del catalogo ETS possono essere letti; le scritture sono accettate solo per gli oggetti classificati come `command`. Operazioni sconosciute, con DPT discordante, non valide o eccessive e scritture verso oggetti di stato/neutrali vengono rifiutate localmente.
+- **Chiedi conferma prima di inviare comandi KNX**: attivo per default. Mostra prima le modifiche validate e non emette comandi KNX finché la stessa sessione chat non le conferma. Quando ci sono comandi in attesa, la risposta aggiunge sempre le istruzioni esatte per confermare o annullare nella lingua della richiesta corrente. I comandi vengono validati nuovamente subito prima dell'uscita.
+- **Preset adattatore**: carica una coppia di mappature ingresso/uscita dal file degli adattatori chat incluso. La selezione sostituisce intenzionalmente entrambe le caselle di testo; il codice resta modificabile.
+- **Mappatura ingresso (chat → KNX AI)**: JavaScript sincrono applicato prima dell'elaborazione del comando in ingresso.
+- **Mappatura uscita (KNX AI → chat)**: JavaScript sincrono applicato solo ai messaggi dell'uscita 3.
+- **Abilita notifiche domestiche proattive**: rilevatore opzionale per stati aperti affidabili di persiane/finestre/porte; non scrive mai autonomamente su KNX.
+- **Destinatario principale / chat ID**: destinazione opzionale dei messaggi spontanei; altrimenti viene ricordata l'ultima sessione Ask.
+- **Avvisa dopo apertura (minuti)**: soglia di durata dell'apertura prima di valutare una notifica proattiva.
+- **Inizio / fine ore silenziose**: intervallo giornaliero in cui i messaggi proattivi sono sospesi.
+- **Educazione AI**: istruzioni autorevoli gestite soltanto dall'utente, lette dall'AI e mai modificate.
+- **Cooldown ripetizione (minuti)**: intervallo minimo prima che lo stesso oggetto possa generare un altro avviso.
+- **Dimensione massima memoria domestica (KB)**: limite rigido da 64 a 1.024 KB; 256 KB per default.
 - Se l'archivio su disco e' attivo, **Ask** lo usa di default: rispetta date/intervalli espliciti e, se non presenti, cerca nelle ultime 24 ore piu' gli eventi correnti in RAM.
 - **Includi payload raw in hex**: include payload raw esadecimale nel prompt.
 - **Includi inventario del progetto Node-RED**: include nel prompt l'inventario dell'intero progetto Node-RED, compresi nodi KNX e altri nodi utili come function/change/inject/template quando contengono logica KNX o group address.
@@ -84,5 +165,5 @@ Di seguito sono elencati tutti i campi presenti nell'editor del nodo KNX AI.
 - Se Node-RED gira in Docker, usa `host.docker.internal` al posto di `localhost` nell'endpoint.
 
 ## Nota sicurezza
-Se l'LLM è abilitato, il contesto traffico KNX può essere inviato all'endpoint configurato. Per privacy on-prem, usa provider locali.
+Se l'LLM è abilitato, il contesto traffico KNX può essere inviato all'endpoint configurato. Per privacy on-prem, usa provider locali. Un comando emesso sull'uscita 4 ha superato la validazione locale ed è stato inoltrato al flow, ma non prova che l'attuatore lo abbia eseguito. Per la conferma usa una GA di stato KNX.
 </script>

package/nodes/locales/it/knxUltimateAI.json

@@ -2,12 +2,19 @@
   "knxUltimateAI": {
     "title": "KNX AI (Analisi Traffico)",
     "sections": {
-      "capture": "Cattura",
-      "storage": "Storico e Summary",
-      "detection": "Rilevamento e Avvisi",
+      "groupAssistant": "Assistente AI",
+      "groupChatHome": "Conversazioni e casa",
+      "groupKnxAnalysis": "Analisi traffico KNX",
+      "quickSetup": "Configurazione assistente",
+      "capture": "Telegrammi dal bus",
+      "storage": "Storico e riepiloghi KNX",
+      "detection": "Anomalie e pattern",
       "llmConnection": "Connessione Assistente AI",
-      "llmContext": "Contesto Assistente AI",
-      "advanced": "Tuning Avanzato"
+      "llmContext": "Conoscenza e contesto AI",
+      "chatAdapter": "Canali chat",
+      "homeIntelligence": "Casa proattiva e memoria",
+      "homeIntelligenceAdvanced": "Impostazioni proattive avanzate",
+      "advanced": "Provider e limiti"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +46,36 @@
       "llmSystemPrompt": "Prompt di sistema",
       "llmIncludeRaw": "Includi payload raw in hex",
       "llmIncludeFlowContext": "Includi inventario del progetto Node-RED",
+      "llmAllowKnxCommands": "Consenti all'AI di leggere stati KNX e comandare attuatori",
+      "llmRequireCommandConfirmation": "Chiedi conferma prima di inviare comandi KNX",
+      "chatAdapterPreset": "Preset adattatore",
+      "chatInputCode": "Mappatura ingresso (chat → KNX AI)",
+      "chatOutputCode": "Mappatura uscita (KNX AI → chat)",
+      "proactiveEnabled": "Abilita notifiche domestiche proattive",
+      "proactiveRecipient": "Destinatario principale / chat ID",
+      "proactiveOpenMinutes": "Avvisa dopo apertura (minuti)",
+      "proactiveCooldownMinutes": "Intervallo prima di ripetere (minuti)",
+      "proactiveQuietStart": "Inizio ore silenziose",
+      "proactiveQuietEnd": "Fine ore silenziose",
+      "homeMemoryMaxKb": "Dimensione massima memoria casa (KB)",
+      "aiEducation": "Educazione AI (gestita dall'utente)",
       "llmIncludeDocsSnippets": "Includi estratti documentazione (help/README/esempi)",
       "llmDocsLanguage": "Lingua documentazione"
     },
     "outputs": {
       "summary": "Summary/Statistiche",
       "anomalies": "Anomalie",
-      "assistant": "Assistente AI"
+      "assistant": "Assistente AI",
+      "knxCommands": "Operazioni KNX"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "Compatibile OpenAI (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (locale, beta)"
+      },
+      "chatAdapter": {
+        "none": "Nessun adattatore"
       }
     },
     "buttons": {
@@ -69,13 +93,20 @@
       "installedOllamaModel": "Modello Ollama installato",
       "installOllamaModelFailed": "Installazione modello Ollama non riuscita",
       "ollamaInstallSteps": "1) Apri la libreria, scegli un modello e copiane il nome (es. llama3.1). 2) Inserisci il nome nel campo Modello e clicca Installalo.",
-      "ollamaStartedAuto": "Server Ollama avviato automaticamente."
+      "ollamaStartedAuto": "Server Ollama avviato automaticamente.",
+      "chatAdapterIntro": "Scegli un preset per inserire il codice di mappatura in ingresso e in uscita. La lista viene caricata dal file degli adattatori chat incluso nel pacchetto; il codice generato resta modificabile.",
+      "chatAdapterCodeHelp": "Le mappature sono sincrone. Restituisci msg per continuare oppure nessun valore per scartarlo. Gli errori vengono intercettati e segnalati senza arrestare Node-RED.",
+      "homeIntelligenceIntro": "Il nodo crea un modello ETS semantico multilingue e può avvisare la chat quando una persiana, finestra o porta riconosciuta con sufficiente affidabilità rimane aperta. Non invia mai autonomamente comandi KNX.",
+      "aiEducationHelp": "Solo l'utente può modificare questa sezione. L'AI la legge come istruzione autorevole, ma la memoria appresa non può mai sovrascriverla. Massimo 16.000 caratteri.",
+      "homeMemoryLimitHelp": "La memoria Markdown viene riscritta atomicamente ogni 15 minuti ed è sempre limitata tra 64 e 1.024 KB. Le osservazioni vecchie vengono eliminate prima delle abitudini e degli oggetti semantici."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (o endpoint compatibile)",
       "llmApiKey": "Incolla la chiave (inizia con sk-)",
       "llmModel": "es. gpt-4o-mini",
-      "llmSystemPrompt": "Opzionale. Lascia vuoto per default."
+      "llmSystemPrompt": "Opzionale. Lascia vuoto per default.",
+      "proactiveRecipient": "Opzionale: chat ID Telegram; altrimenti viene ricordata l'ultima sessione chat",
+      "aiEducation": "Esempio: non avvisarmi tra le 23:00 e le 07:00. La persiana dello studio può restare aperta di notte."
     },
     "sidebar": {
       "ui": {