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¶

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

Calculate effective stack between two players.

Parameters:
Return type:

int

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

games.hold_em.utils.card_to_rank_value(card)¶

Convert card rank to numeric value for comparison.

Parameters:

card (str)

Return type:

int

games.hold_em.utils.card_to_suit(card)¶

Extract suit from card.

Parameters:

card (str)

Return type:

str

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

Count players with specific statuses.

Parameters:
Return type:

int

games.hold_em.utils.create_standard_deck()¶

Create a standard 52-card deck.

Return type:

list[str]

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

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

Parameters:
Return type:

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

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:
Return type:

dict[str, any]

games.hold_em.utils.format_cards(cards)¶

Format cards for display with suit symbols.

Parameters:

cards (list[str])

Return type:

str

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

games.hold_em.utils.get_board_texture_description(community_cards)¶

Describe the board texture.

Parameters:

community_cards (list[str])

Return type:

str

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

Get the next active player starting from a position.

Parameters:
Return type:

int | None

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

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

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

games.hold_em.utils.shuffle_deck(deck)¶

Shuffle a deck of cards.

Parameters:

deck (list[str])

Return type:

list[str]

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]