# holdem


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

**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

``` python
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](https://github.com/galopyz/holdem):

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

or from [pypi](https://pypi.org/project/holdem/)

``` sh
$ pip install pyholdem
```

### Documentation

Documentation can be found hosted on this GitHub
[repository](https://github.com/galopyz/holdem)’s
[pages](https://galopyz.github.io/holdem/). Additionally you can find
package manager specific guidelines on
[pypi](https://pypi.org/project/holdem/).

## Developer Guide

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

### Install holdem in Development mode

``` sh
# 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
```