HomeIntent
Lokale, deterministische Sprachsteuerung für Home Assistant Assist – ohne LLM oder ML-Modell zur Laufzeit.
- Aktuelle Quellstand-Version: 7.13.2
- Sprache: Deutsch
- Mindestversion: Home Assistant 2026.4.0
- Installation: HACS Custom Repository
- Verarbeitung: lokal in Home Assistant
- Lizenz: MIT
Was ist HomeIntent?
HomeIntent ist ein deutschsprachiger Conversation Agent für Home Assistant
Assist. Er analysiert Befehle, Fragen und Automationswünsche lokal, löst Ziele
gegen die echte Home-Assistant-Konfiguration auf und führt Änderungen erst
nach Capability-, Berechtigungs-, Risiko- und Bestätigungsprüfung aus.
HomeIntent ist bewusst kein allgemeiner Chatbot. Gleicher Hauszustand und
gleicher Dialogkontext führen zum gleichen Ergebnis. Bei Mehrdeutigkeit oder
unvollständiger Bedeutung fragt HomeIntent nach oder führt nichts aus.
Voraussetzungen
- Home Assistant 2026.4.0 oder neuer
- HACS für die empfohlene Installation
- für Spracheingabe eine eingerichtete Assist-Pipeline
- sinnvoll benannte und für Assist freigegebene Entitäten
GPU, Cloud-API, Modell-Download und externer HomeIntent-Server sind nicht
erforderlich.
Installation und Update
- In HACS → Integrationen → Benutzerdefinierte Repositories öffnen.
https://github.com/pquandel2-alt/homeintent als Typ Integration hinzufügen.- HomeIntent installieren und Home Assistant neu starten.
- Unter Einstellungen → Geräte & Dienste → Integration hinzufügen
HomeIntent hinzufügen.
- In der gewünschten Assist-Pipeline HomeIntent als Conversation Agent wählen.
Bei Updates über HACS anschließend Home Assistant neu starten. Hinweise für
alte Installationen mit der Domain ha_nlu stehen in der
Migrationsanleitung.
Schnellstart
- Benötigte Geräte, Sensoren, Kalender, Listen und Timer für Assist freigeben.
- Bereiche, Etagen, Geräteklassen und Friendly Names in Home Assistant prüfen.
- Unter HomeIntent → Konfigurieren Auswahl und Sicherheitsoptionen setzen.
- Mit einer lesenden Frage beginnen, danach einen eindeutigen Befehl testen.
Beispiele:
Wie warm ist es im Wohnzimmer?
Schalte die Stehlampe ein.
Mach alle Lichter im Erdgeschoss aus, außer die Küchenlampe.
Erinnere mich in 20 Minuten an den Backofen.
Wenn das Garagentor länger als eine Minute offen ist, melde dich.
Schreibende Automationen und risikoreiche Änderungen werden vor der Ausführung
als Vorschau bestätigt. Eine Rückfrage ist ein Sicherheitsmerkmal, kein Fehler.
Zentrale Konfiguration
Die Optionen befinden sich unter Einstellungen → Geräte & Dienste →
HomeIntent → Konfigurieren. Dort werden insbesondere festgelegt:
- ausgewählte beziehungsweise von Assist freigegebene Entitäten,
- Benutzer-, Haushalts- und Administratorgrenzen,
- Bestätigungs- und Ausführungsrichtlinien,
- proaktive Kategorien, Kanäle und Aufmerksamkeitsbudgets,
- Langläufer-Schwelle (
0 deaktiviert die Kategorie vollständig),
- Benachrichtigungsziele sowie optionale lokale Adapter.
Die vollständige Optionsreferenz steht in der
Agent-Konfiguration. Das Learning Center in der
Seitenleiste zeigt Wissen, Modelle, Berechtigungen und Autonomie transparent an.
Sicherheitsmodell
- Entity Resolution und Grounding erfolgen ausschließlich gegen reale,
freigegebene Home-Assistant-Entitäten.
- Mehrdeutige oder unvollständige Bedeutungen werden nicht geraten.
ExecutionPolicy, Benutzerrechte, Bestätigungen und NEVER_AUTO gelten für
jeden Schreibpfad.- Nur
ServiceExecutor und AutomationExecutor bilden Schreibgrenzen.
- Proaktive Vorschläge vergeben keine Rechte und umgehen keine Bestätigung.
- Technische Provider-, Pfad- und Geheimnisdetails werden nicht in
Assist-Antworten oder dauerhafte Fehlerzustände übernommen; sekundäre
Fehlerlogs werden nach Möglichkeit ebenfalls redigiert und rate-limitiert.
Details: Sicherheit und Datenschutz.
Datenschutz
Sprachverständnis und Entscheidungslogik laufen lokal. HomeIntent benötigt
keine HomeIntent-Cloud und speichert keine Prompts bei einem Modellanbieter,
weil zur Laufzeit kein LLM/ML-Modell beteiligt ist. Externe Wirkung entsteht
nur durch vom Benutzer konfigurierte Home-Assistant-Dienste, etwa Kalender-
oder Push-Integrationen; deren eigene Datenschutzregeln gelten weiterhin.
Die optionale Music-Assistant-Unterstützung nutzt
ausschließlich registrierte Home-Assistant-Aktionen. Direkte Medien-URLs
öffnet HomeIntent nicht.
Bekannte Grenzen
- Die produktive NLU ist deutsch und kein universeller Freitext-Chatbot.
- Nicht belegte Raumbeziehungen, Gerätefähigkeiten oder Entity-Zuordnungen
werden nicht erfunden.
- Kalender- und Automationssprache deckt dokumentierte Strukturen ab, nicht
jede denkbare natürliche Formulierung.
- Der neue Slotdialog deckt unvollständige zeitliche, solare und die
dokumentierten Ereignisformen ab. Weitere wiederkehrende und komplex
verschachtelte Fragmente laufen noch über die bestehenden
Compatibility-Dialoge oder werden sicher abgelehnt.
- Offene Slotentwürfe sind absichtlich flüchtig und werden nach Neustart nicht
wieder aufgenommen.
- Music Assistant ist automatisiert gegen echten Home-Assistant-Komponentencode
und mit Service-Fakes geprüft; ein echter MA-Server samt Audiowiedergabe ist
nur durch die dokumentierte manuelle Matrix abgedeckt.
- Proaktive Raumansprache benötigt aktuelle Präsenzdaten und eine eindeutige
Satellitenzuordnung; andernfalls wird konservativ ausgewichen oder nichts
ausgeführt.
- Unter extremer Event-Überlast bleibt die Queue begrenzt. Drops und
Degradationszustände werden gemessen; Sicherheitsregeln werden nicht gelockert.
Weitere Grenzen und ausführliche Funktionsbeispiele stehen im
Handbuch.
Fehlerdiagnose
- Home-Assistant-Protokoll nach
homeintent filtern.
- Prüfen, ob die betroffene Entity für Assist freigegeben und eindeutig benannt ist.
- Bereiche, Geräteklassen, Benutzerbindung und HomeIntent-Optionen kontrollieren.
- Nach einem Update Home Assistant neu starten und die Integration bei Bedarf
einmal neu laden.
- Bei einem Fehler Version, Eingabe, erwartetes Ergebnis und relevante
anonymisierte Logzeilen angeben; Tokens und private Pfade nicht veröffentlichen.
Ausführlich: Troubleshooting.
Der Quellstand trägt Version 7.13.2. Die zugehörige versionierte
Korpusbaseline ist
corpus-signatures-7.13.2.json.
Tag und GitHub-Release folgen erst, nachdem CI und Nightly für exakt denselben
finalen Commit vollständig grün sind.
Version 7.13.2
7.13.2 schließt die in der unabhängigen Nachprüfung von 7.13.1 verbliebenen
Lücken:
- Klauselspezifische Bindung: Operation, Ziel, Ort, Quelle/Wert, belegte
Tokens und Rest werden für jede schreibende Klausel getrennt gebunden. Ein
unverständlicher Teil verwirft den ganzen Satz vor Vorschau und Service Call;
Operationen und Zielmengen dürfen nicht zwischen Räumen wandern.
- Zusammengesetzte Quellenbefehle: Die gemeinsame Mehrbefehls-Pipeline
materialisiert Quellenwahl noch nicht sicher. Deshalb werden bekannte,
unbekannte und mehrdeutige Quellen in einem zusammengesetzten Satz als
Ganzes abgelehnt (sichere Variante B). Einzelne, exakt aufgelöste
Quellenbefehle bleiben unterstützt.
- Finalisierte Sammelergebnisse: Licht- und Rollladen-Sammelaktionen
beobachten alle angenommenen Ziele gemeinsam in einem begrenzten,
ereignisbasierten Zeitfenster. Antwort, Audit (pro Ziel) und Undo entstehen
erst danach aus demselben unveränderlichen Ergebnis.
- Cover-Risiko vollständig:
shutter, blind, shade und curtain
bleiben MEDIUM und können pro Ziel laufen. Physische Zugänge
(garage, gate, door, window) sowie sonstige oder unbekannte
bewegliche Cover sind atomar und mindestens bestätigungspflichtig;
Garage/Tor bleiben CRITICAL.
- Performance ohne globalen Turn-Cache: Das vorhandene
LanguageDocument und seine Klauselgrenzen werden wiederverwendet. Der
begrenzte Registry-Namenscache hält nur IDs/normalisierte Namen, keine
Entity-Snapshots oder Conversation-Zustände. Ein relatives CI-Gate schützt
koordinierte Writes zusätzlich zum absoluten p95-Budget.
- Strengeres Release-Gate: Ein Release verlangt für den exakten Commit
sowohl die grüne CI als auch den grünen Nightly-Sicherheitslauf.
Details, Root Causes, Testergebnisse und eine manuelle Testmatrix für echte
Hardware stehen in den Release Notes und im
Umsetzungsbericht.
Für Version 7.13.2 gilt: Die verpflichtenden GitHub-Prüfungen
(ci.yml und nightly-live.yml) müssen für den exakten Release-Commit
erfolgreich abgeschlossen sein, bevor Tag und GitHub-Release erstellt werden;
die geprüften Lauf-Links stehen im GitHub-Release.
Die vollständigen Prüfergebnisse und historischen Details stehen ausschließlich
in den Release Notes, im
Versionsarchiv und bei
GitHub Releases.
Weiterführende Dokumentation
Entwicklung
python -m pip install --requirement requirements-dev.txt
python -m pytest -q -W error::RuntimeWarning \\
-W error::pytest.PytestUnraisableExceptionWarning
python -m pyflakes custom_components tests tests_ha scripts
python -m pyright
Echte-HA-Tests verwenden die getrennten Abhängigkeiten aus
requirements-ha-test.txt. CI, Benchmarks, Live-Testbett und Nightly-Gates
sind in der Qualitätscheckliste beschrieben.
Beiträge sollen deterministisch bleiben, Mehrdeutigkeit nie erraten, Bedeutung
und Ausführung trennen und jedes neue Verhalten durch positive, negative und
metamorphische Tests absichern.
