CS Games — Texas Hold'em AI Challenge

This repository contains a lightweight Python 3.11 implementation of a simplified Texas Hold'em engine and a Strategy API students must implement to create bots for the competition. It includes example strategies and a Jupyter-style explanation notebook demonstrating how to run a tournament.

---

Installation

1. Create an environment with Python 3.11

Pick either venv or conda based on your local setup.

Conda is recomended to ensure the proper Python version is used.

Conda setup

conda create -n cs_games_poker python=3.11
conda activate cs_games_poker

Venv setup

python3.11 -m venv .venv
source .venv/bin/activate

2. Install dependencies:

pip install -r requirments.txt

If you require any additional libraries for your agent, please inform us so that we make sure to have it installed on the evaluation server.

All coding from stategy implementation to testing can be done in the provided notebook: tournament_notebook.ipynb

---

Participants guide

Implementing a strategy

• Create a subclass of Strategy from poker_game/strategy.py and implement the act(state: GameState) -> Action method.
• Sample strategies can be found in /strategies

Game state passed to your strategy

Each time it is your turn to act, the engine calls act(state) with a GameState dataclass containing:

Field	Type	Description
player_chips	int	Your current chip stack.
pot	int	Current size of the pot.
community_cards	tuple[str, ...]	Cards on the board (empty preflop; 3 on flop; 4 on turn; 5 on river). Each card is a 2-character string: rank + suit (e.g. "A♠", "T♥", "2♦"). Ranks: 23456789TJQKA. Suits: ♠♥♦♣.
hole_cards	tuple[str, str]	Your two private cards, same 2-character format as above.
to_call	int	Chips you must put in to call (0 if you can check).
min_raise	int	Minimum raise amount (e.g. big blind size for the round).
stage	str	Current betting round: 'preflop', 'flop', 'turn', or 'river'.
player_index	int	Your seat index in the table (0-based).
num_players	int	Total number of players in the game.
metadata	dict	Optional extra data (engine may extend this upon request).

Returning an action

Your act() method must return an Action with:

• type: one of ActionType.FOLD, ActionType.CHECK, ActionType.CALL, or ActionType.RAISE.
• amount: required for RAISE (e.g. Action(ActionType.RAISE, amount=state.min_raise)). Can be None for FOLD, CHECK, or CALL.

Example: Action(ActionType.CALL) to call, or Action(ActionType.RAISE, amount=state.min_raise) to raise the minimum. See strategies/random_bot.py and strategies/heuristic_bot.py for reference implementations.

Any illegal action will result in a fold.

Note that there is a time limit of 100ms per turn. Should this be a major issue for your strategy please approach us.

Hand rankings in Texas Hold'em

Hand strength is determined by evaluate_five in poker_game/cards.py and has been implemented with the following hands. Do note that although you have 7 cards available (2 in your hand and 5 on the table), only 5 cards are used when comparing hands. The best combination of 5 cards is chosen for each player.

Category	Hand	Tiebreakers (summary)
8	Straight flush	High card of the straight (5 for wheel)
7	Four of a kind	Quad value, then kicker
6	Full house	Trips value, then pair value
5	Flush	All five card values (high to low)
4	Straight	High card of the straight (5 for wheel)
3	Three of a kind	Trips value, then two kickers
2	Two pair	High pair, low pair, kicker
1	One pair	Pair value, then three kickers
0	High card	Five card values (high to low)

---

The Tournament

How the tournament will go proceed:

1. Each team submits their AI player at the provided link.
2. Teams will be split into 3 pools of 8 players.
3. Each pool will run a tournament.
4. The 2 winners of each pool will play a final tournament.

Ranking will be determined by chip count.

Please note this is an AI competition, not a cyber-security one. Any attempt by an AI to manipulate the game environment or variables, ie. changing its stack size, will result in its immediate disqualification.