DomoAI

Runtime domótico agéntico universal con un modelo semántico de dispositivos, composición multiadaptador y una interfaz MCP general.

Entorno de desarrollo

Este proyecto utiliza uv y Python 3.12.

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

Las dependencias de ejecución incluyen el SDK MCP de Python, Pydantic, clientes HTTP/WebSocket de Home Assistant, aiomqtt para el adaptador opcional Zigbee2MQTT, validación de esquemas JSON y OR-Tools. La persistencia local SQLite utiliza la biblioteca estándar de Python. Las herramientas de desarrollo se instalan a través del grupo de dependencias dev por defecto de uv.

Para añadir o actualizar una dependencia, edite pyproject.toml y regenere el archivo de bloqueo:

uv lock
uv sync

Servidor MCP local

El servidor MCP semántico puede lanzarse a través de stdio. Sin configuración de Home Assistant utiliza el fixture determinista:

uv run domoai-mcp

Ejemplo de configuración del host:

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

El mismo comando puede registrarse en Claude Code, Codex u otro cliente MCP compatible.

Superficie MCP unificada

El único servidor domoai-mcp expone descubrimiento, estado, contexto energético, validación/ejecución de planes con conciencia de políticas y las herramientas OR-Tools solo de propuesta validate_scenario, optimize_scenario y explain_solution a través de la misma sesión MCP. Registre exactamente un servidor en Claude Code, Codex o cualquier otro cliente MCP compatible que admita stdio local:

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

OR-Tools sigue siendo una capa interna de propuesta/validación/explicación. No puede ejecutar un dispositivo, aprobar un plan ni llamar a un adaptador, y no existe un segundo punto final MCP público de OR-Tools.

La habilidad portátil optimize-home-energy enruta cada operación de DomoAI a través de un único rol mcp. Su flujo de trabajo de referencia se valida localmente con fixtures deterministas en proceso:

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

El flujo de trabajo utiliza la misma conexión para lecturas semánticas, propuestas, explicaciones y validación de planes, y nunca ejecuta fuera de execute_plan. Los planes sensibles se pausan para aprobación explícita del operador.

Para escenarios con conciencia energética, el procedimiento portátil v2 lee un contexto tipado completo a través de mcp.get_energy_context antes de llamar al optimizador solo de propuesta. El contexto alinea tarifas y pronósticos solares a un horizonte fijo y puede incluir un perfil de batería. CP-SAT devuelve evidencia de coste, pico de importación y autoconsumo solar, más el balance energético por intervalo; nunca llama a un adaptador físico. El fallo de contexto, la discrepancia de revisión, la inviabilidad o el tiempo de espera del solucionador se detienen antes de la validación y ejecución. El proveedor determinista y los comandos de aceptación enfocados están cubiertos por el contrato del repositorio y las pruebas de integración.

Perfil solar único para datos energéticos en vivo

Las tarifas OMIE y los pronósticos de Open-Meteo se recopilan automáticamente cada vez que se solicita el contexto energético. Solo es necesario proporcionar los metadatos de la instalación física una vez. Copie el ejemplo, reemplace sus valores de marcador de posición con los datos del inversor o instalador, y apunte el runtime hacia él:

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

El perfil es estricto, versionado y sin credenciales. Debe contener valores reales de instalación antes de usar el resultado para optimización; los valores de Madrid del ejemplo solo documentan la forma. Las variables individuales anteriores DOMOAI_SOLAR_* siguen disponibles como respaldo de compatibilidad mutuamente excluyente.

SDK de Proveedor Universal

Las futuras integraciones de Home Assistant, inversor y MQTT deben traducir sus identidades y cargas útiles específicas de la fuente al límite del SDK de Proveedor v1 antes de llegar al runtime semántico. El SDK reutiliza los modelos canónicos DeviceType, Capability y SourceRef de DomoAI y separa los proveedores en roles de telemetría y comando:

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

Los comandos del proveedor llevan solo parámetros semánticos acotados y una clave de idempotencia. No omiten PlanService, la validación de políticas ni AdapterPort. La primera implementación concreta es HomeAssistantProvider. Reutiliza el cliente REST/WebSocket autenticado, agrupa entidades por device_id de Home Assistant cuando los metadatos del registro están disponibles, y expone solo mapeos explícitos de entidad/capacidad métrica. Sigue siendo aditivo al clásico HomeAssistantAdapter; la fábrica del runtime lo selecciona solo cuando DOMOAI_HOME_ASSISTANT_PROVIDER=1 está explícitamente habilitado. El mismo objeto proveedor se registra en ProviderRegistry y es envuelto por el AdapterPort existente, por lo que DeviceRegistry, StateStore, la ejecución de planes y MCP mantienen una ruta semántica y un cliente de Home Assistant. Consulte docs/adapter-sdk.md y docs/contracts.md para el límite público.

Runtime en vivo de Home Assistant

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.

La raíz de composición selecciona el fixture determinista cuando no hay fuente en vivo configurada, un adaptador directo para una fuente, o un runtime compuesto para dos o más configuraciones de fuente completas. Configure Home Assistant con:

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

El modo proveedor es opt-in. Sin él, se selecciona el clásico HomeAssistantAdapter por compatibilidad. Si está habilitado, se requiere el par URL/token y un documento de mapeo estricto v1 opcional puede hacer explícitos los roles energéticos:

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

El runtime autentica las llamadas al servicio REST, persiste planes, resultados y eventos de auditoría censurados en SQLite, y ejecuta el consumidor de eventos del adaptador en segundo plano. Los mapeos de escritura admitidos actualmente incluyen operaciones de encendido/apagado de luz/interruptor, brillo de luz, posición/apertura/cierre/parada de persiana y temperatura objetivo de climatización. Un par URL/token incompleto se rechaza antes del inicio. Los tokens se leen como configuración secreta y nunca se incluyen en cargas útiles de dispositivo, comando, resultado o auditoría.

La ruta del SDK de Proveedor puede ejercitarse independientemente de la fábrica del runtime:

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

Solo las capacidades de sensor mapeadas se convierten en métricas energéticas canónicas. El cliente también lee el registro de entidades habilitadas de Home Assistant a través de WebSocket cuando las cargas útiles de estado no incluyen device_id; la identidad del registro se preserva cuando se proporciona, nunca se infiere de nombres o áreas.

Eliminar DOMOAI_HOME_ASSISTANT_PROVIDER revierte al adaptador clásico sin cambiar la superficie MCP orientada al agente. La ruta del proveedor está cubierta por fixtures deterministas. El smoke opt-in del runtime proveedor en vivo valida la misma ruta contra una instancia real de Home Assistant sin ejecutar comandos:

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

Requiere un par URL/token real y mantiene el token fuera del repositorio.

Runtime en vivo de Zigbee2MQTT

El adaptador nativo Zigbee2MQTT es opt-in y admite el perfil v1 acotado: potencia de luz/interruptor, brillo de luz, temperatura, humedad y ocupación. Configúrelo junto con Home Assistant u otra fuente:

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 puede ejecutarse junto con Home Assistant u otra fuente configurada. El adaptador consume los temas de bridge/dispositivo de Zigbee2MQTT y publica solo comandos /set de dispositivo mapeados a través del límite existente de plan, política y ejecutor. El emparejamiento, eliminación, OTA, grupos, administración del bridge y publicación arbitraria de MQTT no están expuestos.

Runtime en vivo de Matter Server

El adaptador nativo Matter utiliza Matter Server como límite del controlador y se conecta a su punto final WebSocket compatible. Configúrelo junto con Home Assistant, Zigbee2MQTT u otra fuente:

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

El adaptador valida el rango del esquema del servidor antes del descubrimiento, preserva las referencias de fuente node:<node_id>/endpoint:<endpoint_id> y expone solo el perfil v1 acotado de potencia de luz/interruptor y brillo, más el estado de solo lectura de temperatura, humedad y ocupación. El commissioning, la gestión de fábrica, OTA, grupos, clústeres de proveedor y operaciones de atributos arbitrarios permanecen fuera del límite orientado al agente. Las pruebas smoke en vivo de Matter son opt-in; las pruebas con fixture no necesitan servidor Matter ni hardware.

Runtime en vivo de KNX/IP

El adaptador nativo KNX utiliza un archivo de mapeo explícito en lugar de inferir dispositivos a partir de tráfico de grupo arbitrario. Su perfil v1 acotado admite potencia de luz e interruptor, brillo de luz, y temperatura, humedad y ocupación de solo lectura. Configúrelo junto con las otras fuentes físicas:

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

El archivo de mapeo declara cada entidad, capacidad semántica, dirección de grupo de estado, dirección de grupo de comando y DPT. Los campos desconocidos, direcciones mal formadas, DPT no soportados y mapeos de sensores escribibles se rechazan al inicio. El túnelling KNX/IP es opcional y puede coexistir con los otros adaptadores configurados; las pruebas con fixture utilizan un transporte en memoria y no requieren gateway ni hardware. La importación ETS, commissioning, enrutamiento, credenciales seguras, operaciones de valor de grupo arbitrarias, escenas y perfiles de dispositivo xknx adicionales no están incluidos en v1.

Runtime en vivo de Modbus TCP

El adaptador nativo Modbus utiliza un mapeo explícito v1 de IDs de unidad, áreas de registro, desplazamientos PDU basados en cero y codificaciones escalares. Admite potencia de luz/interruptor, brillo de luz, y temperatura, humedad y ocupación de solo lectura. Configúrelo junto con las otras fuentes físicas:

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

El mapeo es estricto y no escanea ni infiere dispositivos. Los campos desconocidos, direcciones ambiguas de estilo 40001, codificaciones no soportadas, sensores escribibles y comandos inseguros se rechazan. Modbus TCP es opt-in y puede coexistir con Home Assistant, Zigbee2MQTT, Matter Server y KNX. RTU/ASCII, TLS, escaneo, códigos de función de proveedor y lecturas/escrituras de registro arbitrarias están fuera de v1. Las pruebas con fixture utilizan un transporte en memoria y no requieren controlador ni hardware.

Identidad y enrutamiento multiadaptador

El runtime sigue la distinción dispositivo/entidad de Home Assistant: un dispositivo fuente físico puede exponer múltiples entidades fuente, mientras que DomoAI presenta un dispositivo canónico con rutas a nivel de capacidad. Los identificadores y conexiones de fuente estables preservan la identidad a través de cambios de nombre o área; se requiere un canonical_id explícito para vincular contribuciones de diferentes adaptadores. Los comandos se resuelven a una entidad fuente exacta antes de la ejecución. Las rutas ambiguas, desconocidas o no disponibles fallan de forma segura, por lo que el runtime nunca envía silenciosamente un comando a otro protocolo o entidad.

No se requiere ningún gateway, broker o controlador en vivo para este comportamiento. El fixture determinista multiadaptador cubre composición, fallo parcial, topología, enrutamiento exacto y seguridad de escritura cero:

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

Validación local verificada

El 2026-08-17 el repositorio superó las pruebas unitarias, de adaptador, descubrimiento, plan, contrato MCP, optimización, rendimiento, ejecución de Home Assistant, fixture KNX y Modbus, composición del runtime, y escenarios de proveedor OMIE y Open-Meteo cubiertos por el conjunto de pruebas del repositorio. El smoke del adaptador clásico de Home Assistant pasó contra el laboratorio Docker local; los smokes locales de Zigbee2MQTT y Modbus pasaron; y los smokes de solo lectura de OMIE y Open-Meteo en red pública pasaron con configuración opt-in. El descubrimiento de Matter y KNX/IP siguen siendo opcionales porque requieren un nodo Matter comisionado o un gateway KNX alcanzable y mapeo.

El comando de lanzamiento local es:

uv run domoai-mcp

Las puertas de calidad son:

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

El último resultado completo del conjunto sin credenciales en vivo es 318 passed, 8 skipped, sin advertencias. Los omitidos son casos opt-in de Matter Server, KNX/IP y otros casos en vivo sin su nodo externo, gateway o configuración de servicio; la cobertura de fixture determinista permanece habilitada. Los resultados separados en vivo son: Zigbee2MQTT/Modbus 2 passed, OMIE/Open-Meteo 2 passed, adaptador clásico de Home Assistant 1 passed y el puente del runtime del Proveedor de Home Assistant 1 passed. La costura de compatibilidad FastMCP mantiene la conocida advertencia de campo incompleto de pydantic_settings fuera de los contratos MCP sin suprimir advertencias globalmente.

La guía del adaptador y del contrato público se encuentra en docs/adapter-sdk.md y docs/contracts.md.