Overview

Overview#

Maverick is a Python library for simulating poker games with a small, composable API. It’s designed for experiments: swapping player strategies, observing events, and running repeatable simulations.

What You Can Do With Maverick#

  • Run a full game loop with betting rounds, dealing, and showdown.

  • Plug in custom players (bots/agents) by implementing a single decide_action method.

  • Observe the game through an event stream for logging, analytics, or debugging.

  • Evaluate hands and estimate holding strength.

Core Concepts#

Game#

Game is the main engine. It holds the state machine, applies rules, requests actions from players, registers actions, and emits events.

Key inputs:

  • Stakes: small blind, big blind (and optional ante)

  • Table sizing rules: min/max players

  • max_hands: stop condition

Player and PlayerLike#

Players are asked to act when it is their turn. Built-in players live under maverick.players. For your own strategy, implement the Player abstract base class (or any object that satisfies PlayerLike).

The required method is keyword-only:

def decide_action(
    self,
    *,
    game: "Game",
    valid_actions: list[ActionType],
    min_raise_amount: int,
    call_amount: int,
    min_bet_amount: int,
) -> PlayerAction:
    ...

Where:

  • valid_actions tells you what is legal right now.

  • call_amount is how many chips you must add now to call.

  • min_raise_amount is the minimum extra chips you must add now to complete a minimum raise.

  • min_bet_amount is the minimum chips you must add now to make a bet.

PlayerAction and ActionType#

Players return a PlayerAction that contains an ActionType (e.g. FOLD, CHECK, CALL, BET, RAISE, ALL_IN) and an optional amount. The engine validates actions against the current rules and state.

Rules and State#

If you’re building simulations, you typically configure rules once and then run many games.

Events#

The engine emits GameEvent instances (via an internal EventBus) as the game progresses. This is the primary integration point for:

  • logging

  • metrics

  • hand replays

  • custom tooling

See Events and Listeners for details.

A Minimal Flow#

For a runnable end-to-end example, see Getting Started. At a high level:

  1. Create a Game

  2. Add players via add_player()

  3. Call start()

Where To Go Next#