coworld 0.1.0__tar.gz

coworld-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: coworld
+Version: 0.1.0
+Summary: Coworld certification, upload, and runner tooling
+License-Expression: MIT
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: jsonschema>=4.25.1
+Requires-Dist: kubernetes>=31.0.0
+Requires-Dist: mettagrid
+Requires-Dist: packaging>=24.0.0
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: referencing>=0.36.2
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.19.2
+Requires-Dist: websockets>=15.0.1
+Provides-Extra: auth
+Requires-Dist: softmax-cli; extra == "auth"
+Provides-Extra: examples
+Requires-Dist: cogsguard; extra == "examples"
+Requires-Dist: fastapi>=0.115.0; extra == "examples"
+Requires-Dist: numpy>=2.3.0; extra == "examples"
+Requires-Dist: uvicorn>=0.34.0; extra == "examples"
+Provides-Extra: test
+Requires-Dist: cogsguard; extra == "test"
+Requires-Dist: fastapi>=0.115.0; extra == "test"
+Requires-Dist: numpy>=2.3.0; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-httpserver; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Requires-Dist: softmax-cli; extra == "test"
+Requires-Dist: uvicorn>=0.34.0; extra == "test"
+
+# Coworld Guide
+
+This is the canonical overview for Coworlds. Use it to understand the shape of the system and which command to run
+next. Use [COGAME_README.md](COGAME_README.md) for the game-container runtime contract and
+[CLI_README.md](CLI_README.md) for the command reference.
+
+A Coworld is a containerized game package that Softmax can run locally, in hosted play, and in leagues. It has:
+
+- one game image that owns rules, state, viewers, results, and replays;
+- one or more player images that connect to the game and choose actions;
+- a `coworld_manifest.json` file that names the images, configs, schemas, and player docs.
+
+## Player Loop
+
+Use this flow when you want to build a player for an existing Coworld league:
+
+```bash
+uv run softmax login
+uv run coworld download cow_... --output-dir ./coworld
+python -m json.tool ./coworld/coworld_manifest.json | less
+docker build --platform=linux/amd64 -t my-player:latest .
+uv run coworld run-episode ./coworld/coworld_manifest.json my-player:latest
+uv run coworld upload-policy my-player:latest --name my-player
+uv run coworld submit my-player --league league_...
+```
+
+Before writing code, read the downloaded manifest:
+
+- `game.protocols.player` links to the websocket protocol your player must implement.
+- `game.docs.pages` may contain extra game-authored docs such as strategy notes.
+- `certification.game_config` is the small local episode used by `coworld run-episode`.
+- `variants` are named game configs used by leagues or local testing.
+
+A player image receives `COGAMES_ENGINE_WS_URL`, connects to that websocket, follows the game protocol, plays until the
+episode ends, and exits.
+
+For local testing, one image can fill every player slot:
+
+```bash
+uv run coworld run-episode ./coworld/coworld_manifest.json my-player:latest
+```
+
+You can also pass one image per slot:
+
+```bash
+uv run coworld run-episode ./coworld/coworld_manifest.json player-one:latest player-two:latest
+```
+
+If the image needs a specific player command, pass it explicitly:
+
+```bash
+uv run coworld run-episode ./coworld/coworld_manifest.json my-runtime:latest --run python --run /app/player.py
+uv run coworld upload-policy my-runtime:latest --name my-player --run python --run /app/player.py
+```
+
+## Game Author Loop
+
+Use this flow when you want to package a new Coworld:
+
+```bash
+docker build --platform=linux/amd64 -t my-coworld-game:latest .
+uv run coworld certify path/to/coworld_manifest.json
+uv run coworld upload-coworld path/to/coworld_manifest.json
+```
+
+The smallest complete example is [examples/paintarena/](examples/paintarena/).
+
+Certification validates the manifest, checks the referenced Docker images, runs one short episode, checks player and
+global client routes, checks replay viewing, and validates the results file. The certifier does not build images; build
+or pull them first.
+
+## Manifest
+
+Every Coworld package has a `coworld_manifest.json` file that follows
+[coworld_manifest_schema.json](coworld_manifest_schema.json). The main sections are:
+
+- `game`: the game server image, config schema, result schema, and protocol docs.
+- `player`: bundled player images that can play the game.
+- `variants`: named game configs, such as maps, difficulty levels, or league settings.
+- `certification`: the short smoke-test episode used by `coworld certify` and `coworld run-episode`.
+
+The game, player, grader, reporter, commissioner, diagnoser, and optimizer sections all use the same runnable shape: an
+image, an optional command (`run`), and optional public environment variables (`env`). Secrets do not belong in the
+manifest.
+
+Protocol docs are explicit document objects:
+
+```json
+{ "type": "uri", "value": "https://example.com/player_protocol.md" }
+```
+
+Use `type: "uri"` for public HTTP(S) docs. Use `type: "text"` only when the docs are intentionally stored inline in the
+manifest.
+
+Extra docs go in `game.docs.pages`:
+
+```json
+{
+  "id": "play",
+  "title": "play.md",
+  "content": { "type": "uri", "value": "https://example.com/play.md" }
+}
+```
+
+Upload stores the manifest as JSON. It does not bundle local Markdown files, schemas, or assets, so public docs should
+use public URLs.
+
+## Runtime Contract
+
+The game image owns the episode. It must:
+
+- read the config from `COGAME_CONFIG_URI`;
+- serve `GET /healthz`;
+- serve player clients at `GET /clients/player?...` and player websockets at `WEBSOCKET /player?...`;
+- serve a live viewer at `GET /clients/global` and `WEBSOCKET /global`;
+- write final results to `COGAME_RESULTS_URI`;
+- write a replay artifact to `COGAME_SAVE_REPLAY_URI`;
+- serve replay viewers when started with `COGAME_REPLAY_SERVER=1`.
+
+Browser client pages forward their query string when they open the websocket. Hosted proxies may pass an `address`
+query parameter containing the full websocket URL. See [COGAME_README.md](COGAME_README.md) for the exact route,
+websocket, token, reconnect, replay, and artifact contract.
+
+The game config schema must define `tokens` as a required string array with equal `minItems` and `maxItems`. That fixed
+length is the number of player slots. Coworld-authored configs omit `tokens`; the runner creates fresh tokens for each
+episode and injects them into the concrete runtime config.
+
+## Upload And Inspect
+
+Coworld upload certifies the package, uploads every runnable image, rewrites image references to Softmax-managed image
+IDs, and uploads the standalone manifest:
+
+```bash
+uv run coworld upload-coworld path/to/coworld_manifest.json
+uv run coworld list
+uv run coworld show cow_...
+uv run coworld images
+```
+
+Player upload creates a policy version, and submit enters that policy into a league:
+
+```bash
+uv run coworld upload-policy my-player:latest --name my-player
+uv run coworld submit my-player --league league_...
+uv run coworld submit my-player:v2 --league league_...
+```
+
+Public runtime settings belong in the Docker image or manifest `env`. Secrets should be attached to the uploaded policy
+version:
+
+```bash
+uv run coworld upload-policy my-player:latest \
+  --name my-player \
+  --use-bedrock \
+  --secret-env ANTHROPIC_API_KEY=sk-ant-...
+```
+
+`--use-bedrock` adds `USE_BEDROCK=true`. `--secret-env KEY=VALUE` can be repeated. During Coworld episodes, only the
+player pod for that policy version receives those secret variables.
+
+## Results And Replays
+
+Use the Coworld CLI to inspect leagues, submissions, standings, episode requests, logs, and replays:
+
+```bash
+uv run coworld submissions --mine --league league_...
+uv run coworld memberships --mine --division div_... --active-only
+uv run coworld episodes --division div_... --mine --with-replay
+uv run coworld episode-logs ereq_... --mine --download-dir logs/
+uv run coworld replays --division div_... --mine --download-dir replays/
+uv run coworld replay-open ereq_...
+```
+
+See [CLI_README.md](CLI_README.md) for the full command reference.

coworld-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools==80.9.0", "wheel==0.45.1"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "coworld"
+version = "0.1.0"
+description = "Coworld certification, upload, and runner tooling"
+readme = "src/coworld/COWORLD_README.md"
+requires-python = ">=3.11,<3.13"
+license = "MIT"
+dependencies = [
+  "httpx>=0.28.1",
+  "jsonschema>=4.25.1",
+  "kubernetes>=31.0.0",
+  "mettagrid",
+  "packaging>=24.0.0",
+  "pydantic>=2.11.5",
+  "referencing>=0.36.2",
+  "rich>=13.7.0",
+  "typer>=0.19.2",
+  "websockets>=15.0.1",
+]
+
+[project.optional-dependencies]
+auth = ["softmax-cli"]
+examples = ["cogsguard", "fastapi>=0.115.0", "numpy>=2.3.0", "uvicorn>=0.34.0"]
+test = [
+  "cogsguard",
+  "fastapi>=0.115.0",
+  "numpy>=2.3.0",
+  "pytest",
+  "pytest-httpserver",
+  "pytest-xdist",
+  "ruff",
+  "softmax-cli",
+  "uvicorn>=0.34.0",
+]
+
+[project.scripts]
+coworld = "coworld.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["coworld", "coworld.*"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+coworld = ["py.typed", "*.json", "*.md", "runner/*.md", "examples/**/*"]
+
+[tool.setuptools.exclude-package-data]
+coworld = [
+  "**/__pycache__/*",
+  "**/*.pyc",
+  # Files the Python runtime never reads. Excluding them from the
+  # wheel means a non-runtime edit (e.g. updating an example
+  # Dockerfile) doesn't change wheel content, doesn't change the
+  # @pyenv tree bazel hashes into action keys, and so doesn't
+  # invalidate every downstream test that has @pyenv in its
+  # transitive deps.
+  "**/Dockerfile",
+  "examples/**/README.md",
+  "examples/**/*_spec.md",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+markers = ["slow: marks tests as slow"]
+
+[tool.uv.sources]
+mettagrid = { workspace = true }
+softmax-cli = { workspace = true }
+cogsguard = { git = "https://github.com/Metta-AI/cogame-cogsguard.git" }
+
+[tool.ruff]
+extend = "../../.ruff.toml"

coworld-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

coworld-0.1.0/src/coworld/CLI_README.md

@@ -0,0 +1,125 @@
+# Coworld CLI
+
+The `coworld` command is the local tool for Coworld development and league work. It downloads Coworlds, runs local
+episodes, uploads player images, submits policies to leagues, and inspects results. For concepts, start with
+[COWORLD_README.md](COWORLD_README.md).
+
+Commands that talk to Softmax use the current `softmax-cli` login:
+
+```bash
+uv run softmax login
+```
+
+Pass `--server` only when targeting a non-default Observatory API environment.
+
+## Player Loop
+
+```bash
+uv run coworld download cow_... --output-dir ./coworld
+docker build --platform=linux/amd64 -t my-player:latest .
+uv run coworld run-episode ./coworld/coworld_manifest.json my-player:latest
+uv run coworld upload-policy my-player:latest --name my-player
+uv run coworld submit my-player --league league_...
+```
+
+If the image needs a specific player command:
+
+```bash
+uv run coworld run-episode ./coworld/coworld_manifest.json my-runtime:latest --run python --run /app/player.py
+uv run coworld upload-policy my-runtime:latest --name my-player --run python --run /app/player.py
+```
+
+Check the submission and its first episodes:
+
+```bash
+uv run coworld submissions --mine --league league_...
+uv run coworld memberships --mine --division div_... --active-only
+uv run coworld episodes --division div_... --mine --with-replay
+```
+
+## Coworld Packages
+
+```bash
+uv run coworld certify path/to/coworld_manifest.json
+uv run coworld upload-coworld path/to/coworld_manifest.json
+uv run coworld list
+uv run coworld show cow_...
+uv run coworld images
+uv run coworld images img_...
+```
+
+## Tournaments
+
+Inspect the tournament structure:
+
+```bash
+uv run coworld leagues
+uv run coworld leagues league_...
+uv run coworld divisions --league league_...
+uv run coworld divisions div_...
+uv run coworld rounds --division div_... --status completed
+uv run coworld rounds round_...
+uv run coworld pools --round round_...
+uv run coworld pools pool_...
+```
+
+Inspect tournament outcomes:
+
+```bash
+uv run coworld results league_...
+uv run coworld results div_...
+uv run coworld results round_...
+uv run coworld memberships --mine --division div_... --active-only
+uv run coworld submissions --mine --league league_...
+uv run coworld events --division div_...
+```
+
+Most commands support `--json` for machine-readable output.
+
+## Episodes
+
+List episode requests by pool, round, or division:
+
+```bash
+uv run coworld episodes --division div_...
+uv run coworld episodes --round round_... --with-replay
+uv run coworld episodes --pool pool_... --policy my-policy:v3
+uv run coworld episodes ereq_...
+```
+
+Use `--mine` to keep only episodes involving policy versions in your current league memberships:
+
+```bash
+uv run coworld episodes --division div_... --mine --with-replay --json
+```
+
+Fetch artifacts for one episode request:
+
+```bash
+uv run coworld episode-stats ereq_...
+uv run coworld episode-stats ereq_... --json
+uv run coworld episode-results ereq_... --output results.json
+uv run coworld episode-logs ereq_... --list
+uv run coworld episode-logs ereq_... --agent 0
+uv run coworld episode-logs ereq_... --mine --download-dir logs/
+```
+
+Download replay files:
+
+```bash
+uv run coworld replays --division div_... --mine --download-dir replays/
+uv run coworld replays --round round_... --policy my-policy:v3 --json
+```
+
+`replays --download-dir` writes one replay JSON file per episode request plus `index.json` metadata with the episode,
+job, Coworld, participant, score, and source replay URI details.
+
+Open one replay:
+
+```bash
+uv run coworld replay-open ereq_...
+uv run coworld replay-open ereq_... --hosted
+```
+
+The default `replay-open` path runs the replay locally with the Coworld manifest and replay artifact. `--hosted` creates
+an Observatory-hosted replay session and prints the viewer URL.

coworld-0.1.0/src/coworld/COGAME_README.md

@@ -0,0 +1,130 @@
+# Coworld Game Runtime Contract
+
+This is the canonical contract for game images. Player authors usually only need the player protocol linked from a
+Coworld manifest; game authors need this file.
+
+A Coworld episode has one game container and one player container per slot. The runner starts the game, gives it a
+config, starts the players, records logs, and collects results and replay artifacts. The game owns the rules. Players
+connect over websocket and choose actions.
+
+## Manifest Fields
+
+The `game` object in `coworld_manifest.json` describes the game container:
+
+- `name`, `version`, `description`, and `owner`
+- `runnable`: Docker image, optional command, and public environment variables
+- `config_schema`: JSON Schema for the runtime game config
+- `results_schema`: JSON Schema for the final results file
+- `protocols.player`: player websocket protocol docs
+- `protocols.global`: live viewer websocket protocol docs
+
+Protocol docs are document objects:
+
+```json
+{ "type": "uri", "value": "https://example.com/player_protocol.md" }
+```
+
+Use `type: "uri"` for public HTTP(S) docs and `type: "text"` only for deliberately inline docs.
+
+## Player Slots
+
+The game config schema must require a `tokens` field. It must be a string array with equal `minItems` and `maxItems`.
+That fixed length is the number of player slots.
+
+Coworld-authored configs, variants, and certification fixtures do not include `tokens`. The runner creates fresh tokens
+for each episode and injects them into the concrete runtime config.
+
+The game must reject a `/player` websocket connection when the slot/token pair is not valid for that episode.
+
+## Rollout Mode
+
+For a normal episode, the runner starts the game with:
+
+```bash
+COGAME_CONFIG_URI=...
+COGAME_RESULTS_URI=...
+COGAME_SAVE_REPLAY_URI=...
+```
+
+The game must support `file://` URIs. Hosted runners may use other writable URI schemes when the game supports them.
+
+In rollout mode, the game listens on `0.0.0.0:8080` and exposes:
+
+- `GET /healthz`
+- `GET /clients/player?slot=0&token=...&...`
+- `WEBSOCKET /player?slot=0&token=...&...`
+- `GET /clients/global`
+- `WEBSOCKET /global`
+
+`GET /healthz` returns 200 when the game is ready.
+
+`GET /clients/player` serves a browser client for one slot. `GET /clients/global` serves a live viewer.
+
+The served browser clients read the complete page query string before opening their websocket. If the query contains
+`address`, the client uses that value as the full websocket URL after converting `http` or `https` to `ws` or `wss`;
+it must not merge other page query params into that URL. Otherwise, the client derives the websocket URL by replacing
+`/clients/player` with `/player`, or `/clients/global` with `/global`, and preserving the page query params such as
+`slot`, `token`, and game-owned params.
+
+For example, `/clients/player?slot=0&token=abc&role=scout` should open
+`/player?slot=0&token=abc&role=scout`. A hosted proxy may instead serve
+`/clients/player?address=wss://example.com/player?slot=0&token=abc`.
+
+The `/global` websocket must support late viewers. A viewer that joins after the episode starts should receive enough
+state to render from that point forward.
+
+The `/player` websocket must allow the same slot to reconnect with the same token while the episode is still running.
+The slot's game state survives disconnects. During a disconnect, the game may use no-op actions or another documented
+behavior.
+
+Games may expose local-only admin controls by convention:
+
+- `GET /clients/admin`
+- `WEBSOCKET /admin?...`
+
+The admin route is game-owned. The platform must not expose `/admin` in production.
+
+## Replay Mode
+
+For replay viewing, the runner starts or reuses the same game image with:
+
+```bash
+COGAME_REPLAY_SERVER=1
+```
+
+In replay mode, the game listens on `0.0.0.0:8080` and exposes:
+
+- `GET /healthz`
+- `GET /clients/replay?uri=<uri>`
+- `WEBSOCKET /replay?uri=<uri>`
+
+`GET /clients/replay?uri=<uri>` serves a browser replay viewer. The served client opens `/replay?uri=<uri>`. The game
+loads the replay artifact and handles game-owned replay controls such as start, stop, seek, or speed changes.
+
+The replay artifact format and replay websocket protocol are game-owned.
+
+## Episode Lifecycle
+
+1. The runner receives a job with the manifest, game config, players, and artifact output URIs.
+2. The runner generates one token per player slot.
+3. The runner writes the concrete game config, including `tokens`.
+4. The runner starts the game container with config, result, and replay URIs.
+5. The game reads its config and starts listening on port 8080.
+6. The runner waits for `GET /healthz` to return 200.
+7. The runner starts one player container per slot.
+8. Each player gets `COGAMES_ENGINE_WS_URL=ws://<engine-host>/player?slot=<slot>&token=<token>`.
+9. Players connect to `/player` and send game-specific actions.
+10. Viewers may connect to `/global`.
+11. The game runs until the episode ends.
+12. The game writes results to `COGAME_RESULTS_URI`.
+13. The game writes a replay to `COGAME_SAVE_REPLAY_URI`.
+14. The runner validates results against `results_schema` and stores results, replay, and logs.
+
+The final results file must match `game.results_schema`. It must include `scores`, one number per player slot, and may
+include extra game-specific fields declared by the schema.
+
+## Certification
+
+Coworld certification turns the manifest's `certification` fixture into one local episode. It runs the game and bundled
+player images, checks the HTTP routes, verifies that bad player tokens are rejected, validates final results, and checks
+that the replay viewer can start.