Python Playing Cards Module

What This Is

A production-grade Python card game engine but more importantly, a clean, deterministic substrate for training game-theoretic AI agents. If you want to study GTO poker strategy, train a CFR agent, or benchmark multi-agent decision-making, you need a fast, correct, and fully observable game engine first. This is it.

Why Correctness Matters Here

Texas Hold'em has 2.6 trillion distinct game states. Any bug in hand evaluation, dealing logic, or pot calculation corrupts every downstream agent that trains on it. We verify correctness with:

• Exhaustive unit tests against known hand rankings
• Statistical tests: deal 10M hands, verify suit/rank distribution matches hypergeometric expectation
• Cross-validation against reference implementations

What's Built

• Card, Deck, Hand, Player classes with a clean API
• PokerHandEvaluator: two-plus-two inspired fast lookup for 5-card and 7-card hand ranking
• 6 complete games: Blackjack, War, Go Fish, Crazy Eights, Solitaire, Texas Hold'em
• ASCII art rendering for terminal-based agents
• Card counting utilities: Hi-Lo, Omega II, KO count implementations
• Deterministic RNG mode for reproducible experiments

The Game Theory Connection

Texas Hold'em is the canonical benchmark for imperfect-information game AI. Libratus (2017) and Pluribus (2019) both from CMU solved heads-up and 6-player Hold'em respectively using CFR variants. Pluribus runs at ~$1000/hand profit against top pros.

This engine is the foundation layer for a full CFR implementation. The game tree abstraction maps directly onto the regret minimisation update: at each information set, maintain a strategy profile and update based on counterfactual regret.

What's Next

• Implement vanilla CFR as the first agent
• Add information set abstraction (card bucketing, bet size abstraction) to make the game tree tractable
• Benchmark against rule-based baselines
• Package and publish to PyPI