plzebo

plzebo

エージェントのループをコスト同等性でベンチマークします。同じタスクを完了するための方法を2つ以上指定すると（より安価なモデルの組み合わせ、別のセットアップ、ツールのオン／オフなど）、どちらがより少ない費用と時間で成果を出すかを測定し、その差が実際のものか、単なるノイズかを判定します。自分のキーまたはサブスクリプションを使って、ローカルで実行します。エージェントはMCP経由で自分自身に対して実行できます。

主要指標は成果成功1件あたりのコストです。計測された総支出を成功件数で割り、95％信頼区間とともに各条件間で比較します。成果成功1件あたりの時間も併記します。データから主張を裏付けられない場合、plzeboは無理に主張せず、その旨を示します。

測定方法

• 条件はループ全体です。 条件とは、タスクを最後まで実行するエージェントを起動するシェルコマンドと、ローカルの計測ゲートウェイで適用されるモデルの書き換えルールを組み合わせたものです。ゲートウェイがすべてのclaude-*呼び出しを各条件のモデルに割り当てるため、ループのコードを各条件間でバイト単位で同一にできます。
• すべてのモデル呼び出しはゲートウェイを経由します。 各条件にはプレースボキー（sk-placebo-...）とリダイレクトされたベースURLが割り当てられます。ゲートウェイは上流で実際のキーに置き換え、プロバイダーが報告するトークン使用量を呼び出しごとに記録します。ゲートウェイを迂回した呼び出しは、利用料金が気付かれずに発生する代わりにプロバイダー側で失敗します。また、計測された呼び出しがゼロの試行にはフラグが付き、比較対象にはなりません。
• 試行はペアにして、交互に実施します。 K組のペアを連続して実行し、シード付きコイントスでペアごとの条件の順序を決めることで、プロバイダーの変動がペア内に収まるようにします。プロンプトキャッシュは無効にし、すべての試行に一意のノンスを付けるため、ある条件によって別の条件のキャッシュが温まることはありません。
• 採点ではエージェントの作業ツリーを決して信頼しません。 差分を保護対象パスのリスト（テスト、ランナーの設定）に照らしてフィルタリングし、変更のないチェックアウトに適用してから、その場所でテストコマンドを実行します。テストを編集すると試行は失敗します。
• 統計的な主張は過大にならないようにします。 成功率の差には、条件間の多重性をHolm補正した正確なMcNemar検定を使います。同等性を主張するには、単に有意差が認められなかっただけではなく、同等性検定が必要です。コストと時間の差分には、ペアに対応したブートストラップを使います。いずれかの条件で成功が5件未満の場合、コストに関する判定は行いません。タイムアウトは支出を含めて失敗として採点します。クラッシュとプロバイダーによるスロットリング（429/529）は、支出を明示したうえで除外します。判定を見送る場合は、その理由を主張不可の明示的な行として出力します。
• 成果物は検証記録です。 実行のたびにJSON検証記録が作成されます。記録には、仕様とその事前登録ハッシュ、すべての試行の生データ行（トークン数、呼び出しごとのステータス、変更されたパス、出力末尾）、統計の入力値、価格表のバージョン、生成された推定対象の記述が含まれます。plzebo verify receipt.jsonは、生データ行からすべての導出値を再計算し、差異があれば報告します。

必要条件

Node 22.6以降が必要です（CLIはNodeの型ストリッピング機能を使ってTypeScriptのソースを実行します。必要なバージョンではランチャーがフラグを指定します）。Gitに加え、各条件とオラクルが必要とするものも必要です（ここでの例ではpython3）。

クイックスタート

npx plzebo run spec.yaml --estimate   # prices the run from prior receipts; spends nothing
npx plzebo run spec.yaml              # runs the experiment
npx plzebo verify <receipt.json>      # recompute a receipt's claims from its raw rows

仕様の例：

name: sonnet-vs-opus
fixture:
  repo: ./my-fixture-repo        # a git repo; every trial gets a fresh clone
  ref: main
task: "Make the failing tests in this repo pass. Do not edit the tests."
arms:
  sonnet:
    cmd: claude --print "$PLZEBO_TASK" --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}' --model claude-sonnet-5
    auth: passthrough            # runs on your logged-in Claude subscription
    rewrite:
      claude-*: claude-sonnet-5  # pin every call this arm makes, including auxiliary ones
  opus:
    cmd: claude --print "$PLZEBO_TASK" --dangerously-skip-permissions --strict-mcp-config --mcp-config '{"mcpServers":{}}' --model claude-opus-4-7
    auth: passthrough
    rewrite:
      claude-*: claude-opus-4-7
baseline: opus
oracle:
  cmd: [python3, -m, unittest, discover, -s, tests, -t, .]
k: 3
trialTimeoutMs: 600000
budgetUsd: 30                    # hard kill switch enforced at the gateway

各実行では、最初の試行の前にコストの推定値が表示されます。予算が指定されていない実行は拒否されます。まずは小さなKから始めてください。結論が出ない実行のレポートには、結論を出すために必要な正確なKと推定コストが表示されます。また、plzebo extend <receipt.json> --to-k Kを使えば、すでに費用をかけた試行を再利用できます。検証記録を延長できるのは1回だけで、その延長は記録内に明示されます。

認証モード

• auth: placebo（デフォルト）：ANTHROPIC_API_KEY または OPENAI_API_KEY をエクスポートします。アームが参照できるのは常にプラセボキーだけです。計測の保証が最も強く、迂回する呼び出しは明確なエラーで失敗します。
• auth: passthrough：アームは独自のログインを使用します。API クレジットは消費されず、計測されたトークン数に定価を適用して USD 額を推定し、レシートにその旨を記載します。いずれの場合も、トークン数が実測値です。サブスクリプション認証時に ANTHROPIC_BASE_URL を尊重する Claude Code で動作を確認済みです。ChatGPT 認証時の Codex は独自のバックエンドにルーティングされ、OPENAI_BASE_URL を無視するため、サブスクリプション認証の Codex は計測できません。代わりに codex-cli テンプレートを使い、API キーモードで Codex のアームを実行してください。

passthrough アームには、注意点が 2 つあります。計測を迂回した試行は誤って計上されず、除外されますが、その試行で上流のサービスが消費したトークンは実際に発生しています。レシートからは確認できません。また、個人アカウントでログインすると、指示、フック、メモリファイルなどの個人用エージェント設定も引き継がれます。これによりコストが増える可能性があり、常時有効な指示に従って動作するエージェントは、試行用ワークスペースの外部に書き込みを行うことがあります。ループを比較する際は、独自の設定ではなく、設定を分離したテンプレートを使用してください。

モデル混在アーム（オーケストレーターとワーカーで異なるモデルを使用）

レシート内の各コストノードには、2 つのモデルが記録されます。ループが要求したモデルである role と、アームの書き換えルールによって解決されたモデルである model です。ジョブごとに異なるモデルを要求するループ（メインセッションでは一方のモデル、サブエージェントでは別のモデルを使用するなど）では、レシートにロール構成が記録されます。また、同じコマンドを共有するアームでも、書き換えルールだけで各ロールを異なるモデルに割り当てられます。

arms:
  mixed:
    cmd: sh scripts/arms/subagent-mix.sh   # opus main session + a worker agent definition requesting sonnet
    auth: passthrough
    rewrite:
      claude-opus-*: claude-opus-4-7       # orchestrator stays opus
      claude-sonnet-*: claude-sonnet-5     # workers stay sonnet
      claude-*: claude-opus-4-7            # catch-all LAST: wildcard rules match in order after exact keys
  all_opus:
    cmd: sh scripts/arms/subagent-mix.sh   # byte-identical loop; only the mapping differs
    auth: passthrough
    rewrite:
      claude-*: claude-opus-4-7

同梱の scripts/arms/subagent-mix.sh では、Claude Code の構成例として、メインセッションとは異なるモデルを要求するワーカーをインラインの --agents 定義で指定し、ヘッドレスセッションを実行しています。タスクに合わせてエージェントのプロンプトとモデルを調整してください。

モデル混在の比較が有効なのは、ループが実際に処理を委譲した場合に限られます。コストツリーにワーカーロールの呼び出しがない試行は、混在構成ではなく、単独実行を計測したものです。

npx plzebo fidelity <receipt.json|run-dir>        # per-trial requested -> resolved counts
npx plzebo fidelity <run-dir> --worker "claude-haiku-*"

fidelity は、完了した試行のうちワーカーロールの呼び出しが一度もなかったものがある場合、終了コード 1 で終了します。また、各試行の呼び出し回数、トークン数、推定支出額を、要求モデルと解決済みモデルごとに集計して出力するため、アームが申告する混在構成をレシートで検証できます。

プロバイダー

ゲートウェイは 2 種類のワイヤーフォーマットに対応しています。Anthropic と OpenAI 互換です。OpenAI 互換フォーマットは、オープンウェイトモデルのサービングの大半（Ollama、vLLM、OpenRouter、Together など）をカバーします。アームごとにプロバイダーを個別に上書きできます。

arms:
  local-qwen:
    cmd: my-loop --task "$PLZEBO_TASK"
    upstreams:
      openai: http://127.0.0.1:11434   # any OpenAI-compatible server
  gpt:
    cmd: my-loop --task "$PLZEBO_TASK"
    keysFrom:
      openai: OPENAI_API_KEY           # env var NAME; specs never contain key values

制約：plzebo が計測できるのは、キーまたはトークンで認証し、リダイレクト可能なベース URL（ANTHROPIC_BASE_URL／OPENAI_BASE_URL）を尊重するループに限られます。

MCP

npx plzebo-mcp は stdio 経由で 4 つのツールを提供します。measure_start、measure_extend、measure_status、measure_result です。計測の開始は 2 段階で行われます。最初の呼び出しではリクエストを検証し、コストの見積もりと 1 回限りの確認トークンを返します。この段階では何も消費されません。確認トークンを提示する 2 回目の呼び出しでのみ、試行が実行されます。予算の指定は必須です。MCP アームには、名前付きテンプレート（claude-cli、claude-subscription、codex-cli）のみを使用でき、生のシェルは指定できません。ジョブの状態とレシートは .plzebo/ に保存されるため、判定結果はそれを生成したセッションの終了後も保持されます。

レシートが示すことと、示さないこと

レシートは、明示されたモデルの対応関係における単一タスクの結果です。モデルの能力ランキングではなく、対象のフィクスチャを超えて一般化できるものでもありません。レシート内の推定対象の説明には、この点が明記されています。passthrough アームの USD 額は、請求額ではなく、計測されたトークン数に価格表の料金を適用して推定した額です。価格表のバージョンもレシートに記録されるため、価格変更後も数値を再計算できます。

ライセンス

MIT