A Python library for simulating poker games with custom player strategies.

Poker is a great sandbox for decision-making systems: hidden information, imperfect opponents, probabilistic outcomes, and lots of room for experimentation.

Maverick is a Python library for simulating poker games with custom player strategies. It gives you a complete poker game loop (dealing, betting rounds, showdown, pot distribution) plus a clean player interface so you can swap strategies in and out.

Highlights

Maverick is designed for building and testing strategies:

• Composable API: build your own players by implementing a single method.
• State-machine engine: clear phases and transitions, easier to reason about.
• Event stream: observe what happens (for logging, analytics, replay, debugging).
• Hand evaluation utilities: score hands and compare outcomes.

If you’ve ever wanted to:

• benchmark bots against each other,
• run repeatable simulations,
• prototype an agent that makes betting decisions,

…Maverick is meant to make that workflow straightforward.

Installation

You can install Maverick from PyPI

pip install maverick

Your first game (minimal example)

Here’s an end-to-end example using built-in bots:

from maverick import Game, PlayerLike, PlayerState
from maverick.players import FoldBot, CallBot, AggressiveBot

# Create a game with blinds and a stop condition
game = Game(small_blind=10, big_blind=20, max_hands=10)

# Create players
players: list[PlayerLike] = [
    CallBot(name="CallBot", state=PlayerState(stack=1000)),
    AggressiveBot(name="AggroBot", state=PlayerState(stack=1000)),
    FoldBot(name="FoldBot", state=PlayerState(stack=1000)),
]

for player in players:
    game.add_player(player)

game.start()

# Inspect results
for player in players:
    print(f"{player.name} - Stack: {player.state.stack}")

(See the documentation for more examples and APIs.)

Documentation

The project has extensive documentation hosted on ReadTheDocs. Most library information is documented there, with only the essentials kept here.

Changes and Versioning

The changelog is maintained in CHANGELOG.md. The project adheres to semantic versioning.

Contributing

Contributions are currently expected in any the following ways:

• finding bugs If you run into trouble when using the library and you think it is a bug, feel free to raise an issue.
• feedback All kinds of ideas are welcome. For instance if you feel like something is still shady (after reading the user guide), we want to know. Be gentle though, the development of the library is financially not supported yet.
• feature requests Tell us what you think is missing (with realistic expectations).
• examples If you've done something with the library and you think that it would make for a good example, get in touch with the developers and we will happily inlude it in the documention.
• funding Use one of the supported funding channels. Any amount you can afford is appreciated.
• sharing is caring If you like the library, share it with your friends or colleagues so they can like it too.

In all cases, read the contributing guidelines before you do anything.

License

This package is licensed under the MIT license.