games.hold_em.game_agent

Texas Hold’em Game Agent module - Main game coordinator and manager.

This module implements the core game management system for Texas Hold’em poker, coordinating the game flow, player interactions, betting rounds, and showdowns. It serves as the central orchestrator that manages the complete lifecycle of a poker game from setup to completion.

Key features:

• Complete poker game flow management with LangGraph

• Betting round coordination and hand progression

• Player action validation and processing

• Pot management and chip tracking

• Showdown evaluation and winner determination

• Game state persistence and history tracking

The game agent creates and manages subgraph agents for each player, allowing them to make independent decisions within the overall game context. It handles all aspects of the game rules, ensuring proper sequencing of rounds and actions.

Examples

>>> from haive.games.hold_em.game_agent import HoldemGameAgent
>>> from haive.games.hold_em.config import create_default_holdem_config
>>>
>>> # Create a game configuration
>>> config = create_default_holdem_config(num_players=4)
>>>
>>> # Initialize the game agent
>>> agent = HoldemGameAgent(config)
>>>
>>> # Run the game
>>> result = agent.app.invoke({}, debug=True)

Implementation details:

• Enhanced player ID handling and validation

• Robust error checking and recovery

• Comprehensive logging for debugging

• Fixed player lookup and identification

Classes

HoldemGameAgent	Main Texas Hold'em game agent that coordinates the complete poker game.
HoldemGameAgentConfig	Configuration for the main Hold'em game agent.

Module Contents

class games.hold_em.game_agent.HoldemGameAgent(config)

Bases: haive.core.engine.agent.agent.Agent[HoldemGameAgentConfig]

Main Texas Hold’em game agent that coordinates the complete poker game.

This agent manages the entire lifecycle of a Texas Hold’em poker game, implementing all game rules, betting rounds, player actions, and hand evaluations. It creates and coordinates player subgraphs, manages the central game state, and ensures proper game flow from initial setup through the final showdown.

The game progresses through the standard Texas Hold’em phases: 1. Setup hand and post blinds 2. Deal hole cards and run preflop betting 3. Deal flop (3 community cards) and run flop betting 4. Deal turn (4th community card) and run turn betting 5. Deal river (5th community card) and run river betting 6. Showdown evaluation and pot distribution 7. Proceed to next hand or end game

Between betting rounds, the agent routes the game flow based on the current state, handling special cases like all players folded or all-in situations.

This version includes enhanced debugging capabilities, robust player ID handling, and comprehensive error recovery mechanisms.

Init .

Parameters:

config (HoldemGameAgentConfig) – [TODO: Add description]

award_pot(state)

Award the pot to the winner and record hand history.

This node adds the pot to the winner’s chip stack and records the completed hand in the game history. If no winner is explicitly determined (e.g., from showdown), it finds the last remaining player as the winner.

The hand history is recorded with details about the hand number, winner, pot size, community cards, and betting actions for later analysis.

Parameters:

state (HoldemState) – The current game state

Returns:

State update with winner’s updated chips and hand history,

and incremented hand number

Return type:

Command

Raises:

RuntimeError – If pot awarding fails

check_game_end(state)

Check if the game should end.

Parameters:

state (haive.games.hold_em.state.HoldemState)

Return type:

langgraph.types.Command

deal_flop(state)

Deal the flop (3 community cards).

Parameters:

state (haive.games.hold_em.state.HoldemState)

Return type:

langgraph.types.Command[Literal[‘flop_betting’]]

deal_hole_cards(state)

Deal two hole cards to each active player in the game.

This node deals two private cards to each active player from the deck, and determines the first player to act in the preflop betting round. For standard games, the first player to act is the one after the big blind.

Parameters:

state (HoldemState) – The current game state

Returns:

State update with updated deck, player hole cards, and

the index of the first player to act

Return type:

Command

Raises:

RuntimeError – If there aren’t enough cards or dealing fails

deal_river(state)

Deal the river (5th community card).

Parameters:

state (haive.games.hold_em.state.HoldemState)

Return type:

langgraph.types.Command[Literal[‘river_betting’]]

deal_turn(state)

Deal the turn (4th community card).

Parameters:

state (haive.games.hold_em.state.HoldemState)

Return type:

langgraph.types.Command[Literal[‘turn_betting’]]

flop_betting(state)

Handle flop betting round.

Parameters:

state (haive.games.hold_em.state.HoldemState)

Return type:

langgraph.types.Command

get_player_decision(state)

Get decision from current player using their subgraph agent.

This is a critical node that invokes the current player’s subgraph agent to get their poker decision (fold, check, call, bet, raise, or all-in). The method performs extensive validation of player IDs and provides detailed debugging information to track the decision process.

The workflow: 1. Identifies the current player and validates their player_id 2. Prepares input for the player’s subgraph agent 3. Invokes the player agent with the game state and player ID 4. Receives the decision and applies it to the game state

Enhanced debug features include: - Comprehensive player ID validation and repair - Detailed logging of decision context and results - Error tracking with comprehensive context

Parameters:

state (HoldemState) – The current game state

Returns:

State update based on the player’s action

Return type:

Command

Raises:

RuntimeError – If player lookup fails or decision-making fails

log_agent_config(player_config)

Log detailed player agent configuration for debugging purposes.

This method creates a structured representation of a player agent’s configuration and logs it for debugging. It includes information about the player’s style, risk tolerance, engines, and engine details such as models and output formats.

Parameters:

player_config (HoldemPlayerAgentConfig) – The player configuration to log

Returns:

The configuration is logged to the logger

Return type:

None

post_blinds(state)

Post small and big blinds to start the betting.

This node identifies the small blind and big blind players based on their positions, collects the blind amounts from them, and adds these amounts to the pot. If a player doesn’t have enough chips for their blind, they go all-in with their remaining chips.

Parameters:

state (HoldemState) – The current game state

Returns:

State update with updated pot, player chips, and actions

Return type:

Command

Raises:

RuntimeError – If blind players cannot be found or posting fails

preflop_betting(state)

Handle preflop betting round.

Parameters:

state (haive.games.hold_em.state.HoldemState)

Return type:

langgraph.types.Command

river_betting(state)

Handle river betting round.

Parameters:

state (haive.games.hold_em.state.HoldemState)

Return type:

langgraph.types.Command

route_after_betting(state)

Route game flow after a betting round completes.

This conditional routing method determines where the game should proceed after a betting round. The routing logic considers:

1. If only one player remains (others folded) -> award_pot

2. If betting is not complete -> player_decision (continue betting)

3. If only one active player (rest all-in) -> showdown

4. Otherwise, proceed to next game phase based on current phase: - Preflop -> deal_flop - Flop -> deal_turn - Turn -> deal_river - River -> showdown

Parameters:

state (HoldemState) – The current game state

Returns:

The name of the next node to route to

Return type:

str

route_game_continuation(state)

Route game continuation.

Parameters:

state (haive.games.hold_em.state.HoldemState)

Return type:

str

setup_hand(state)

Setup a new poker hand by initializing deck and player states.

This node initializes a new hand by creating and shuffling a deck, resetting player states, advancing the dealer position, and setting up player positions around the table. It prepares all the necessary state for starting a new hand of poker.

Parameters:

state (HoldemState) – The current game state

Returns:

State update with new deck, reset community cards, pot, etc.

Return type:

Command

Raises:

RuntimeError – If hand setup fails due to errors

setup_player_agents()

Set up player subgraph agents with detailed logging.

This method initializes a HoldemPlayerAgent instance for each player in the game based on the player configurations. It creates the independent decision-making subgraphs that will be invoked during betting rounds. The method includes comprehensive error handling and logging to ensure all agents are properly created.

The player agents are stored in a dictionary keyed by player name for later retrieval during decision-making phases.

Raises:

RuntimeError – If any required player agent cannot be created successfully

setup_workflow()

Setup the main game workflow graph with all nodes and transitions.

This method configures the complete LangGraph workflow for the poker game, defining all game phases, decision points, and conditional routing logic. It establishes the core game flow including:

1. Game setup nodes: setup_hand, post_blinds, deal_hole_cards

2. Betting round nodes: preflop_betting, flop_betting, turn_betting, river_betting

3. Card dealing nodes: deal_flop, deal_turn, deal_river

4. Game conclusion nodes: showdown, award_pot, check_game_end

5. Player decision node: Invokes player subgraphs for decisions

The graph includes conditional edges to route game flow based on the current state, such as proceeding to the next betting round or directly to showdown when appropriate. This creates a complete state machine for poker game flow.

showdown(state)

Handle showdown - evaluate player hands and determine the winner.

This node evaluates the hand of each player still in the game (not folded) and determines the winner based on hand strength. In case only one player remains, that player automatically wins. Otherwise, all qualifying hands are compared to find the strongest.

The current implementation uses a simplified hand evaluation algorithm, which would be replaced by a more sophisticated poker hand evaluator in a production version.

Parameters:

state (HoldemState) – The current game state

Returns:

State update with the winner’s player ID

Return type:

Command

Raises:

RuntimeError – If showdown evaluation fails

turn_betting(state)

Handle turn betting round.

Parameters:

state (haive.games.hold_em.state.HoldemState)

Return type:

langgraph.types.Command

class games.hold_em.game_agent.HoldemGameAgentConfig

Bases: haive.core.engine.agent.agent.AgentConfig

Configuration for the main Hold’em game agent.

This configuration class defines the parameters for a Texas Hold’em game, including the number of players, blinds, starting chips, game limits, and player agent configurations. It encapsulates all the settings needed to initialize and run a complete poker game.

The configuration serves as the blueprint for creating a HoldemGameAgent instance with specific game rules and player characteristics. It can be created directly or through helper functions in the config module.