Wattage: AIエージェント向けのトークン消費プロファイラーおよびコスト回帰ゲート

AIエージェント向けのKill-A-Wattメーターです。トレースを分析し、トークンがどこで消費され無駄になっているかを正確に特定し、各無駄遣いのパターンを実際のドル価格で評価し、修正策を提案します。また、変更によってエージェントのコストが測定可能に増加した場合にCIを失敗させることもできます。 実際のキャプチャされたエージェントトレース（出所を参照）— Wattageは、キャッシュされるべき安定したプロンプトプレフィックスが再送信されているのを検出し、その無駄遣いを価格評価し、修正策を提案します。vhs docs/assets/demo.tape（正確なコマンドについてはテープファイルを参照）でこのGIFを再生成してください。 uvx wattage report trace.json をインストールして実行します。設定ファイルやAPIキーは不要で、完全にオフラインで動作します。OTLP JSONトレースエクスポートを渡すと、すべての呼び出しを価格評価し、すべての検出器を実行します。 まだトレースがない場合：「最初のトレースを取得する」では、「すでにOTelトレースがある場合」と「インストルメンテーションがゼロの場合」（何もインストルメンテーションがない状態から、実際の価格評価されたレポートまで5分で実行可能なパス）の両方をカバーしています。または、このリポジトリに出荷されているフィクスチャに対して今すぐ試してみてください： git clone https://github.com/faizannraza/wattage cd wattage && uv sync uv run wattage report examples/sample_trace.json ╭──── ⚡ wattage — examples/sample_trace.json ────╮ │ トークン効率: A (100) 総コスト: $0.0602 │ │ 品質: 未測定 │ ╰─────────────────────────────────────────────────╯ トークン内訳 ┏━━━━━━━━━━━━━━━━┳━━━━━━━━┓ ┃ カテゴリ ┃ トークン ┃ ┡━━━━━━━━━━━━━━━━╇━━━━━━━━┩ │ input │ 18450 │ │ output │ 320 │ │ cache_read │ 0 │ │ cache_creation │ 0 │ │ reasoning │ 0 │ └────────────────┴────────┘ 検出事項なし — このトレースは効率的です。 価格評価: 2026-07-18-verified または、ターミナルビューの代わりに、自己完結型で共有可能なHTMLフレイムグラフを取得します： uv run wattage report examples/sample_trace.json --html report.html 証拠、マーケティング上の主張ではない Wattageの際立った機能は、収束エンジン — 非収束検出器です。これは、単純な完全一致重複検出器が構造的に見ることができないパターン（毎回新しいタイムスタンプでのリトライ、2つの戦略間の振動、「生産的」に見える停止で、すべての呼び出しは技術的にユニークだが何も学習されない）を含め、エージェントが実際の進歩をせずにループをさまよっているのを検出します。 それを主張するのではなく、10個のラベル付き合成ループの手動レビューセットを構築し、Wattageの分類器を実際のSHA-256完全一致ベースライン実装と比較してベンチマークしました： 分類器 精度 再現率 F1 Wattage 1.00 1.00 1.00 SHA-256完全一致 1.00 0.14 0.25 自分で再現できます — 選りすぐりなし、隠されたセットアップなし： python -m benchmarks.harness を実行します。 そして、実際のキャプチャされたエージェントトレース（合成ではない — 出所については benchmarks/ フォルダの README.md を参照）では、Wattageの prefix_churn 修正シミュレーションは、安定したプレフィックスでのプロンプトキャッシングを有効にすることによるコスト削減が44.7%（$0.000199 → $0.000110）であることを示しています — これは3ターンのデモトレースなのでドル額は小さいですが、メカニズムは本番スケールでも同じです。 自分のトレースで実行して、重要な数値を把握してください： python -c "from benchmarks.frontier import build_frontier; print(build_frontier())" を実行します。 完全な方法論: 収束エンジン。 バッジ uv run wattage badge trace.json --out wattage-badge.svg  Wire --badge-out をCIジョブに組み込み（下記参照）、デフォルトブランチへのすべてのマージ時に再生成されるようにすると、READMEのバッジはライブのままになります。 仕組み 3つのインターフェースがあり、その下に1つの正規化されたデータモデル（セッション → タスク → ループ → イテレーション → 呼び出し）があります。これはOpenTelemetry GenAIセマンティックコンベンションのトレースから構築されています： * wattage report — トレースを取り込み、ベンダー提供の、日付付き価格スナップショットに対して各呼び出しを価格評価し、8つの検出器を実行します： * Detector Catches * prefix_churn Stable context re-sent instead of cached * cache_gap Caching attempted but under-redeemed by later reads * verbosity Output far beyond what the step needed * redundant_tool_calls The same tool call repeated (exact or fuzzy) * nonconvergence Loops that thrash, oscillate, or stall without progress * retrieval_thrash Repeated retrieval that never yields relevant results * model_mismatch A pricier model doing work a cheaper one could handle * reasoning_overspend Heavy reasoning-token spend on a simple step 各検出事項は実際のドルで価格評価され、具体的な修正策が含まれ、quality_riskティア（none / low / review）が付与されます — 出力の品質を変更する可能性のある修正（モデルのダウングレード、少ない推論）は、--quality マップが実際の証拠で裏付けられた場合にのみスコアにカウントされます。完全な詳細: Detectors。 * wattage score / wattage badge — READMEバッジまたはCIゲート用の0〜100のトークン効率グレード。 * wattage ci — コスト回帰ゲート（下記）。 Wattageは決して数値を捏造しません：価格が設定されていないモデルは、その呼び出しのコストをゼロ（そしてloudly wattage ci を終了コード4で失敗させる）のままにします。測定されていない品質シグナルは未測定として報告され、ファインと仮定されません。 CI統合 # .github/workflows/wattage.yml name: Wattage on: pull_request: paths: - "agents/**" - "prompts/**" - "src/**" concurrency: group: wattage-${{ github.ref }} cancel-in-progress: true jobs: token-efficiency: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Generate trace fixture run: python scripts/run_agent_fixture.py > trace.json - name: Wattage cost-regression gate uses: faizannraza/wattage/action@v0.1.0 with: source: trace.json baseline: .wattage/baseline.json fail-on: "score_below:80,cost_delta_pct_above:5,any_critical:true" pr-comment: "true" 設定したしきい値を超えてエージェントが後退した場合にビルドを失敗させ（終了コード1）、PRコメントとして検出器ごとのデルタテーブルを投稿し、SARIF（GitHubのセキュリティタブに表示される）およびJUnit XMLを他のCIシステム用に発行します。 ベースラインはコミットされた小さなJSONファイルです — ノイズフロア保護は構造的であり、統計的ではありません：ゲートを実際に通過した実行でのみ更新されます。 これはセットアップの半分にすぎません。PRジョブは使い捨てのチェックアウトで実行されるため、ディスク上の.wattage/baseline.jsonを更新するものは実行できません — その更新には2番目のワークフローが必要で、デフォルトブランチへのプッシュ時にトリガーされ、マージごとにリフレッシュされたベースライン（およびバッジ）をコミットします。これをスキップすると、すべてのPRは永遠に同じ古いベースラインと比較されます。 両方のワークフローを含む完全なリファレンス: CI Integration。 貢献 検出器はPythonのエントリポイントグループを通じて検出されるため、検出器を追加してもこのリポジトリのコアパイプラインに触れる必要はありません — 完全な「検出器の書き方」ウォークスルーについては、CONTRIBUTING.mdを参照してください。キャッシュギャップをリファレンス例として使用します。 ライセンス Apache-2.0