DanKS: a three-generation GuanDan AI you can install and run locally

What DanKS is for, and who it is written for

GuanDan is a four-player, partnership-based card game played with two decks, so the action space is large and structured rather than flat. DanKS is a Python project from the Kingsoft AI Product Center that attacks that action space with retrieval plus a learned scorer, and it ships three generations of that idea in one repository. The engine is shared: the README describes a single 108-card GuanDan rules engine used across all three versions.

The audience is narrow and specific. If you are studying how to shrink a combinatorial card-game action space before feeding it to a policy network, the repository is laid out so you can read V1, then V2, then V3 and see what changed. If you just want to play, the project points at an online demo at calixlin.com/CardKS/ with one human seat and three bot seats, in Chinese and English. Those are different products. The repository is the research artifact; the demo is the game.

The four-stage pipeline: state, candidates, Top-K scoring, self-play

The architecture section of the README describes one pipeline shared by all three generations. First, the policy encodes an information state: the visible hand, public action history, legal actions, and seat-aware game context. Second, a budgeted decomposition search retrieves structured candidates, summarizing each play by length, pairs, sequences, suits, gaps, and remaining-hand structure. Third, a shared encoder combines state, candidate and structural features, and the actor ranks valid candidates while the critic estimates state value. Fourth, trajectories from self-play produce GAE advantages for clipped PPO updates.

The interesting design claim is the last sentence of that list: PPO improves the selector without expanding the inference-time candidate budget. That is a real constraint, not marketing. Candidate generation stays bounded, so inference cost stays predictable, and the learning has to happen inside the ranking step. The README's own framing of why this matters is about delayed outcomes: a move that looks cheap now can destroy the only useful combination left in the hand. Retrieval organizes the action space; structure features expose what each candidate consumes and preserves; the policy learns the long-horizon consequence.

What the README does not give is the search budget itself. The word "budgeted" is doing a lot of work with no number attached, and there is no table of how many candidates survive retrieval at each stage. If you need to reason about latency, that number is the one you will have to measure.

Installing DanKS and running V3 on CPU

The quick start assumes Python 3.11 and a POSIX shell, and calls the V3 path the shortest runnable one. Clone the repository, create a virtual environment, then install the V3 package from its subdirectory rather than from the repository root:

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

The separate torch install with the CPU index URL is the part worth noticing. It pins torch to 2.8.0 and pulls the CPU wheel, which is why this path works without a GPU. On Windows PowerShell the README says to use `.venv\Scripts\Activate.ps1` instead of the `source` line.

Two example scripts follow. The first runs the retrieval path against V3, the second is a model smoke test:

python examples/retrieval_quickstart.py --version v3
python examples/v3_model_smoke.py

The `--version v3` flag on the retrieval example is the only argument shown. Note what the quick start does not do: it never downloads a trained checkpoint, and it does not tell you what output the smoke test prints. Treat both scripts as wiring checks that your environment imports and executes, not as evidence of playing strength. The README also lists `examples/engine_quickstart.py` and `examples/v3_ppo_smoke.py` in the repository, so a PPO training smoke test exists, but the quick start does not walk through it.

One environment per generation, and what that costs you

The README is explicit that V1, V2 and V3 are separate packages, and that each should get its own environment: "Give each generation its own environment to keep the `DanKS` import, feature schema, and checkpoint format aligned." Read that as a warning rather than a suggestion. The import name is the same across generations, the feature schemas differ, and checkpoints are not interchangeable.

That has practical consequences. You cannot install all three into one virtualenv and compare them by switching a flag, because the `DanKS` import would collide. Any benchmark you build across generations needs three environments and three processes. It also means a checkpoint trained under one generation's feature schema will not load meaningfully under another, and the README does not document a conversion path.

The top-level `pyproject.toml` adds a second wrinkle. It declares a package named `danks-engine` with no runtime dependencies and packages limited to `guandan` and `guandan.engine`, so installing from the repository root gets you the shared engine, not the agents. The version-specific code lives under `versions/` and installs from there. If you run `pip install -e .` at the root expecting the V3 policy, you will not get it.

Where DanKS is the wrong tool

The repository is a research codebase with a v0.1.0 release, and the README does not document rollback, upgrade or migration procedures. There is no stated compatibility policy between releases, no deprecation notes, and no guidance on what happens to a trained checkpoint when the feature schema changes. If your requirement is a dependency you can pin and upgrade on a schedule, this is not that yet.

There is also no documented serving layer. The README describes training, checkpoints, native acceleration and runnable inference examples, but it does not describe an API, a port, a container image or a deployment topology. Anyone expecting a drop-in service will be building that themselves.

A third limit is scope. Everything here assumes GuanDan with its specific rules, its two decks and its partnership structure. The retrieval and ranking idea transfers conceptually to other trick-taking or shedding games, but the engine and the feature schemas are GuanDan-shaped, and the README offers no abstraction layer for a different ruleset. If you want a general card-game framework, this is the wrong starting point.

How DanKS differs from a plain deep RL card agent

The obvious comparison is an end-to-end agent that maps a raw observation straight to an action distribution, in the style of the AlphaZero family. DanKS does not do that. It inserts a retrieval stage between the state and the policy, so the network only ever ranks a bounded candidate set instead of scoring every legal play. The README's own summary of the generations shows how the two halves trade off: V1 is structural retrieval with candidate scoring and a NumPy selector; V2 adds broader action generation and an ONNX selector; V3 adds card memory, candidate coverage, recall, team belief and PPO.

That progression is the argument. V1 and V2 lean on retrieval quality and a lightweight selector. V3 keeps the retrieval budget fixed and moves the intelligence into a memory-aware policy trained with PPO. An end-to-end agent has no equivalent of that separation, which makes it harder to reason about inference cost but removes the risk that a bad retrieval stage silently caps how well the agent can ever play.

Which side you land on depends on what you are optimizing. Bounded candidates mean predictable inference and a readable failure mode; a full action space means no ceiling imposed by retrieval, at a higher and less predictable cost per decision.

Licence, maintenance and upgrade cost

DanKS is Apache-2.0, and the repository carries both a LICENSE and a NOTICE file, with `license-files = ["LICENSE", "NOTICE"]` declared in `pyproject.toml`. Apache-2.0 includes an explicit patent grant and requires that the NOTICE file be preserved in distributions. If you redistribute the code or a modified version, the NOTICE file is the concrete artifact to carry along. That is a description of the licence text, not legal advice; read the LICENSE and NOTICE yourself before shipping anything.

The last push to the default branch was on 2026-09-02, and the repository is not archived. The only release listed is v0.1.0 from 2026-08-21. A single release plus a recent push means the API surface is young, and the README's own instruction to isolate each generation in its own environment is the clearest signal that internal interfaces still move. Budget for reading source when you upgrade, not for changelog-driven upgrades. The repository also names an AtomGit mirror for mainland China, which is worth knowing if GitHub access is the constraint rather than the code.

Editorial conclusion

Adopt DanKS if you want a readable GuanDan rules engine plus three generations of a card-playing agent in one Apache-2.0 repository, and you are comfortable reading Python to find the API surface. Do not adopt it if you need a documented rollback path, a stable multi-version install, or a single package that gives you a trained policy out of the box. Before building on it, verify three things yourself: that `guandan/engine` exposes the state fields your code needs, that `examples/v3_ppo_smoke.py` runs on your hardware, and that the checkpoint format your training run produces matches what your inference path loads.

Frequently asked questions

Official sources

1. Calix-L/DanKS on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases