ツール・設定モジュール¶

対象: pca.tools, pca.cli, config/YAML helpers

役割¶

補助ツール、統一 CLI entrypoint、設定ファイルの扱いを説明する。大規模 self-play / training / evaluation は CLI option が長いため、pca command、YAML profile、command-specific YAML、script wrapper を併用する。

モジュール一覧¶

モジュール	役割	実装の要点
`pca.tools.export_attack_data`	attack metadata export	CABT 公式 API から attack metadata を JSON に出力し、v13 static attack embedding に使う。
`pca.__main__`	package entrypoint	`python -m pca` から `pca.cli.main()` を呼ぶ。
`pca.cli`	unified command	`pca selfplay/train/eval/...` を受け取り、profile の default を既存 CLI へ委譲する。
`pca.app_config`	app profile dataclasses	`configs/default.yaml` を dataclass に読み、command defaults を argv に変換する。
`pca.cli_config`	YAML config parser	flat YAML を argparse default に反映する。unknown key は検出して typo を防ぐ。
`pca.tools.mlflow_log_manifest`	MLflow manifest logger	`pca selfplay-train` の run manifest を MLflow run に記録する。
`pca.tools.mlflow_tracking`	live MLflow lifecycle	pipeline親runとcycle子runの作成/再開/終了、cycle指標集約、Notesとmetric catalog登録。
`pca.tools.telemetry_runner`	stage telemetry wrapper	child process treeのsystem metricsを収集し、stage単位のMLflow traceを記録する。
`pca.training.metric_catalog`	metric metadata	metric patternごとの日本語説明、単位、変化方向、注意点を一元管理する。
`pca.training.champion_adoption`	Champion adoption	外部実験の昇格結果を検証し、latest / ledger / replayを一括更新する。
`pca.training.telemetry`	live metrics	append-only JSONL、MLflow metrics、CPU/RAM/disk/network/NVIDIA GPU sampler。
`pca.training.tracing`	sampled traces	stage、validation、代表/異常self-play gameをMLflow Traceへ記録する。
`configs/`	run configs	self-play / train / evaluation の長い option 群を YAML 化する。
`dvc.yaml` / `params.yaml`	MLOps pipeline	DVC で self-play/train と MLflow logging の依存関係を表す。
`scripts/`	wrappers	local/Docker/server 実行を shell script としてまとめる。

公開API¶

API	用途
`pca.cli.main(argv)`	統一 CLI entrypoint。profile を読み、既存 command へ委譲する。
`load_app_profile(path)`	v14 などの top-level profile YAML を読む。
`args_mapping_to_argv(args)`	profile の mapping を CLI option list に変換する。
`parse_args_with_config(parser, section)`	CLI parser に YAML default を適用する。
`pca.tools.export_attack_data.main()`	attack metadata JSON を作る。
`pca.tools.mlflow_log_manifest.main()`	過去run manifestをMLflowへ手動登録する。
`pca.tools.mlflow_tracking.main()`	通常はselfplay-train wrapperから呼ぶrun lifecycle。
`TelemetrySink.log_metrics(stage, ...)`	JSONLと既存MLflow runへ同じmetricを記録する。
`SystemMetricsSampler`	stage process treeを既定15秒間隔で監視する。
`TraceOperation`	validationなどの処理区間を成功/失敗を含むtraceにする。

使い方¶

統一入口:

pca commands
pca train --input data/selfplay/custom.jsonl --device mps
pca selfplay --games 100 --workers 8
pca selfplay-train --total-games 10000 --games-per-cycle 1000 --chunks 10 --workers 8 --resume
pca promote-checkpoint --help
pca eval --games 20 --device cpu

pca command は configs/default.yaml を default profile として読む。profile は command ごとの最新 config を指す薄い layer であり、利用者が --model-class unified などを毎回指定しなくて済むようにする。

commands:
  train:
    module: pca.training.train
    args:
      config: configs/v13/train-policy-unified-selfplay.yaml

別 profile を使う場合:

pca --profile configs/default.yaml train --device cpu

実行せず delegated command だけ確認する場合:

pca --print-command train --input data/selfplay/custom.jsonl

selfplay-train は train stage 完了後に checkpoints/policy_value_latest_best.pt と run-name scoped alias を更新する。次の収集・学習を最新 checkpoint から始める場合は次のように指定する。

pca selfplay-train \
  --checkpoint checkpoints/policy_value_latest_best.pt \
  --run-name next-selfplay \
  --total-games 10000 \
  --games-per-cycle 1000 \
  --chunks 10 \
  --workers 8 \
  --resume

pipeline外のtrain-compareで作ったcheckpointは、pca promotion-runが評価と判定を担当し、pca promote-checkpointが合格結果を運用状態へ反映する。後者は評価時のCandidate / Champion fingerprintと現在latestを照合し、古い評価結果による上書きを拒否する。

既定profileはself-playとpromotion評価をCPU、trainをMPS、self-play precisionをfp32に固定する。異なるhardwareで実行する場合だけ各device optionを上書きする。

--games-per-cycle は「何試合 self-play したら学習するか」を表す。--total-games を一緒に指定すると必要な cycle 数を自動計算し、最後の cycle だけ端数試合にできる。--chunks は各 cycle 内の分割数で、--games-per-cycle 1000 --chunks 10 なら 1 chunk 100 試合になる。

同じpipeline run IDは既定でpokemon-card-ai MLflow experimentの親runにまとまり、各cycleは子runとして記録される。親runはcycle番号をstepにした全体推移、子runはcycle内の詳細を持つ。backendはsqlite:///mlflow.db、UIはmise run mlflow:uiで起動する。--no-mlflowでもappend-only metrics JSONLは維持される。

self-playの各試合は子runのselfplay/game/*へgame IDをstepとして記録する。直近20/100試合の移動値はMLflowで傾向を確認し、deck/agent名とraw diagnosticsはdata/selfplay/*.game-metrics.jsonlから分析する。chunk完了時に親processが一括反映し、--resumeでは既存game IDを重複記録しない。

各stageはpca.tools.telemetry_runnerから起動され、CPU/RAM/disk/networkとNVIDIA GPUを15秒間隔で記録する。同じ子cycle runのTracesにはstage所要時間、validation、cycle先頭の代表game、未完了や探索fallbackなどの異常gameだけを保存する。全simulationや全training batchをtrace化しないため、長時間runでも記録量は制限される。

親runへのcycle集約ではtrain/validation gap、replay量、Candidate対ChampionのWilson 95%信頼区間、rule-poolのmacro/microおよび固定デッキ別勝率を保持する。metric名のデッキ部分はMLflowで扱えるstemへ正規化する。

run開始時にmlflow.note.contentへ短い日本語ガイドを設定し、Artifacts/metadataへ全metric patternのmetrics-reference.md/jsonを保存する。run終了時には実際に観測されたmetricだけを metrics-catalog.md/jsonへ出力する。catalog生成やMLflowへの登録に失敗しても、学習本体はwarningを出して継続する。

--selfplay-precision fp16 は self-play stage だけに効く。script は元の checkpoint から checkpoints/quantized/<run_name>/*_fp16.pt を作り、pca.training.selfplay へ --policy-precision fp16 と一緒に渡す。train stage の --init-checkpoint は元の fp32 checkpoint のままなので、学習済み重みと latest alias の扱いは従来と同じ。

複数 NVIDIA GPU で self-play を分散する場合は --selfplay-devices auto を使う。これは pca.training.selfplay --worker-devices auto に展開され、visible な CUDA device へ worker を round-robin に割り当てる。手動指定は --selfplay-devices cuda:0,cuda:1。

個別 tool:

PYTHONPATH=src uv run python -m pca.tools.export_attack_data \
  --output data/metadata/attacks.json

PYTHONPATH=src uv run python -m pca.tools.convert_checkpoint_precision \
  --input checkpoints/policy_value_latest_best.pt \
  --output checkpoints/quantized/manual/policy_value_latest_best_fp16.pt \
  --precision fp16

MLOps pipeline:

uv sync --group mlops
uv run --group mlops dvc dag
uv run --group mlops dvc repro selfplay_train
uv run --group mlops dvc repro log_mlflow

YAML config の例:

selfplay:
  games: 1000
  workers: 8
  policy: search
  search-mode: ismcts

注意点¶

top-level profile は「今どの config を標準にするか」を表す。v15/v16 に進んだら configs/default.yaml の参照先を更新する。
command-specific YAML は既存の self-play / train / eval parser が読む。top-level profile はそれを --config として渡すだけに留める。
CLI option は profile / command YAML より優先される。
YAML key は argparse dest と対応する。max-steps と max_steps のような表記揺れは吸収する。
実行生成物は data/、学習済み checkpoint は checkpoints/ に置く。
latest checkpoint alias は configs/default.yaml の selfplay-train.args.latest-dir で保存先を変えられる。