games.poker.models

Core data models for the Poker game implementation.

This module defines the fundamental data structures and models used in the poker game, including:

• Card suits and values

• Hand rankings and game phases

• Player actions and states

• Game state tracking

• Decision models for LLM output

The models use Pydantic for validation and serialization, ensuring type safety and consistent data structures throughout the game.

Examples

>>> from poker.models import Card, Suit, CardValue
>>>
>>> # Create a card
>>> ace_of_spades = Card(suit=Suit.SPADES, value=CardValue.ACE)
>>> print(ace_of_spades)  # Shows "Ace of spades"

Classes

ActionRecord	Record of a player's action.
AgentDecision	Agent's decision in the game.
AgentDecisionSchema	Schema for LLM decision output.
Card	Playing card model.
CardValue	Card value enumeration.
GamePhase	Poker game phase enumeration.
GameResult	Poker game result record.
Hand	Playing hand model.
HandRank	Poker hand ranking enumeration.
HandRanking	Poker hand ranking result.
Player	Player model for poker game.
PlayerAction	Player action enumeration.
PlayerObservation	Player's view of the game state.
PokerGameState	Texas Hold'em poker game state.
Pot	Poker pot model.
Suit	Card suit enumeration.

Module Contents

class games.poker.models.ActionRecord(/, **data)

Bases: pydantic.BaseModel

Record of a player’s action.

Tracks a single action taken by a player during the game, including the type of action, amount (if any), and game phase.

Parameters:

data (Any)

player_id

ID of player who took action

Type:

str

action

Type of action taken

Type:

PlayerAction

amount

Chips bet/raised, if applicable

Type:

int

phase

Game phase when action occurred

Type:

GamePhase

Examples

>>> record = ActionRecord(
...     player_id="p1",
...     action=PlayerAction.RAISE,
...     amount=100,
...     phase=GamePhase.FLOP
... )

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.

class games.poker.models.AgentDecision(/, **data)

Bases: pydantic.BaseModel

Agent’s decision in the game.

Represents a decision made by an AI agent, including the action, bet amount (if any), and reasoning behind the decision.

Parameters:

data (Any)

action

Chosen action

Type:

PlayerAction

amount

Bet/raise amount if applicable

Type:

int

reasoning

Explanation of decision

Type:

str

Examples

>>> decision = AgentDecision(
...     action=PlayerAction.RAISE,
...     amount=100,
...     reasoning="Strong hand, building pot"
... )
>>> print(decision)  # Shows decision details

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.

class games.poker.models.AgentDecisionSchema(/, **data)

Bases: pydantic.BaseModel

Schema for LLM decision output.

Defines the expected structure for decisions generated by the language model, ensuring consistent and valid output format.

Parameters:

data (Any)

action

Type of action to take

Type:

PlayerAction

amount

Chips to bet/raise

Type:

int

reasoning

Explanation of decision

Type:

str

Examples

>>> schema = AgentDecisionSchema(
...     action=PlayerAction.CALL,
...     amount=50,
...     reasoning="Good pot odds with drawing 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.

class games.poker.models.Card(/, **data)

Bases: pydantic.BaseModel

Playing card model.

Represents a standard playing card with suit and value. Provides methods for numeric value comparison.

Parameters:

data (Any)

suit

Card’s suit

Type:

Suit

value

Card’s value

Type:

CardValue

Examples

>>> card = Card(suit=Suit.HEARTS, value=CardValue.ACE)
>>> print(card)  # Shows "Ace of hearts"
>>> print(card.numeric_value)  # Shows 14

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.

property numeric_value: int

Get numeric value of card (2-14, with Ace being 14).

Return type:

int

property numeric_value_low: int

Get numeric value treating Ace as 1.

Used for A-2-3-4-5 straight calculations.

Return type:

int

class games.poker.models.CardValue

Bases: int, enum.Enum

Card value enumeration.

Represents standard playing card values from 2 to Ace. Inherits from int.Enum for numeric comparison (e.g., King > Queen). Ace is highest by default (14) but can be treated as 1 in certain contexts (e.g., A-2-3-4-5 straight).

TWO

Value 2

Type:

int

THREE

Value 3

Type:

int

...

KING

Value 13

Type:

int

ACE

Value 14 (or 1 in some contexts)

Type:

int

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

class games.poker.models.GamePhase

Bases: str, enum.Enum

Poker game phase enumeration.

Represents the different phases of a Texas Hold’em poker game. Inherits from str.Enum for easy serialization and comparison.

SETUP

Initial game setup

Type:

str

PREFLOP

Before community cards

Type:

str

FLOP

First three community cards

Type:

str

TURN

Fourth community card

Type:

str

RIVER

Fifth community card

Type:

str

SHOWDOWN

Hand comparison

Type:

str

GAME_OVER

Game completed

Type:

str

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

class games.poker.models.GameResult(/, **data)

Bases: pydantic.BaseModel

Poker game result record.

Stores the final outcome of a completed game, including winners, chip counts, and hand rankings.

Parameters:

data (Any)

winners

IDs of winning players

Type:

List[str]

final_chips

Final chip counts by player

Type:

Dict[str, int]

hand_rankings

Final hand evaluations

Type:

Dict[str, HandRanking]

total_hands_played

Number of hands completed

Type:

int

Examples

>>> result = GameResult(
...     winners=["p1"],
...     final_chips={"p1": 2000, "p2": 0},
...     hand_rankings={"p1": ace_high_flush},
...     total_hands_played=1
... )

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.

class games.poker.models.Hand(/, **data)

Bases: pydantic.BaseModel

Playing hand model.

Represents a collection of cards held by a player or on the board. Limited to 7 cards maximum (2 hole cards + 5 community cards).

Parameters:

data (Any)

cards

List of cards in the hand

Type:

List[Card]

Examples

>>> hand = Hand(cards=[
...     Card(suit=Suit.HEARTS, value=CardValue.ACE),
...     Card(suit=Suit.HEARTS, value=CardValue.KING)
... ])
>>> print(hand)  # Shows "Ace of hearts, King of hearts"

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.

class games.poker.models.HandRank

Bases: int, enum.Enum

Poker hand ranking enumeration.

Represents the standard poker hand rankings from high card to royal flush. Inherits from int.Enum for easy comparison of hand strengths.

HIGH_CARD

Highest card in hand

Type:

int

PAIR

Two cards of same value

Type:

int

TWO_PAIR

Two different pairs

Type:

int

THREE_OF_A_KIND

Three cards of same value

Type:

int

STRAIGHT

Five sequential cards

Type:

int

FLUSH

Five cards of same suit

Type:

int

FULL_HOUSE

Three of a kind plus a pair

Type:

int

FOUR_OF_A_KIND

Four cards of same value

Type:

int

STRAIGHT_FLUSH

Sequential cards of same suit

Type:

int

ROYAL_FLUSH

A-K-Q-J-10 of same suit

Type:

int

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

class games.poker.models.HandRanking(/, **data)

Bases: pydantic.BaseModel

Poker hand ranking result.

Represents the evaluation of a player’s best possible hand, including rank, high cards for tiebreakers, and description.

Parameters:

data (Any)

player_id

ID of player whose hand was ranked

Type:

str

rank

Type of hand (pair, flush, etc.)

Type:

HandRank

high_cards

Cards used for tiebreaking

Type:

List[CardValue]

description

Human-readable hand description

Type:

str

Examples

>>> ranking = HandRanking(
...     player_id="p1",
...     rank=HandRank.FLUSH,
...     high_cards=[CardValue.ACE, CardValue.KING],
...     description="Ace-high flush"
... )

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.

class games.poker.models.Player(/, **data)

Bases: pydantic.BaseModel

Player model for poker game.

Represents a player in the game, tracking their cards, chips, and game status. Includes betting information and position at the table.

Parameters:

data (Any)

id

Unique identifier for the player

Type:

str

name

Display name of the player

Type:

str

chips

Current chip count, defaults to 1000

Type:

int

hand

Player’s hole cards

Type:

Hand

is_active

Whether player is still in current hand

Type:

bool

is_all_in

Whether player has gone all-in

Type:

bool

current_bet

Amount bet in current round

Type:

int

total_bet

Total amount bet in current hand

Type:

int

position

Position at table (0 = dealer)

Type:

int

Examples

>>> player = Player(
...     id="p1",
...     name="Alice",
...     chips=1000,
...     position=0
... )
>>> print(player)  # Shows "Player Alice ($1000)"

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.

class games.poker.models.PlayerAction

Bases: str, enum.Enum

Player action enumeration.

Represents the possible actions a player can take during their turn. Inherits from str.Enum for easy serialization and comparison.

FOLD

Give up hand

Type:

str

CHECK

Pass action when no bet to call

Type:

str

CALL

Match current bet

Type:

str

BET

Place initial bet

Type:

str

RAISE

Increase current bet

Type:

str

ALL_IN

Bet all remaining chips

Type:

str

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

class games.poker.models.PlayerObservation(/, **data)

Bases: pydantic.BaseModel

Player’s view of the game state.

Represents what a specific player can observe about the current game state, hiding information they shouldn’t have access to (e.g., other players’ hole cards).

Parameters:

data (Any)

player_id

ID of observing player

Type:

str

hand

Player’s hole cards

Type:

Hand

chips

Player’s chip count

Type:

int

position

Player’s position at table

Type:

int

position_name

Name of position (e.g., “Button”)

Type:

str

community_cards

Shared cards on board

Type:

List[Card]

visible_players

Observable player info

Type:

List[Dict[str, Any]]

phase

Current game phase

Type:

GamePhase

current_bet

Amount to call

Type:

int

pot_sizes

Sizes of all pots

Type:

List[int]

recent_actions

Recent action history

Type:

List[ActionRecord]

min_raise

Minimum raise amount

Type:

int

is_active

Whether player is in hand

Type:

bool

is_current_player

Whether it’s player’s turn

Type:

bool

Examples

>>> obs = PlayerObservation(
...     player_id="p1",
...     hand=Hand(cards=[ace_of_spades, king_of_hearts]),
...     position=0,
...     position_name="Button"
... )

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.

class games.poker.models.PokerGameState(/, **data)

Bases: pydantic.BaseModel

Texas Hold’em poker game state.

Comprehensive model of the current game state, including all player information, community cards, betting status, and game progression.

Parameters:

data (Any)

players

All players in the game

Type:

List[Player]

active_players

IDs of players still in hand

Type:

List[str]

dealer_position

Position of dealer button

Type:

int

current_player_idx

Index of player to act

Type:

int

community_cards

Shared cards on board

Type:

List[Card]

deck

Remaining cards in deck

Type:

List[Card]

phase

Current game phase

Type:

GamePhase

pots

Main pot and side pots

Type:

List[Pot]

current_bet

Amount to call

Type:

int

small_blind

Small blind amount

Type:

int

big_blind

Big blind amount

Type:

int

min_raise

Minimum raise amount

Type:

int

action_history

Record of all actions

Type:

List[ActionRecord]

last_aggressor

ID of last betting/raising player

Type:

Optional[str]

hand_rankings

Final hand evaluations

Type:

Dict[str, HandRanking]

winners

IDs of hand winners

Type:

List[str]

round_complete

Whether betting round is finished

Type:

bool

Examples

>>> state = PokerGameState(
...     players=[Player(id="p1", name="Alice")],
...     small_blind=5,
...     big_blind=10
... )

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.

property active_player_count: int

Get the number of active players in the game.

Return type:

int

class games.poker.models.Pot(/, **data)

Bases: pydantic.BaseModel

Poker pot model.

Represents a pot of chips in the game, tracking both the amount and which players are eligible to win it (for side pots).

Parameters:

data (Any)

amount

Total chips in the pot

Type:

int

eligible_players

IDs of players who can win

Type:

List[str]

Examples

>>> pot = Pot(
...     amount=500,
...     eligible_players=["p1", "p2", "p3"]
... )

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.

class games.poker.models.Suit

Bases: str, enum.Enum

Card suit enumeration.

Represents the four standard playing card suits. Inherits from str.Enum for easy serialization and string comparison.

HEARTS

Hearts suit

Type:

str

DIAMONDS

Diamonds suit

Type:

str

CLUBS

Clubs suit

Type:

str

SPADES

Spades suit

Type:

str

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