CoGames

0.24.3 · active · verified Thu Apr 09

CoGames is a collection of multi-agent cooperative and competitive environments designed for reinforcement learning research. It serves as the game environment for the Alignment League Benchmark (ALB), a suite of multi-agent games to measure AI alignment, coordination, and collaboration. It currently features the 'Cogs vs Clips' game, offering environments for creating new games, training agents, and submitting them to the ALB leaderboard.

Warnings

gotcha CoGames has strict Python version requirements, specifically supporting Python 3.12. Using other versions (e.g., Python 3.11 or 3.13+) may lead to installation or runtime issues.
Fix: Ensure your environment uses Python 3.12. Consider using `pyenv` or `conda` to manage Python versions. Refer to the PyPI `requires_python` field.
gotcha The primary interaction model for CoGames, especially for quickstarts and common tasks like playing or training agents, is through its comprehensive command-line interface (CLI). Users expecting a rich, immediately accessible Python API for environment setup or direct game manipulation might find the documentation lean in that area, favoring CLI commands.
Fix: Familiarize yourself with the `cogames` CLI commands (`cogames missions`, `cogames play`, `cogames train`, `cogames upload`). For programmatic policy development, refer to the structure of `cogames.policy` modules.
gotcha When using `cogames tutorial make-policy`, if the `-o` (output file) argument is not specified, the command might overwrite existing policy files without warning.
Fix: Always use the `-o <filename.py>` flag with `cogames tutorial make-policy` to specify a new, unique filename and avoid accidental overwrites of your work.
gotcha Specifying policies for CLI commands like `cogames play`, `cogames train`, or `cogames run` can be complex. Policies can be referenced by URIs (for checkpoint bundles) or in a key-value format (for explicit class paths, optional weights, proportions, and `__init__` keyword arguments).
Fix: Carefully review the `POLICY` specification format in the documentation. For simple cases, `random` or `class=cogames.policy.starter_agent.StarterPolicy` might suffice. For custom or trained policies, ensure the format `class=<your.module.MyPolicyClass> [data=/path/to/weights.safetensors] [kw.arg=value]` is correctly applied.

Install

pip install cogames Install latest stable version

Imports

StarterPolicy
```
from cogames.policy.starter_agent import StarterPolicy
```
Commonly used as a base or example for custom scripted policies, often generated via `cogames tutorial make-policy`.
RandomPolicy
```
from cogames.policy.random import RandomPolicy
```
A basic random policy for testing and quick play, typically referred to as 'random' in CLI commands.

Quickstart

This quickstart demonstrates how to install CoGames, list the available game missions, and then run a single episode of a mission using a simple random policy via the command-line interface. The CLI is the primary interaction method for CoGames.

# Install CoGames (if you haven't already)
pip install cogames

# List available missions
cogames missions

# Play an episode of the 'training_facility_1' mission with a random policy
cogames play -m training_facility_1 -p random

view raw JSON →