PokerKit Documentation

PokerKit is a highly customizable poker game simulation library designed to support almost any poker variant. It allows users to define unique games, adapt existing variants, or implement unsupported ones.

The library is designed to cater to different levels of control depending on the use case:

1. AI Agent Development: Focuses on action selection during betting rounds. In these scenarios, granular details like showdown order, posting blinds/antes, and bet collection can be abstracted away.
2. Online Poker Casino Simulation: Requires granular control over every game aspect, including dealing hole cards individually, burning cards, managing mucking/showing during showdown, killing hands, and the precise movement of chips between stacks.

PokerKit provides varying levels of automation to balance these needs, allowing developers to choose between high-level automation or low-level manual control.

When defining a poker variant, use the following 'raw' parameter formats which PokerKit will automatically clean and interpret:

Antes

• Uniform Antes: Provide a single value (e.g., 2.00) to apply to all players.
• Non-uniform/Big-blind Antes: Use a list [0, 2] or a dictionary {1: 2}.
• Button Antes: Use a dictionary with key -1 (e.g., {-1: 2}).
• Ante Trimming Status: Set to True for uniform antes and False for non-uniform antes.

Blinds and Straddles

• Standard Blinds: Use a list like [0.5, 1] for SB and BB.
• Multi-level Straddles: Use a list like [0.5, 1, 2] for UTG, SB, and BB.
• Button Straddles: Use a dictionary with key -1 (e.g., {0: 0.5, 1: 1, -1: 2}).
• No Blinds: Supply 0 or a list of zeros (e.g., [0, 0, 0, 0]).

Other Configuration

• Bring-In: A positive value (e.g., 1.5) if the game uses bring-ins; otherwise 0. Note: Blinds/Straddles and Bring-ins are mutually exclusive.
• Starting Stacks: A numeric value or math.inf if unknown.
• Player Count: Total number of players.
• Mode: Use pokerkit.state.Mode to specify tournament or cash-game rulesets.
• Starting Board Count: Number of boards to be dealt (usually 1, or 2 for double board games).

PokerKit structures game flow into distinct, sequential phases. Each phase supports a specific set of operations (e.g., dealing, betting, collecting bets).

Key behaviors:

• Phase Skipping: Phases are automatically bypassed if they are not applicable to the current game state. For example, if no antes are configured, the Ante Posting phase is skipped. If no bets are placed, Bet Collection is skipped.
• Internal Management: Transitions between phases are managed internally by the framework. Once a phase is completed, the game automatically moves to the next logical phase.
• Phase-Specific Operations: You can only invoke specific methods (operations) when the game is in the corresponding active phase. Attempting to call a betting operation during a dealing phase will not work.
• Repetition: Depending on the specific poker variant and the number of betting rounds, the Dealing, Betting, and Bet Collection phases may repeat multiple times during a single hand.

Every operation in PokerKit is implemented as a triplet of associated methods:

1. Verifier: Validates if a move is legal according to the rules and current state. It raises a ValueError if the move is illegal or issues a UserWarning for suspicious actions.
2. Querier: A Boolean check (e.g., can_fold()) that wraps the Verifier. It returns True if the action is valid and False if the Verifier raises a ValueError.
3. Operator: The actual execution method (e.g., fold()). It first runs the Verifier; if no error is raised, it executes the operation and returns a result object describing the action (players involved, amounts, cards, etc.).

Error Handling Note: PokerKit uses ValueError for illegal moves and UserWarning for suspicious moves. By default, Queriers ignore warnings and only return False on ValueError. To treat warnings as errors, configure Python's warning filter:

from warnings import filterwarnings

filterwarnings('error')

When warnings are treated as errors, PokerKit's action query methods will return False if a warning is issued.

If a variant is not pre-defined, you must define a custom variant by specifying its core rules. A variant definition requires the following components:

• Deck: The deck used (e.g., standard 52-card deck).
• Hand Types: The number of hand types (typically 1, or 2 for split-pot games).
• Streets: For each street, define:
  • Card Burning Status: Whether to burn a card (True or False).
  • Hole Dealings: How to deal hole cards (face-up/down); use an empty tuple () for none.
  • Board Dealings: Number of board cards to deal (0 for none).
  • Is Draw Stage: Whether it is a draw round (True or False).
  • Opening: Logic for who acts first (e.g., position-based or card-based).
  • Min Completion/Bet/Raise: The minimum size for actions.
  • Max # of Completion/Bet/Raise: Maximum number of actions allowed (None for unlimited).
• Betting Structure: The limits applied (e.g., no-limit, pot-limit, or fixed-limit).