Tools and Config Modules¶

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

Purpose¶

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

Modules¶

Module	Role	Implementation Details
`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 を防ぐ。
`configs/`	run configs	self-play / train / evaluation の長い option 群を YAML 化する。
`scripts/`	wrappers	local/Docker/server 実行を shell script としてまとめる。

Public API¶

API	Usage
`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 を作る。

Usage¶

統一入口:

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 --train-device mps --resume
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 \
  --train-device mps \
  --resume

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

個別 tool:

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

YAML config の例:

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

Notes¶

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 で保存先を変えられる。