haive.games.poker.state ======================= .. py:module:: haive.games.poker.state .. autoapi-nested-parse:: 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. .. rubric:: 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 ------- .. autoapisummary:: haive.games.poker.state.PokerState Module Contents --------------- .. py:class:: PokerState(/, **data) Bases: :py:obj:`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. .. attribute:: messages Message history for agent communication :type: List[BaseMessage] .. attribute:: current_step Current step in the game progression :type: int .. attribute:: max_steps Maximum allowed steps before forced game end :type: int .. attribute:: error Current error state, if any :type: Optional[str] .. attribute:: memory Persistent memory for game state :type: Dict[str, Any] .. attribute:: game Current game state :type: PokerGameState .. attribute:: waiting_for_player ID of player we're waiting for :type: Optional[str] .. attribute:: game_log Timestamped log of game events :type: List[str] .. attribute:: current_decision Last decision made :type: Optional[AgentDecision] .. rubric:: 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. .. py:method:: 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 .. py:method:: 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). :param player_id: ID of player to create observation for :type player_id: str :returns: Object containing all information visible to player :rtype: PlayerObservation :raises ValueError: If player_id is not found .. rubric:: Example >>> obs = state.create_player_observation("player_0") >>> print(obs.hand) # Shows player's hole cards >>> print(obs.community_cards) # Shows shared cards .. py:method:: 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. :param count: Number of cards to deal. Defaults to 3 for flop. :type count: int, optional :raises Sets self.error if there aren't enough cards in the deck.: .. py:method:: 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. .. py:method:: 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. :param player_id: ID of player taking action :type player_id: str :param decision: Player's chosen action and amount :type decision: AgentDecision 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 .. py:method:: 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. .. py:method:: 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. :param player_names: Names of players to add :type player_names: List[str] :param starting_chips: Initial chips per player. Defaults to 1000. :type starting_chips: int, optional .. rubric:: Example >>> state.initialize_game(["Alice", "Bob", "Charlie"], 2000) .. py:method:: 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. :param message: Event message to log :type message: str .. rubric:: Example >>> state.log_event("Alice raises to $100") [14:30:45] Alice raises to $100 .. py:method:: 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: :raises positions can't be determined.: .. py:method:: 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