An end-to-end heads-up No-Limit Hold'em poker AI in Rust β precompute, train, export, and query a CFR blueprint on a single machine.
Overview Β· Workspace Β· How it works Β· Quickstart Β· Configuration Β· CI Β· Status Β· Docs
pkr-sota is a Cargo workspace that takes heads-up No-Limit Hold'em from raw Card bytes to a queried strategy, split by one design constraint: train on one beefy machine, answer queries anywhere. An offline half builds hand-strength tables and runs counterfactual-regret-minimization training; the result is frozen into a single self-describing blueprint.bin that the online half loads with mmap and answers in nanoseconds β no server, no heap allocations, no heap of dependencies.
The pipeline has four stages, and each one is its own crate boundary:
training host (offline)
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β pkr-abstraction-precompute β
β hand_ranks.bin Β· centroids Β· per-street bucket tables β
β β β
β βΌ β
β pkr-trainer ββ pkr-cfr (external-sampling MCCFR + DCFR) β
β β β
β βΌ β
β pkr-export βββΆ blueprint.bin (sorted keys + u8 CDFs) β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
runtime host (online)
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β pkr-runtime β
β mmap β branchless binary search β advice (p50 β 42 ns) β
β RuntimeSession: range tracking Β· off-tree bet translation β
β river-only subgame search (bounded Β· CFR-D gadget) β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Note
"sota" is the destination, not a claim. The project's own assessments in docs/STATUS.md grade the current bot honestly, and the history records its measurement caveats β including the negative results. See Project status.
- End-to-end on one machine.
./smoke.shruns the full pipeline β hand-rank table, centroids, per-street bucket tables, training, export, reload β and finishes with a release-mode integration test that loads the blueprint throughpkr-runtime. - Deterministic by construction. Same seed and inputs produce a byte-identical
blueprint.binat any thread count; thegoldenCI workflow fails on any drift from stored SHA-256 hashes. - Nanosecond queries. The runtime
mmaps the blueprint and answers lookups with a branchless binary search β p50 β 42 ns, p99 β 84 ns against a large blueprint (seedocs/STATUS.md). - Safety-first search. River subgame solving ships only in provably-safe modes: a bounded variant that blends back until the opponent's best response is no better than against the blueprint, and a CFR-D gadget (Burch et al., 2014) that grants the opponent a terminate option paying blueprint continuation value.
- Honest instrumentation. Sampled best response with held-out lower bounds, myopic local best response, duplicate-poker tournaments with common random numbers, and exact-enumeration convergence canaries on Kuhn and Leduc.
- Battle-tested. 460+
#[test]functions across the workspace, Miri on the core crates, fuzz targets over the blueprint loader and game-state transitions, nightly criterion benchmarks pushed to Bencher.
19 members: 12 library crates, 1 binary, 6 benchmark crates (all paths relative to the repo root).
| Member | Role |
|---|---|
crates/pkr-core |
Game model: cards, deck, zero-alloc GameState, NLHE rules, the 7-bucket action abstraction, infoset signatures |
crates/pkr-contracts |
Trait boundaries shared by every layer β Evaluator, AbstractionBuilder, BlueprintProvider β plus FNV-1a infoset hashing |
crates/pkr-eval |
Hand evaluation: a reference evaluator, a C(52,5)-entry mmap lookup table, and Fast7Evaluator (bit-identical by design, enforced by differential tests) |
crates/pkr-abstraction |
Card abstraction: Monte-Carlo EHS/EHSΒ², equity histograms, k-means bucket tables, and the pkr-abstraction-precompute binary |
crates/pkr-cfr |
Training engine: external-sampling MCCFR with DCFR discounting over a lock-free CompactRegretTable |
crates/pkr-export |
blueprint.bin writer/reader: versioned header, abstraction fingerprint, quantized u8 CDFs |
crates/pkr-runtime |
Query side: mmap + branchless binary search, RuntimeSession, opponent range tracking, live bet translation |
crates/pkr-subgame |
Subgame solving on the public tree; a vector-form solver carrying full 1326-hand ranges; the CFR-D safety gadget |
crates/pkr-exploit |
Exploitability instruments: sampled best response (held-out lower bound) and myopic local best response |
crates/pkr-fuzz |
Differential game-rules fuzzing against a reference implementation, plus duplicate-poker tournament and arena harnesses |
crates/pkr-testgames |
Kuhn poker harness with exact best-response enumeration (Nash value β1/18) |
crates/pkr-leduc-check |
Leduc hold'em convergence gate over the production CFR path β a CI canary for the trainer's numerics |
binaries/pkr-trainer |
The pkr-trainer CLI that orchestrates the whole pipeline |
benches/ |
Six criterion bench crates: hashing, eval, runtime lookup, CFR table ops, abstraction, core primitives |
Texas Hold'em is far too large to solve directly, so both axes of the game get compressed. On the action side, every bet is bucketed into one of 7 discrete actions β fold, check/call, four pot-relative bet sizes, or jam β with the mapping defined once in pkr-core/src/abstraction.rs and a CI gate (ci/scripts/check-no-hardcoded-k.sh) that rejects any hard-coded copy of that count. On the card side, preflop hands map to the exact 169 strategic classes, while flop, turn, and river situations map through precomputed bucket tables built by k-means over equity features (EHS/EHSΒ² and equity histograms, compared with an earth-mover-distance metric). A 40-byte abstraction fingerprint describing every one of these choices is written into checkpoints and blueprints, and the loader refuses artifacts whose fingerprint doesn't match the code.
pkr-trainer runs external-sampling MCCFR with DCFR discounting (Ξ± = 1.5, Ξ² = 0, Ξ³ = 2), RM+ flooring, and optional PCFR+ momentum (off by default β the docs recommend keeping it off). Regrets live in a CompactRegretTable: a lock-free concurrent map onto flat atomic planes, 112 bytes per infoset at K=7, with thread-local lookup caches and rayon-parallel traversal batches. Checkpointing is rolling and atomic (.tmp β .prev β final), so a crash mid-write cannot corrupt the main checkpoint, and --checkpoint resumes from wherever training stopped. Hyperparameters are read from PKR_* environment variables exactly once per process and pinned by regression tests.
pkr-export writes a single self-describing file: an 8-byte PKRSOTA1 magic, format version (v4), a per-street bet-sizing anchor block, the abstraction fingerprint, then ascending u64 infoset keys and one quantized u8 cumulative-distribution byte-slice per key. Writing is atomic (.tmp + rename), keys are sorted defensively, and the runtime validates magic, version, hash algorithm, and counts before trusting anything. The reader accepts v2βv4; anything newer is rejected loudly rather than misread.
pkr-runtime maps the blueprint read-only and answers SolverHandle::get_advice_fast(hash) with a branchless binary search over the sorted keys β no allocator on the hot path. On a miss, a fixed mild fallback policy is returned rather than garbage. Above the blueprint sits RuntimeSession: it tracks a 1326-hand posterior over the opponent's holdings from observed actions, translates off-tree bet sizes into the nearest in-tree bucket (pseudo-harmonic translation, Ganzfried & Sandholm 2013), and optionally runs river-only subgame search inside a wall-clock budget (default 2000 ms).
Search is shipped river-only and safe-by-default. The bounded mode solves the subgame, measures the opponent's best response against it, and blends back toward the blueprint until that response is no better than against the blueprint itself. The gadget mode instead wraps the solve in a CFR-D terminate option paying blueprint continuation value, which bounds exploitability independent of range accuracy. Turn search costs ~45 s per decision on the M1 and stays offline; river decisions fit comfortably in the live budget.
Prerequisites: a stable Rust toolchain (edition 2021, no pinning), a Unix-ish shell, and roughly 1 GB of disk for generated tables. Note that .cargo/config.toml builds everything with -C target-cpu=native by design β these binaries are meant for the machine that built them.
git clone https://github.com/elcoosp/pkr-sota
cd pkr-sota
# End-to-end proof: precompute β train β export β load
./smoke.shsmoke.sh caches its artifacts under outputs/v0-smoke/ and re-runs incrementally; SMOKE_FRESH=1 ./smoke.sh starts from scratch. It also asserts exact byte sizes on the generated tables (e.g. the 305 MB turn-abstraction table), so a truncated run fails loudly.
Train a real blueprint:
VERSION=v1 ITERATIONS=1000000 ./run.sh # defaults: 30M iterations, checkpoints every 5Mrun.sh handles precompute (rebuilding only on REBUILD=1), launches training with periodic sampled-exploitability evals behind promotion gates (an improvement must clear both a margin and 2 standard errors), and writes blueprint.bin, train.ckpt, metrics.csv, and stats.json under outputs/$VERSION/. Interrupt it freely β SIGINT/SIGTERM are handled and the checkpoint resumes.
Query the result:
# Post-deploy health check: latency percentiles and hit rate, meaningful exit codes
cargo run --release -p pkr-runtime --bin health -- outputs/v1/blueprint.bin
# Line-protocol bot over stdin/stdout: JSON requests in, one action token out (f | k | c | b<chips>)
cargo run --release -p pkr-runtime --bin pkr-bot-pipe -- outputs/v1/blueprint.bin outputs/v1Common maintenance commands (via justfile):
| Command | What it does |
|---|---|
just fast |
fmt + clippy -D warnings + nextest β the inner development loop |
just smoke / just smoke-fresh |
end-to-end pipeline (cached / from scratch) |
just train |
./run.sh with environment-driven configuration |
just bench |
thread-scaling throughput benchmark |
just prof |
production-scale profiled run (100k iterations) |
just check |
fmt check + clippy + tests, mirroring CI's fast workflow |
All hyperparameters are environment variables read once per process (set them before launching):
| Variable | Default | Effect |
|---|---|---|
PKR_STACK_BB |
100 |
Starting stack in big blinds (clamped to 20β400) |
PKR_RM_PLUS |
on | RM+ floor of sampled regrets at zero |
PKR_MOMENTUM |
off | PCFR+ momentum term (project docs recommend off) |
PKR_DCFR_ALPHA |
1.5 |
Positive-regret discount exponent |
PKR_EXPLORE_EPSILON |
0.01 |
Uniform exploration mixed into opponent sampling |
PKR_ALLOW_EHS_FALLBACK |
off | Permit the slow Monte-Carlo fallback when a bucket table misses (trainer otherwise aborts) |
PKR_VSEARCH |
off | Enable river subgame search on top of the blueprint |
PKR_VSEARCH_BUDGET_MS |
2000 |
Wall-clock budget per search decision |
EHS_SAMPLES |
1000 |
Monte-Carlo deals per EHS estimate during precompute |
PKR_EMIT_FMPH |
off | Emit the optional minimal-perfect-hash tail in the blueprint |
Tip
cargo run --release -p pkr-trainer -- --help documents all ~42 trainer flags β capacity, evaluator choice (table or fast7), checkpoint intervals, sync batching, eval scheduling, promotion gates, plateau stopping, seeding, and JSON logging.
Nine GitHub Actions workflows guard the repo; the full definitions live in .github/workflows/.
| Workflow | Trigger | What it checks |
|---|---|---|
fast |
every push to main, all PRs |
fmt, clippy -D warnings, nextest, doctests |
golden |
PRs touching solver crates | 100k-iteration seed-42 training must reproduce stored SHA-256 hashes (blueprint at any thread count, checkpoint at 1 thread) |
smoke |
PRs + daily schedule | the full end-to-end pipeline plus artifact byte-size assertions |
bench |
nightly | six criterion suites, thread scaling, and a Kuhn experiment, pushed to Bencher with PR baselines |
proftest |
nightly | a 50k-iteration profiled training run with metrics pushed to Bencher |
weekly |
weekly | coverage, dhat heap profiling, two 5-minute fuzz runs, Miri on pkr-core + pkr-cfr, flamegraph |
audit |
daily + dependency PRs | cargo audit + cargo deny (RUSTSEC advisories, licenses, bans) |
pr-comment |
PRs | criterion A/B against main, posted as a diff-table comment |
commit-bench |
after bench |
archives nightly benchmark results to the perf-history branch |
The deterministic-training gate deserves a mention: ci/golden-training.sha256 stores reference hashes for a fixed 100k-iteration run, and any unintended change to the trainer's numerics shows up as a hash mismatch.
What is verified working today:
- The full pipeline (precompute β train β export β load β query), exercised by
smoke.shand held in place by the golden-hash CI gate. - Deterministic training: identical seed and inputs yield a byte-identical blueprint regardless of thread count.
- Runtime lookups at p50 β 42 ns / p99 β 84 ns (large blueprint β
docs/STATUS.md). - River-only bounded search beats the bare blueprint by β +1.03 chips/deal on average across four decorrelated seeds (t β₯ 4.1), with the safety bound (search best-response β€ blueprint best-response) passing in test.
- The production CFR path converges on Leduc hold'em to well under the CI gate's 70 milli-chips/game threshold (~21 measured at 2M iterations).
- 460+ unit/integration tests, Miri-clean core crates, fuzzed blueprint loader and state transitions.
Important
Three honesty rules the project holds itself to, which apply to anything you read here:
- This is not a superhuman bot. The project's own reviews place it far from competitive HUNL solvers; the realistic near-term goal is a strategy that is provably not trivially exploitable.
- Absolute exploitability numbers are inflated. The in-sample estimator behind the historical numbers (see
docs/HISTORY.md) is known-biased; only seeded, relative A/B comparisons between runs are meaningful. - K=6 history is closed. The 7-bucket action abstraction shipped on 2026-10-10; every earlier checkpoint is unloadable by design, K=6 and K=7 are different abstract games whose numbers must not be compared. The follow-up "run 1" (eps + strict min-raise combined) measured as a mild regression and was not shipped.
The project also keeps a deliberate record of dead ends β finer river bucketing, k=400 abstraction, turn-time search, PCFR+ momentum, AIVAT-style variance reduction, and more, all with negative or inconclusive verdicts (see docs/HISTORY.md).
The documentation set is deliberately small β four living files:
docs/STATUS.mdβ current state: what works, verified numbers, known gapsdocs/ARCHITECTURE.mdβ architecture and design decisions, as implementeddocs/HISTORY.mdβ session timeline, verified findings, negative results, methodology lessonsCHANGELOG.mdβ release notes