haive.games.hold_em.utils

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

calculate_effective_stack(player, opponent)	Calculate effective stack between two players.
calculate_pot_odds(pot_size, bet_to_call)	Calculate pot odds as a ratio.
card_to_rank_value(card)	Convert card rank to numeric value for comparison.
card_to_suit(card)	Extract suit from card.
count_players_in_phase(game_state, statuses)	Count players with specific statuses.
create_standard_deck()	Create a standard 52-card deck.
deal_cards(deck, num_cards)	Deal cards from deck, returning (dealt_cards, remaining_deck).
evaluate_hand_simple(hole_cards, community_cards)	Simple hand evaluation (placeholder for production poker evaluator).
format_cards(cards)	Format cards for display with suit symbols.
format_game_summary(game_state)	Format a summary of the current game state.
get_board_texture_description(community_cards)	Describe the board texture.
get_next_active_player(game_state, start_position)	Get the next active player starting from a position.
get_position_name(position, num_players, dealer_pos)	Get position name based on seat and dealer position.
is_position_early(position, num_players, dealer_pos)	Check if position is early.
is_position_late(position, num_players, dealer_pos)	Check if position is late.
shuffle_deck(deck)	Shuffle a deck of cards.
validate_game_state(game_state)	Validate game state and return list of issues.

Module Contents

haive.games.hold_em.utils.calculate_effective_stack(player, opponent)

Calculate effective stack between two players.

Parameters:

• player (haive.games.hold_em.state.PlayerState)

• opponent (haive.games.hold_em.state.PlayerState)

Return type:

int

haive.games.hold_em.utils.calculate_pot_odds(pot_size, bet_to_call)

Calculate pot odds as a ratio.

Parameters:

• pot_size (int)

• bet_to_call (int)

Return type:

float

haive.games.hold_em.utils.card_to_rank_value(card)

Convert card rank to numeric value for comparison.

Parameters:

card (str)

Return type:

int

haive.games.hold_em.utils.card_to_suit(card)

Extract suit from card.

Parameters:

card (str)

Return type:

str

haive.games.hold_em.utils.count_players_in_phase(game_state, statuses)

Count players with specific statuses.

Parameters:

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

• statuses (list[haive.games.hold_em.state.PlayerStatus])

Return type:

int

haive.games.hold_em.utils.create_standard_deck()

Create a standard 52-card deck.

Return type:

list[str]

haive.games.hold_em.utils.deal_cards(deck, num_cards)

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

Parameters:

• deck (list[str])

• num_cards (int)

Return type:

tuple[list[str], list[str]]

haive.games.hold_em.utils.evaluate_hand_simple(hole_cards, community_cards)

Simple hand evaluation (placeholder for production poker evaluator).

Returns hand rank, strength score, and description.

Parameters:

• hole_cards (list[str])

• community_cards (list[str])

Return type:

dict[str, any]

haive.games.hold_em.utils.format_cards(cards)

Format cards for display with suit symbols.

Parameters:

cards (list[str])

Return type:

str

haive.games.hold_em.utils.format_game_summary(game_state)

Format a summary of the current game state.

Parameters:

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

Return type:

str

haive.games.hold_em.utils.get_board_texture_description(community_cards)

Describe the board texture.

Parameters:

community_cards (list[str])

Return type:

str

haive.games.hold_em.utils.get_next_active_player(game_state, start_position)

Get the next active player starting from a position.

Parameters:

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

• start_position (int)

Return type:

int | None

haive.games.hold_em.utils.get_position_name(position, num_players, dealer_pos)

Get position name based on seat and dealer position.

Parameters:

• position (int)

• num_players (int)

• dealer_pos (int)

Return type:

str

haive.games.hold_em.utils.is_position_early(position, num_players, dealer_pos)

Check if position is early.

Parameters:

• position (int)

• num_players (int)

• dealer_pos (int)

Return type:

bool

haive.games.hold_em.utils.is_position_late(position, num_players, dealer_pos)

Check if position is late.

Parameters:

• position (int)

• num_players (int)

• dealer_pos (int)

Return type:

bool

haive.games.hold_em.utils.shuffle_deck(deck)

Shuffle a deck of cards.

Parameters:

deck (list[str])

Return type:

list[str]

haive.games.hold_em.utils.validate_game_state(game_state)

Validate game state and return list of issues.

Parameters:

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

Return type:

list[str]