108 cards. Four players. Hidden information. Teammates. And a legal action space that can explode before the model even makes a decision.
That is the problem we took on with DanKS, an open-source AI system for GuanDan.
We did not build it once.
We built it three times—moving from handcrafted structural search, to learned candidate selection, and finally to a memory-aware actor-critic trained with PPO. We kept all three generations in the repository because the evolution of the design is as useful as the final model.
If you just want to see whether it can play, challenge DanKS in your browser. No installation required.
The real problem is not choosing a card
GuanDan is a four-player partnership game played with two standard decks. A player may hold 27 cards, but a move is not necessarily one card. It can be a pair, triple, sequence, bomb, or another structured combination.
So the model faces three problems at once:
- Combinatorial actions: legal moves are structured card combinations, not a small fixed menu.
- Imperfect information: each player sees only part of the state and must reason from public history.
- Delayed credit: a move that looks harmless now may destroy the shape of the hand several turns later.
A giant policy head over every possible combination sounds simple. In practice, most outputs would be irrelevant on any given turn, while legal-action enumeration and scoring become expensive.
Our answer was to make the network solve a smaller, better-defined problem.
The design choice that survived all three versions
DanKS uses a two-stage decision pipeline:
- Retrieve candidates. Decompose the hand and produce a bounded, strategically varied set of legal moves.
- Rank the Top-K. Let the policy compare those candidates using the visible state, public history, seat context, and structural features.
The retrieval stage is not just a speed optimization. Two legal moves may look similar on the table but consume very different parts of the remaining hand. Candidate generation therefore tries to preserve meaningful structural alternatives for the policy to compare.
In short: search proposes; the policy decides.
Version 1: make the action space understandable
V1 establishes the structural retrieval pipeline and uses a NumPy-based selector. It is the smallest implementation in the repository and the best place to learn the candidate representation without first unpacking the full training stack.
The important result of V1 was architectural: game rules, legal-action generation, and candidate selection became separate concerns.
Version 2: replace the selector, keep the interface
V2 expands action generation and introduces an ONNX model for candidate selection.
The retrieval interface stays stable. That means the learned ranker can change without forcing a rewrite of the game engine—a separation that becomes increasingly valuable as experiments multiply.
Version 3: remember what happened—and learn from what happens later
V3 adds card memory, candidate-coverage features, recall signals, team-belief features, an actor-critic model, and PPO training.
The critic and generalized advantage estimation help assign credit across delayed outcomes. The actor can then learn that two moves with similar immediate effects may create very different future hands.
We intentionally keep V1, V2, and V3 as separate packages. Their schemas, checkpoints, and dependencies are not interchangeable, and making those boundaries explicit is safer than hiding them behind one mutable interface.
Try the model in about a minute
The shortest CPU path uses Python 3.11 and V3:
git clone https://github.com/Calix-L/DanKS.git
cd DanKS
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e versions/v3
python -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cpu
python examples/retrieval_quickstart.py --version v3
python examples/v3_model_smoke.py
On Windows, activate the environment with .venv\Scripts\Activate.ps1.
The repository also includes examples for the shared rules engine and a synthetic PPO optimizer update. CUDA 12.8, Ascend NPU, and optional C++17 retrieval kernels are documented for readers who want to go beyond the CPU smoke test.
Why we open-sourced every version
Many AI repositories show only the final checkpoint and a polished inference script. DanKS instead preserves the path from explicit structure to learned ranking and then memory-aware policy optimization.
That makes the project useful beyond one card game. If you work on agents with structured or variable action spaces, the candidate-retrieval boundary may be more reusable than any individual network layer.
The project was initiated by the Kingsoft AI Product Center and is available under the Apache-2.0 license.
We would especially value feedback on:
- candidate diversity and coverage;
- evaluation protocols for partnership card games;
- PPO training and delayed credit assignment;
- portability of the native retrieval kernels;
- reproducible comparisons with other game-AI systems.
Explore DanKS on GitHub, try the online demo, and tell us: if you were building V4, what would you change first?
Top comments (0)