Poker TUI

A terminal gym for no-limit hold'em: drill preflop decisions against GTO-style charts, then play 6-max cash games (100bb) against agents powered by the local pi coding-agent CLI. Built with Textual and managed with uv. Requires Python 3.11 or newer.

Quick start

uvx poker-tui

uvx downloads the published package into an isolated, cached environment and starts the TUI without a manual install. For a persistent command:

uv tool install poker-tui
poker-tui

Check the installed release with poker-tui --version.

Screens:

• Preflop Trainer — random spots (RFI + facing opens across all positions), you pick fold/call/raise, graded against built-in charts with frequencies. Reveals a 13x13 range grid after each decision, tracks accuracy by seat, and "Why?" explanations in three styles (newb / learner / expert) generated via pi and cached locally. Range charts and explanations can be opened full-screen; expanded range cells show the complete action mix in hover tooltips.
• Play vs Agents — six-handed NLHE, unitless BB, auto-rebuy. Five villain seats decide via pi (one-shot LLM calls) with a fast heuristic bot as fallback. Dedicated seat chips keep each blind post and latest street action visible. Once you're out of a hand the rest plays out at high speed; N jumps to the next deal.
• Stats — quiz accuracy by spot and table results.
• Agent Settings — choose from models discovered through Pi for the default, trainer coach, and each of the five villains, or enter any custom provider/model ID. You can also switch to heuristic-only play.

Keys: T trainer · P play · S stats · G settings · Q quit · inside screens N next, Esc back. Trainer actions use F/C/R; table actions use F to fold, C to check or call, and R to raise at the selected size. S changes table speed. In the trainer, G expands the revealed range and X expands a loaded explanation.

Agents

Villain brains come from the pi CLI in print mode (pi -p --no-tools --no-session ...). Each seat gets one of four personas; invalid/failed LLM replies fall back to the heuristic bot (chart-based preflop, Monte-Carlo-equity postflop) automatically.

Environment:

The settings screen loads Pi's local model catalog and persists choices in settings.json. Per-agent models can inherit the default, while leaving the default unset uses Pi's own configured default. Environment variables override saved settings, which is useful for one-off runs and automation.

The solver

poker_gym.solve implements CFR+ over heads-up preflop subgames on top of a 169×169 all-in equity matrix (poker_gym.equity) computed by a custom vectorized numpy 7-card evaluator that is fuzz-tested against treys.

uvx --from poker-tui poker-gym-solve --quality fast --jobs 4
uvx --from poker-tui poker-gym-stats

Quality tiers: fast (~2k trials/matchup), standard (4k), thorough (8k). Builds are chunked with deterministic seeds and checkpointed, so they can be interrupted and resumed, and parallelized with --jobs. On a Raspberry Pi, prefer --quality fast --jobs 4; the evaluator is int32/vectorized to keep the working set cache-friendly.

Honest caveat: the solver's game abstraction folds everyone but two players and models postflop as equity × realization factors. Calibration shows this cannot reproduce position-dependent open frequencies (UTG and BTN become literally the same game), so the trainer grades against hand-calibrated charts modeled on published solver baselines; solver output is stored separately as an experimental "solver view" (kind='solver' in the charts table).

Data

Everything persists under $XDG_DATA_HOME/poker_gym (default ~/.local/share/poker_gym): gym.db (quiz attempts, hand histories, explanation cache, charts), settings.json (Pi model routing), and equity.npz.

Development

uv sync
uv run poker-tui
uv run pytest -m "not slow"   # full suite minus long equity-matrix test
uv run pytest -m slow         # equity matrix sanity (builds a small matrix)
uv run python scripts/smoke_app.py    # headless TUI smoke test

Build the same artifacts uploaded to PyPI with:

uv build --clear
uv publish

Layout: src/poker_gym/ — cards, ranges (chart DSL), charts (the ranges themselves — edit freely, they're plain strings), spots (trainer), engine (table state machine), agents, explain, equity, solve, db, cli, app.