A handy package for building turn‑based game environments for AI agents

We proudly provide a lightweight Python framework that makes it easy to create adversarial games and run matches with AI agents – whether they run locally, in isolated processes, over a network, or are human‑controlled via a GUI.

Why Seahorse?

Developing a game environment for autonomous agents involves many repetitive tasks: managing turns, validating moves, enforcing time limits, handling player connections, and recording results. Seahorse takes care of all that boilerplate, letting you focus on your game logic and agent strategies.

Define your own game – describe the states, rules, possible moves, and winning condition.
Plug in any agent – implement the decision logic once.
Interaction via proxies - agents can compete whether they are all run locally or on another machine. human can also play against agent through an interactive GUI.
Let the master run the match – the built‑in game master enforces turn order, time budgets, move legality, and determines winners.
Real‑time communication – a server broadcasts game states and collects actions, making remote play and live recording effortless.

Installation

The package is publicly available on PyPI. We strongly recommend using a virtual environment:

python3 -m venv venv

# On Linux / macOS:
source venv/bin/activate

# On Windows (PowerShell):
# venv\Scripts\Activate.ps1

pip install seahorse

Core concepts

Seahorse is built around a few simple ideas that work together seamlessly.

Concept	What it does
Game State	Stores the active player, the environment representation, etc. It also encapsulate legal moves and game termination computation.
Action	A generic representation of a player move or decision during their turn that affect the current game state.
Player	The agent that receives the current game informations and returns an action.
Proxy	A wrapper that runs an agent in a specific environment or allows human interaction with the game. The game master interact with agents only through their proxy.
Game master	The referee that initialises the game, asks each proxy for an action on the player’s turn, validates the move, checks time limits, updates the state, and broadcasts everything with the event master singleton.
EventMaster	A WebSocket server that all proxies and listeners connect to. It relays game states and receives actions, enabling real‑time remote play and recording. All clients identify themselves, and the hub routes messages accordingly.

Seahorse also provide several utilities in the form of JSON serialization for all core objects, custom exceptions for game mechanics, or recorders for logging game traces. Please consider reading the overview section for further informations.

Example: Tic‑Tac‑Toe

Initial state	Intermediate state	Final state

A complete implementation of Tic‑Tac‑Toe is available in the seahorse-zoo repository. It demonstrates how to define the game state, possible actions, and a simple minimax agent.

Follow our tutorials to learn how to run the example and create your own game.

Main contributors

We are an enthusiastic team of M.Sc. and PhD candidates led by Pr. Quentin Cappart at Polytechnique Montréal. The package was originally developed in the context of an introductory course to artificial intelligence given to computer and software engineering students.