verify

Honcho の変更を検証する

前提条件

スタックの実行には Docker Compose を使うのが推奨です。リポジトリルートの docker-compose.yml を使うと、Postgres（pgvector）、Redis、API サーバー、deriver ワーカーをまとめて起動できます。Docker Compose を利用できない場合は、スタックをホスト上で直接実行することもできます（「起動」を参照してください）。Postgres と pgvector、接続可能な Redis に加え、モデルを呼び出すすべてのフロー（deriver、dialectic、dreamer）で使用する、接続文字列と LLM プロバイダーキーを含む .env が必要です。

ワークツリーで作業していますか？ワークツリーには .env も node_modules も含まれません。プロバイダーキーが保存されているメインのチェックアウトから .env をコピーしてください。テストスイート全体を実行する場合は、sdks/typescript で bun install を実行してください。そうしないと、プッシュ前のチェックで架空の Cannot find package 'zod' エラーが発生します。

起動

まず、Docker Compose でスタックがすでに実行中かどうかを確認します。

docker compose ps          # look for api / deriver / database / redis
docker compose up -d       # start it if not

スタックが実行中でも、自分のブランチのコードが実行されているとは限りません。CREATED 列を確認してください。イメージが数週間前のものかもしれません。差分を検証する手軽な方法は、スタックの Postgres／Redis コンテナを再利用しつつ、ブランチの API をホストプロセスとして空いているポートで実行することです。

uv run uvicorn src.main:app --port 8901   # branch code, stack's DB/Redis
uv run python -m src.deriver              # if the diff touches the worker

これなら、イメージの再ビルドも、ワークツリーで 2 つ目の Compose スタックを起動することで発生するポートやプロジェクト名の競合も避けられます。Docker をまったく使わない場合は、ホスト上の Postgres と Redis に対して、同じように 2 つのプロセスを実行してください（API のデフォルトポートは 8000 で、uv run fastapi dev src/main.py を使用します）。

サーバーログを読む際は、メインの .env を使うと、テレメトリーエミッターが到達不能なエンドポイントへの接続警告を大量に出す点に注意してください。本当のエラーを探す前に、grep -v telemetry.emitter を使って除外してください。

動作させる

まず honcho-cli スキルを使って操作してください。上位レイヤーで利用できるメソッドがない場合は、SDK（sdks/python、sdks/typescript）、それでもできない場合は /v3 に対する REST の順で利用してください。SDK の使い方については honcho-integration スキルを参照してください。

変更によってエンドポイントが更新された場合やスキーマが変更された場合は、CLI、SDK、REST の 3 つすべてで検証してください。それぞれが独立して異なる状態になる可能性があるためです。

LLM を使う処理の変更では、同期的に試す最速の方法は、推論レベルを minimal にした dialectic です。メッセージをいくつか送信してから、/v3/.../peers/{peer_id}/chat を呼び出し、応答を確認します。

設定

設定は、アプリの操作とテストの実行のどちらにとっても重要です。API キーをサーバーに渡し、設定に関する変更を実際にテストするための手段だからです。設定は環境変数またはファイルから取得され、優先順位は env > .env > config.toml > デフォルトです。設定変更を検証するには、次のいずれかのレイヤーで該当オプションを設定し、影響を受けるプロセスを再起動して、実際の動作の違いを確認してください。同じ方法で、プロバイダーのベース URL、モデルの選択、タイムアウトを、実際に使用できる認証情報やプロキシに合わせて設定できます。

具体的な設定方法を 2 つ紹介します。深くネストされた設定（例：[dialectic.levels.minimal.model_config.overrides.provider_params]）を環境変数で設定するのは非常に困難です。代わりに、部分的な config.toml をリポジトリルートに配置してください。また、読み込み時の設定の動作確認には、サーバーを起動するより uv run python -c "import src.config; ..." のほうが高速です。

テストスイート

ここで重要なテストは 3 種類あります。すべて CI で実行されますが、手元にある API キーと設定を使ってローカルでも実行できます。Honcho の設定項目は多いため、エージェントごとのタイムアウトやプロバイダーのベース URL などのオプションを、自分のキーやプロキシに合わせて設定し、変更をテストできます。

# Unit tests (pytest; spins up its own infra via fixtures)
uv run pytest tests/

# Unified tests — step-based end-to-end flows defined in JSON
# (config hierarchy, multi-turn interactions, LLM-as-judge assertions)
uv run python -m tests.unified.run
uv run python -m tests.unified.run --test-dir tests/unified/test_cases

# Live LLM tests — real provider calls, for testing specific backends.
# Needs provider API keys AND model vars — without LIVE_LLM_*_MODELS the
# tests silently deselect that provider. See tests/live_llm/README.md.
export LLM_ANTHROPIC_API_KEY=...
export LIVE_LLM_ANTHROPIC_45_PLUS_MODELS=claude-sonnet-4-5
uv run pytest tests/live_llm -n 0 --live-llm --no-header -q