hotato

hotato

エージェントの呼び出しで何が壊れたのかを見つけます。問題を固定し、修正するまで CI を失敗状態に保ちます。

pip install hotato
hotato check --demo             # a bundled failing call: what broke, and when
hotato check ./call.wav         # then your own recording
hotato vapi health              # or your last 100 Vapi calls

設定不要です。Vapi、Retell、Bland、Synthflow、Millis、またはローカル音声に対応しています。 モノラル、デュアルチャンネル、文字起こしなど、あらゆる録音で動作します。判定者ではなく、タイミングの計算に基づきます。オフラインで利用でき、無料です。MIT ライセンスです。

hotato.dev

検出できること

• 発話と動作の食い違い：通話相手が割り込んでキャンセル（バージイン）し、エージェントが「キャンセルしました」と言ったのに、予約ツールが実行されてしまうケースです。hotato は音声からターンのタイミングを取得し、OTel トレースからツール呼び出しを取得します。
• レイテンシの急増：応答前の間が 800 ms から 2 秒超に伸びるケースです。
• 無音：間が 5 秒に達する、または回線が無音になるケースです。
• 発話の重なり：エージェントが通話相手の発話中に新しい発話を始めるケースです。

クイックスタート

Vapi

pip install hotato
export VAPI_API_KEY=...
hotato vapi health --last 7d --output report.html

report.html を開くと、重大インシデントとタイムスタンプ、Voice Stability Score が確認できます。

Retell

export RETELL_API_KEY=...
hotato retell health --call-id CALL_ID

--call-id は必須で、繰り返し指定できます。取得する Retell の通話を指定してください。 hotato bland health、hotato synthflow health、hotato millis health も Vapi と同じ形式で動作します。これらのスタックでは両方の音声が 1 つのチャンネルに混在するため、 無音のタイミング、無音状態、レイテンシの間を測定し、各検出結果には 測定された信頼度が付きます。バージインと発話の重なりの検出には 2 つのチャンネルが必要です。

ローカル音声

hotato autopsy ./call.wav

hotato-output/ に自己完結型の HTML レポートと、pin が読み込む JSON を出力します。 HTML をブラウザーで開いてください。

バグの検出からゲート設定まで

autopsy は 1 つの録音からタイムスタンプ付きのインシデントを生成します。scan はフォルダーを読み取り、傾向を追跡します。準備ができたら、検出結果を CI に組み込みます。 hotato pin は 1 つのインシデントをポータブルな失敗チェックに変換し、hotato prove は保存済みのすべてのチェックを再実行します。読み直せない証拠に基づいて成功とするのではなく、ビルドを失敗させます。各判定には、次の 5 つの観点にわたる独自の証拠が含まれます：結果、ポリシー、会話、音声、信頼性。

固定したチェックは保存済みの録音を再測定するため、そのバグがある限りビルドを失敗状態に保ち、編集されたバンドル、緩められたポリシー、同じバイト列を異なるスコアで評価するエンジンのアップグレードも検出します。これを解消するには、現在のエージェントで同じ状況を新たに録音します。hotato drive <bundle> はその通話を Vapi または Twilio で実行します。それ以外のスタックについては、 docs/RECAPTURE.md にすべての手順が記載されています。

バグを固定する →

継続的に利用するには、スケジュールに従って hotato vapi health を実行し、 hotato console --production-db evidence.db を開いて、通話がリアルタイムで記録される様子を確認します。

CI に組み込む

終了コードが判定です：0 は成功、1 は失敗、2 は判定不能（判断できなかった場合）です。

# .github/workflows/voice-qa.yml
on: [pull_request]
jobs:
  hotato:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: attenlabs/[email protected]
        with:
          contracts: contracts/
          hotato-version: 1.20.0

contracts/ には pin が書き込んだ内容が格納されます。ワークフロー全体については、docs/CI.md をご覧ください。

エージェントを向ける

Claude Code、Cursor、または任意のコーディングエージェントをこのリポジトリに向けてください。エージェントは AGENTS.md を読み、キーなしでオフラインのまま、最初から最後まで一連の処理を実行します。ローカル stdio では、MCP サーバーがスコアラーに加えて、読み取り／検証／提案ツールを提供します。 uvx --from "hotato[mcp]" hotato-mcp（docs/MCP.md）。デプロイはご自身で行ってください。

何もマシンの外に出ません

hotato は、実行したマシン上でオフライン動作します。コアは標準ライブラリのみの Python で、アカウントもキーも、独自のネットワーク呼び出しも必要ありません。トレース、プロンプト、 音声はディスク上にとどまります。ご自身でホストする言語モデルによるスコアリングは、コアとは別の、任意で追加できる機能です。

詳しく見る

一連の処理をコマンドごとに解説：docs/LIFECYCLE.md。 最初の操作から CI ゲートまで：docs/GETTING-STARTED.md。 すでにあるデータを取り込む：docs/CONNECT.md · docs/TRACE.md · docs/SIMULATE.md。 すべての判定を支える根拠：docs/EVIDENCE-CONTRACT.md。 ホスト型の代替サービスとの比較：docs/COMPARE.md。

キャプチャ、シミュレーション、負荷テスト、ベンチマーク、修正手順、 フリート制御プレーンを備えた高度なツールキットは、hotato lab の配下にあります（hotato lab --help）。 公開コマンドは安定しており、hotato lab はより速いペースで進化します。また、1.17 より前に動作していたコマンド名はすべて、これまでどおり使用できます。

仕様

PYTHONPATH=src python3 -m hotato.benchmark \
  --scenarios corpus/real/scenarios --audio corpus/real/audio

貢献

Issue と PR を歓迎します：CONTRIBUTING.md · SECURITY.md · CHANGELOG · docs/

ライセンス

MIT（LICENSE）

mcp-name: io.github.attenlabs/hotato