PokerMind

Texas Hold'em Training Engine -- learn winning poker through interactive practice against AI opponents with real-time HUD analysis.

Features

• 6-Max No-Limit Hold'em with 2-6 players
• 5 AI opponent archetypes with distinct play styles:
  • TAG (Tight-Aggressive) -- plays few hands, plays them hard
  • LAG (Loose-Aggressive) -- wide range, maximum pressure
  • Nit -- only premium hands, very predictable
  • Fish -- plays too many hands, calls too much
  • Maniac -- raises everything, high variance
• Real-time HUD showing equity, pot odds, outs, hand description, SPR
• Monte Carlo equity calculator (3,000 simulations per decision)
• Position-based preflop ranges loaded from JSON data files
• Colored card rendering with Unicode suit symbols
• Rich terminal UI with table layout, action prompts, and autocomplete

Requirements

• Python 3.11+
• Virtual environment with dependencies (treys, rich, prompt_toolkit, pydantic, numpy)

Installation

cd pokermind
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Running the Game

source venv/bin/activate
python -m src

With options:

python -m src --players 4 --starting-stack 100 --blinds 0.5/1 --seed 42

CLI Arguments

Flag	Short	Default	Description
--players	-p	6	Number of players (2-6)
--starting-stack	-s	200	Starting stack in big blinds
--blinds	-b	0.5/1	Blind levels as SB/BB
--seed		None	Random seed for reproducible games

Game Controls

Key	Action
f or fold	Fold
x or check	Check
c or call	Call
b <amount>	Bet (amount in BB, e.g., b 3)
r <amount>	Raise to (amount in BB, e.g., r 10)
a or allin	All-in
Ctrl+C	Quit

Amounts are in big blinds. Tab completion is available for action names.

Running Tests

source venv/bin/activate
python -m pytest tests/ -v

167 tests across 6 test files covering the core engine, AI opponents, and edge cases (split pots, side pots, walks, all-in runouts, min raise enforcement).

Project Structure

src/
  engine/     Core poker engine (deck, hand eval, equity, betting, game state)
  ai/         AI opponent system (profiles, ranges, postflop logic, sizing)
  ui/         Terminal UI (table display, card rendering, HUD, input handling)
  utils/      Constants (enums) and helper functions
data/
  preflop_ranges/   JSON position-based opening ranges (utg, hj, co, btn, sb, bb)
tests/              Unit tests for engine, AI, and edge cases

Architecture Notes

• All monetary values use integer BB units (1 BB = 100 internal units) to avoid floating point errors
• Hand evaluation uses the treys library (Cactus Kev algorithm) for O(1) lookup
• Game state machine: DEALING -> PREFLOP -> FLOP -> TURN -> RIVER -> SHOWDOWN -> HAND_COMPLETE
• AI decisions are profile-driven with randomized noise for natural play variation
• Preflop ranges are tier-based (premium/strong/playable/marginal/speculative) controlled by profile tightness

Development Roadmap

• Phase 1: Core Engine
• Phase 2: AI Opponents
• Phase 3: Terminal UI
• Phase 4: Coaching System (EV calculator, real-time advisor, mistake detection)
• Phase 5: Training Modules (preflop drills, pot odds quizzes, scenario practice)
• Phase 6: Stats & Persistence (SQLite database, session tracking, leak analysis)