Submission and Serving Modules¶

対象: pca.submission, pca.serving

Purpose¶

学習済み checkpoint を Kaggle 提出 runtime とローカル実験 runtime で使うための module 群である。提出では model server を立てず、submission.tar.gz に main.py、deck.csv、policy_value.pt、pca/ package を同梱し、pca.submission.main が checkpoint を直接ロードして行動を返す。

pca.serving.policy_server は self-play / evaluation の推論を別 process に逃がすための補助機能であり、提出 bundle の標準経路ではない。

Modules¶

Module	Role	Implementation Details
`pca.submission.main`	Kaggle agent	Kaggle runtime の observation を受け、同梱された deck / checkpoint / optional opponent deck pool / search 設定を使って selected option を返す。
`pca.submission.build_bundle`	bundle builder	`src/pca`、checkpoint、card data、deck、opponent deck pool を Kaggle 提出用 `submission.tar.gz` に固める。
`pca.serving.policy_server`	HTTP inference server	checkpoint model をロードし、`/predict` で observation から `PolicyDecision` JSON を返す。self-play worker から NN 推論を分離したい時だけ使う。

Public API¶

API	Usage
`pca.submission.main.agent(obs)`	Kaggle runtime が呼ぶ提出 entrypoint。
`pca.submission.build_bundle.main()`	提出 bundle を作る CLI entrypoint。
`pca.serving.policy_server.main()`	ローカル実験用 HTTP server を起動する。

Submission Bundle¶

通常は top-level profile 経由で作る。

pca submission-bundle \
  --checkpoint checkpoints/policy_value_latest_best.pt \
  --output dist/submission.tar.gz

configs/default.yaml の submission-bundle は標準で次を同梱する。

Bundle Path	Source
`main.py`	`src/pca/submission/main.py`
`deck.csv`	`decks/own/mega-abomasnow/deck.csv`
`policy_value.pt`	`checkpoints/policy_value_latest_best.pt`
`card_data.csv`	`pokemon-tcg-ai-battle/EN_Card_Data.csv`
`opponent_decks.json`	`decks/opponents/*/.csv`
`pca/`	`src/pca`

policy_value_latest_best.pt は selfplay-train 完了時に最新 best checkpoint へ更新されるため、self-play / train / eval と同じ感覚で「最新モデルを使う」運用にできる。特定 checkpoint を提出したい場合だけ --checkpoint checkpoints/xxx_best.pt で上書きする。

Runtime Behavior¶

提出 runtime では pca.submission.main が以下の順で動く。

deck.csv を読み、自分の 60 枚 deck を返す。
policy_value.pt が存在すれば load_policy_value_checkpoint() で直接ロードする。
card_data.csv があれば static card feature / vocab metadata に使う。
opponent_decks.json があれば hidden-state prior / search 用の相手 deck pool として使う。
observation ごとに NN policy、または環境変数で有効化された search policy で selected option を返す。

重要なのは、提出時に HTTP server は不要という点である。bundle 内の Python と checkpoint だけで完結する。

Optional Search¶

提出 bundle は同じ checkpoint を使い、環境変数で探索を有効化できる。

PCA_ENABLE_SEARCH=1
PCA_SEARCH_MODE=ismcts
PCA_ISMCTS_DETERMINIZATIONS=4
PCA_ISMCTS_SIMULATIONS_PER_DETERMINIZATION=32
PCA_TIME_BUDGET_SECONDS=540

Kaggle の制限時間に合わせる必要があるため、提出標準は軽量な NN policy を基本にし、search は検証済みの値だけを使う。

Local Policy Server¶

pca.serving.policy_server は提出用ではなく、ローカル self-play / evaluation で NN forward を別 process に分離したい時の補助機能である。

PYTHONPATH=src uv run python -m pca.serving.policy_server \
  --checkpoint checkpoints/policy_value_latest_best.pt \
  --device mps \
  --host 127.0.0.1 \
  --port 8765

self-play 側で使う場合:

PYTHONPATH=src uv run python -m pca.training.selfplay \
  --policy search \
  --remote-policy-url http://127.0.0.1:8765/predict

Notes¶

提出 bundle は sample/ や local-only script に依存しない。
build_bundle は checkpoint を policy_value.pt という固定名で bundle に入れる。submission.main もこの名前を探す。
pca.serving.policy_server の response は PolicyDecision の JSON 表現と互換だが、Kaggle 提出 runtime の標準経路には入れない。