Directory Layout¶
更新日: 2026-07-04
方針¶
このリポジトリは、CABT シミュレーター境界、探索、学習、評価、提出 bundle を分けて管理する。 現行手法の全体像は current-method.md を正とし、この文書は実際のコード配置を説明する。
configs/は長い self-play / evaluation コマンドを再利用するための設定。data/は self-play JSONL、評価 JSON/CSV、replay HTML などの生成物。decks/は学習・評価に使うデッキプール。docs/は調査、設計判断、共有用の手法説明。notebooks/は Kaggle self-play 収集などの実行補助。sample/は公式サンプル、viewer、可視化実験。現行本体からは依存しない。scripts/は Docker / notebook bundle / replay / evaluation などの実行 wrapper。共通 shell 処理はscripts/lib/に置く。src/pca/はエージェント本体。tests/はsrc/pca/の単体・統合テスト。
主要ディレクトリ¶
configs/
└─ v12/ # self-play / evaluation 用 YAML 設定
data/
├─ selfplay/ # training.train / belief_train の入力 JSONL
├─ eval/ # tournament 評価結果 JSON/CSV
└─ replays/ # HTML replay
decks/
├─ own/ # 提出候補デッキを置く場所
└─ opponents/
├─ train/ # 汎用 self-play のデッキプール
└─ holdout/ # 評価用 holdout デッキ
notebooks/
└─ selfplay_collect.ipynb # Kaggle 上で self-play JSONL を集める notebook
scripts/
├─ lib/ # local Python / CABT Docker wrapper の共通処理
├─ collect_selfplay_local.sh # macOS / local Python で self-play 収集
├─ evaluate_local.sh # macOS / local Python で評価
├─ collect_selfplay_docker.sh # Docker で self-play 収集
├─ evaluate_docker.sh # Docker で評価
├─ render_match_replay_docker.sh
└─ build_notebook_bundle.py # Kaggle input 用 bundle 作成
src/pca/
├─ cabt/
│ ├─ card_db.py # CardStaticFeatures / EN_Card_Data.csv 参照
│ ├─ schema.py # CABT API 境界の軽量 schema
│ └─ search_api.py # CABT search API wrapper
├─ data/
│ └─ deck_pool.py # デッキプール読み込み
├─ features/
│ └─ encoder.py # observation / legal option の特徴量化
├─ models/
│ ├─ belief.py # BeliefNet
│ ├─ policy_value.py # legacy ActionConditionedPolicyValueNet
│ └─ policy_value_unified/ # v13 UnifiedTokenPolicyValueNet
├─ decision/
│ ├─ policy.py # checkpoint / search policy adapter
│ ├─ remote_policy.py # local Mac policy server 連携
│ └─ reranker.py # heuristic reranker 実験
├─ search/
│ ├─ belief.py # hidden state sampling / PublicKnowledgeTracker
│ ├─ determinized.py # legacy determinized search
│ ├─ ismcts/ # 現行 Belief-Guided Neural ISMCTS package
│ │ ├─ __init__.py # 互換 entrypoint / public re-export
│ │ ├─ impl.py # root policy orchestration
│ │ ├─ config.py # ISMCTSConfig / SearchApi Protocol
│ │ ├─ runtime_stats.py # ISMCTSRuntimeStats
│ │ ├─ tree.py # ISMCTSNode / ISMCTSTree
│ │ ├─ simulation_types.py # deferred / completed simulation dataclasses
│ │ ├─ types.py # compatibility facade
│ │ ├─ public_state.py # information-set / public token helpers
│ │ ├─ actions.py # candidate / PUCT / visit selection helpers
│ │ ├─ simulation.py # simulation loop / leaf value / leaf batching
│ │ └─ policy.py # policy entry facade
│ └─ mcts.py # value shaping / search value utilities
├─ training/
│ ├─ selfplay/ # CABT self-play JSONL generation package
│ │ ├─ __init__.py # 互換 entrypoint / public re-export
│ │ ├─ __main__.py # `python -m pca.training.selfplay`
│ │ ├─ impl.py # orchestration / parent-worker flow
│ │ ├─ types.py # dataclass / Protocol / 定数
│ │ ├─ state.py # public observation state helpers
│ │ ├─ diagnostics.py # diagnostics 表示 / result helper
│ │ ├─ diagnostic_outcomes.py # result reason / policy target helpers
│ │ ├─ diagnostic_stats.py # runtime/search diagnostic stats collection
│ │ ├─ formatting.py # ANSI 色 / ログ表示 helper
│ │ ├─ decks.py # deck CSV loading / deck-pool sampling
│ │ ├─ battle.py # single-game self-play execution / CG adapter
│ │ ├─ agents.py # rule-agent summary / mixed-policy helpers
│ │ ├─ summary.py # summary compatibility facade
│ │ ├─ summary_stats.py # aggregate stats / table rows
│ │ ├─ summary_display.py # console summary rendering
│ │ ├─ summary_csv.py # summary CSV writers
│ │ ├─ records.py # training record assembly facade
│ │ ├─ record_targets.py # belief / aux prize / oracle hidden targets
│ │ ├─ record_metadata.py # embedded card / attack metadata
│ │ ├─ record_io.py # JSONL write / append / truncate / lock cleanup
│ │ ├─ policies.py # policy / checkpoint / belief prior / search policy
│ │ ├─ policy_factory.py # CLI worker args から policy / oracle factory を構築
│ │ ├─ parallel.py # multiprocessing / local batcher / stream output
│ │ ├─ runner.py # battle runner / worker facade
│ │ ├─ cli_args.py # CLI argument definitions / config parse
│ │ └─ cli.py # CLI defaults / entrypoint wrapper
│ ├─ train.py # Policy/Value training CLI / loop facade
│ ├─ policy_value/ # Policy/Value training helper package
│ │ ├─ __init__.py # public re-export
│ │ ├─ checkpointing.py # checkpoint payload / metadata
│ │ ├─ config.py # TrainConfig / data summary
│ │ ├─ data.py # search record summary / streaming dataloader
│ │ ├─ losses.py # policy/value/aux/belief loss
│ │ ├─ metadata.py # JSONL embedded card/attack metadata loader
│ │ ├─ model_config.py # model_config resolution / compatible load
│ │ └─ runtime.py # device / memory / progress / scheduler helper
│ ├─ belief_train.py # BeliefNet training CLI / compatibility facade
│ ├─ belief/ # BeliefNet training helper package
│ │ ├─ __init__.py # public re-export
│ │ ├─ checkpointing.py # checkpoint payload / metadata
│ │ ├─ config.py # BeliefTrainConfig
│ │ ├─ data.py # belief record filtering / streaming dataloader
│ │ ├─ losses.py # belief supervised loss
│ │ └─ runner.py # BeliefNet training loop
│ ├─ dataset.py # training.data compatibility facade
│ ├─ data/ # JSONL loading / filtering / batch collation
│ │ ├─ __init__.py # public re-export
│ │ ├─ belief_collate.py # BeliefBatch collation
│ │ ├─ collate_utils.py # card id / multi-hot / object padding helpers
│ │ ├─ records.py # JSONL record loading / filtering
│ │ ├─ search_collate.py # SearchBatch collation
│ │ ├─ types.py # SearchBatch / BeliefBatch dataclasses
│ │ └─ weights.py # teacher policy/value weighting heuristics
│ └─ targets.py # training record schema
├─ evaluation/
│ ├─ tournament/ # デッキ間評価 / metrics / CSV package
│ │ ├─ __init__.py # 互換 entrypoint / public re-export
│ │ ├─ __main__.py # `python -m pca.evaluation.tournament`
│ │ ├─ impl.py # 現行実体
│ │ ├─ agents.py # agent factory facade
│ │ ├─ deck_pool.py # deck-pool evaluation facade
│ │ ├─ matches.py # match execution facade
│ │ ├─ summaries.py # metrics / CSV
│ │ ├─ cli.py # CLI facade
│ │ └─ types.py # dataclass / type
│ ├─ bundle_battle.py
│ └─ bundle_loader.py
├─ serving/
│ └─ policy_server.py # Mac MPS / CUDA policy server 実験
└─ submission/
├─ main.py # Kaggle 提出 entrypoint
└─ build_bundle.py # 提出 bundle 作成
境界ルール¶
- CABT 固有の API 変換は
cabt/とfeatures/に寄せる。 - Torch に依存するモデル本体は
models/、学習ループはtraining/、推論 adapter はdecision/に置く。 - ISMCTS の tree policy / hidden sampling / diagnostics は
search/ismcts/とsearch/belief.pyに閉じる。探索フローはimpl.py、型と tree state はtypes.py、候補手選択はactions.py、public observation のキー化はpublic_state.pyに置く。 - 評価指標は
evaluation/tournament/に集約し、self-play ログ固有のものはtraining/selfplay/に置く。 - 大きい CLI module は、既存 import /
python -m互換を保つ package facade と、現行実体のimpl.py、責務別 facade に分ける。 - Kaggle 提出で直接呼ばれる entrypoint は
submission/に置く。 sample/の viewer や実験コードからsrc/pca/を import してよいが、src/pca/からsample/へ依存しない。docs/PLAN.mdは大方針、docs/architecture/current-method.mdは現行手法、ここはコード配置の最新状態を示す。