プロジェクトロードマップ¶

更新日: 2026-07-24

この文書には、Pokemon Card AIを継続的に強くするための現在のロードマップを記載する。初期計画は docs/PLAN.md、実験の根拠はdocs/journal/とdocs/research/、実装済みの仕様はアーキテクチャを参照する。

目標¶

最終目標は、限られた推論予算で多様なデッキを扱い、未知情報を考慮しながらポケモンカードとして一貫した手順を実行できるエージェントを作ることである。

強さは勝率だけで判断しない。少なくとも次を同時に改善する。

固定したルールエージェント群、過去のチェックポイント、候補モデルに対する先後入れ替え勝率
平均取得サイド、攻撃回数、ポケモン切れ、山札切れ、未完了の割合
攻撃可能ターンの未攻撃率、空ベンチ、エネルギーや進化の機会を使わなかった割合
教師方策に対する正解率とKLダイバージェンス、教師分布のエントロピー、Valueの較正
1回の意思決定にかかる時間、ニューラルネットワークの呼び出し回数、探索深度、攻撃やサイド取得へ到達した割合
Gumbelからの退避、探索失敗、チェックポイントと学習データの系譜を追跡できること

現在地¶

現在の主モデルはUnifiedTokenPolicyValueNetで、d_model=256、共有Transformer 4層、Policy・Value・サイド取得補助・Beliefの複数ヘッドを持つ。自己対戦では、ルートにGumbel Sequential Halvingを適用したBelief-Guided Neural ISMCTSを使用している。

V14の反復学習では、次の状態まで進んだ。

サイクル1は、乱数シードと試合IDの重複、デッキ分布の偏りを特定して却下した。
サイクル2は、終了試合でV13サイクル10のChampionに65.44%で勝ち、正式昇格した。
サイクル3は、複数ヘッドの損失バランスを調整した試行Mが、旧Championとの直接対戦で51.47%、ルールエージェント群との対戦で22.32%を記録した。直接対戦は正式基準の52%に届かなかったが、ルールエージェント群に対する改善条件を満たして正式昇格した。
現在のChampionは checkpoints/experiments/v14-cycle003-multi-head-balance/attempt-m-best.ptである。
サイクル4は、このChampionから自己対戦データを生成中である。学習と昇格評価はまだ完了していない。

学習パイプラインには、試合単位の学習・検証分割、昇格済みデータの再利用、候補モデルとChampionの直接対戦、ルールエージェント群による回帰評価、最新モデルの別名の保護、MLflow・DVCによる追跡を導入済みである。

現在の主な未解決事項は次の通り。

サイクル3の改善幅は小さく、複数サイクルにわたって安定して強くなるかは未確認である。
デッキ別の性能差が大きく、Starmie・ArchaludonやIono・Belliboltで回帰や未完了が発生しやすい。
検証時のPolicy指標とオンライン対戦の強さが必ずしも一致しない。
Value損失、サイド取得補助損失、Belief損失が共有表現へ与える影響は、1サイクル分しか確認できていない。
探索で生成した教師方策が、ニューラルネットワーク単体よりどの局面でも優れているとはまだ証明できていない。
残存山札、相手のデッキ候補、行動後の盤面変化をモデルへ明示的に渡していない。

開発原則¶

計測してから拡張する。モデル規模や試合数を増やす前に、固定評価と検証データで改善を確認する。
探索を教師として監査する。探索が作る教師方策が元のPolicyより強いと仮定せず、高予算探索と戦術プローブで検証する。
改善したモデルだけ昇格する。最新モデルの別名は、学習損失ではなく昇格判定の結果に基づいて更新する。
過去の良い経験を保持する。直近と過去の自己対戦、ルールエージェントとの対戦、明確な失敗例を再生データとして管理する。
ポケカ固有の不完全情報を明示する。相手のデッキ候補、残存山札、相手の脅威を、カードごとの独立した予測だけに任せない。
一度に一つの仮説を比較する。チェックポイント、乱数シード、デッキの組み合わせ、先後、シミュレーション数を揃えてA/Bテストを行う。

全体フェーズ¶

段階	状態	主題	到達目標
0	完了	基準モデルと探索の妥当性	再現可能な固定評価と正しい探索統計
1	効果を検証中	学習ループの安定化	再生データ、検証、昇格判定による回帰防止
2	効果を検証中	探索による教師方策の改善	同じシミュレーション予算でより良い教師方策
3	次に実施	入力表現とBelief	残存山札、行動結果、相手の脅威を明示
4	効果を検証中	モデルと学習目的	共有表現と複数ヘッドの安定した同時学習
5	計画済み	対戦相手群と大規模学習	多様な相手に対する安定した反復改善
6	継続的に実施	提出・性能・運用	再現可能で高速な提出用生成物

段階0: 基準モデルと探索の妥当性¶

状態: 完了

固定7デッキによる先後入れ替え評価、ルールエージェント群との対戦、戦術プローブ、探索診断を実装した。同一チェックポイント・同一シミュレーション数の比較では、GumbelがVisitに対して終了試合で56.4%となり、V14の自己対戦設定に採用した。

実施項目¶

候補モデルとChampionを固定7デッキ、同じ乱数シード、先後入れ替えで比較できる評価条件
モデル対ルールエージェントを先後入れ替えで実行する評価
Visit 480シミュレーション、決定的なGumbel 480シミュレーション、高予算Visitの比較
攻撃可能時のターン終了、攻撃しなかったターン、空ベンチ、エネルギー・進化機会の未使用を試合単位で集計
ISMCTSの予算消費、葉ノードのバッチ、深度、Q値とVisitのエントロピー、退避処理の診断
攻撃、エネルギー、進化、ベンチ準備、にげる、サイドレースを含む戦術プローブ用データ

Gumbel Sequential Halvingは、探索数を減らすためではなく、現在の480シミュレーションを有望なルート行動へ配分する方式として評価する。評価時はノイズとスコア補正を切った決定的な設定、自己対戦時は探索の多様性を持つ設定を使い分ける。

2026-07-12から13の直接対戦では、同一チェックポイント、固定7デッキ、プレイヤー位置の入れ替えで560試合を実施し、Gumbelが決着509試合中287勝、56.4%となった。95%信頼区間は52.0%から60.6%であり、同じ480シミュレーションにおける先後入れ替え勝率の基準を満たした。詳細は評価レポートを参照する。

完了条件¶

同じ評価を再実行して、デッキの組み合わせ、乱数シード、先後、チェックポイントを追跡できる
GumbelとVisitのすべての意思決定で、シミュレーション予算、退避処理、実際のVisit・Q分布を説明できる
サイクル間の比較を学習損失ではなく固定した外部評価で行える
攻撃可能だったのに攻撃せずターンを終えた割合をチェックポイントごとに比較できる

段階1: 学習ループの安定化¶

状態: 主要機能は実装済み、サイクルをまたいだ効果を検証中

実施項目¶

試合単位の学習・検証分割を実装済み。隣接する意思決定が両方へ混ざらない。
直近の自己対戦をすべて使用し、過去3つの昇格済みサイクルから直近試合数の25%を 50% / 30% / 20%で追加する再生データを実装済み。
現在のChampionと候補モデルを固定7デッキ・先後入れ替えで比較し、ルールエージェント群に対する相対回帰も測る昇格判定を実装済み。
latestの別名は昇格時だけ更新する。外部実験のチェックポイントも、評価結果とハッシュを検証してから正式採用できる。
DVCとMLflowへ、データの構成、親チェックポイント、設定、学習指標、昇格結果、システム指標、トレースを記録する。
現在のV14学習設定は1エポック、実効バッチ64、学習率1e-5、勾配クリップ10.0である。
未実装なのは、過去の昇格済みモデルを複数含む対戦相手リーグと、検証指標に基づく早期終了である。

この段階は、AlphaGo Zero型の自己対戦、再生データ、評価、最良モデルの更新を土台にする。ただし、ルールエージェントの教師データと明確な失敗例はポケカ向けの追加要素であり、永続的な正解ラベルとはみなさない。

完了条件¶

候補モデルが固定評価を悪化させた場合、最新チェックポイントが更新されない
ルールエージェントによる初期学習データを除いた場合と混ぜた場合の忘却を、検証データで比較できる
すべての昇格済みチェックポイントについて、親データと親チェックポイントを実行記録からたどれる
3サイクル以上で外部評価が継続的に改善し、単発の学習損失低下だけに依存しない

段階2: 探索が作る教師方策の改善¶

状態: Gumbel探索と学習ターゲットは実装済み、教師品質を検証中

実施項目¶

Visit 480とGumbel 480の先後入れ替えA/Bテスト（560試合でGumbel 56.4%、実施済み）
Gumbelの初期候補と最終候補を別々に対戦記録のメタデータへ保存する
全合法手の事前logitと補完Q値を使う滑らかな教師方策（実装済み）の評価
Visitと補完Q値を混ぜた教師方策。Q値の較正に応じて混合比を調整する
強制選択、同値のカード選択、実質的な一択を探索深度から除外する仕組み
ターン終了、攻撃、きぜつまでをPolicyで短く継続する比較実験
高予算探索を基準とした行動一致率と後悔量の評価

ルートのGumbelはVisitと同じ固定された非公開状態の候補群を再利用する。ルート以外ではPUCTを維持する。gumbel-scope: treeは論文の完全な木内Gumbel選択ではないため、ルート限定方式とは別の比較条件として扱う。

完了条件¶

同じ480シミュレーションで、GumbelがVisitと同等以上の先後入れ替え勝率、または高予算探索に対する後悔量を示す
滑らかな補完Q値の教師方策が、一点に集中した教師方策より検証時のPolicy指標を改善する
攻撃やサイド取得への到達率を上げても、処理時間と失敗率が許容範囲に収まる
探索が作る教師方策が、ニューラルネットワーク単体より戦術プローブと固定対戦の両方で強い

段階3: 入力表現とBelief¶

状態: 次に着手する設計課題

実施項目¶

既知の残存山札。初期デッキから公開済みの領域を差し引いたカード枚数をトークン化する
合法手ごとの盤面変化。ダメージ、きぜつ、サイド、エネルギー、にげるコスト、ベンチの安全性を含める
相手のデッキ候補に対する事後分布と、デッキ候補を考慮した非公開状態のサンプリング
相手の主力アタッカー、進化系列、次のターンのきぜつリスクを表す構造化トークン
サイドの対応関係、必要なきぜつ回数、最短でサイドを取り切るまでの補助教師
トレーナーズ、特性、ワザの効果を共有して表す意味タグ
一つの入力要素だけを変えて出力の変化を確かめる反実仮想プローブ

完了条件¶

残存山札、相手のデッキ候補、履歴の順序を変えたプローブでPolicy・Valueが期待する方向へ変化する
Beliefを損失だけでなく、上位候補の再現率、較正、デッキ事後分布の正解率で評価できる
行動後の盤面変化を表す特徴量が、固定探索予算での行動の後悔量と戦術指標を改善する

段階4: モデルと学習目的¶

状態: 256次元化と損失調整を実施済み、再現性を検証中

実施項目¶

共有Transformerの比較。d_model=128/192/256、4層と6層を同じデータと計算量で比較する
既存チェックポイントから形が共通するパラメータを読み込み、新規層の初期化と移行結果を実行記録へ残す
次の脅威ときぜつを予測するヘッドを有効にし、損失の重みと教師データの網羅率を検証する
勝ち・引き分け・負け、サイド差、きぜつまでのターン数を分布として予測するValueを比較する
教師方策のエントロピー、上位候補の正解率、KL、ValueのBrierスコアと較正曲線を標準レポートにする

V14ではd_model=256、4層へ移行し、約6,117万パラメータのモデルを採用した。サイクル3では value-loss-weight=0.5、aux-prize-loss-scale=1.25、 belief-backbone-gradient-scale=1.0を新しい基準設定とした。ただし、128次元モデルとの同一データ・同一計算量による比較は未実施であり、256次元化だけの効果とは断定しない。

完了条件¶

モデル拡張が、同一データによる検証とオンライン対戦の両方を改善する
処理時間とメモリ使用量の増加に対する強さの改善量を報告できる
補助ヘッドが主となるPolicy・Valueを悪化させず、探索Q値の安定性を改善する

段階5: 対戦相手リーグと大規模学習¶

実施項目¶

現在のモデル、過去の昇格済みモデル、ルールエージェント、特定の弱点を突く対戦相手からなるリーグ
デッキの強さと相性を層化したサンプリングとカリキュラム
同一デッキ、異なるデッキ、学習に使わない未知デッキを分けた評価
5万から10万試合規模へ段階的に拡大するDVCパイプライン
レーティング、信頼区間、昇格履歴の可視化

完了条件¶

過去のチェックポイントやルールエージェントに対する破滅的忘却を抑えられる
複数のデッキ系統と未知デッキで改善が再現する
自己対戦の追加が外部評価の改善につながり、停滞時に停止できる

段階6: 提出・性能・運用¶

実施項目¶

CPU・CUDAのワーカー配分、バッチ推論、キャッシュ、数値精度の再現可能な性能評価
提出用バンドルの動作確認、合法手、安全な退避処理、チェックポイントの互換性テスト
最新の昇格済みチェックポイントから提出用生成物までのDVCによる系譜
CIでのRuff、Pytest、ドキュメント構築、提出用バンドルの動作確認
運用手順書とアーキテクチャ文書の継続的な更新

完了条件¶

新しく構築した環境から提出用生成物を再生成できる
提出環境の時間・メモリ制限内で固定評価を通過する
チェックポイント、設定、カードのメタデータ、コードの版を一つの実行記録から追跡できる

直近の実行順¶

実行中のサイクル4を完了し、サイクル3のChampionに対する直接対戦、ルールエージェント群との対戦、デッキ別指標を確認する。
サイクル3と4のMLflow指標を比較し、新しい複数ヘッド設定でPolicy、Value、Auxiliary、Beliefが同時に安定するか確認する。
サイクル4が昇格した場合は、同じ設定でもう1サイクル実行し、3サイクル連続の外部評価で改善傾向を判断する。却下された場合は同じ自己対戦データで損失の重みを再比較し、追加の自己対戦へ進まない。
Starmie・ArchaludonとIono・Belliboltを重点評価し、未完了、攻撃機会の損失、サイド取得数の回帰を試合ログから切り分ける。
同じ戦術プローブ集合で、ニューラルネットワーク単体、Visit、Gumbel、高予算探索の行動一致率とQ値の後悔量を測り、教師方策の品質を確認する。
Gumbel completed-Q、Visit、両者を混ぜた教師分布を、同一データ・同一チェックポイントから学習して比較する。
残存山札のカード枚数と、合法手を実行した後の盤面変化を入力へ追加し、固定局面とオンライン対戦で効果を確認する。
その後に、128次元と256次元、4層と6層を同一条件で比較し、モデル規模をさらに変更するか判断する。

ロードマップの更新規則¶

実装が完了した項目は、対応するアーキテクチャ・運用文書へ仕様を反映してから状態を更新する。
実験結果は開発記録へ残し、この文書には採用判断と次の判定条件だけを記載する。
戻しにくい設計判断は設計判断記録へADRを追加する。
新しい大規模学習へ進む前に、直前の段階の完了条件を満たしたか明記する。