haive.games.hold_em.utils
=========================

.. py:module:: haive.games.hold_em.utils

.. autoapi-nested-parse::

   Texas Hold'em utility functions.

   This module provides utility functions for the Hold'em game, including:
       - Card and hand evaluation
       - Game state utilities
       - Poker calculations



Functions
---------

.. autoapisummary::

   haive.games.hold_em.utils.calculate_effective_stack
   haive.games.hold_em.utils.calculate_pot_odds
   haive.games.hold_em.utils.card_to_rank_value
   haive.games.hold_em.utils.card_to_suit
   haive.games.hold_em.utils.count_players_in_phase
   haive.games.hold_em.utils.create_standard_deck
   haive.games.hold_em.utils.deal_cards
   haive.games.hold_em.utils.evaluate_hand_simple
   haive.games.hold_em.utils.format_cards
   haive.games.hold_em.utils.format_game_summary
   haive.games.hold_em.utils.get_board_texture_description
   haive.games.hold_em.utils.get_next_active_player
   haive.games.hold_em.utils.get_position_name
   haive.games.hold_em.utils.is_position_early
   haive.games.hold_em.utils.is_position_late
   haive.games.hold_em.utils.shuffle_deck
   haive.games.hold_em.utils.validate_game_state


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

.. py:function:: calculate_effective_stack(player, opponent)

   Calculate effective stack between two players.


.. py:function:: calculate_pot_odds(pot_size, bet_to_call)

   Calculate pot odds as a ratio.


.. py:function:: card_to_rank_value(card)

   Convert card rank to numeric value for comparison.


.. py:function:: card_to_suit(card)

   Extract suit from card.


.. py:function:: count_players_in_phase(game_state, statuses)

   Count players with specific statuses.


.. py:function:: create_standard_deck()

   Create a standard 52-card deck.


.. py:function:: deal_cards(deck, num_cards)

   Deal cards from deck, returning (dealt_cards, remaining_deck).


.. py:function:: evaluate_hand_simple(hole_cards, community_cards)

   Simple hand evaluation (placeholder for production poker evaluator).

   Returns hand rank, strength score, and description.



.. py:function:: format_cards(cards)

   Format cards for display with suit symbols.


.. py:function:: format_game_summary(game_state)

   Format a summary of the current game state.


.. py:function:: get_board_texture_description(community_cards)

   Describe the board texture.


.. py:function:: get_next_active_player(game_state, start_position)

   Get the next active player starting from a position.


.. py:function:: get_position_name(position, num_players, dealer_pos)

   Get position name based on seat and dealer position.


.. py:function:: is_position_early(position, num_players, dealer_pos)

   Check if position is early.


.. py:function:: is_position_late(position, num_players, dealer_pos)

   Check if position is late.


.. py:function:: shuffle_deck(deck)

   Shuffle a deck of cards.


.. py:function:: validate_game_state(game_state)

   Validate game state and return list of issues.