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

package/nodes/locales/de/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 Dieser Node überwacht **alle KNX-Telegramme** des ausgewählten KNX-Ultimate-Gateways, erstellt Verkehrsstatistiken, erkennt Anomalien und kann optional ein LLM befragen.
 
+Die Editor-Bereiche verwenden dieselben vertikalen Tabs auf der linken Seite wie die Matter-Nodes. **Schnelleinrichtung** enthält nur die üblichen KI-Einstellungen (Aktivierung, Anbieter, Zugangsdaten, Modell, KNX-Zustandsabfrage/Aktorsteuerung und Bestätigung); technische Parameter sind thematisch in den übrigen Tabs gruppiert.
+
 ## Ausgänge
 1. **Zusammenfassung/Statistik** (`msg.payload` JSON)
 2. **Anomalien** (`msg.payload` JSON)
 3. **KI-Assistent** (`msg.payload` Text, mit `msg.summary`)
+4. **KNX-Operationen** (eine Universal-Mode-Nachricht je validierter Lese- oder Schreiboperation)
+
+Jede an den Ausgängen 3 und 4 ausgegebene Nachricht enthält außerdem eine Kopie der ursprünglichen Eingangsnachricht in `msg.inputMessage`. Dadurch bleiben der ursprüngliche Payload, das Topic, die Chat-Metadaten und alle weiteren Eingangseigenschaften für nachfolgende Nodes verfügbar. Fehler beim Klonen oder Ausgeben werden abgefangen und gemeldet, statt in die Node-RED-Laufzeit zu gelangen.
 
 ## Befehle (Eingang)
 Sende `msg.topic`:
 - `summary` (oder leer): Summary sofort senden
 - `reset`: internen Verlauf/Zähler zurücksetzen
 - `ask`: Frage an das konfigurierte LLM senden
+- `confirm` / `cancel`: ausstehende KNX-Befehle ohne erneuten LLM-Aufruf bestätigen oder abbrechen
+- `clear_chat`: Gesprächsspeicher der aktuellen Sitzung löschen
+
+Für `ask` die Frage in `msg.prompt` (empfohlen), `msg.payload` (String) oder den üblichen Telegram-Feldern `msg.payload.content` / `msg.payload.text` übergeben.
+
+Bei aktiviertem KNX-Steuern werden die letzten Gesprächsschritte im RAM nach `msg.knxAi.sessionId`, `msg.sessionId` oder erkannter Telegram-Chat-ID getrennt. Ausgang 3 mit dem Chat-Sender und Ausgang 4 mit einem KNX-Ultimate-Node im **Universalmodus** verbinden. Bei aktiver Bestätigung zeigt die erste Antwort GA, DPT und Payload, ohne Schreiboperationen auszugeben; dieselbe Sitzung muss innerhalb von 5 Minuten `BESTÄTIGEN` oder `ABBRECHEN` antworten. Eine neue Anfrage ersetzt einen älteren Plan. Jeder bestätigte Befehl enthält `msg.destination`, `msg.dpt`, `msg.payload` und `msg.event = "GroupValue_Write"`.
+Bei DPT-1.xxx-Schreibvorgängen werden die sicheren KI-Entsprechungen `true`/`false`, `1`/`0` und `on`/`off` vor der lokalen Validierung und Ausgabe in echte Boolesche Werte normalisiert.
+
+### Aktuelle KNX-Lesewerte
+Wenn der Benutzer ausdrücklich einen aktuellen oder aktualisierten Zustand anfordert, kann die KI exakte Objekte aus dem importierten ETS-Katalog abfragen, einschließlich Status- und anderer schreibgeschützter Objekte. Ausgang 4 gibt `msg.destination`, `msg.dpt`, `msg.event = "GroupValue_Read"` und `msg.readstatus = true` aus. Der Node wartet bis zu 6 Sekunden auf jede `GroupValue_Response` oder ein aktuelles Write-Telegramm, gibt anschließend die dekodierten Werte an Ausgang 3 zurück und stellt Details in `msg.knxAi.readResults` bereit. Leseoperationen erfordern keine Bestätigung und werden niemals in Schreiboperationen umgewandelt.
+
+### Bestätigungsanfrage für Chat-Schaltflächen
+Solange ein Plan aussteht, enthält Ausgang 3 `msg.knxAi.confirmationRequest`. Das Objekt enthält `required`, `status`, `sessionId`, `expiresAt`, `commandCount` und zwei Einträge in `actions`. Verwenden Sie `action.label` als Text der Telegram-Schaltfläche, `action.callbackData` als Callback und senden Sie `action.message` an KNX AI zurück, um ohne Texteingabe zu bestätigen oder abzubrechen.
+
+### Chat-Adapter-Vorlagen
+Der Tab **Chat-Adapter** lädt seine auswählbaren Zuordnungen aus `resources/KNXAIChatAdapterMappings.js`. Die Auswahl einer Vorlage fügt zwei bearbeitbare synchrone JavaScript-Zuordnungen in Textfeldern über die volle Breite ein: eine vor der Verarbeitung des Eingangs durch KNX AI und eine vor der Ausgabe an Ausgang 3. Geben Sie `msg` zurück, um fortzufahren, oder keinen Wert, um die Nachricht zu verwerfen. Syntax- und Laufzeitfehler werden abgefangen und gemeldet, ohne Node-RED anzuhalten.
+
+Die enthaltene Vorlage **windkh/node-red-contrib-telegrambot** folgt dem Receiver-/Sender-Vertrag des Pakets. Verbinden Sie einen `telegram receiver` direkt mit KNX AI und Ausgang 3 direkt mit einem `telegram sender`. Für Inline-Bestätigungsschaltflächen verbinden Sie zusätzlich einen als `callback_query` konfigurierten `telegram event` mit demselben KNX-AI-Eingang. Die Eingangszuordnung liest `msg.payload.content`, `msg.payload.chatId` und die Telegram-Sprache. Die Ausgangszuordnung erstellt `msg.payload.chatId`, `type` und `content` und ergänzt bei ausstehender Schreibbestätigung `options.reply_markup` aus `msg.knxAi.confirmationRequest`. Das Telegram-Paket bleibt eine separate optionale Abhängigkeit.
 
-Für `ask` die Frage in `msg.prompt` (empfohlen) oder `msg.payload` (String) übergeben.
+## Kurzer Ablauf: KNX-Steuerung
+1. Importieren Sie die ETS-CSV in das Gateway und konfigurieren Sie LLM-Anbieter, Modell und Zugangsdaten.
+2. Aktivieren Sie **LLM-Assistent** und **KNX-Zustände lesen und Aktoren steuern**; lassen Sie die Bestätigung aktiviert.
+3. Verbinden Sie den Chat-Eingang mit KNX AI und behalten Sie eine stabile Sitzungs-/Chat-ID bei.
+4. Verbinden Sie Ausgang 3 mit der Chat-Antwort und Ausgang 4 mit KNX Ultimate im **Universalmodus**.
+5. Der Benutzer sendet eine Anfrage; aktuelle Zustandsabfragen werden sofort gelesen, während Schreiboperationen zuerst GA, DPT und Wert ohne Bus-Schreibzugriff anzeigen.
+6. Innerhalb von 5 Minuten antwortet derselbe Chat exakt mit `BESTÄTIGEN` oder `ABBRECHEN`.
+7. Nur `BESTÄTIGEN` validiert erneut und gibt Befehle an Ausgang 4 aus; prüfen Sie die Ausführung über eine KNX-Status-GA.
 
 ## Konfigurationsfelder
 Hier sind alle Felder aufgeführt, wie sie im KNX-AI-Editor sichtbar sind.
@@ -53,7 +83,13 @@ Hier sind alle Felder aufgeführt, wie sie im KNX-AI-Editor sichtbar sind.
 - **Endpoint URL**: URL des Chat/Completions-Endpunkts.
 - **API key**: API-Schlüssel (für lokales Ollama nicht erforderlich).
 - **Model**: Modell-ID/Name.
+- **Chatmodell-Kompatibilität**: Das ausgewählte Modell muss den konfigurierten Chat-Completions-Endpunkt unterstützen. Ältere reine Completions-Modelle wie `gpt-3.5-turbo-instruct` werden beim Aktualisieren der Modellliste ausgeschlossen. Lehnt der Anbieter einen benutzerdefinierten Temperaturwert oder den Token-Limit-Parameter ab, wiederholt KNX AI die Anfrage und entfernt oder ersetzt nur das inkompatible Feld.
 - **System prompt**: Globale Instruktion für KNX-Analyse (Advanced).
+- **KI darf KNX-Zustände lesen und Aktoren steuern**: Aktiviert Ausgang 4 und ist standardmäßig aus. Exakte ETS-Katalogobjekte dürfen gelesen werden; Schreiboperationen werden ausschließlich für Objekte mit Rolle `command` akzeptiert. Unbekannte, DPT-falsche, ungültige oder überzählige Operationen sowie Schreiboperationen auf Status-/Neutralobjekte werden lokal abgewiesen.
+- **Vor dem Senden von KNX-Befehlen bestätigen lassen**: Standardmäßig aktiv. Zeigt zuerst die validierten Änderungen und sendet nichts, bis dieselbe Chat-Sitzung bestätigt. Wenn Befehle auf Bestätigung warten, fügt die Antwort immer die genauen Anweisungen zum Bestätigen oder Abbrechen in der Sprache der aktuellen Anfrage hinzu. Vor der Ausgabe werden die Befehle erneut validiert.
+- **Adapter-Vorlage**: Lädt ein Paar aus Ein- und Ausgangszuordnung aus der mitgelieferten Chat-Adapter-Datei. Die Auswahl ersetzt bewusst beide Textfelder; der Code bleibt danach bearbeitbar.
+- **Eingangszuordnung (Chat → KNX AI)**: Synchrones JavaScript vor der Verarbeitung des Eingangsbefehls.
+- **Ausgangszuordnung (KNX AI → Chat)**: Synchrones JavaScript ausschließlich für Nachrichten an Ausgang 3.
 - Wenn das Festplattenarchiv aktiv ist, nutzt **Ask** standardmäßig dieses Archiv: explizite Datumsangaben/Zeitbereiche werden beachtet, sonst durchsucht der Assistent die letzten 24 Stunden plus aktuelle RAM-Events.
 - **Include raw payload hex**: Rohe Hex-Payload im Prompt einfügen.
 - **Node-RED-Projektinventar einbeziehen**: Nimmt das gesamte Node-RED-Projektinventar in den Prompt auf, einschließlich KNX-Nodes und anderer hilfreicher Nodes wie function/change/inject/template, wenn sie KNX-Logik oder Gruppenadressen enthalten.
@@ -84,5 +120,5 @@ Hier sind alle Felder aufgeführt, wie sie im KNX-AI-Editor sichtbar sind.
 - Wenn Node-RED in Docker läuft, im Endpoint `host.docker.internal` statt `localhost` verwenden.
 
 ## Sicherheitshinweis
-Bei aktiviertem LLM kann KNX-Traffic-Kontext an den konfigurierten Endpoint gesendet werden. Für striktes On-Premise lokale Provider verwenden.
+Bei aktiviertem LLM kann KNX-Traffic-Kontext an den konfigurierten Endpoint gesendet werden. Für striktes On-Premise lokale Provider verwenden. Ein Befehl an Ausgang 4 hat die lokale Validierung bestanden und wurde an den Flow weitergegeben; dies bestätigt nicht die Ausführung durch den Aktor. Dafür eine KNX-Status-GA verwenden.
 </script>

package/nodes/locales/de/knxUltimateAI.json

@@ -2,12 +2,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
+      "quickSetup": "Schnelleinrichtung",
       "capture": "Capture",
       "storage": "Speicher & Zusammenfassung",
       "detection": "Erkennung & Warnungen",
       "llmConnection": "KI-Assistent-Verbindung",
       "llmContext": "KI-Assistent-Kontext",
-      "advanced": "Erweiterte Einstellungen"
+      "chatAdapter": "Chat-Adapter",
+      "advanced": "Erweiterte KI"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "Node-RED-Projektinventar einbeziehen",
+      "llmAllowKnxCommands": "KI darf KNX-Zustände lesen und Aktoren steuern",
+      "llmRequireCommandConfirmation": "Vor dem Senden von KNX-Befehlen bestätigen lassen",
+      "chatAdapterPreset": "Adapter-Vorlage",
+      "chatInputCode": "Eingangszuordnung (Chat → KNX AI)",
+      "chatOutputCode": "Ausgangszuordnung (KNX AI → Chat)",
       "llmIncludeDocsSnippets": "Include documentation snippets (help/README/examples)",
       "llmDocsLanguage": "Docs language"
     },
     "outputs": {
       "summary": "Zusammenfassung/Statistik",
       "anomalies": "Anomalien",
-      "assistant": "KI-Assistent"
+      "assistant": "KI-Assistent",
+      "knxCommands": "KNX-Operationen"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "OpenAI-compatible (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (local, beta)"
+      },
+      "chatAdapter": {
+        "none": "Kein Adapter"
       }
     },
     "placeholder": {
@@ -67,7 +78,9 @@
       "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": "Wählen Sie eine Vorlage, um den Code für Ein- und Ausgang einzufügen. Die Liste wird aus der mitgelieferten Chat-Adapter-Datei geladen; der erzeugte Code bleibt bearbeitbar.",
+      "chatAdapterCodeHelp": "Zuordnungen laufen synchron. Geben Sie msg zurück, um fortzufahren, oder keinen Wert, um die Nachricht zu verwerfen. Fehler werden abgefangen und gemeldet, ohne Node-RED anzuhalten."
     },
     "sidebar": {
       "ui": {

package/nodes/locales/en/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 This node listens to **all KNX telegrams** from the selected KNX Ultimate gateway, builds traffic statistics, detects anomalies, and can optionally query an LLM.
 
+The editor sections use the same left-hand vertical tabs as the Matter nodes. **Quick setup** contains only the common AI choices (enable, provider, credentials, model, KNX state reads/actuator control and confirmation); technical settings are grouped by topic in the other tabs.
+
 ## Outputs
 1. **Summary/Stats** (`msg.payload` JSON)
 2. **Anomalies** (`msg.payload` JSON)
 3. **AI Assistant** (`msg.payload` text, with `msg.summary`)
+4. **KNX operations** (one Universal Mode message per validated read or write)
+
+Every message emitted by outputs 3 and 4 also contains a clone of the original input message in `msg.inputMessage`. This preserves the original payload, topic, chat metadata, and any other input properties for downstream nodes. Cloning and output errors are contained and reported instead of escaping into the Node-RED runtime.
 
 ## Commands (input)
 Send `msg.topic`:
 - `summary` (or empty): emit summary immediately
 - `reset`: clear internal history/counters
 - `ask`: send a question to the configured LLM
+- `confirm` / `cancel`: confirm or cancel pending KNX commands without calling the LLM
+- `clear_chat`: clear the conversation memory for the current session
+
+For `ask`, provide the question in `msg.prompt` (preferred), `msg.payload` (string), or the common Telegram fields `msg.payload.content` / `msg.payload.text`.
+
+When KNX control is enabled, recent turns are remembered in RAM per `msg.knxAi.sessionId`, `msg.sessionId`, or a detected Telegram chat ID. Wire output 3 back to the chat sender and output 4 to a KNX Ultimate node configured in **Universal mode**. With confirmation enabled, the first reply previews every write GA, DPT, and payload without emitting writes; the same session must then reply `CONFIRM`/`CANCEL` (localized equivalents are accepted) within 5 minutes. A new request replaces any older pending plan. Each confirmed command has `msg.destination`, `msg.dpt`, `msg.payload`, and `msg.event = "GroupValue_Write"`.
+For DPT 1.xxx writes, safe AI equivalents `true`/`false`, `1`/`0`, and `on`/`off` are normalized to a real boolean before local validation and output.
+
+### Fresh KNX reads
+When the user explicitly asks for a fresh/current state, the AI may query exact objects from the imported ETS catalog, including status and other read-only objects. Output 4 emits `msg.destination`, `msg.dpt`, `msg.event = "GroupValue_Read"`, and `msg.readstatus = true`. The node waits up to 6 seconds for each `GroupValue_Response` or fresh write, then returns the decoded values on output 3 and exposes details in `msg.knxAi.readResults`. Reads never require confirmation and never become writes.
+
+### Confirmation request for chat buttons
+While a plan is pending, output 3 contains `msg.knxAi.confirmationRequest`. The object includes `required`, `status`, `sessionId`, `expiresAt`, `commandCount`, and two entries in `actions`. Use `action.label` as the Telegram button text, `action.callbackData` as its callback, and send `action.message` back to KNX AI to confirm or cancel without typed text.
+
+### Chat adapter presets
+The **Chat adapters** tab loads its selectable mappings from `resources/KNXAIChatAdapterMappings.js`. Selecting a preset inserts two editable synchronous JavaScript mappings in full-width text boxes: one before KNX AI processes an input and one before output 3 is emitted. Return `msg` to continue or no value to discard the message. Syntax and execution failures are caught and reported without stopping Node-RED.
+
+The included **windkh/node-red-contrib-telegrambot** preset follows the package's receiver/sender contract. Connect a `telegram receiver` directly to KNX AI, output 3 directly to a `telegram sender`, and—when inline confirmation buttons are required—connect a `telegram event` configured for `callback_query` to the same KNX AI input. The input mapping extracts `msg.payload.content`, `msg.payload.chatId`, and the Telegram language. The output mapping creates the required `msg.payload.chatId`, `type`, and `content`, adding `options.reply_markup` from `msg.knxAi.confirmationRequest` when writes await confirmation. The Telegram package remains a separate optional dependency.
 
-For `ask`, provide the question in `msg.prompt` (preferred) or `msg.payload` (string).
+## Quick workflow: KNX control
+1. Import the ETS CSV into the gateway and configure the LLM provider, model, and credentials.
+2. Enable **LLM assistant** and **KNX state reads and actuator control**; leave confirmation enabled.
+3. Connect the chat input to KNX AI while preserving a stable session/chat ID.
+4. Connect output 3 to the chat reply and output 4 to KNX Ultimate in **Universal mode**.
+5. The user sends a request; fresh state requests are read immediately, while writes first show the proposed GA, DPT, and value without writing to the bus.
+6. Within 5 minutes, the same chat replies exactly `CONFIRM` or `CANCEL`.
+7. Only `CONFIRM` revalidates and emits commands on output 4; verify execution through a KNX status GA.
 
 ## Configuration fields
 All fields exposed in the KNX AI editor are listed below.
@@ -53,7 +83,13 @@ All fields exposed in the KNX AI editor are listed below.
 - **Endpoint URL**: Chat/completions endpoint URL.
 - **API key**: API key (not required for local Ollama).
 - **Model**: Model ID/name.
+- **Chat model compatibility**: The selected model must support the configured Chat Completions endpoint. Legacy completion-only models such as `gpt-3.5-turbo-instruct` are excluded when the model list is refreshed. If the provider rejects a custom temperature or token-limit parameter, KNX AI retries after removing or replacing only that incompatible field.
 - **System prompt**: Global instruction for KNX analysis behavior (Advanced).
+- **Allow AI to read KNX states and control actuators**: Enables output 4 and is off by default. Exact ETS catalog objects may be read; writes are accepted only for objects classified as `command`. Unknown, DPT-mismatched, invalid, or excessive operations and writes to status/neutral objects are rejected locally.
+- **Ask for confirmation before sending KNX commands**: Enabled by default. Shows the validated changes first and emits no KNX command until the same chat session confirms them. Whenever commands are awaiting confirmation, the response always appends the exact confirmation/cancellation instructions in the language of the current request. Commands are validated again immediately before output.
+- **Adapter preset**: Loads an input/output mapping pair from the packaged chat-adapter file. Selecting a preset intentionally replaces both mapping text boxes; they remain editable afterwards.
+- **Input mapping (chat → KNX AI)**: Synchronous JavaScript applied before input command processing.
+- **Output mapping (KNX AI → chat)**: Synchronous JavaScript applied only to messages on output 3.
 - If disk archive is enabled, **Ask** uses the archive by default: explicit dates/ranges are honored, otherwise the assistant searches the last 24 hours plus current RAM events.
 - **Include raw payload hex**: Include raw telegram hex in prompt.
 - **Include Node-RED project inventory**: Include the whole Node-RED project inventory in the prompt, including KNX nodes and other useful nodes such as function/change/inject/template when they contain KNX-related logic or group addresses.
@@ -84,5 +120,5 @@ All fields exposed in the KNX AI editor are listed below.
 - If Node-RED runs in Docker, use `host.docker.internal` instead of `localhost` in the endpoint URL.
 
 ## Security note
-If LLM is enabled, KNX traffic context can be sent to the configured endpoint. Use local providers if you need strict on-prem data handling.
+If LLM is enabled, KNX traffic context can be sent to the configured endpoint. Use local providers if you need strict on-prem data handling. A command emitted on output 4 passed local validation and was forwarded to the flow; it is not proof that the actuator executed it. Use a KNX status GA when confirmation is required.
 </script>

package/nodes/locales/en/knxUltimateAI.json

@@ -2,12 +2,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
+      "quickSetup": "Quick setup",
       "capture": "Capture",
       "storage": "Storage & Summary",
       "detection": "Detection & Alerts",
       "llmConnection": "AI Assistant Connection",
       "llmContext": "AI Assistant Context",
-      "advanced": "Advanced Tuning"
+      "chatAdapter": "Chat adapters",
+      "advanced": "Advanced AI"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "llmSystemPrompt": "System prompt",
       "llmIncludeRaw": "Include raw payload hex",
       "llmIncludeFlowContext": "Include Node-RED project inventory",
+      "llmAllowKnxCommands": "Allow AI to read KNX states and control actuators",
+      "llmRequireCommandConfirmation": "Ask for confirmation before sending KNX commands",
+      "chatAdapterPreset": "Adapter preset",
+      "chatInputCode": "Input mapping (chat → KNX AI)",
+      "chatOutputCode": "Output mapping (KNX AI → chat)",
       "llmIncludeDocsSnippets": "Include documentation snippets (help/README/examples)",
       "llmDocsLanguage": "Docs language"
     },
     "outputs": {
       "summary": "Summary/Stats",
       "anomalies": "Anomalies",
-      "assistant": "AI Assistant"
+      "assistant": "AI Assistant",
+      "knxCommands": "KNX operations"
     },
     "selectlists": {
       "llmProvider": {
         "openai_compat": "OpenAI-compatible (chat/completions)",
         "anthropic": "Anthropic (Claude)",
         "ollama": "Ollama (local, beta)"
+      },
+      "chatAdapter": {
+        "none": "No adapter"
       }
     },
     "buttons": {
@@ -69,7 +80,9 @@
       "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": "Choose a mapping preset to insert its input and output code. The list is loaded from the packaged chat-adapter mappings file; the generated code remains editable.",
+      "chatAdapterCodeHelp": "Mappings run synchronously. Return msg to continue or return no value to discard it. Errors are caught and reported without stopping Node-RED."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",

package/nodes/locales/es/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <script type="text/markdown" data-help-name="knxUltimateAI">
 Este nodo escucha **todos los telegramas KNX** del gateway KNX Ultimate seleccionado, genera estadísticas de tráfico, detecta anomalías y puede consultar opcionalmente un LLM.
 
+Las secciones del editor utilizan las mismas pestañas verticales a la izquierda que los nodos Matter. **Configuración rápida** contiene solo las opciones habituales de AI (activación, proveedor, credenciales, modelo, lectura de estados/control de actuadores KNX y confirmación); los parámetros técnicos se agrupan por tema en las demás pestañas.
+
 ## Salidas
 1. **Resumen/Estadísticas** (`msg.payload` JSON)
 2. **Anomalías** (`msg.payload` JSON)
 3. **Asistente IA** (`msg.payload` texto, con `msg.summary`)
+4. **Operaciones KNX** (un mensaje Universal Mode por cada lectura o escritura validada)
+
+Cada mensaje emitido por las salidas 3 y 4 también contiene una copia del mensaje de entrada original en `msg.inputMessage`. Así, el payload, el topic, los metadatos del chat y cualquier otra propiedad de entrada permanecen disponibles para los nodos posteriores. Los errores de clonación o envío se interceptan y notifican sin propagarse al runtime de Node-RED.
 
 ## Comandos (entrada)
 Envía `msg.topic`:
 - `summary` (o vacío): emite el resumen inmediatamente
 - `reset`: limpia historial y contadores internos
 - `ask`: envía una pregunta al LLM configurado
+- `confirm` / `cancel`: confirma o cancela los comandos KNX pendientes sin volver a llamar al LLM
+- `clear_chat`: borra la memoria de conversación de la sesión actual
+
+Para `ask`, envía la pregunta en `msg.prompt` (recomendado), `msg.payload` (string), o los campos comunes de Telegram `msg.payload.content` / `msg.payload.text`.
+
+Cuando el control KNX está habilitado, los turnos recientes se guardan en RAM por `msg.knxAi.sessionId`, `msg.sessionId` o el ID de chat Telegram detectado. Conecta la salida 3 al nodo emisor del chat y la salida 4 a un nodo KNX Ultimate en **modo universal**. Con la confirmación activa, la primera respuesta muestra GA, DPT y payload sin emitir escrituras; la misma sesión debe responder `CONFIRMAR` o `CANCELAR` en 5 minutos. Una solicitud nueva sustituye cualquier plan anterior. Cada comando confirmado contiene `msg.destination`, `msg.dpt`, `msg.payload` y `msg.event = "GroupValue_Write"`.
+Para las escrituras DPT 1.xxx, los equivalentes seguros producidos por la IA `true`/`false`, `1`/`0` y `on`/`off` se normalizan a booleanos reales antes de la validación local y la salida.
+
+### Lecturas KNX actualizadas
+Cuando el usuario solicita explícitamente un estado actual o actualizado, la IA puede consultar objetos exactos del catálogo ETS importado, incluidos objetos de estado y otros objetos de solo lectura. La salida 4 emite `msg.destination`, `msg.dpt`, `msg.event = "GroupValue_Read"` y `msg.readstatus = true`. El nodo espera hasta 6 segundos cada `GroupValue_Response` o escritura reciente, devuelve los valores decodificados por la salida 3 y expone los detalles en `msg.knxAi.readResults`. Las lecturas nunca requieren confirmación ni se convierten en escrituras.
+
+### Solicitud de confirmación para botones de chat
+Mientras un plan está pendiente, la salida 3 contiene `msg.knxAi.confirmationRequest`. El objeto incluye `required`, `status`, `sessionId`, `expiresAt`, `commandCount` y dos elementos en `actions`. Usa `action.label` como texto del botón de Telegram, `action.callbackData` como callback y devuelve `action.message` a KNX AI para confirmar o cancelar sin escribir texto.
+
+### Preajustes del adaptador de chat
+La pestaña **Adaptadores de chat** carga sus mapeos seleccionables desde `resources/KNXAIChatAdapterMappings.js`. Al elegir un preajuste se insertan dos mapeos JavaScript síncronos y editables en cuadros de texto de ancho completo: uno antes de que KNX AI procese la entrada y otro antes de emitir por la salida 3. Devuelve `msg` para continuar o ningún valor para descartar el mensaje. Los errores de sintaxis y ejecución se capturan y notifican sin detener Node-RED.
+
+El preajuste incluido **windkh/node-red-contrib-telegrambot** sigue el contrato receiver/sender del paquete. Conecta directamente un `telegram receiver` a KNX AI y la salida 3 a un `telegram sender`. Para los botones inline de confirmación, conecta también un `telegram event` configurado como `callback_query` a la misma entrada KNX AI. El mapeo de entrada extrae `msg.payload.content`, `msg.payload.chatId` y el idioma de Telegram. El mapeo de salida crea `msg.payload.chatId`, `type` y `content`, y añade `options.reply_markup` desde `msg.knxAi.confirmationRequest` cuando una escritura espera confirmación. El paquete Telegram sigue siendo una dependencia opcional separada.
 
-Para `ask`, envía la pregunta en `msg.prompt` (recomendado) o `msg.payload` (string).
+## Flujo rápido: control KNX
+1. Importa el CSV de ETS en el gateway y configura el proveedor, el modelo y las credenciales LLM.
+2. Activa **Asistente LLM** y **lectura de estados KNX y control de actuadores**; deja activada la confirmación.
+3. Conecta la entrada del chat a KNX AI manteniendo un ID de sesión/chat estable.
+4. Conecta la salida 3 a la respuesta del chat y la salida 4 a KNX Ultimate en **modo universal**.
+5. El usuario envía una solicitud; los estados actuales se leen inmediatamente, mientras que las escrituras muestran primero GA, DPT y valor sin escribir en el bus.
+6. En un plazo de 5 minutos, el mismo chat responde exactamente `CONFIRMAR` o `CANCELAR`.
+7. Solo `CONFIRMAR` vuelve a validar y emite los comandos por la salida 4; verifica la ejecución mediante una GA de estado KNX.
 
 ## Campos de configuración
 Aquí tienes todos los campos tal como se muestran en el editor de KNX AI.
@@ -53,7 +83,13 @@ Aquí tienes todos los campos tal como se muestran en el editor de KNX AI.
 - **Endpoint URL**: URL endpoint chat/completions.
 - **API key**: clave API (no requerida con Ollama local).
 - **Model**: ID/nombre de modelo.
+- **Compatibilidad del modelo de chat**: el modelo seleccionado debe admitir el endpoint Chat Completions configurado. Los modelos antiguos disponibles solo mediante completions, como `gpt-3.5-turbo-instruct`, se excluyen al actualizar la lista. Si el proveedor rechaza un valor personalizado de temperatura o el parámetro de límite de tokens, KNX AI vuelve a intentarlo eliminando o sustituyendo únicamente el campo incompatible.
 - **System prompt**: instrucción global para análisis KNX (Advanced).
+- **Permitir que la IA lea estados KNX y controle actuadores**: habilita la salida 4 y está desactivado por defecto. Los objetos exactos del catálogo ETS se pueden leer; solo se aceptan escrituras hacia objetos clasificados como `command`. Las operaciones desconocidas, con DPT distinto, inválidas o excesivas, y las escrituras hacia objetos de estado o neutrales, se rechazan localmente.
+- **Pedir confirmación antes de enviar comandos KNX**: activado por defecto. Muestra primero los cambios validados y no emite comandos hasta que la misma sesión de chat los confirme. Cuando hay comandos pendientes, la respuesta añade siempre las instrucciones exactas para confirmar o cancelar en el idioma de la solicitud actual. Los comandos se validan de nuevo justo antes de la salida.
+- **Preajuste del adaptador**: carga una pareja de mapeos entrada/salida desde el archivo de adaptadores de chat incluido. La selección sustituye intencionadamente ambos cuadros de texto; el código sigue siendo editable.
+- **Mapeo de entrada (chat → KNX AI)**: JavaScript síncrono aplicado antes de procesar el comando de entrada.
+- **Mapeo de salida (KNX AI → chat)**: JavaScript síncrono aplicado solo a los mensajes de la salida 3.
 - Si el archivo en disco esta activo, **Ask** lo usa por defecto: respeta fechas/rangos explicitos y, si no los indicas, busca en las ultimas 24 horas mas los eventos actuales en RAM.
 - **Include raw payload hex**: incluye payload hex raw en el prompt.
 - **Incluir inventario del proyecto Node-RED**: incluye en el prompt el inventario de todo el proyecto Node-RED, con nodos KNX y otros nodos utiles como function/change/inject/template cuando contienen logica KNX o direcciones de grupo.
@@ -84,5 +120,5 @@ Aquí tienes todos los campos tal como se muestran en el editor de KNX AI.
 - Si Node-RED se ejecuta en Docker, usa `host.docker.internal` en lugar de `localhost` en el endpoint.
 
 ## Nota de seguridad
-Si el LLM está habilitado, el contexto de tráfico KNX puede enviarse al endpoint configurado. Para privacidad on-premise, usa proveedores locales.
+Si el LLM está habilitado, el contexto de tráfico KNX puede enviarse al endpoint configurado. Para privacidad on-premise, usa proveedores locales. Un comando emitido por la salida 4 superó la validación local y fue enviado al flow, pero no confirma que el actuador lo ejecutara. Usa una GA de estado KNX para confirmarlo.
 </script>

package/nodes/locales/es/knxUltimateAI.json

@@ -2,12 +2,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
+      "quickSetup": "Configuracion rapida",
       "capture": "Capture",
       "storage": "Historial y Resumen",
       "detection": "Deteccion y Alertas",
       "llmConnection": "Conexion del Asistente IA",
       "llmContext": "Contexto del Asistente IA",
-      "advanced": "Ajustes Avanzados"
+      "chatAdapter": "Adaptadores de chat",
+      "advanced": "IA avanzada"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "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)",
       "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,7 +72,9 @@
       "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."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",

package/nodes/locales/fr/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <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.
 
+Les sections de l'éditeur utilisent les mêmes onglets verticaux à gauche que les nœuds Matter. **Configuration rapide** ne contient que les choix AI courants (activation, fournisseur, identifiants, modèle, lecture des états/commande des actionneurs KNX et confirmation) ; les paramètres techniques sont regroupés par thème dans les autres onglets.
+
 ## 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
 - `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.
 
-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 +83,13 @@ 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.
 - 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 +120,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,14 @@
   "knxUltimateAI": {
     "title": "KNX AI (Traffic Analyzer)",
     "sections": {
+      "quickSetup": "Configuration rapide",
       "capture": "Capture",
       "storage": "Historique et Resume",
       "detection": "Detection et Alertes",
       "llmConnection": "Connexion Assistant IA",
       "llmContext": "Contexte Assistant IA",
-      "advanced": "Reglages Avances"
+      "chatAdapter": "Adaptateurs de chat",
+      "advanced": "IA avancee"
     },
     "properties": {
       "server": "Gateway",
@@ -39,19 +41,28 @@
       "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)",
       "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,7 +72,9 @@
       "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."
     },
     "placeholder": {
       "llmBaseUrl": "https://api.openai.com/v1/chat/completions (or your compatible endpoint)",

package/nodes/locales/it/knxUltimateAI.html

@@ -1,18 +1,48 @@
 <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.
 
+Le sezioni dell'editor utilizzano le stesse tab verticali a sinistra dei nodi Matter. **Configurazione rapida** contiene soltanto le scelte AI più comuni (abilitazione, provider, credenziali, modello, lettura stati/comando attuatori KNX e conferma); i parametri tecnici sono raggruppati per argomento nelle altre tab.
+
 ## 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
 - `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.
 
-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 +83,13 @@ 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.
 - 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 +120,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>