haive.games.hold_em.models ========================== .. py:module:: haive.games.hold_em.models .. autoapi-nested-parse:: 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 .. rubric:: 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 ------- .. autoapisummary:: haive.games.hold_em.models.BettingDecision haive.games.hold_em.models.GameSituationAnalysis haive.games.hold_em.models.HandEvaluation haive.games.hold_em.models.HandRank haive.games.hold_em.models.OpponentModel haive.games.hold_em.models.PlayerDecisionModel haive.games.hold_em.models.PokerAction haive.games.hold_em.models.PokerAnalysis haive.games.hold_em.models.PokerCard haive.games.hold_em.models.PokerHandHistory haive.games.hold_em.models.Position haive.games.hold_em.models.TableDynamics Module Contents --------------- .. py:class:: BettingDecision(/, **data) Bases: :py:obj:`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. .. py:class:: GameSituationAnalysis(/, **data) Bases: :py:obj:`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. .. py:class:: HandEvaluation(/, **data) Bases: :py:obj:`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. .. py:class:: HandRank Bases: :py:obj:`str`, :py:obj:`enum.Enum` Hand rankings in poker. Initialize self. See help(type(self)) for accurate signature. .. py:class:: OpponentModel(/, **data) Bases: :py:obj:`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. .. py:class:: PlayerDecisionModel(/, **data) Bases: :py:obj:`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. .. py:method:: validate_amount(v) :classmethod: Validate bet amount. .. py:method:: validate_confidence(v) :classmethod: Validate confidence score. .. py:class:: PokerAction Bases: :py:obj:`str`, :py:obj:`enum.Enum` Possible poker actions. Initialize self. See help(type(self)) for accurate signature. .. py:class:: PokerAnalysis(/, **data) Bases: :py:obj:`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. .. py:class:: PokerCard(/, **data) Bases: :py:obj:`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. .. py:method:: validate_rank(v) :classmethod: Validate card rank. .. py:method:: validate_suit(v) :classmethod: Validate card suit. .. py:class:: PokerHandHistory(/, **data) Bases: :py:obj:`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. .. py:class:: Position Bases: :py:obj:`str`, :py:obj:`enum.Enum` Player positions. Initialize self. See help(type(self)) for accurate signature. .. py:class:: TableDynamics(/, **data) Bases: :py:obj:`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.