コンテンツにスキップ

CABT Official API Notes

更新日: 2026-06-22

確認元

  • https://matsuoinstitute.github.io/cabt/index.html
  • https://matsuoinstitute.github.io/cabt/api.html
  • https://matsuoinstitute.github.io/cabt/game.html
  • https://matsuoinstitute.github.io/cabt/sim.html
  • https://matsuoinstitute.github.io/cabt/utils.html

Observation

公式 docs では Observation は主に次の3要素を持つ。

  • logs: 過去イベントログ
  • current: 現在盤面。初期デッキ選択時は None
  • select: 合法選択。初期デッキ選択時は None

PlayerState.hand は自分のみ visible、相手は None。handCount は常に参照できる。prize は裏向きカードが None で表現される。

実装への影響:

  • features/encoder.py の default public-view encoder は公式仕様に沿っている。
  • policy/value 用 tokens に opponent hand / facedown prize の card id を混ぜない方針は維持する。
  • belief 学習ラベルは通常 Observation からは取れないため、ローカル自己対戦では game.visualize_data() の完全状態を訓練専用に使う。

Game API

公式 docs の game module は以下。

  • battle_start(deck0, deck1) -> tuple[dict | None, StartData]
  • battle_select(select_list) -> dict
  • battle_finish()
  • visualize_data() -> str

battle_start は両プレイヤーの 60枚デッキを受け取り、失敗時は observation が None になる。battle_select は select.option の index list を渡す。

実装への影響:

  • training/selfplay.py の BattleApi protocol はこの形でよい。
  • submission/main.py は obs.select is None のとき 60枚 deck を返す必要がある。
  • visualize_data() は提出 agent が使うものではなく、ローカル訓練データ作成用に限定する。

Search API

公式 docs の search_begin は次を要求する。

search_begin(
  agent_observation,
  your_deck,
  your_prize,
  opponent_deck,
  opponent_prize,
  opponent_hand,
  opponent_active,
  manual_coin=False,
)

重要な制約:

  • agent_observation は agent に渡された observation をそのまま使う。
  • your_deck は自分の山札枚数と整合する必要がある。ただし Observation.select.deck != None のときは無視される。
  • your_prize, opponent_deck, opponent_prize, opponent_hand はそれぞれ表示されている枚数・カウントと整合する必要がある。
  • opponent_active は相手 Active が裏向きの場合のみ必要。

実装への影響:

  • search/belief.py::sample_hidden_state() の出力形式は Search API の入力に対応している。
  • BeliefNet の役割は、Search API に渡す opponent_deck / opponent_prize / opponent_hand の prior を改善すること。
  • 次の実装では cg.api.search_begin/search_step/search_release を包む adapter を search/ または cabt/ に追加し、determinized_policy() へ注入する。
  • src/pca/cabt/search_api.py に公式 cg.api adapter を追加済み。HiddenStateSample を search_begin() の hidden list 引数へそのまま渡し、search_release() は SearchState.searchId を使う。

API module / utils / sim

  • api.all_card_data() はカードメタデータを返す。
  • api.all_attack() は attack metadata を返す。
  • api.to_observation_class() は dict を Observation dataclass に変換する。
  • utils.json_to_dataclass() / utils.to_dataclass() は JSON/dict から dataclass を構築する補助。
  • sim は libcg.so / cg.dll への ctypes binding で、Python-native API ではない。

実装への影響:

  • 現状の card_db.py は CSV から static features を読む実装だが、将来的には api.all_card_data() / api.all_attack() 由来の構造化特徴も検討できる。
  • cg.sim は低レベル境界なので、本体ロジックから直接触るより cg.api / cg.game 経由に寄せる。

現時点の結論

現在の設計は公式 API と概ね整合している。

  • encoder は public observation を使う。
  • belief label は training-only に分離する。
  • hidden state sampler は Search API に必要な hidden lists を生成する。
  • Search API adapter は submission/main.py から環境変数 PCA_SEARCH_DETERMINIZATIONS に応じて使う。初期値は安全側で 1 なので、4 以上にすると公式 Search API 経路が有効になる。
  • 次は search_step() を複数回使う root rollout / MCTS と、探索統計を policy target に反映する部分を厚くする。