haive.games.hold_em.state_manager
=================================

.. py:module:: haive.games.hold_em.state_manager

.. autoapi-nested-parse::

   Texas Hold'em game state management module.

   This module provides a dedicated state manager for Texas Hold'em poker games,
   offering static methods for state manipulation, including:
       - Creating and initializing game states
       - Advancing game phases
       - Applying player actions
       - Handling betting rounds
       - Managing pot and chip distribution
       - Tracking hand history

   The state manager serves as a central interface for manipulating the game state
   in a consistent manner, separating state manipulation logic from the game agent.

   .. rubric:: Example

   >>> from haive.games.hold_em.state_manager import HoldemGameStateManager
   >>> from haive.games.hold_em.state import HoldemState, PlayerState
   >>>
   >>> # Create player states
   >>> players = [
   >>>     PlayerState(player_id="p1", name="Alice", chips=1000, position=0),
   >>>     PlayerState(player_id="p2", name="Bob", chips=1000, position=1),
   >>> ]
   >>>
   >>> # Initialize a new game state
   >>> state = HoldemGameStateManager.create_initial_state(
   >>>     players=players,
   >>>     small_blind=10,
   >>>     big_blind=20
   >>> )
   >>>
   >>> # Advance the game to the next phase
   >>> updated_state = HoldemGameStateManager.advance_phase(state)



Classes
-------

.. autoapisummary::

   haive.games.hold_em.state_manager.HoldemGameStateManager


Module Contents
---------------

.. py:class:: HoldemGameStateManager

   State manager for Texas Hold'em poker games.

   This class provides static methods for manipulating the game state, separating state
   logic from the game agent. It handles state transitions, player actions, and game
   flow management in a functional manner.

   All methods are static and take a state object as input, returning a new state
   object with the requested changes applied, following an immutable approach to state
   management.



   .. py:method:: advance_phase(state)
      :staticmethod:


      Advance the game to the next phase based on current phase.

      :param state: Current game state

      :returns: Updated state in the next game phase



   .. py:method:: apply_player_action(state, player_index, action, amount = 0)
      :staticmethod:


      Apply a player's action to the game state.

      :param state: Current game state
      :param player_index: Index of the player taking the action
      :param action: Action to take (fold, check, call, bet, raise, all_in)
      :param amount: Amount for bet/raise (if applicable)

      :returns: Updated state with the action applied



   .. py:method:: award_pot(state)
      :staticmethod:


      Award the pot to the winner and record hand history.

      :param state: Current game state

      :returns: Updated state with pot awarded and hand recorded



   .. py:method:: check_game_end(state)
      :staticmethod:


      Check if the game should end.

      :param state: Current game state

      :returns: Tuple of (updated state, game_over flag)



   .. py:method:: create_initial_state(players, small_blind = 10, big_blind = 20, starting_chips = 1000, game_id = None)
      :staticmethod:


      Create an initial game state for a new poker game.

      :param players: List of player states
      :param small_blind: Small blind amount
      :param big_blind: Big blind amount
      :param starting_chips: Starting chips for each player
      :param game_id: Optional game identifier (generated if not provided)

      :returns: A new HoldemState instance ready for the first hand



   .. py:method:: deal_community_cards(state, num_cards, phase)
      :staticmethod:


      Deal community cards (flop, turn, or river).

      :param state: Current game state
      :param num_cards: Number of cards to deal
      :param phase: New game phase

      :returns: Updated state with community cards dealt



   .. py:method:: deal_hole_cards(state)
      :staticmethod:


      Deal two hole cards to each active player.

      :param state: Current game state

      :returns: Updated state with hole cards dealt



   .. py:method:: evaluate_showdown(state)
      :staticmethod:


      Evaluate player hands at showdown and determine winner.

      :param state: Current game state

      :returns: Updated state with winner determined



   .. py:method:: post_blinds(state)
      :staticmethod:


      Post small and big blinds to start the betting.

      :param state: Current game state

      :returns: Updated state with blinds posted



   .. py:method:: setup_new_hand(state)
      :staticmethod:


      Set up a new poker hand with shuffled deck and reset player states.

      :param state: Current game state

      :returns: Updated state with new hand setup