games.hold_em.player_agent¶

Texas Hold’em Player Agent module for LLM-powered poker players.

This module implements the player decision-making system for Texas Hold’em poker, providing a complete workflow for analyzing the game state and making strategic decisions. The player agent is implemented as a subgraph in the main game graph, with each player having their own autonomous decision-making process.

Key components:

PlayerSubgraphState: State model for player decision-making
HoldemPlayerAgentConfig: Configuration for player agents
HoldemPlayerAgent: The player agent implementation with decision workflow
Decision pipeline: Situation analysis -> Hand analysis -> Opponent analysis -> Decision

The agent uses a multi-step analysis process, with each step handled by a specialized LLM engine to generate the final poker decision. This design allows for detailed reasoning about poker strategy based on the current game state.

Examples

>>> from haive.games.hold_em.player_agent import HoldemPlayerAgent, HoldemPlayerAgentConfig
>>> from haive.games.hold_em.engines import build_player_engines
>>>
>>> # Create a player configuration
>>> player_engines = build_player_engines("Alice", "balanced")
>>> player_config = HoldemPlayerAgentConfig(
...     name="player_alice",
...     player_name="Alice",
...     player_style="balanced",
...     engines=player_engines
... )
>>>
>>> # Create the player agent
>>> player_agent = HoldemPlayerAgent(player_config)

Classes¶

`HoldemPlayerAgent`	Player agent for Texas Hold'em poker games.
`HoldemPlayerAgentConfig`	Configuration for Hold'em player agent.
`PlayerSubgraphState`	State model for the player decision subgraph.

Module Contents¶

class games.hold_em.player_agent.HoldemPlayerAgent(config)¶

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

Player agent for Texas Hold’em poker games.

This agent implements the complete decision-making pipeline for a poker player, analyzing the game state and making betting decisions based on a multi-step process:

Situation analysis - Evaluate position, pot odds, betting action, etc.
Hand analysis - Assess hole cards and community cards strength
Opponent analysis - Model opponents’ tendencies and likely holdings
Final decision - Synthesize analyses into a concrete betting action

Each step is handled by a specialized LLM engine configured with poker-specific prompts. The agent supports different playing styles (tight, loose, aggressive, etc.) and can adapt its risk tolerance and strategy based on configuration.

This agent does not include fallback mechanisms, allowing for clear error exposure and debugging of decision-making issues.

Init .

Parameters:: config (HoldemPlayerAgentConfig) – [TODO: Add description]

analyze_hand(state)¶

Analyze the player’s hand strength and potential.

This node evaluates the strength of the player’s hole cards in combination with the community cards, calculating hand rankings, draw potential, and relative strength against likely opponent ranges.

The analysis is performed by the ‘hand_analyzer’ LLM engine, which considers: - Current made hand (pair, two pair, etc.) - Drawing possibilities (flush draws, straight draws) - Pot odds vs. hand equity - Hand strength at current game phase

Parameters:: state (PlayerSubgraphState) – The current state containing game information, player identity, and situation analysis.
Returns:: State update with hand analysis results
Return type:: Command
Raises:: RuntimeError – If player not found or analysis fails

analyze_opponents(state)¶

Analyze opponent behavior, tendencies, and likely holdings.

This node models opponents’ play styles, betting patterns, and probable hand ranges based on their actions in the current hand and previous history. It helps inform strategic decisions by understanding opponent tendencies.

The analysis is performed by the ‘opponent_analyzer’ LLM engine, which considers: - Betting patterns and sizing tells - Position-based tendencies - Aggression levels - Likely hand ranges based on actions - Exploitable tendencies

Parameters:: state (PlayerSubgraphState) – The current state containing game information, player identity, situation analysis, and hand analysis.
Returns:: State update with opponent analysis results
Return type:: Command
Raises:: RuntimeError – If analysis fails

analyze_situation(state)¶

Analyze the current game situation and table dynamics.

This node in the decision graph evaluates the overall poker situation including position, pot size, betting action, stack sizes, and game phase. It forms the foundation for subsequent decision-making steps.

The analysis is performed by the ‘situation_analyzer’ LLM engine and the results are added to the state for use in later decision steps.

Parameters:: state (PlayerSubgraphState) – The current state containing game information and player identity.
Returns:: State update with situation analysis results
Return type:: Command
Raises:: RuntimeError – If player not found in game state or analysis fails

make_decision(state)¶

Make the final betting decision based on all previous analyses.

This is the final node in the decision graph that synthesizes all previous analyses (situation, hand, opponents) into a concrete poker action: fold, check, call, bet, raise, or all-in. It handles validation and correction of decisions to ensure they’re legal within the game rules.

The decision is made by the ‘decision_maker’ LLM engine, which produces a structured betting decision with: - The primary action to take - Bet/raise amount if applicable - Detailed reasoning for the decision - Confidence level

This method handles both PlayerDecisionModel and BettingDecision model formats by normalizing them to a consistent structure.

Parameters:: state (PlayerSubgraphState) – The complete state with all analysis results
Returns:: Final state update with the betting decision
Return type:: Command
Raises:: RuntimeError – If player lookup fails or decision making fails

save_debug_logs(timestamp=None)¶

Save debug logs for this player agent to JSON files.

This method saves three types of debug logs to help with debugging and analyzing player agent behavior: - Analysis log: Records details of situation, hand, and opponent analyses - Decision log: Records betting decisions and their reasoning - Error log: Records any errors encountered during decision-making

Parameters:

timestamp (str, optional) – Timestamp string for log filenames. If None, current datetime will be used.

Returns:

Files are saved to the current directory with names like:: player_analysis_{player_name}_{timestamp}.json player_decisions_{player_name}_{timestamp}.json player_errors_{player_name}_{timestamp}.json

Return type:

None

setup_workflow()¶

Setup the player decision workflow graph.

This method configures the LangGraph workflow for player decision-making, establishing the sequence of analysis steps and their dependencies.

The workflow follows a linear sequence: 1. START → analyze_situation: Evaluate the current game situation 2. analyze_situation → analyze_hand: Assess the player’s hand strength 3. analyze_hand → analyze_opponents: Analyze opponent tendencies 4. analyze_opponents → make_decision: Make the final betting decision 5. make_decision → END: Return the final decision

Each step must complete successfully in sequence for the decision to be made.

Return type:: None

class games.hold_em.player_agent.HoldemPlayerAgentConfig¶

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

Configuration for Hold’em player agent.

This configuration class defines the parameters for a Texas Hold’em player agent, including player identity, playing style, risk tolerance, and the LLM engines used for different aspects of decision-making.

The configuration is used to initialize a player agent with specific characteristics and behavior patterns. Different combinations of style and risk_tolerance create varied player behaviors from conservative to aggressive play.

class games.hold_em.player_agent.PlayerSubgraphState(/, **data)¶

Bases: pydantic.BaseModel

State model for the player decision subgraph.

This model represents the complete state for a player’s decision- making process, including the inputs from the main game, intermediate analysis results, and the final decision output. It tracks the entire decision pipeline from situation analysis through hand analysis and opponent modeling to the final betting decision.

The state is passed between nodes in the player’s decision graph and accumulates information at each step, ultimately producing a final poker action decision.

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.

Parameters:: data (Any)