holdem

holdem is a Python library for Texas Hold’em poker, built as an interactive learning environment for probability and game strategy. It provides not only complete game logic (cards, deck handling, hand evaluation, betting rounds, and AI players), but also an LLM tutor skill (holdem.skill pyskill) that teaches everything from basic poker rules to related topics such as probability, simulations, game theory.

Why it exists: Poker is a natural classroom for mathematics with topics ranging from combinatorics, pot odds, expected value, variance, Bayesian reasoning, and game theory. In traditional classroom settings, those topics are taught from bottom up, and it’s often hard to see how these topics are directly connected to anything important and useful in practice. Students therefore lose interest, become demotivated, and learn less. holdem lets a tutor agent and student play actual hands, so concepts come up when they matter or when students are curious. The students have clear goals on what and why they want to learn, rather than the whole curriculum imposed on them. It’s like how we learned to play soccer (or any game) as kids. We learned about rules and strategies slowly as we needed to play the game over time.

The learning is hands-on: students run Monte Carlo simulations (equity) to watch win rates converge, count outcomes on small decks, and experiment with code that generate real data. The tutor’s philosophy is play-first: explain only what the learner asks about, check prerequisites before diving in, and treat wrong answers as teaching moments.

I hope students have fun playing, and enjoy asking questions and thinking about them. It may be challenging and hard at times, but it’s fun hard. And play on your pace. The tutor isn’t going anywhere.

How to use

from holdem.skill import *
game = Game([Player('you', balance=20, strategy=human), # Create a game with players.
             Player('bot', balance=20, strategy=always_call)])
game.start()   # deal and show your hand
game.act()     # one human turn; bots auto-play; repeat until "Game is over"

Key pieces:

• Player(username, balance, strategy) — human puts a learner in the seat; always_call/always_check/always_fold/always_raise(n) create bot personalities
• Game.start() / Game.act() / Game.state() — play one turn per cell so learners can explore between turns; start() again deals a fresh hand
• evaluate_hand, compare_hands, hand_name — hand ranking, e.g. (7,3,2) → 'full house, threes over twos'
• equity(hand, community, n_opponents, n_sims) — Monte Carlo win/tie/lose estimate; pass a seed for reproducible classroom demos
• mk_deck(suits, ranks), shuffle_deck, withdraw_card — build small decks (e.g. mk_deck(suits[:2], ranks[:5])) to make counting outcomes concrete before switching to real odds

Usage

Installation

Install latest from the GitHub repository:

$ pip install git+https://github.com/galopyz/holdem.git

or from pypi

$ pip install holdem

Documentation

Documentation can be found hosted on this GitHub repository’s pages. Additionally you can find package manager specific guidelines on pypi.

Developer Guide

If you are new to using nbdev here are some useful pointers to get you started.

Install holdem in Development mode

# make sure holdem package is installed in development mode
$ pip install -e .

# make changes under nbs/ directory
# ...

# compile to have changes apply to holdem
$ nbdev_prepare