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 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 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 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 games.hold_em.models.HandRank¶

Bases: str, enum.Enum

Hand rankings in poker.

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

class 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 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 games.hold_em.models.PokerAction¶

Bases: str, enum.Enum

Possible poker actions.

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

class 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 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 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 games.hold_em.models.Position¶

Bases: str, enum.Enum

Player positions.

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

class 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)