games.poker.state¶

Texas Hold’em Poker game state management.

This module implements the core state management for a Texas Hold’em poker game, including:

  • Game initialization and progression

  • Player action handling

  • Betting rounds and pot management

  • Hand evaluation and showdown logic

  • Side pot creation for all-in situations

The state management is built on top of LangGraph for AI agent integration, using Pydantic models for type safety and validation.

Example

>>> from poker.state import PokerState
>>>
>>> # Initialize a new game
>>> state = PokerState()
>>> state.initialize_game(["Alice", "Bob", "Charlie"], starting_chips=1000)
>>> state.start_new_hand()

Classes¶

PokerState

State manager for Texas Hold'em Poker game.

Module Contents¶

class games.poker.state.PokerState(/, **data)¶

Bases: pydantic.BaseModel

State manager for Texas Hold’em Poker game.

Manages the complete state of a poker game, including player actions, game progression, betting rounds, and hand evaluation. Built on top of LangGraph for AI agent integration.

Parameters:

data (Any)

messages¶

Message history for agent communication

Type:

List[BaseMessage]

current_step¶

Current step in the game progression

Type:

int

max_steps¶

Maximum allowed steps before forced game end

Type:

int

error¶

Current error state, if any

Type:

Optional[str]

memory¶

Persistent memory for game state

Type:

Dict[str, Any]

game¶

Current game state

Type:

PokerGameState

waiting_for_player¶

ID of player we’re waiting for

Type:

Optional[str]

game_log¶

Timestamped log of game events

Type:

List[str]

current_decision¶

Last decision made

Type:

Optional[AgentDecision]

Example

>>> state = PokerState()
>>> state.initialize_game(["Alice", "Bob"], 1000)
>>> state.start_new_hand()
>>> obs = state.create_player_observation("player_0")

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

advance_game_phase()¶

Move the game to the next phase if current phase is complete.

Handles progression through game phases:

  1. Preflop -> Flop (deal 3 cards)

  2. Flop -> Turn (deal 1 card)

  3. Turn -> River (deal 1 card)

  4. River -> Showdown (evaluate hands)

For each phase transition:

  • Resets betting amounts

  • Deals appropriate community cards

  • Sets first player to act

  • Updates game phase

Side Effects:

  • Updates game phase

  • Deals community cards

  • Resets betting state

  • May end the hand

create_player_observation(player_id)¶

Create an observation object for a player.

Generates a view of the game state from a specific player’s perspective, hiding information they shouldn’t have access to (e.g., other players’ hole cards).

Parameters:

player_id (str) – ID of player to create observation for

Returns:

Object containing all information visible to player

Return type:

PlayerObservation

Raises:

ValueError – If player_id is not found

Example

>>> obs = state.create_player_observation("player_0")
>>> print(obs.hand)  # Shows player's hole cards
>>> print(obs.community_cards)  # Shows shared cards
deal_community_cards(count=3)¶

Deal community cards to the board.

Deals the specified number of cards from the deck to the community cards area. Used for flop (3 cards), turn (1 card), and river (1 card). Logs the dealt cards with appropriate phase name.

Parameters:

count (int, optional) – Number of cards to deal. Defaults to 3 for flop.

Raises:

Sets self.error if there aren't enough cards in the deck. –

deal_hands()¶

Deal two cards to each active player.

Deals hole cards to all active players with chips. Skips inactive or busted players. Logs an error if there aren’t enough cards.

handle_player_action(player_id, decision)¶

Process a player’s action in the game.

Handles all possible player actions (fold, check, call, bet, raise, all-in), including validation, bet placement, and game state updates.

Parameters:

  • player_id (str) – ID of player taking action

  • decision (AgentDecision) – Player’s chosen action and amount

Side Effects:

  • Updates player state (chips, active status)

  • Updates game state (pot, current bet, etc.)

  • Advances to next player

  • May complete betting round

  • May end hand if only one player remains

Raises:

Sets self.error for invalid actions –

  • Player not found

  • Player not active

  • Invalid action for current state

  • Invalid bet/raise amount

Parameters:
initialize_deck()¶

Create and shuffle a new deck of cards.

Creates a standard 52-card deck and performs a random shuffle. Updates the game state with the new deck.

initialize_game(player_names, starting_chips=1000)¶

Initialize a new poker game with the given players.

Creates a new game state with the specified players, assigning IDs, positions, and starting chip stacks.

Parameters:

  • player_names (List[str]) – Names of players to add

  • starting_chips (int, optional) – Initial chips per player. Defaults to 1000.

Example

>>> state.initialize_game(["Alice", "Bob", "Charlie"], 2000)
log_event(message)¶

Add a timestamped message to the game log.

Records game events with timestamps for history tracking and debugging. Events are both added to the game_log list and sent to the logger.

Parameters:

message (str) – Event message to log

Example

>>> state.log_event("Alice raises to $100")
[14:30:45] Alice raises to $100
post_blinds()¶

Post small and big blinds.

Forces the two players after the dealer to post the small and big blinds. Updates player chips, pot size, and current bet amount. Sets minimum raise to the big blind size.

Raises:

  • Sets self.error if there aren't enough players or if blind –

  • positions can't be determined. –

start_new_hand()¶

Start a new hand of poker.

Resets all necessary state for a new hand:

  • Rotates dealer position

  • Resets player hands and bets

  • Clears community cards and pots

  • Initializes new deck and deals cards

  • Posts blinds

  • Sets first player to act (UTG)

The game progresses through these phases:

  1. Setup (reset state)

  2. Deal hole cards

  3. Post blinds

  4. Start preflop betting