DomoAI

범용 에이전틱 홈 오토메이션 런타임으로, 시맨틱 장치 모델, 다중 어댑터 구성 및 하나의 일반 MCP 인터페이스를 제공합니다.

개발 환경

이 프로젝트는 uv와 Python 3.12를 사용합니다.

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

런타임 종속성에는 MCP Python SDK, Pydantic, Home Assistant HTTP/WebSocket 클라이언트, 선택적 Zigbee2MQTT 어댑터용 aiomqtt, JSON Schema 검증 및 OR-Tools가 포함됩니다. 로컬 SQLite 영속성은 Python 표준 라이브러리를 사용합니다. 개발 도구는 uv의 기본 dev 종속성 그룹을 통해 설치됩니다.

종속성을 추가하거나 업데이트하려면 pyproject.toml을 편집하고 잠금 파일을 다시 생성하십시오:

uv lock
uv sync

로컬 MCP 서버

시맨틱 MCP 서버는 stdio를 통해 실행할 수 있습니다. Home Assistant 설정이 없으면 결정론적 픽스처를 사용합니다:

uv run domoai-mcp

호스트 구성 예시:

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

동일한 명령을 Claude Code, Codex 또는 기타 호환 MCP 클라이언트에 등록할 수 있습니다.

통합 MCP 표면

단일 domoai-mcp 서버는 동일한 MCP 세션을 통해 검색, 상태, 에너지 컨텍스트, 정책 인식 계획 검증/실행 및 제안 전용 OR-Tools 도구 validate_scenario, optimize_scenario 및 explain_solution을 노출합니다. Claude Code, Codex 또는 로컬 stdio를 지원하는 기타 호환 MCP 클라이언트에 정확히 하나의 서버를 등록하십시오:

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

OR-Tools는 내부 제안/검증/설명 계층으로 유지됩니다. 장치를 실행하거나, 계획을 승인하거나, 어댑터를 호출할 수 없으며, 두 번째 공개 OR-Tools MCP 엔드포인트는 없습니다.

이식 가능한 optimize-home-energy 스킬은 모든 DomoAI 작업을 하나의 mcp 역할을 통해 라우팅합니다. 해당 참조 워크플로는 결정론적 인-프로세스 픽스처로 로컬에서 검증됩니다:

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

워크플로는 시맨틱 읽기, 제안, 설명 및 계획 검증에 동일한 연결을 사용하며 execute_plan 외부에서는 절대 실행되지 않습니다. 민감한 계획은 명시적 운영자 승인을 위해 일시 중지됩니다.

에너지 인식 시나리오의 경우, 이식 가능한 v2 절차는 제안 전용 최적화 도구를 호출하기 전에 mcp.get_energy_context를 통해 완전한 유형화된 컨텍스트를 읽습니다. 컨텍스트는 요금제와 태양광 예측을 고정된 기간에 맞추고 하나의 배터리 프로필을 포함할 수 있습니다. CP-SAT는 비용, 최대 수입 및 태양광 자체 소비 증거와 슬롯별 에너지 균형을 반환합니다. 물리적 어댑터는 절대 호출하지 않습니다. 컨텍스트 실패, 수정 불일치, 실행 불가능 또는 솔버 시간 초과는 검증 및 실행 전에 중지됩니다. 결정론적 제공자와 집중된 승인 명령은 저장소 계약 및 통합 테스트로 다루어집니다.

실시간 에너지 데이터를 위한 일회성 태양광 프로필

OMIE 요금제와 Open-Meteo 예측은 에너지 컨텍스트가 요청될 때마다 자동으로 수집됩니다. 물리적 설치 메타데이터만 한 번 제공하면 됩니다. 예제를 복사하고, 자리 표시자 값을 인버터 또는 설치업체 데이터로 바꾼 다음 런타임이 이를 가리키도록 하십시오:

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

프로필은 엄격하고 버전이 지정되며 자격 증명이 없습니다. 최적화에 결과를 사용하기 전에 실제 설치 값을 포함해야 합니다. 예제의 마드리드 값은 형식만 문서화합니다. 이전의 개별 DOMOAI_SOLAR_* 변수는 상호 배타적인 호환성 대체 수단으로 계속 사용할 수 있습니다.

범용 제공자 SDK

향후 Home Assistant, 인버터 및 MQTT 통합은 시맨틱 런타임에 도달하기 전에 소스별 ID와 페이로드를 제공자 SDK v1 경계로 변환해야 합니다. SDK는 DomoAI의 표준 DeviceType, Capability 및 SourceRef 모델을 재사용하고 제공자를 텔레메트리 및 명령 역할로 분리합니다:

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

제공자 명령은 제한된 시맨틱 매개변수와 멱등성 키만 전달합니다. PlanService, 정책 검증 또는 AdapterPort를 우회하지 않습니다. 첫 번째 구체적인 구현은 HomeAssistantProvider입니다. 인증된 REST/WebSocket 클라이언트를 재사용하고, 레지스트리 메타데이터를 사용할 수 있을 때 Home Assistant device_id로 엔터티를 그룹화하며, 명시적 엔터티/기능 메트릭 매핑만 노출합니다. 이는 기존 HomeAssistantAdapter에 추가됩니다. 런타임 팩토리는 DOMOAI_HOME_ASSISTANT_PROVIDER=1이 명시적으로 활성화된 경우에만 이를 선택합니다. 동일한 제공자 객체가 ProviderRegistry에 등록되고 기존 AdapterPort로 래핑되므로 DeviceRegistry, StateStore, 계획 실행 및 MCP는 하나의 시맨틱 경로와 하나의 Home Assistant 클라이언트를 유지합니다. 공개 경계는 docs/adapter-sdk.md 및 docs/contracts.md를 참조하십시오.

실시간 Home Assistant 런타임

하드웨어 없이 로컬 개발을 위해 재현 가능한 가상 실험실은 dev/lab/README.md에 있으며, 최소 시작은 Mosquitto/가짜 Zigbee2MQTT 및 PyModbus를 다룹니다. Home Assistant, Matter Server 및 KNX Virtual/ETS는 선택적 수동 프로필로 유지됩니다.

해당 실험실을 운영하는 권장 경로는 명시적 실행기입니다:

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

스모크 테스트는 로컬 Home Assistant, MQTT/Zigbee2MQTT, Modbus, Matter 및 KNX 픽스처만 사용합니다. 게이트웨이, 토큰 또는 커미셔닝을 생성하지 않습니다. 실시간 스모크 테스트는 분리되어 있으며 실제 서비스와 DOMOAI_* 변수가 필요합니다.

구성 루트는 실시간 소스가 구성되지 않은 경우 결정론적 픽스처를 선택하고, 하나의 소스에 대한 직접 어댑터를 선택하거나, 두 개 이상의 완전한 소스 구성에 대한 복합 런타임을 선택합니다. Home Assistant를 다음과 같이 구성하십시오:

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

제공자 모드는 선택 사항입니다. 활성화되지 않으면 호환성을 위해 기존 HomeAssistantAdapter가 선택됩니다. 활성화된 경우 URL/토큰 쌍이 필요하며 선택적 엄격한 v1 매핑 문서로 에너지 역할을 명시적으로 만들 수 있습니다:

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

런타임은 REST 서비스 호출을 인증하고, 계획, 결과 및 수정된 감사 이벤트를 SQLite에 유지하며, 백그라운드에서 어댑터 이벤트 소비자를 실행합니다. 지원되는 쓰기 매핑에는 현재 조명/스위치 전원 및 토글 작업, 조명 밝기, 커버 위치/열기/닫기/중지 및 기후 목표 온도가 포함됩니다. 불완전한 URL/토큰 쌍은 시작 전에 거부됩니다. 토큰은 비밀 구성으로 읽히며 장치, 명령, 결과 또는 감사 페이로드에 포함되지 않습니다.

제공자 SDK 경로는 런타임 팩토리와 독립적으로 실행될 수 있습니다:

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

매핑된 센서 기능만 표준 에너지 메트릭이 됩니다. 클라이언트는 또한 상태 페이로드에 device_id가 포함되지 않은 경우 WebSocket을 통해 Home Assistant의 활성화된 엔터티 레지스트리를 읽습니다. 레지스트리 ID는 제공될 때 보존되며 이름이나 영역에서 유추되지 않습니다.

DOMOAI_HOME_ASSISTANT_PROVIDER를 제거하면 에이전트 직면 MCP 표면을 변경하지 않고 기존 어댑터로 롤백됩니다. 제공자 경로는 결정론적 픽스처로 다루어집니다. 선택적 실시간 제공자-런타임 스모크는 명령을 실행하지 않고 실제 Home Assistant 인스턴스에 대해 동일한 경로를 검증합니다:

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

실제 URL/토큰 쌍이 필요하며 토큰은 저장소 외부에 보관됩니다.

실시간 Zigbee2MQTT 런타임

네이티브 Zigbee2MQTT 어댑터는 선택 사항이며 제한된 v1 프로필(조명/스위치 전원, 조명 밝기, 온도, 습도 및 재실 여부)을 지원합니다. Home Assistant 또는 다른 소스와 함께 구성하십시오:

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는 Home Assistant 또는 다른 구성된 소스와 함께 실행될 수 있습니다. 어댑터는 Zigbee2MQTT 브리지/장치 토픽을 소비하고 기존 계획, 정책 및 실행기 경계를 통해 매핑된 장치 /set 명령만 게시합니다. 페어링, 제거, OTA, 그룹, 브리지 관리 및 임의 MQTT 게시는 노출되지 않습니다.

실시간 Matter Server 런타임

네이티브 Matter 어댑터는 Matter Server를 컨트롤러 경계로 사용하고 호환되는 WebSocket 엔드포인트에 연결합니다. Home Assistant, Zigbee2MQTT 또는 다른 소스와 함께 구성하십시오:

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

어댑터는 검색 전에 서버 스키마 범위를 검증하고 node:<node_id>/endpoint:<endpoint_id> 소스 참조를 보존하며 제한된 v1 조명/스위치 전원 및 밝기 프로필과 읽기 전용 온도, 습도 및 재실 여부 상태만 노출합니다. 커미셔닝, 패브릭 관리, OTA, 그룹, 공급업체 클러스터 및 임의 속성 작업은 에이전트 직면 경계 외부에 남아 있습니다. 실시간 Matter 스모크 테스트는 선택 사항입니다. 픽스처 테스트에는 Matter 서버나 하드웨어가 필요하지 않습니다.

실시간 KNX/IP 런타임

네이티브 KNX 어댑터는 임의 그룹 트래픽에서 장치를 유추하는 대신 명시적 매핑 파일을 사용합니다. 제한된 v1 프로필은 조명 및 스위치 전원, 조명 밝기, 읽기 전용 온도, 습도 및 재실 여부를 지원합니다. 다른 물리적 소스와 함께 구성하십시오:

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

매핑 파일은 각 엔터티, 시맨틱 기능, 상태 그룹 주소, 명령 그룹 주소 및 DPT를 선언합니다. 알 수 없는 필드, 잘못된 형식의 주소, 지원되지 않는 DPT 및 쓰기 가능한 센서 매핑은 시작 시 거부됩니다. KNX/IP 터널링은 선택 사항이며 다른 구성된 어댑터와 공존할 수 있습니다. 픽스처 테스트는 인메모리 전송을 사용하며 게이트웨이나 하드웨어가 필요하지 않습니다. ETS 가져오기, 커미셔닝, 라우팅, 보안 자격 증명, 임의 그룹 값 작업, 장면 및 추가 xknx 장치 프로필은 v1에 포함되지 않습니다.

실시간 Modbus TCP 런타임

네이티브 Modbus 어댑터는 유닛 ID, 레지스터 영역, 0 기반 PDU 오프셋 및 스칼라 인코딩의 명시적 v1 매핑을 사용합니다. 조명/스위치 전원, 조명 밝기, 읽기 전용 온도, 습도 및 재실 여부를 지원합니다. 다른 물리적 소스와 함께 구성하십시오:

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

매핑은 엄격하며 장치를 스캔하거나 유추하지 않습니다. 알 수 없는 필드, 모호한 40001 스타일 주소, 지원되지 않는 인코딩, 쓰기 가능한 센서 및 안전하지 않은 명령은 거부됩니다. Modbus TCP는 선택 사항이며 Home Assistant, Zigbee2MQTT, Matter Server 및 KNX와 공존할 수 있습니다. RTU/ASCII, TLS, 스캐닝, 공급업체 기능 코드 및 임의 레지스터 읽기/쓰기는 v1 외부에 있습니다. 픽스처 테스트는 인메모리 전송을 사용하며 컨트롤러나 하드웨어가 필요하지 않습니다.

다중 어댑터 ID 및 라우팅

런타임은 Home Assistant 장치/엔터티 구분을 따릅니다. 하나의 물리적 소스 장치는 여러 소스 엔터티를 노출할 수 있는 반면, DomoAI는 기능 수준 경로가 있는 하나의 표준 장치를 제공합니다. 안정적인 소스 식별자와 연결은 이름이나 영역 변경 전반에 걸쳐 ID를 보존합니다. 다른 어댑터의 기여를 연결하려면 명시적 canonical_id가 필요합니다. 명령은 실행 전에 정확히 하나의 소스 엔터티로 확인됩니다. 모호하거나, 알 수 없거나, 사용할 수 없는 경로는 실패 시 닫히므로 런타임은 다른 프로토콜이나 엔터티로 명령을 자동으로 보내지 않습니다.

이 동작에는 실시간 게이트웨이, 브로커 또는 컨트롤러가 필요하지 않습니다. 결정론적 다중 어댑터 픽스처는 구성, 부분 실패, 토폴로지, 정확한 라우팅 및 쓰기 금지 안전성을 다룹니다:

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

확인된 로컬 검증

2026-08-17에 저장소는 저장소 테스트 스위트가 다루는 단위, 어댑터, 검색, 계획, MCP-계약, 최적화, 성능, Home Assistant 실행, KNX 및 Modbus 픽스처, 런타임 구성, OMIE 및 Open-Meteo 제공자 시나리오를 통과했습니다. Home Assistant 기존 어댑터 스모크는 로컬 Docker 실험실에 대해 통과했습니다. 로컬 Zigbee2MQTT 및 Modbus 스모크가 통과했습니다. 읽기 전용 OMIE 및 Open-Meteo 공용 네트워크 스모크는 선택적 구성으로 통과했습니다. Matter 검색 및 KNX/IP는 커미셔닝된 Matter 노드 또는 연결 가능한 KNX 게이트웨이와 매핑이 필요하기 때문에 선택 사항으로 남아 있습니다.

로컬 실행 명령은 다음과 같습니다:

uv run domoai-mcp

품질 게이트는 다음과 같습니다:

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

실시간 자격 증명이 없는 최신 전체 스위트 결과는 318 passed, 8 skipped이며 경고가 없습니다. 건너뛰기는 선택적 Matter Server, KNX/IP 및 외부 노드, 게이트웨이 또는 서비스 구성이 없는 기타 실시간 사례입니다. 결정론적 픽스처 범위는 활성화된 상태로 유지됩니다. 별도의 실시간 결과는 Zigbee2MQTT/Modbus 2 passed, OMIE/Open-Meteo 2 passed, Home Assistant 기존 어댑터 1 passed 및 Home Assistant 제공자 런타임 브리지 1 passed입니다. FastMCP 호환성 심은 전역적으로 경고를 억제하지 않고 알려진 pydantic_settings 불완전 필드 경고를 MCP 계약 외부에 유지합니다.

어댑터 및 공개 계약 가이드는 docs/adapter-sdk.md와 docs/contracts.md에 있습니다.