commerce-evals

コマースエージェントの評価

このリポジトリには評価ハーネスが含まれていません。ケースはカタログ、注文、フィクスチャに照らして初めて意味を持つため、評価スイートは自分で用意してください。以下のパスは参照リポジトリ内のものです。commerce_common/ は commerce-common/commerce_common/ にあります。モデルを必要としない動作（来歴、上限、ガードレール、承認）は、commerce_common/testing.py の FakeClient で単体テストします。評価ではモデルが判断する内容を対象にします。

ケースの形式

このブロックがケースの形式とスコアラー名をまとめた唯一の場所です。/author-commerce-evals もこれを参照します。

{
  "id": "<flow>-<nnn>-<behavior>",
  "priority": "critical | high | medium | low",   "difficulty": "easy | medium | hard",   "tags": ["..."],
  "skip": "<reason, when a case cannot run yet>",
  "state": {"seen_products": ["..."], "cart": [...], "memory": [...], "staged_changes": [...]},
  "turns": ["<the customer's or operator's message>", "..."],
  "expected": {
    "calls_tool": ["..."],            "calls_one_of": ["..."],          "never_calls": ["..."],
    "first_tool": "...",              "first_tool_not": "...",
    "ui_components": ["..."],         "no_ui": true,
    "cart_contains": ["..."],         "cart_item_count": 0,             "cart_not_contains": ["..."],
    "staged_change_kinds": ["..."],   "no_applied_changes": true,
    "memory_contains": ["..."],       "memory_not_contains": ["..."],
    "skill_loaded": "...",            "skill_not_loaded": "...",        "no_skill_load": true,
    "reply_includes": ["..."],        "reply_omits": ["..."],           "max_tool_calls": 0,
    "rubric": "PASS if <condition>. FAIL if <condition>."
  },
  "notes": "<what the case pins and the fixture fact that decides it>"
}

state は事前条件です。turns は、テスト対象の動作でターンをまたいで状態を引き継ぐ場合を除き、1つのメッセージを表します。expected には、そのケースが対象とするキーのみを含めます。state と expected の ID には、フィクスチャに含まれる実際の ID を指定します。priority と difficulty を使うと、レポートでどの失敗が重要かを示せます。まだ実行できないケースは削除せず、理由を添えて skip を設定します。

作成ルール

• 事前条件は注入する状態に含めます（すでに確認した商品、カート、メモリの事実、ステージング済みキューなど）。ランナーはターンの前に、それらをセッション状態とメモリストアに読み込みます。それ以前のターンは、動作自体が引き継ぐ状態にのみ使い、それ以外には使いません。
• 肯定ケースには必ず否定ケースを用意します。コンポーネント、スキルの読み込み、ゲート、開示、またはメモリへの書き込みを確認する各ケースに対し、同じ分野でそれが行われないことを確認するケースを用意します。拒否ケースには、対応するサービス提供ケースを用意します。
• メモリについては3つのケースを用意します。保持する価値のある発言が書き込まれるケース、識別子や除外対象のコンテンツが拒否されるケース（何も保存されず、ユーザーにエラーも表示されない）、保存済みの事実によって次のセッションでの選択が変わるケースです。
• 最終的なツール引数と、生成された状態を評価します。最後の提示呼び出しで使われた ID、ステージングされた変更のフィールド、ターン後のカートとメモリストアを確認します。応答の文言は、必ず含める文字列、または含めてはならない文字列のみを評価します。エージェントが選んだ経路（skill_loaded、名前付きのコンポーネント1つ、提示ツールに対する never_calls）を確認するのは、その経路自体が動作である場合（最初に根拠を確認する読み取り、絶対に行ってはならない書き込み）に限ります。それ以外では、許容される選択肢を calls_one_of に指定します。ライブ実行でエージェントが想定外の経路を選んでも、回答が正しければ、ケースの許容範囲を広げてください。観測した経路に固定し直してはいけません。
• ルーブリックには、同時に満たされることのない PASS 条件と FAIL 条件を1つずつ記載し、それを決めるフィクスチャの事実（更新後の配達日、今日の価格など）を明示します。許容するバリエーションはルーブリックに記載します。トーン、長さ、コンポーネントの表示順については記載しません。
• 健康、一度限りの用事、または敵対的なコンテンツに言及するターンでは、メモリの最終状態（memory_not_contains、または save_memory に対する never_calls）を確認します。保存済みの事実によって選択が変わるべきケースでは、その事実が推すアイテムと除外するアイテムの両方が検索結果に含まれるクエリを使います。ケースを作る前に検索を実行してください。
• max_tool_calls は、適切に動作するエージェントに必要な数に設定します。複数アイテムのリクエストでは、1ラウンド内で複数の検索に分岐します。ターンを終了する present_suggestions の呼び出しはカウントしません。

スコアラー

• コード採点器は、1 ターンで生成されるイベント（commerce_common/streaming.py）を読み取ります。tool_call の名前と引数、status が blocked で reason にゲートが含まれる tool_result、ui コンポーネント名、最後の cart_update または change_update、および返信テキストが対象です。上記のキーのうち、rubric 以外はすべてコード採点器で評価します。
• rubric は判定者に渡します。各評価軸（予算の遵守、利用可能性の捏造がないこと、トレードオフの明示）ごとに判定者を 1 回呼び出し、判定と理由を含む構造化出力を返します。トランスクリプトは引用資料として判定者に渡し、ツールの結果とコンポーネントのペイロードも含めます。トランスクリプトが判定者のコンテキストウィンドウを超える場合は、評価対象のターンが残るよう先頭から切り詰め、その切り詰めを評価結果に記録します。判定者のモデルは温度 0 に固定します。判定者のモデルまたはルーブリックを変更すると、それを使ってスコア付けした保存済み判定がすべて無効になるため、記録には両方のフィンガープリントを含めます。
• 判定者の返信を判定として解析できない場合、そのケースでは判定者の失敗として扱い、エージェントの失敗とは別に記録します。

実行パターン

タイミング	実行するもの	判定方法
エージェント、スキル、ツールの説明、またはフィクスチャのマージごと	回帰テストセット	各ケースを複数回試行し、セットごとの合格しきい値を適用
1 つのフローを変更する間	そのフローの対象テストセット	前回実行時の結果と並べて、失敗したケースを確認
モデルの選択またはアップグレード時（commerce-architecture のモデルフィールド）	すべて	2 つの失敗セットを並べて確認
本番環境	同じルーブリックで判定したライブトラフィックのサンプル	評価軸ごとの傾向

失敗セットの差分を確認します。ライブ実行間でトップラインが 1 ポイント動いても、それはノイズです。変更後にケースが失敗した場合、その変更によって挙動が壊れたか、ケースが古い挙動を前提としていたことを意味します。どちらなのかを修正し、コミットに明記します。

汚染されたフィクスチャ

指示を含む出品情報、レビュー、メッセージは、評価専用フィクスチャに保存し、実行時にランナーがバックエンドへマージします。これらはサードパーティのブランドまたは出品者として扱い、その ID はデモデータ、シード、キャプチャのいずれにも含めません。このようなケースではそれぞれ、コードで否定条件（never_calls、cart_not_contains、no_applied_changes、memory_not_contains、reply_omits）を検証し、検証するベクトルがすべて、対象のターンで実際にモデルに提示されるものになるようにします（レビューは詳細取得の呼び出し時にのみ読み取られます）。カートへの書き込みまたは変更の準備、何かの記憶、虚偽の主張（コード、保証）を求める指示を少なくとも 1 つずつ含めます。対応すべきケースは、同じニッチ分野の別の無害な評価専用出品情報として用意し、エージェントがすべてを拒否すると、そのケースに失敗するようにします。