DomoAI

Universelle agentische Gebäudeautomatisierungs-Laufzeit mit einem semantischen Gerätemodell, Multi-Adapter-Komposition und einer allgemeinen MCP-Schnittstelle.

Entwicklungsumgebung

Dieses Projekt verwendet uv und Python 3.12.

uv sync
uv run pytest
uv run ruff check .
uv run mypy src

Die Laufzeitabhängigkeiten umfassen das MCP Python SDK, Pydantic, Home Assistant HTTP/WebSocket-Clients, aiomqtt für den optionalen Zigbee2MQTT-Adapter, JSON-Schema-Validierung und OR-Tools. Die lokale SQLite-Persistenz verwendet die Standardbibliothek von Python. Entwicklungswerkzeuge werden über die standardmäßige dev-Abhängigkeitsgruppe von uv installiert.

Um eine Abhängigkeit hinzuzufügen oder zu aktualisieren, bearbeiten Sie pyproject.toml und generieren Sie die Sperrdatei neu:

uv lock
uv sync

Lokaler MCP-Server

Der semantische MCP-Server kann über stdio gestartet werden. Ohne Home Assistant-Einstellungen verwendet er die deterministische Testumgebung:

uv run domoai-mcp

Beispielhafte Host-Konfiguration:

{
  "mcpServers": {
    "domoai": {
      "command": "uv",
      "args": ["run", "domoai-mcp"],
      "cwd": "/path/to/DomoAI"
    }
  }
}

Derselbe Befehl kann in Claude Code, Codex oder einem anderen kompatiblen MCP-Client registriert werden.

Einheitliche MCP-Oberfläche

Der einzelne domoai-mcp-Server stellt Discovery, Zustand, Energiekontext, richtlinienbewusste Planvalidierung/-ausführung und die nur für Vorschläge vorgesehenen OR-Tools validate_scenario, optimize_scenario und explain_solution über dieselbe MCP-Sitzung bereit. Registrieren Sie genau einen Server in Claude Code, Codex oder einem anderen kompatiblen MCP-Client, der lokales stdio unterstützt:

{
  "mcpServers": {
    "domoai": {
      "command": "uv",
      "args": ["run", "domoai-mcp"],
      "cwd": "/path/to/DomoAI"
    }
  }
}

OR-Tools bleibt eine interne Vorschlags-/Validierungs-/Erklärungsschicht. Es kann kein Gerät ausführen, keinen Plan genehmigen oder einen Adapter aufrufen, und es gibt keinen zweiten öffentlichen OR-Tools-MCP-Endpunkt.

Die portable Fähigkeit optimize-home-energy leitet jede DomoAI-Operation über eine einzige mcp-Rolle. Ihr Referenzworkflow wird lokal mit deterministischen prozessinternen Testumgebungen validiert:

uv run pytest -q tests/contract/test_skill_contract.py
uv run pytest -q tests/integration/test_energy_skill_workflow.py

Der Workflow verwendet dieselbe Verbindung für semantische Lesevorgänge, Vorschläge, Erklärungen und Planvalidierung und führt niemals außerhalb von execute_plan aus. Sensible Pläne pausieren für die explizite Zustimmung des Bedieners.

Für energiebewusste Szenarien liest die portable v2-Prozedur einen vollständigen typisierten Kontext über mcp.get_energy_context, bevor sie den nur für Vorschläge vorgesehenen Optimierer aufruft. Der Kontext richtet Tarife und Solarprognosen auf einen festen Horizont aus und kann ein Batterieprofil enthalten. CP-SAT gibt Kosten, Spitzenimport und Eigenverbrauchsnachweise sowie den Energie-Saldo pro Zeitslot zurück; es ruft niemals einen physischen Adapter auf. Kontextfehler, Revisionskonflikte, Unlösbarkeit oder Zeitüberschreitung des Lösers stoppen vor Validierung und Ausführung. Der deterministische Anbieter und die fokussierten Akzeptanzbefehle werden durch den Repository-Vertrag und Integrationstests abgedeckt.

Einmaliges Solarprofil für Live-Energiedaten

OMIE-Tarife und Open-Meteo-Vorhersagen werden automatisch gesammelt, sobald der Energiekontext angefordert wird. Nur die Metadaten der physischen Installation müssen einmalig bereitgestellt werden. Kopieren Sie das Beispiel, ersetzen Sie seine Platzhalterwerte durch die Wechselrichter- oder Installateur-Daten und weisen Sie die Laufzeit darauf hin:

cp config/solar-profile.example.json config/solar-profile.json
export DOMOAI_ENERGY_LIVE=1
export DOMOAI_TARIFF_PROVIDER=omie
export DOMOAI_SOLAR_PROVIDER=open_meteo
export DOMOAI_SOLAR_PROFILE_PATH=config/solar-profile.json
uv run domoai-mcp

Das Profil ist streng, versioniert und anmeldeinformationsfrei. Es muss echte Installationswerte enthalten, bevor das Ergebnis für die Optimierung verwendet wird; die Madrider Werte im Beispiel dokumentieren nur die Form. Die älteren einzelnen DOMOAI_SOLAR_*-Variablen bleiben als sich gegenseitig ausschließender Kompatibilitätsfallback verfügbar.

Universelles Provider-SDK

Zukünftige Home Assistant-, Wechselrichter- und MQTT-Integrationen müssen ihre quellspezifischen Identitäten und Nutzdaten in die Provider-SDK-v1-Grenze übersetzen, bevor sie die semantische Laufzeit erreichen. Das SDK verwendet DomoAIs kanonische DeviceType-, Capability- und SourceRef-Modelle wieder und trennt Provider in Telemetrie- und Befehlsrollen:

external provider
      ↓
ProviderManifest + DeviceDescriptor + Measurement
      ↓
ProviderRegistry (stable order, safe diagnostics)
      ↓
canonical runtime / StateStore / MCP / OR-Tools

Provider-Befehle tragen nur begrenzte semantische Parameter und einen Idempotenzschlüssel. Sie umgehen nicht PlanService, Richtlinienvalidierung oder AdapterPort. Die erste konkrete Implementierung ist HomeAssistantProvider. Sie verwendet den authentifizierten REST/WebSocket-Client wieder, gruppiert Entitäten nach Home Assistant device_id, wenn Registrierungsmetadaten verfügbar sind, und legt nur explizite Entitäts-/Fähigkeitsmetrikzuordnungen offen. Sie bleibt additiv zum klassischen HomeAssistantAdapter; die Laufzeitfabrik wählt sie nur aus, wenn DOMOAI_HOME_ASSISTANT_PROVIDER=1 explizit aktiviert ist. Dasselbe Provider-Objekt wird in ProviderRegistry registriert und vom bestehenden AdapterPort umschlossen, sodass DeviceRegistry, StateStore, Planausführung und MCP einen semantischen Pfad und einen Home Assistant-Client behalten. Siehe docs/adapter-sdk.md und docs/contracts.md für die öffentliche Grenze.

Live Home Assistant-Laufzeit

Para desarrollo local sin hardware, el laboratorio virtual reproducible está en dev/lab/README.md y su arranque mínimo cubre Mosquitto/fake Zigbee2MQTT y PyModbus. Home Assistant, Matter Server y KNX Virtual/ETS permanecen como perfiles manuales opt-in.

La ruta recomendada para operar ese laboratorio es el runner explícito:

uv run domoai-lab up
uv run domoai-lab status
uv run domoai-lab smoke

El smoke usa únicamente fixtures locales de Home Assistant, MQTT/Zigbee2MQTT, Modbus, Matter y KNX; no inventa gateways, tokens ni commissioning. Los smoke tests live siguen separados y requieren sus servicios y variables DOMOAI_* reales.

Die Kompositionswurzel wählt die deterministische Testumgebung aus, wenn keine Live-Quelle konfiguriert ist, einen direkten Adapter für eine Quelle oder eine zusammengesetzte Laufzeit für zwei oder mehr vollständige Quellkonfigurationen. Konfigurieren Sie Home Assistant mit:

export DOMOAI_HOME_ASSISTANT_URL="http://home-assistant.local:8123"
export DOMOAI_HOME_ASSISTANT_TOKEN="<long-lived-access-token>"
export DOMOAI_HOME_ASSISTANT_PROVIDER="1"
export DOMOAI_HOME_ASSISTANT_MAPPING_PATH="config/home-assistant-mappings.json"
export DOMOAI_DATABASE_PATH="data/domoai.sqlite3"
uv run domoai-mcp

Der Provider-Modus ist optional. Ohne ihn wird der klassische HomeAssistantAdapter aus Kompatibilitätsgründen ausgewählt. Wenn er aktiviert ist, sind das URL/Token-Paar erforderlich, und ein optionales strenges v1-Zuordnungsdokument kann Energierollen explizit machen:

{
  "schema_version": "v1",
  "metric_mappings": {
    "sensor.pv_power": {"power": "energy.pv.power"},
    "sensor.grid_power": {"power": "energy.grid.power"}
  }
}

Die Laufzeit authentifiziert REST-Serviceaufrufe, persistiert Pläne, Ergebnisse und geschwärzte Audit-Ereignisse in SQLite und führt den Adapter-Ereigniskonsumenten im Hintergrund aus. Unterstützte Schreibzuordnungen umfassen derzeit Licht-/Schalterleistungs- und Umschaltoperationen, Lichthelligkeit, Position/Öffnen/Schließen/Stopp von Abdeckungen und Klima-Zieltemperatur. Ein unvollständiges URL/Token-Paar wird vor dem Start abgelehnt. Token werden als geheime Konfiguration gelesen und niemals in Geräte-, Befehls-, Ergebnis- oder Audit-Nutzdaten aufgenommen.

Der Provider-SDK-Pfad kann unabhängig von der Laufzeitfabrik getestet werden:

provider = HomeAssistantProvider(
    HomeAssistantClient(base_url, token),
    metric_mappings={
        "sensor.pv_power": {"power": "energy.pv.power"},
        "sensor.battery_soc": {"battery": "battery.soc"},
    },
)

Nur zugeordnete Sensor-Fähigkeiten werden zu kanonischen Energiemetriken. Der Client liest auch das aktivierte Entitätsregister von Home Assistant über WebSocket, wenn Zustandsnutzdaten keine device_id enthalten; die Registrierungsidentität wird beibehalten, wenn sie bereitgestellt wird, und niemals aus Namen oder Bereichen abgeleitet.

Das Entfernen von DOMOAI_HOME_ASSISTANT_PROVIDER kehrt zum klassischen Adapter zurück, ohne die agentenseitige MCP-Oberfläche zu ändern. Der Provider-Pfad wird durch deterministische Testumgebungen abgedeckt. Der optionale Live-Provider-Laufzeit-Smoke validiert dieselbe Route gegen eine echte Home Assistant-Instanz, ohne Befehle auszuführen:

uv run pytest -q tests/integration/test_home_assistant_provider_smoke.py

Es erfordert ein echtes URL/Token-Paar und hält den Token außerhalb des Repositorys.

Live Zigbee2MQTT-Laufzeit

Der native Zigbee2MQTT-Adapter ist optional und unterstützt das begrenzte v1-Profil: Licht-/Schalterleistung, Lichthelligkeit, Temperatur, Luftfeuchtigkeit und Anwesenheit. Konfigurieren Sie ihn zusammen mit Home Assistant oder einer anderen Quelle:

export DOMOAI_ZIGBEE2MQTT_URL="mqtt://mqtt-broker.local:1883"
export DOMOAI_ZIGBEE2MQTT_BASE_TOPIC="zigbee2mqtt"
export DOMOAI_MQTT_TIMEOUT_SECONDS="5"
export DOMOAI_MQTT_USERNAME="domoai"
export DOMOAI_MQTT_PASSWORD="<mqtt-password>"
uv run domoai-mcp

Zigbee2MQTT kann zusammen mit Home Assistant oder einer anderen konfigurierten Quelle laufen. Der Adapter konsumiert Zigbee2MQTT-Bridge-/Gerätethemen und veröffentlicht nur zugeordnete Geräte-/set-Befehle über die bestehende Plan-, Richtlinien- und Ausführungsgrenze. Pairing, Entfernung, OTA, Gruppen, Bridge-Verwaltung und beliebiges MQTT-Publishing werden nicht bereitgestellt.

Live Matter Server-Laufzeit

Der native Matter-Adapter verwendet Matter Server als Controller-Grenze und verbindet sich mit seinem kompatiblen WebSocket-Endpunkt. Konfigurieren Sie ihn zusammen mit Home Assistant, Zigbee2MQTT oder einer anderen Quelle:

export DOMOAI_MATTER_SERVER_URL="ws://matter-server.local:5580/ws"
export DOMOAI_MATTER_TIMEOUT_SECONDS="5"
uv run domoai-mcp

Der Adapter validiert den Server-Schemabereich vor der Erkennung, bewahrt node:<node_id>/endpoint:<endpoint_id>-Quellreferenzen und legt nur das begrenzte v1-Licht-/Schalterleistungs- und Helligkeitsprofil plus schreibgeschützten Temperatur-, Luftfeuchtigkeits- und Anwesenheitszustand offen. Inbetriebnahme, Fabric-Management, OTA, Gruppen, Hersteller-Cluster und beliebige Attributoperationen bleiben außerhalb der agentenseitigen Grenze. Live Matter-Smoke-Tests sind optional; Fixture-Tests benötigen keinen Matter-Server oder keine Hardware.

Live KNX/IP-Laufzeit

Der native KNX-Adapter verwendet eine explizite Zuordnungsdatei anstatt Geräte aus beliebigem Gruppenverkehr abzuleiten. Sein begrenztes v1-Profil unterstützt Licht- und Schalterleistung, Lichthelligkeit sowie schreibgeschützte Temperatur, Luftfeuchtigkeit und Anwesenheit. Konfigurieren Sie ihn zusammen mit den anderen physischen Quellen:

export DOMOAI_KNX_GATEWAY_HOST="knx-gateway.local"
export DOMOAI_KNX_CONFIG_PATH="config/knx.json"
export DOMOAI_KNX_TIMEOUT_SECONDS="5"
uv run domoai-mcp

Die Zuordnungsdatei deklariert jede Entität, semantische Fähigkeit, Zustandsgruppenadresse, Befehlsgruppenadresse und DPT. Unbekannte Felder, fehlerhafte Adressen, nicht unterstützte DPTs und beschreibbare Sensorzuordnungen werden beim Start abgelehnt. KNX/IP-Tunneling ist optional und kann mit den anderen konfigurierten Adaptern koexistieren; Fixture-Tests verwenden einen speicherinternen Transport und benötigen kein Gateway oder keine Hardware. ETS-Import, Inbetriebnahme, Routing, sichere Anmeldeinformationen, beliebige Gruppenwertoperationen, Szenen und zusätzliche xknx-Geräteprofile sind in v1 nicht enthalten.

Live Modbus TCP-Laufzeit

Der native Modbus-Adapter verwendet eine explizite v1-Zuordnung von Einheiten-IDs, Registerbereichen, nullbasierten PDU-Offsets und skalaren Kodierungen. Er unterstützt Licht-/Schalterleistung, Lichthelligkeit sowie schreibgeschützte Temperatur, Luftfeuchtigkeit und Anwesenheit. Konfigurieren Sie ihn zusammen mit den anderen physischen Quellen:

export DOMOAI_MODBUS_HOST="modbus-controller.local"
export DOMOAI_MODBUS_PORT="502"
export DOMOAI_MODBUS_CONFIG_PATH="config/modbus.json"
export DOMOAI_MODBUS_TIMEOUT_SECONDS="5"
export DOMOAI_MODBUS_POLL_INTERVAL_SECONDS="5"
uv run domoai-mcp

Die Zuordnung ist streng und scannt oder leitet keine Geräte ab. Unbekannte Felder, mehrdeutige 40001-artige Adressen, nicht unterstützte Kodierungen, beschreibbare Sensoren und unsichere Befehle werden abgelehnt. Modbus TCP ist optional und kann mit Home Assistant, Zigbee2MQTT, Matter Server und KNX koexistieren. RTU/ASCII, TLS, Scannen, Hersteller-Funktionscodes und beliebige Register-Lese-/Schreibvorgänge sind außerhalb von v1. Fixture-Tests verwenden einen speicherinternen Transport und benötigen keinen Controller oder keine Hardware.

Multi-Adapter-Identität und Routing

Die Laufzeit folgt der Home Assistant-Gerät-/Entitätsunterscheidung: Ein physisches Quellgerät kann mehrere Quellentitäten bereitstellen, während DomoAI ein kanonisches Gerät mit fähigkeitsbasierten Routen präsentiert. Stabile Quellkennungen und Verbindungen bewahren die Identität über Namens- oder Bereichsänderungen hinweg; eine explizite canonical_id ist erforderlich, um Beiträge verschiedener Adapter zu verknüpfen. Befehle werden vor der Ausführung zu einer genauen Quellentität aufgelöst. Mehrdeutige, unbekannte oder nicht verfügbare Routen schlagen geschlossen fehl, sodass die Laufzeit niemals stillschweigend einen Befehl an ein anderes Protokoll oder eine andere Entität sendet.

Für dieses Verhalten ist kein Live-Gateway, -Broker oder -Controller erforderlich. Die deterministische Multi-Adapter-Testumgebung deckt Komposition, teilweisen Ausfall, Topologie, exaktes Routing und Null-Schreib-Sicherheit ab:

uv run pytest -q tests/contract/test_multi_adapter_runtime.py \
  tests/integration/test_multi_adapter_runtime.py \
  tests/performance/test_multi_adapter_targets.py

Verifizierte lokale Validierung

Am 2026-08-17 bestand das Repository die Unit-, Adapter-, Discovery-, Plan-, MCP-Vertrags-, Optimierungs-, Leistungs-, Home Assistant-Ausführungs-, KNX- und Modbus-Fixture-, Laufzeitkompositions-, OMIE- und Open-Meteo-Provider-Szenarien, die von der Repository-Testsuite abgedeckt werden. Der Home Assistant-Klassik-Adapter-Smoke bestand gegen das lokale Docker-Labor; die lokalen Zigbee2MQTT- und Modbus-Smokes bestanden; und die schreibgeschützten OMIE- und Open-Meteo-öffentlichen Netzwerk-Smokes bestanden mit optionaler Konfiguration. Matter-Discovery und KNX/IP bleiben optional, da sie einen in Betrieb genommenen Matter-Knoten oder ein erreichbares KNX-Gateway und eine Zuordnung erfordern.

Der lokale Startbefehl lautet:

uv run domoai-mcp

Die Qualitätstore sind:

uv run pytest -q
uv run ruff check .
uv run mypy src
uv lock --check

Das neueste vollständige Testergebnis ohne Live-Anmeldeinformationen ist 318 bestanden, 8 übersprungen, ohne Warnungen. Die Überspringungen sind optionale Matter Server-, KNX/IP- und andere Live-Fälle ohne ihren externen Knoten, ihr Gateway oder ihre Servicekonfiguration; die deterministische Fixture-Abdeckung bleibt aktiviert. Die separaten Live-Ergebnisse sind: Zigbee2MQTT/Modbus 2 bestanden, OMIE/Open-Meteo 2 bestanden, Home Assistant-Klassik-Adapter 1 bestanden und die Home Assistant-Provider-Laufzeitbrücke 1 bestanden. Der FastMCP-Kompatibilitätsnaht hält die bekannte pydantic_settings-Warnung über unvollständige Felder aus den MCP-Verträgen heraus, ohne Warnungen global zu unterdrücken.

Leitfäden für Adapter und öffentliche Verträge befinden sich in docs/adapter-sdk.md und docs/contracts.md.