haive.games.hold_em.models

Comprehensive data models for Texas Hold’em poker gameplay.

This module defines the complete set of data structures for Texas Hold’em poker, providing models for betting actions, hand evaluation, strategic analysis, and game state management. The implementation supports standard No-Limit Texas Hold’em rules with comprehensive position and action tracking.

Texas Hold’em is a strategic poker variant involving: - Two hole cards dealt to each player - Five community cards dealt in stages (flop, turn, river) - Multiple betting rounds with strategic decision-making - Hand ranking system for winner determination - Position-based strategy and betting patterns

Key Models:

HandRank: Poker hand strength enumeration PokerAction: Available betting actions Position: Player seating positions with strategic implications HoldEmDecision: Complete player decision with analysis HoldEmAnalysis: Strategic position evaluation

Examples

Working with hand rankings:

from haive.games.hold_em.models import HandRank

# Hand strength comparison
royal_flush = HandRank.ROYAL_FLUSH
high_card = HandRank.HIGH_CARD
assert royal_flush.value == "royal_flush"

# Ranking order (strongest to weakest)
hand_strength = [
    HandRank.ROYAL_FLUSH,
    HandRank.STRAIGHT_FLUSH,
    HandRank.FOUR_OF_A_KIND,
    HandRank.FULL_HOUSE,
    HandRank.FLUSH,
    HandRank.STRAIGHT,
    HandRank.THREE_OF_A_KIND,
    HandRank.TWO_PAIR,
    HandRank.PAIR,
    HandRank.HIGH_CARD
]

Making betting decisions:

from haive.games.hold_em.models import PokerAction, HoldEmDecision

# Aggressive betting decision
decision = HoldEmDecision(
    action=PokerAction.RAISE,
    amount=100,
    reasoning="Strong hand with flush draw",
    confidence=0.85
)

# Conservative play
conservative = HoldEmDecision(
    action=PokerAction.CHECK,
    amount=0,
    reasoning="Weak hand, wait for better spot",
    confidence=0.9
)

Strategic position analysis:

from haive.games.hold_em.models import Position, HoldEmAnalysis

analysis = HoldEmAnalysis(
    position=Position.BUTTON,
    hand_strength=0.75,
    pot_odds=2.5,
    implied_odds=4.0,
    strategic_advice="Raise for value, good position"
)

The models provide comprehensive support for strategic poker AI development with proper validation and poker-specific business logic.

Classes

BettingDecision	Structured betting decision.
GameSituationAnalysis	Analysis of the current game situation.
HandEvaluation	Model for hand evaluation.
HandRank	Hand rankings in poker.
OpponentModel	Model of an opponent's playing style.
PlayerDecisionModel	Model for player decision-making.
PokerAction	Possible poker actions.
PokerAnalysis	Model for poker position analysis.
PokerCard	Model for a poker card.
PokerHandHistory	History of a completed poker hand.
Position	Player positions.
TableDynamics	Analysis of table dynamics.

Module Contents

class haive.games.hold_em.models.BettingDecision(/, **data)

Bases: pydantic.BaseModel

Structured betting decision.

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.

Parameters:

data (Any)

class haive.games.hold_em.models.GameSituationAnalysis(/, **data)

Bases: pydantic.BaseModel

Analysis of the current game situation.

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.

Parameters:

data (Any)

class haive.games.hold_em.models.HandEvaluation(/, **data)

Bases: pydantic.BaseModel

Model for hand evaluation.

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.

Parameters:

data (Any)

class haive.games.hold_em.models.HandRank

Bases: str, enum.Enum

Hand rankings in poker.

Initialize self. See help(type(self)) for accurate signature.

class haive.games.hold_em.models.OpponentModel(/, **data)

Bases: pydantic.BaseModel

Model of an opponent’s playing style.

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.

Parameters:

data (Any)

class haive.games.hold_em.models.PlayerDecisionModel(/, **data)

Bases: pydantic.BaseModel

Model for player decision-making.

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.

Parameters:

data (Any)

classmethod validate_amount(v)

Validate bet amount.

Parameters:

v (int)

Return type:

int

classmethod validate_confidence(v)

Validate confidence score.

Parameters:

v (float)

Return type:

float

class haive.games.hold_em.models.PokerAction

Bases: str, enum.Enum

Possible poker actions.

Initialize self. See help(type(self)) for accurate signature.

class haive.games.hold_em.models.PokerAnalysis(/, **data)

Bases: pydantic.BaseModel

Model for poker position analysis.

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.

Parameters:

data (Any)

class haive.games.hold_em.models.PokerCard(/, **data)

Bases: pydantic.BaseModel

Model for a poker card.

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.

Parameters:

data (Any)

classmethod validate_rank(v)

Validate card rank.

Parameters:

v (str)

Return type:

str

classmethod validate_suit(v)

Validate card suit.

Parameters:

v (str)

Return type:

str

class haive.games.hold_em.models.PokerHandHistory(/, **data)

Bases: pydantic.BaseModel

History of a completed poker hand.

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.

Parameters:

data (Any)

class haive.games.hold_em.models.Position

Bases: str, enum.Enum

Player positions.

Initialize self. See help(type(self)) for accurate signature.

class haive.games.hold_em.models.TableDynamics(/, **data)

Bases: pydantic.BaseModel

Analysis of table dynamics.

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.

Parameters:

data (Any)