self-playモジュール¶

対象: pca.training.selfplay

役割¶

CABT self-play を実行し、1 decision point ごとの SelfPlayRecord を JSONL に保存する。checkpoint policy、search policy、rule agent、remote policy、parallel workers、summary CSV をまとめて扱う。

モジュール一覧¶

モジュール	役割	実装の要点
`__main__.py`	module entrypoint	`python -m pca.training.selfplay` から `cli.main()` を呼ぶ。
`__init__.py`	public facade	package 外向き API を re-export する。
`cli_args.py`	CLI args	self-play の全 option と YAML config parse。
`cli.py`	CLI orchestration	defaults、attack metadata、output/summary writing。
`impl.py`	collection flow	single-process collection と worker execution。
`battle.py`	one-game loop	CABT battle API を進め、pending records と game diagnostics を集める。
`parallel.py`	multiprocessing	worker 分割、local policy batcher、incremental output。
`policy_factory.py`	policy construction	CLI args から player0/player1 policy と oracle policy を作る。
`policies.py`	policy implementations	checkpoint/search/remote/local batch policy、belief prior source 解決。
`records.py`	record assembly	`PendingRecord` を final `SelfPlayRecord` に変換する facade。
`record_targets.py`	training labels	belief label、oracle hidden state、aux prize target を抽出する。
`record_metadata.py`	embedded metadata	visible card / legal attack metadata を JSONL に埋め込む。
`record_io.py`	JSONL I/O	write/truncate/append と lock cleanup。
`decks.py`	deck loading	deck CSV / directory / `DeckSpec`。
`scheduling.py`	game scheduling	global game ID由来のseedとdeck matchup順を決める。
`state.py`	observation state	current player/result helpers。
`agents.py`	rule-agent metadata	rule-agent assignment summary。
`diagnostic_outcomes.py`	outcome helpers	result reason、policy target normalization、softmax scores。
`diagnostic_stats.py`	stats collection	policy/search/CABT runtime stats を diagnostics に反映する。
`diagnostics.py`	log rendering	board/perf/search sections を組み立てる。
`game_metrics.py`	per-game telemetry	game summaryを比較用metricへ変換し、MLflowとresume-safe JSONLへ記録する。
`summary_stats.py`	summary stats	deck/agent/matchup table の集計。
`summary_display.py`	console output	summary table の表示。
`summary_csv.py`	CSV output	deck/agent/matchup と gameごとの探索診断 CSV。
`summary.py`	summary facade	summary 系 API の re-export。
`runner.py`	runner facade	battle runner の re-export。
`formatting.py`	log formatting	ANSI color と section helper。
`types.py`	shared types	`SelfPlayConfig`, `SelfPlaySummary`, `PendingRecord`, `DeckSpec`, worker args。

公開API¶

API	用途
`run_selfplay_battle(...)`	1 game の records と summary を返す。
`collect_selfplay_games(...)`	single-process collection。
`collect_selfplay_games_parallel(...)`	worker 並列 collection。
`make_pending_record(...)`	decision point record の中間表現を作る。
`finalize_records(...)`	game 終了後に result/value/aux target を確定する。
`write_records_jsonl(...)` / `append_records_jsonl(...)`	JSONL 出力。
`selfplay_game_metrics(summary)`	1 gameの結果・盤面・行動・探索・速度を数値化する。
`record_selfplay_game_metrics(...)`	game ID順でJSONL/MLflowへ記録し移動値を計算する。

CLIの使い方¶

PYTHONPATH=src uv run python -m pca.training.selfplay \
  --config configs/v14/selfplay-gumbel-sh-ismcts.yaml \
  --output data/selfplay/example.jsonl \
  --game-metrics-output data/selfplay/example.game-metrics.jsonl \
  --search-diagnostics-output data/selfplay/example.search-diagnostics.csv \
  --games 100 \
  --workers 8

注意点¶

長時間実行では incremental JSONL append を使う。中断しても完了 game の record は残る。
--search-diagnostics-output は game ごとの平均探索深さ、visit のroot実効候補数、Gumbel sequential-halving の候補数・round数・round別simulation配分・round別深さを CSV に保存する。 selfplay-train のchunk実行では *.search-diagnostics.csv を自動生成する。
records.py は facade。label 抽出や I/O の実体は record_targets.py / record_io.py に分かれている。
pca selfplay-train は scripts/run_selfplay_train.sh を入口に、self-play、train、promotion benchmark、latest alias 更新を順に行う。既定では configs/benchmarks/model-decks-v1.yaml の固定7デッキで candidate と直前 champion を比較する。
通常のpca selfplay-trainはpipeline run IDごとの親MLflow runとcycleごとの子runを自動作成する。self-play chunk完了ごとにgame品質、探索、性能の試合別metricを子runへ記録し、cycle完了時には最終指標を親runのcycle番号stepへ集約する。--resumeでは保存済みの親子MLflow run IDを再利用する。
game_metrics.pyは全試合をselfplay/game/*へstep=game_idで記録し、直近20/100試合の移動値も作る。*.game-metrics.jsonlにはMLflowへ送らないdeck/agent dimensionとraw diagnosticsも保持し、既存game IDを読み飛ばして再開時の重複を防ぐ。
self-play telemetryは勝率のWilson 95%信頼区間、setup/energy/evolve/trainerの見送り率、攻撃可能時END、攻撃せずturn終了、初回攻撃可能turnを含む。探索はdepthだけでなくprior/visit/Q entropy、Gumbel候補数・round数、NN/encoder/ISMCTS時間を分離して記録する。
leaf batching telemetry は平均item数に加えて unique leaf 比率と information-set collision比率を記録する。--ismcts-reuse-root-states は実CABTで完全同値にならなかったため既定無効で、v14の通常実行でも有効化しない。
各chunkの先頭gameと、未完了・Gumbel fallback・攻撃可能turn終了などの異常gameは、件数上限付きで selfplay.game MLflow Traceにも保存する。summaryの実game ID、deck、結果、step数、異常理由から該当JSONLを追跡できる。
promotionは同じbenchmarkを正式52%と学習継続50%の二段階で判定する。既定のany方式では、直接対戦の閾値またはrule-pool非回帰条件のどちらかで正式合格できる。正式合格時はcandidate bestを通常のlatest aliasへ、学習継続だけの合格時はtraining latest aliasと次cycleのcheckpointへ反映する。正式Championは直接対戦またはrule-poolの正式基準を満たすまで維持する。--resume では checkpoint ごとの .promotion-status を読み、完了済み評価を再実行しない。
既定V14 profileは両方のtierで初回却下時に同じTraining Championと同じdata splitからretry candidateを独立学習する。retry群はvalidation lossで1つに絞ってからpromotionを一度だけ再実行し、全候補却下時は次cycleを停止する。 pca.training.retry_selectionが候補条件と選抜結果をJSONへ保存する。
V14のtrain profileは--d-model 256と--num-layers 4を明示する。128次元checkpointからの移行時はshapeが一致するparameterだけを読み込み、残りを新規初期化して警告とload reportを出す。256次元のcheckpointが一度昇格した後は、以降のcycleで同じshapeを完全warm startできる。
pipeline chunk offsetはworkerのgame_idへ加算される。merged JSONL、validation split、replay、game metricsで同じrun内のgame IDが重複しない。
V14のself-playは--deck-sampling balanced_pairsを使う。uniform weightのplayer 0 / player 1 poolについて、全ordered pairを一巡してから次のcycleへ進む。30対30 decksでは900 gamesで900 matchupsを一度ずつ使い、30 games単位の途中経過でも両poolの周辺出現数を均等に保つ。異なる match_weightを使うrule poolはweighted_randomを指定する。
deck選択、search policy、oracle policyのseedはbase seedとglobal game IDから分離して導出する。同じglobal game IDならworker数、chunk境界、--resumeの有無にかかわらず同じdeck matchupと乱数系列を使う。chunk実行では全chunkへ同じbase seedを渡し、global game IDで系列を分ける。
--no-promotion-gate は診断や短い smoke 用の明示的な opt-out であり、通常の反復学習では使用しない。
rule-pool の Champion 評価は fingerprint 付きで cache する。self-play の cycle seed とは別に --promotion-seed を固定し、前 cycle の promoted Candidate 評価または却下後の同一 Champion 評価を再利用する。--no-promotion-rule-cache で明示的に無効化できる。