評価モジュール

対象: pca.evaluation

役割

deck pool に対する head-to-head / tournament evaluation を実行し、win rate だけでなく attack、prize、unfinished、deck-out / pokemon-out などの metrics を集計する。

モジュール一覧

モジュール	役割	実装の要点
pca.evaluation.tournament.__main__	module entrypoint	python -m pca.evaluation.tournament から CLI を起動する。
pca.evaluation.tournament.impl	evaluation core	CLI、policy construction、match loop、deck-pool loop、v12/v13 search defaults。
pca.evaluation.tournament.types	dataclasses	MatchConfig, MatchSummary, DeckEvaluation など。
pca.evaluation.tournament.summaries	summary	match result aggregation、CSV rows、metrics formatting。
pca.evaluation.tournament.agents	policy factory facade	evaluation 用 agent/policy construction の re-export。
pca.evaluation.tournament.deck_pool	deck-pool facade	deck pool evaluation の re-export。
pca.evaluation.tournament.matches	match facade	match execution helper の re-export。
pca.evaluation.tournament.cli	CLI facade	parse/main/default helper の re-export。
pca.evaluation.ab	A/B evaluation runner	baseline / experiment の evaluation config を同じ override で実行し、主要 metric の差分 JSON/CSV を保存する。
pca.evaluation.deck_manifest	fixed deck manifest	benchmark 用 YAML から順序付き DeckSpec を読み、重複・欠損を検証する。
pca.evaluation.promotion_benchmark	promotion benchmark	candidate/champion の先後入れ替え直接対戦と、両者の rule-pool 評価を同一 deck/seed で実行・集約する。
pca.evaluation.promotion_run	promotion runner	promotion benchmarkの4評価を実行し、同じartifactへgate判定を適用する。条件一致時は--resumeで評価を再利用する。
pca.evaluation.tactical_probe	tactical probe	同じ固定hidden局面でNN-only、Visit、Gumbel、高予算oracleを比較し、agreementとQ regretを保存する。
pca.evaluation.search_ab	search paired A/B	同一checkpointと固定deckでGumbel対Visitを直接対戦し、player位置を交換して方式基準に集計する。
pca.evaluation.bundle_loader	bundle loading	submission bundle を local Python で読み込む。
pca.evaluation.bundle_battle	bundle battle CLI	bundle agent を使って local battle を実行する。

公開API

API	用途
run_head_to_head(...)	2 deck/policy の直接対戦。
run_against_deck_pool(...)	own/opponent deck pool の総当たり評価。
summarize_matches(matches)	match summary list を集計する。
write_csv_summary(...)	summary CSV を保存する。
apply_v12_search_defaults(args)	evaluation CLI の search default を補う。
pca.evaluation.ab.comparison_rows(...)	2 つの evaluation JSON から勝率、通常勝ち、サイド、探索 diagnostics などの差分行を作る。
load_deck_manifest(path)	benchmark でモデル側に使う固定 deck 順を読み込む。
head_to_head_summary(forward, reverse)	player side を candidate 基準へ正規化し、完了試合勝率を集計する。
model_rule_metrics(payload)	rule-pool 結果を deck ごとの macro win rate と失敗率へ集約する。
TacticalProbeEvaluator.evaluate(...)	固定局面を4方式で評価し、action agreement、oracle Q regret、policy KLを返す。
tactical_categories(obs)	MAIN選択にある戦術的な合法手をカテゴリ分類する。

CLIの使い方

PYTHONPATH=src uv run python -m pca.evaluation.tournament \
  --own-deck-dir decks/own \
  --opponent-deck-dir decks/opponents/holdout \
  --games 20 \
  --policy search \
  --checkpoint checkpoints/policy_value_best.pt \
  --search-mode ismcts

A/B evaluation:

pca eval-ab \
  --set games=20 \
  --set workers=4 \
  --set device=cpu

Tactical probeをオンライン収集する:

pca tactical-probe \
  --games 1 \
  --max-probes 6 \
  --device cpu

各probeでは対戦を進めるNN-onlyの行動とは別に、同じ完全情報hidden stateを固定してVisit 480、Gumbel 480、高予算Visit 1920 simulationsを評価する。probe評価結果は実際の対戦trajectoryには使わない。

保存済み局面を別checkpointで再評価する:

pca tactical-probe \
  --checkpoint checkpoints/candidate_best.pt \
  --input data/eval/tactical-probe/probes.jsonl \
  --output data/eval/tactical-probe/candidate.jsonl \
  --summary-output data/eval/tactical-probe/candidate.summary.json

oracle_agreement_rateは高いほどよく、mean_oracle_q_regretとmean_oracle_policy_klは低いほどよい。固定hidden比較は探索方式とvalue精度を検査するもので、belief sampling自体の評価は別途paired対戦で行う。

GumbelとVisitを直接比較する:

pca search-ab \
  --checkpoint checkpoints/policy_value_latest_best.pt \
  --games-per-deck 20 \
  --workers 8 \
  --device cpu

固定7deckについて、Gumbelがplayer 0の方向とplayer 1の方向をそれぞれdeckあたり20試合実行するため、合計は7 × 20 × 2 = 280試合になる。両方向には同じevaluation seedを渡すが、CABTのbattle_startにはseed APIがないため、山札shuffleまで同一にしたcommon-random-number比較ではない。deck、試合数、player位置を対称化した直接対戦として解釈する。

summary.jsonにはGumbel基準の勝数、完了試合勝率、Wilson 95%信頼区間、平均attack、prize、attack-ready、方式別推論時間を保存する。95%信頼区間が0.5をまたぐ場合は、勝率差を確定的な優劣として扱わない。

デフォルトでは visit-based ISMCTS の configs/v13/evaluate-v13-ismcts-vs-rule.yaml と、Gumbel sequential-halving ISMCTS の configs/v14/evaluate-gumbel-sh-vs-rule.yaml を同じ rule-agent pool に対して実行し、data/eval/ab/gumbel-sh-vs-visit/eval-ab.json と data/eval/ab/gumbel-sh-vs-visit/eval-ab.metrics.csv に比較結果を保存する。片側だけ変えたい場合は --baseline-set KEY=VALUE / --experiment-set KEY=VALUE を使う。

固定デッキの champion/challenger 評価では、--deck0-manifest / --deck1-manifest と --paired-decks を使う。--paired-decks は総当たりではなく manifest の同じ位置にある deck 同士だけを対戦させる。 pca selfplay-train はこの経路を pca.evaluation.promotion_benchmark 経由で自動実行する。

promotion benchmark の判定材料:

• candidate 対 champion: 7 deck を両 player side で評価した完了試合勝率
• rule-pool 回帰: candidate と champion の deck macro win rate 差
• 安定性: unfinished rate と pokemon-out loss rate の増加量
• seed: candidate/champion、forward/reverse で対応する評価に同じ seed を使う

pca selfplay-trainの既定はpromotion-criteria-mode=anyで、candidate対Championの直接対戦、またはrule-pool勝率と安定性の非回帰条件のどちらかを満たせば正式昇格する。allでは両経路を必須にする。判定後はpromotion-benchmark.jsonへpromotion_gateを追記し、各経路の合否と採用modeを残す。

学習実験で得たcheckpointだけを同じ条件で評価し、続けてgate判定する場合は次を使う。

pca promotion-run \
  --run-name candidate-vs-champion \
  --candidate-checkpoint checkpoints/experiments/candidate-best.pt \
  --champion-checkpoint checkpoints/policy_value_latest_best.pt \
  --resume

出力はdata/eval/promotion-gate/<run-name>/promotion-benchmark.jsonとpromotion-status.txtに保存する。--resumeはcheckpoint、config、deck manifest、試合数、worker、device、seedがすべて一致する完了済みbenchmarkだけを再利用し、gateは現在の閾値で再判定する。--dry-runでは4評価と後続gateのcommandを表示し、試合は実行しない。

rule-pool 評価は data/eval/promotion-gate/cache/ に保存する。cache key には checkpoint 内容、固定 deck、rule config、評価に関係する実装、試合数、worker、device、固定 promotion seed を含める。Candidate が昇格すると、その Candidate の rule 評価が次 cycle の Champion 評価として再利用される。却下時も Champion が変わらないため同じ cache を使う。条件が1つでも変われば cache miss として再評価する。

注意点

• 評価では self-play よりも holdout deck pool と result reason を重視する。
• unfinished が多い場合は search depth/candidate cap/max steps を確認する。
• 新しい探索方式は単独の pca eval だけで良し悪しを判断せず、同じ checkpoint / deck pool / games で A/B 比較する。特に policy0_gumbel_fallback_rate が高い場合は結果を性能差として扱わず、探索設定や実装問題を先に確認する。