node-red-contrib-knx-ultimate 6.3.25 → 6.3.26

package/CHANGELOG.md

@@ -6,6 +6,14 @@
 
 # CHANGELOG
 
+**Version 6.3.26** - August 2026<br/>
+
+- **KNX AI — opt-in Web Intelligence with verified sources**: added a provider-independent general Web tool that the conversational model selects semantically from the current request, without topic-specific logic, keywords or intent classifiers. Web access is off by default; proactive Web checks require a separate opt-in, explicit user-authored AI Education, a destination learned from at least one normal chat request and a configurable 5, 10, 15, 30, 60 or 180-minute minimum interval. Setup Doctor reports Web/proactive readiness, missing Education or recipient and the live hourly budget. Interactive and proactive requests share a rolling hourly call budget, with at most three Web operations in total per user turn or proactive cycle. Web-backed answers carry runtime-validated numbered citations (`[S1]`, …) with sanitized URLs and available publication/retrieval times; external content remains untrusted data and cannot override assistant rules or permissions. Only bounded public HTTPS resources are accepted, with private/local/link-local/cloud-metadata targets, unsafe redirects, authenticated browsing and cookies blocked. Queries and the server's public IP are disclosed to external sites or the search service, while KNX/ETS data, camera content, chat identifiers, learned memory and credentials are never added automatically. Once verified Web results are available, the model can compose other enabled tools when authorized by the current chat or AI Education; existing tool availability, KNX permissions, ETS/DPT validation and configured write confirmation remain unchanged. Editor help and wiki documentation were aligned in EN, IT, DE, FR, ES and zh-CN.<br/>
+- **KNX AI — clearer chat wiring terminology**: renamed the editor labels for chat input/output pins, message adapters and automatically detected compatible nodes in all six shipped languages, including the related empty/loading/error states and localized help/wiki references.<br/>
+- **KNX AI — automatic Setup Doctor and personalized safe first run**: added an editor and Web UI preflight that checks the selected gateway and ETS import, AI/provider/model/API-key setup, provider reachability, chat and KNX-operation wiring, detected cameras and optional TTS Ultimate wiring. The provider check calls only its model-list endpoint, never sends a chat request and consumes no inference tokens; unused camera and TTS integrations do not reduce core readiness. Inventory wording now distinguishes the exact number of unique KNX group-address signals from estimated logical functions and deliberately avoids an unreliable physical-device count. Sending `/start` or `/help` produces a deterministic localized welcome on output 3 with installation-specific statistics and up to three safe suggestions, without calling the LLM, reading or writing KNX, or generating TTS; the Telegram preset renders those suggestions as an explicit reply keyboard. After explicit selection, a starter suggestion may perform exact KNX reads when needed, while KNX writes and routines, camera actions, TTS, persistent-memory changes and GA-role learning are suppressed. Help, wiki and the direct Telegram example were updated in EN, IT, DE, FR, ES and zh-CN.<br/>
+- **KNX AI — explicit TTS Ultimate flow output**: replaced the internal **TTS Ultimate node for announcements** selector and direct node injection with a dedicated fifth output labelled **TTS Ultimate**. Each model-selected announcement now leaves the node through normal Node-RED wiring with the exact spoken text in `msg.payload`, `msg.topic = "knx_ai_announcement"` and `msg.knxAi` metadata for type, source node, session and reason; normal fan-out or Link Out/Link In can route it to one or more `ttsultimate` nodes. Output positions 1–4 remain unchanged. Existing flows that relied on the saved `ttsUltimateNodeId` selection must physically connect output 5 after upgrading; the old selection is no longer used. Help, wiki pages and importable KNX AI examples were updated in EN, IT, DE, FR, ES and zh-CN.<br/>
+- **KNX AI — two-way Telegram voice chat**: the `windkh/node-red-contrib-telegrambot` preset now accepts native OGG/Opus voice messages, downloads them through the receiver-provided Telegram link with same-origin, timeout, 20 MB and five-minute safeguards, redacts the token-bearing URL, and transcribes them through OpenAI-compatible `/audio/transcriptions`. Successful voice requests receive native Telegram OGG/Opus replies synthesized by `/audio/speech`, including a localized AI-generated-voice disclosure, the text caption and confirmation keyboard; failed or oversized synthesis falls back to the complete text answer. Voice processing is intentionally plug-and-play only with the selected **OpenAI-compatible** chat provider: it reuses that provider's endpoint and API key with built-in `gpt-4o-mini-transcribe`, `gpt-4o-mini-tts` and `alloy` defaults. The separate Telegram voice-service section, credential and model fields were removed. Anthropic, Ollama and Bionic LM Studio remain available for text chat; a voice request with one of them returns a localized provider-selection instruction before audio download. Existing saved preset mappings are upgraded at runtime, the direct Telegram example now ships with the preset selected, and help/wiki documentation covers provider and privacy requirements in EN, IT, DE, FR, ES and zh-CN.<br/>
+
 **Version 6.3.25** - August 2026<br/>
 
 - **IoT Bridge — direct Modbus Flex adapter without a bundled Modbus client**: Modbus mappings can now emit the exact `modbus-flex-write` request consumed by `node-red-contrib-modbus` and decode `modbus-read` / `modbus-flex-getter` responses back to KNX. The protocol-specific editor asks only for Unit ID, zero-based address, Modbus area and Boolean/unsigned 16-bit/signed 16-bit format; FC1–FC6 and quantity are derived automatically. TCP/RTU connections, polling, queues and reconnects remain in the external Modbus nodes. KNX responses never become Modbus commands, write acknowledgements never become KNX state, unchanged polls can be suppressed with **Emit on change only**, and local KNX echoes are loop-protected. Existing scalar Modbus mappings remain on the legacy contract until explicitly switched to Flex. A safe manual example and the six localized help/wiki sets document the wiring and host-version compatibility.<br/>
@@ -22,7 +30,7 @@
 - **KNX AI — user-selectable local chat context**: added a localized **Chat context amount** selector for Ollama and Bionic LM Studio with 4K, 8K and 16K choices; 16K remains the default. The selected budget proportionally bounds KNX traffic, archives, ETS catalog, Node-RED inventory, memory and adapter context, and is also sent as Ollama's `num_ctx`, while the complete agent tool contract stays available without phrase classifiers, keyword gates or linguistic intent routing. The context overview now reports the configured operational limit. Editor help and wiki documentation were updated in EN, IT, DE, FR, ES and zh-CN.<br/>
 - **KNX AI — reliable conversational recall**: verified that session IDs and recent turns were already persisted correctly, then moved the current session memory next to the current request in the operational prompt so small local models do not lose user-supplied facts inside large KNX context. The structured memory tool now explicitly covers durable user facts such as preferred name and language as well as preferences and instructions, while remaining model-selected with no phrase classifiers or intent routing; credentials, security codes and API keys are excluded.<br/>
 - **KNX AI — editable and portable CHAT learning**: added **Settings → AI Chat Learning** to the Vue web UI for viewing the exact absolute path and editing, copying, downloading or restoring the shared learning file. The **Conversations & home** tab in the Node-RED node configuration includes a localized shortcut that opens the Web UI directly on this editor for the current node. Saves are validated, bounded to 512 KB, written atomically and applied immediately to every KNX AI node sharing the same storage, while revision checks prevent stale editors from overwriting newer learning. UI strings, editor help and wiki documentation were updated in EN, IT, DE, FR, ES and zh-CN.<br/>
-- **KNX AI — intent-free agentic chat tools**: removed hard-coded semantic phrase classifiers from conversational routing. Every Ask/CHAT request now lets the model reason directly over the current goal, persistent user guidance, AI Education and the available structured KNX, camera, TTS Ultimate and memory tools. Routine planning no longer depends on a multilingual keyword list, TTS announcements no longer require an action alias, and durable chat instructions are remembered or forgotten through model-selected structured actions instead of regular-expression intent detection. Runtime argument validation, adapter availability checks, ETS/DPT safeguards and command confirmation remain unchanged.<br/>
+- **KNX AI — intent-free agentic chat tools**: removed hard-coded semantic phrase classifiers from conversational routing. Every Ask/CHAT request now lets the model reason directly over the current goal, persistent user guidance, AI Education and the available structured KNX, camera, TTS Ultimate and memory tools. Routine planning no longer depends on a multilingual keyword list, TTS announcements no longer require an action alias, and durable chat instructions are remembered or forgotten through model-selected structured actions instead of regular-expression intent detection. Runtime argument validation, camera-adapter availability checks, ETS/DPT safeguards and command confirmation remain unchanged.<br/>
 - **KNX AI — learned KNX group-address roles**: a `neutral` GA is now treated as unresolved rather than permanently uncontrollable. The conversational model can learn or forget the exact `command`, `status` or `neutral` role from trusted user teaching, persistent chat guidance, AI Education or unequivocal ETS semantics through the structured `gaRoleActions` tool. Learned role, reason and evidence are persisted per node in `knxai-config-<node-id>.json`, synchronized into bounded semantic home memory and reused after restart. A command role learned in the current answer can validate a write in that same turn, while exact ETS membership, immutable DPT, payload validation and configured confirmation still apply. Help and wiki documentation were aligned in EN, IT, DE, FR, ES and zh-CN.<br/>
 
 **Version 6.3.22** - August 2026<br/>

package/examples/KNX AI - Conversational Control with Confirmation.json

@@ -262,6 +262,8 @@
       [
         "dbg_knx_ai_control_command",
         "node_knx_ai_control_universal"
+      ],
+      [
       ]
     ]
   },
@@ -371,8 +373,8 @@
     "id": "cmt_knx_ai_control_output",
     "type": "comment",
     "z": "tab_knx_ai_control",
-    "name": "Replace Debug 3 with your Telegram sender node",
-    "info": "The third output carries the text in msg.payload. Fresh reads are returned after KNX feedback and detailed in msg.knxAi.readResults. When a write confirmation is pending, msg.knxAi.confirmationRequest contains localized button labels, callbackData values and ready-to-send confirm/cancel messages. Every message on outputs 3 and 4 also preserves the triggering input in msg.inputMessage.",
+    "name": "Replace Debug 3 with Telegram; optionally wire output 5 to TTS Ultimate",
+    "info": "The third output carries the text in msg.payload. Fresh reads are returned after KNX feedback and detailed in msg.knxAi.readResults. When a write confirmation is pending, msg.knxAi.confirmationRequest contains localized button labels, callbackData values and ready-to-send confirm/cancel messages. Every message on outputs 3 and 4 also preserves the triggering input in msg.inputMessage. Output 5 is deliberately unwired in this example: connect it to one or more ttsultimate nodes (or use Link Out/Link In across tabs) to receive model-selected announcements with msg.topic=knx_ai_announcement.",
     "x": 850,
     "y": 100,
     "wires": []

package/examples/KNX AI - Summary Anomalies and Ask.json

@@ -158,6 +158,10 @@
       ],
       [
         "dbg_knx_ai_answer"
+      ],
+      [
+      ],
+      [
       ]
     ]
   },

package/examples/KNX AI - Telegrambot Direct Chat.json

@@ -4,14 +4,14 @@
     "type": "tab",
     "label": "KNX AI - Telegrambot direct chat",
     "disabled": false,
-    "info": "Direct chat wiring for windkh/node-red-contrib-telegrambot using the KNX AI chat-adapter preset. Confirmation buttons return through the same receiver; no callback event node is required."
+    "info": "Direct text and voice chat wiring for windkh/node-red-contrib-telegrambot using the KNX AI chat-adapter preset. After deploying, review the automatic Setup Doctor and send /start to the bot for a deterministic, localized introduction with personalized safe suggestions. A voice request is transcribed and receives an Opus voice reply; confirmation buttons return through the same receiver, so no callback event node is required. Voice processing requires the selected OpenAI-compatible chat provider and reuses its endpoint and API key."
   },
   {
     "id": "comment_knx_ai_telegram_setup",
     "type": "comment",
     "z": "tab_knx_ai_telegram",
-    "name": "1. Open KNX AI → Chat adapters → select windkh/node-red-contrib-telegrambot",
-    "info": "Selecting the preset inserts the editable input and output mappings. Then configure the KNX gateway, import the ETS CSV, set the LLM credentials and configure the Telegram bot token.",
+    "name": "1. Configure, check Setup Doctor, then send /start",
+    "info": "The windkh/node-red-contrib-telegrambot preset is already selected. Configure the KNX gateway, import the ETS CSV, select the OpenAI-compatible chat provider with an endpoint that supports /audio/transcriptions and /audio/speech, enter its API key when required, and configure the Telegram bot token. Deploy, review the automatic Setup Doctor, then send /start or /help to receive the safe personalized welcome and Telegram suggestion keyboard; this onboarding does not call the LLM, read or write KNX, or generate TTS. Text requests receive text; voice requests receive voice, with text fallback if speech synthesis fails. Anthropic, Ollama and Bionic LM Studio remain available for text chat but do not process Telegram voice. Output 5 is left unwired: connect it to one or more ttsultimate nodes, or use Link Out/Link In across flow tabs, for model-selected home announcements.",
     "x": 500,
     "y": 40,
     "wires": []
@@ -40,7 +40,7 @@
     "id": "telegram_receiver_knx_ai",
     "type": "telegram receiver",
     "z": "tab_knx_ai_telegram",
-    "name": "Telegram text",
+    "name": "Telegram text + voice",
     "bot": "telegram_bot_knx_ai",
     "saveDataDir": "",
     "filterCommands": false,
@@ -69,7 +69,7 @@
     "llmIncludeDocsSnippets": true,
     "llmAllowKnxCommands": true,
     "llmRequireCommandConfirmation": true,
-    "chatAdapterPreset": "none",
+    "chatAdapterPreset": "windkh-telegrambot",
     "chatInputCode": "",
     "chatOutputCode": "",
     "aiEducation": "Avvisa la mia ultima chat se una persiana, una finestra o una porta rimane aperta per almeno 120 minuti. Non inviare notifiche tra le 23:00 e le 07:00 e non ripetere lo stesso avviso prima di 6 ore.",
@@ -84,6 +84,8 @@
       ],
       [
         "node_knx_ai_telegram_universal"
+      ],
+      [
       ]
     ]
   },