Ludotastic

Welcome to Ludotastic's documentation!

Where humans and AI come to play.

Read the Docs

Installation

PyPI

ludotastic is available on PyPI:

# With uv
uv add ludotastic
# With pip
pip install ludotastic
# With Poetry
poetry add ludotastic

GitHub

You can also install the latest version of the code directly from GitHub:

# With uv
uv add git+https://github.com/MicaelJarniac/ludotastic
# With pip
pip install git+git://github.com/MicaelJarniac/ludotastic
# With Poetry
poetry add git+git://github.com/MicaelJarniac/ludotastic

Usage

Ludotastic is a playground for pitting people, scripted bots and AI models against each other in games. Any model Pydantic AI supports can play, including decision models such as TypeSafe's Jev (typesafe:jev-latest).

Set the API keys for the models you want to use, such as TYPESAFE_API_KEY or OPENAI_API_KEY, then start the playground:

ludotastic serve

Open http://127.0.0.1:8080 to set up and watch matches, browse past matches and compare results. The REST API lives under /api, documented at /docs.

Matches can also run headless, which is handy for comparing models:

ludotastic games
ludotastic play tictactoe typesafe:jev-latest bot:minimax --rounds 10
ludotastic play tictactoe openai:gpt-6.1-sol@structured anthropic:claude-opus-5-5@tools

Each player is bot:NAME, or a model name with an optional action mode:

• @choice: pick one of the legal moves, each described in words. The model can never make an illegal move, and this mode suits decision models best.
• @structured: fill in the game's move model. Illegal moves go back to the model for another try.
• @tools: look at the game through tools, then submit a move.

Settings come from LUDOTASTIC_* environment variables or a .env file; see [Settings][ludotastic.Settings].

Writing a game

A game is a [Game][ludotastic.Game] subclass whose states and moves are Pydantic models. Ludotastic finds games through the ludotastic.games entry point group, so a game can ship in its own package:

[project.entry-points."ludotastic.games"]
connect-four = "ludotastic_connect_four:ConnectFour"

The bundled games, such as Tic-Tac-Toe, are registered the same way and make good templates. A game can also provide its own scripted bots, extra AI tools and a NiceGUI renderer; games without one get a generic text view. Games are turn-based (Timing.STEP) or real-time (Timing.TICK), where a player that is too slow on a tick loses its turn.

How a game describes its state in [observe][ludotastic.Game.observe] affects how well models play it, sometimes a lot: see the Tic-Tac-Toe notes for a measured example.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

More details can be found in CONTRIBUTING.

Contributors ✨

Micael Jarniac 💻 ⚠️ 📖 🚇 🚧 🤔 📆

License

MIT

This project was created with the MicaelJarniac/crustypy template.