DomoAI

セマンティックデバイスモデル、マルチアダプター構成、および1つの汎用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サーバーは、ディスカバリー、状態、エネルギーコンテキスト、ポリシー認識型プラン検証/実行、および提案専用のOR-Toolsツールであるvalidate_scenario、optimize_scenario、explain_solutionを同じMCPセッションを通じて公開します。Claude Code、Codex、またはローカルstdioをサポートする他の互換性のあるMCPクライアントに、正確に1つのサーバーを登録します：

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

OR-Toolsは内部の提案/検証/説明レイヤーのままです。デバイスの実行、プランの承認、アダプターの呼び出しはできず、2番目のパブリックOR-Tools MCPエンドポイントはありません。

ポータブルなoptimize-home-energyスキルは、すべてのDomoAI操作を1つの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を通じて完全な型付きコンテキストを読み取ります。コンテキストは、料金と太陽光発電予測を固定の地平線に合わせ、1つのバッテリープロファイルを含む場合があります。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統合は、セマンティックランタイムに到達する前に、ソース固有のアイデンティティとペイロードをProvider 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は1つのセマンティックパスと1つのHome Assistantクライアントを維持します。

公開バウンダリーについては、docs/adapter-sdk.mdおよびdocs/contracts.mdを参照してください。

ライブHome Assistantランタイム

ハードウェアなしのローカル開発には、再現可能な仮想ラボがdev/lab/README.mdにあり、最小限の起動でMosquitto/fake 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_*変数が必要です。

構成ルートは、ライブソースが設定されていない場合は決定論的フィクスチャを、1つのソースの場合は直接アダプターを、2つ以上の完全なソース構成の場合は複合ランタイムを選択します。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/トークンペアは起動前に拒否されます。トークンはシークレット構成として読み取られ、デバイス、コマンド、結果、監査ペイロードに含まれることはありません。

Provider 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、レジスタ領域、ゼロベース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の範囲外です。フィクスチャテストはインメモリトランスポートを使用し、コントローラーやハードウェアは必要ありません。

マルチアダプターのアイデンティティとルーティング

ランタイムはHome Assistantのデバイス/エンティティの区別に従います。1つの物理ソースデバイスが複数のソースエンティティを公開する場合がありますが、DomoAIは機能レベルのルートを持つ1つの正規デバイスを提示します。安定したソース識別子と接続は、名前やエリアの変更を超えてアイデンティティを保持します。異なるアダプターからの貢献をリンクするには、明示的なcanonical_idが必要です。コマンドは実行前に1つの正確なソースエンティティに解決されます。曖昧、不明、または利用できないルートはフェイルクローズするため、ランタイムは別のプロトコルやエンティティにコマンドを黙って送信することはありません。

この動作にはライブゲートウェイ、ブローカー、コントローラーは必要ありません。決定論的マルチアダプターフィクスチャは、構成、部分的な障害、トポロジー、正確なルーティング、ゼロ書き込み安全性をカバーします：

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 Providerランタイムブリッジ 1 passed。FastMCP互換性シームは、既知のpydantic_settings不完全フィールド警告をグローバルに抑制せずにMCP契約の外に保持します。

アダプターと公開契約のガイダンスは、docs/adapter-sdk.md と docs/contracts.md にあります。