coworld 0.1.23

Coworld certification, upload, and runner tooling

Coworld

Coworld is where games become programmable arenas: worlds you can run locally, play in the browser, submit players to, replay, score, and study. A good Coworld gives game authors a complete packaging contract and gives player authors a clear target for building smarter agents.

The coworld package contains the public CLI, Python helpers, manifest types and schemas, runner tooling, and the Paint Arena reference world.

Start with the Coworld overview for the conceptual map of a complete Coworld.

What Is A Coworld?

A Coworld is a game environment built around a player-improvement loop. It brings together a game, the players that act inside that game, and supporting components that help turn each episode into something useful: results, replays, reports, grader scores, diagnoses, or optimization inputs.

The core loop is simple: run an episode, inspect what happened, improve a player, and run again. The same Coworld can be used for local development and hosted league competition.

Most readers are here to build a player for an existing Coworld. If that is you, start with Developing Players.

If you are building a complete Coworld, start with Developing Coworlds.

Developing Players (Work In Progress)

Most Coworld users are player builders: they want to build an agent for a game that already exists. A player developer chooses a Coworld, learns its rules and player protocol, runs local episodes, inspects the resulting artifacts, improves their policy, and submits it to a league when it is ready.

The player development user guide is still under construction. For now, use:

• Player role for the current player contract.
• Coworld cookbook for current player development recipes.
• Paint Arena as the canonical example world.

Developing Coworlds (Work In Progress)

Coworld builders create the worlds that player developers target. They define the game, the player experience, example or baseline players, local test episodes, local browser-play surfaces, and supporting outputs that help humans and agents understand what happened.

For uploaded games, game.docs.readme should be the durable game-owned guide: rules, strategy, how to use or modify a game-specific policy, and game-specific FAQs. Shared protocol docs belong in game.protocols; Softmax participation, policy upload, league submission, standings, logs, and replay instructions belong in the platform play_*.md guide.

The Coworld development user guide is still under construction. For now, start with the Paint Arena example and use the Documentation Map for the current reference docs.

Main Workflows

Workflow	Start with
Build or improve a player	Cookbook: Upload And Submit A Player and Player role
Iterate a player against hosted opponents (XP Requests)	Cookbook: Request Experience Runs and uv run coworld xp-request --help
Run local episodes or browser play	Cookbook: Build And Run Paint Arena Locally
Inspect league status, logs, results, and replays	Cookbook: Watch Results And Find Episodes
Save per-player debugging files after an episode	Player artifact and uv run coworld episode-logs --help
Build, certify, and upload a Coworld	Cookbook: Certify And Upload A Coworld
Improve a policy in the optimizer workbench	uv run coworld optimize and Optimizer role
Understand package structure and manifest fields	Manifest reference

What This Package Provides

• CLI workflows for local play, local episode runs, certification, Coworld upload, policy upload/submission, league inspection, and artifact retrieval.
• Pydantic models and generated JSON schemas for Coworld manifests and runner episode requests.
• Local and Kubernetes runner code for executing Coworld episodes.
• Public API client helpers for coding agents that need to inspect leagues, rounds, episodes, replays, and uploaded Coworlds.
• The Paint Arena example, which is the canonical example used by this package documentation.

Coworld does not currently provide a supported hosted game-only lobby where users connect their own remote players. Use coworld play for local browser play, or submit policies to leagues for fully hosted tournament episodes where the platform runs the game and every player container.

Documentation Map

The Coworld docs are being reorganized. These links are the current source-of-truth entry points while that work is in progress:

Need	Current doc
Understand what a complete Coworld is	Coworld overview
Build or operate from recipes	Coworld cookbook
Understand manifest fields	Manifest reference
Understand roles and artifact flow	Coworld overview
Implement a game runnable	Game role
Implement or submit a player	Player role and Coworld cookbook
Implement supporting roles	Reporter, Commissioner, Grader, Diagnoser, and Optimizer
Understand artifact contracts	Artifact reference
Consume episode artifacts as a unit	Episode bundle reference
Understand the episode lifecycle	Lifecycle overview
Debug local or hosted execution	Local runner and Kubernetes runner
Start from the canonical example	Paint Arena
Look up exact CLI or API reference	uv run coworld --help, uv run coworld <command> --help, and Observatory OpenAPI

Planned cleanup will shrink or move several of these pages into a smaller set of cookbook, lifecycle, runnable, and artifact documents. Until those pages exist, prefer the links above over older duplicated prose.