Wattage: AIエージェント向けトークン支出プロファイラとコスト回帰ゲート

Wattage は、AI エージェント向けのオープンソースのトークン支出プロファイラおよびコスト回帰ゲートです。OpenTelemetry (OTLP) JSON 形式のトレースエクスポートを読み取り、設定ファイルや API キー不要で完全にオフライン動作し、各呼び出しの価格設定と複数の効率検出を実行します。

クイックスタート

uvx wattage report trace.json でトレースファイルを分析できます。リポジトリに付属のサンプルトレースに対して uv run wattage report examples/sample_trace.json を実行すると、総コスト、トークン内訳、効率グレード（例: A）を表示するターミナル表が出力されます。--html オプションでスタンドアロンの HTML フレームグラフも生成可能です。

核心機能：収束エンジン

Wattage の際立った特徴は収束エンジン、特に非収束検出器です。これは、エージェントがループ内で実質的な進展なく無駄に動き回るパターン（タイムスタンプが異なる再試行、2つの戦略間の振動、各呼び出しが技術的に一意だが何も学習されない「生産的に見える」停滞）を捕捉します。SHA-256 完全一致ベースラインと比較したベンチマークでは、Wattage は F1 スコア 1.00（適合率 1.00、再現率 1.00）を達成し、ベースラインの F1 0.25 を大きく上回りました。また、プレフィックスチャーン修正シミュレーションでは、安定したプレフィックスにプロンプトキャッシュを有効にすることでコストが 44.7% 削減されることを示しています。

8つの検出器

wattage report は8つの検出器を実行します：プレフィックスチャーン（安定したコンテキストがキャッシュされず再送される）、キャッシュギャップ（キャッシュ試行後に後続読み取りが未活用）、冗長性（必要な出力を大幅に超える）、冗長ツール呼び出し（同じツール呼び出しの繰り返し）、非収束（進展のないループ）、検索スラッシング（関連結果を得られない反復検索）、モデル不一致（より安価なモデルで処理可能な作業に高価なモデルを使用）、推論過剰支出（単純なステップに過剰な推論トークンを使用）。各問題は実際のドルコストで評価され、具体的な修正案と品質リスクレベル（なし/低/レビュー）がタグ付けされます。

CI 統合

wattage ci コマンドはコスト回帰ゲートとして機能します。GitHub Actions ワークフローで設定すると、PR 実行時にエージェントのパフォーマンスがしきい値（例: スコア80未満、コスト増加5%超、重大問題あり）を超えた場合、ビルドが失敗し、各検出器の差分表を含む PR コメントが投稿されます。SARIF や JUnit XML 出力にも対応し、他の CI システムにも統合可能です。ベースラインファイルは小さな JSON ファイルで、ゲートを通過した実行でのみ更新されるため、ノイズの影響を受けません。

バッジとコントリビューション

uv run wattage badge で README バッジを生成でき、CI で自動更新可能です。Wattage は Apache-2.0 ライセンスで提供され、コントリビュータは Python entry-point グループを通じて新しい検出器を追加でき、コアパイプラインを変更する必要はありません。