coworld 0.0.0__tar.gz

coworld-0.0.0/.github/workflows/sync-issues-to-asana.yml

@@ -0,0 +1,37 @@
+name: Sync GitHub issues to Asana
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  create-asana-task:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create Asana task
+        env:
+          ASANA_TOKEN: ${{ secrets.ASANA_TOKEN }}
+          ASANA_PROJECT_GID: "1210062854657778"
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+          ISSUE_URL: ${{ github.event.issue.html_url }}
+          ISSUE_AUTHOR: ${{ github.event.issue.user.login }}
+          ISSUE_BODY: ${{ github.event.issue.body }}
+        run: |
+          NOTES=$(printf "GitHub Issue: %s\n\nFiled by: %s\n\n%s" "$ISSUE_URL" "$ISSUE_AUTHOR" "$ISSUE_BODY")
+          BODY=$(jq -n \
+            --arg name "$ISSUE_TITLE" \
+            --arg notes "$NOTES" \
+            --arg project "$ASANA_PROJECT_GID" \
+            '{data: {name: $name, notes: $notes, projects: [$project]}}')
+
+          RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "https://app.asana.com/api/1.0/tasks" \
+            -H "Authorization: Bearer $ASANA_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "$BODY")
+
+          HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+
+          if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
+            echo "Asana API returned HTTP $HTTP_CODE"
+            exit 1
+          fi

coworld-0.0.0/AGENTS.md

@@ -0,0 +1,98 @@
+# AGENTS.md - coworld
+
+Public CLI and Python package for Softmax v2 tournaments ("Coworlds"). This package owns the user-facing `coworld`
+entrypoint, local episode/play tooling, Coworld uploads, policy uploads/submission helpers, the Paint Arena reference
+Coworld, and the public Coworld docs shipped with the package. It depends on `softmax-cli` for auth-backed commands.
+
+## Before Editing
+
+- Read this file, `LESSONS.md`, the package [README](README.md), and the [Coworld docs map](src/coworld/docs/README.md)
+  before changing user-facing Coworld behavior or docs.
+- Keep package docs public-package-facing. Avoid private Metta backend paths unless the document is intentionally
+  explaining a platform integration boundary.
+- Treat Paint Arena under `src/coworld/examples/paintarena/` as the canonical in-tree example.
+
+## CLI
+
+The package installs the Typer app at `coworld.cli:app`:
+
+```bash
+uv run coworld --help
+uv run coworld leagues
+uv run coworld download <coworld-name-or-id> --output-dir ./coworld
+uv run coworld run-episode <manifest.json> <image:tag>
+uv run coworld play <manifest.json> [image|request.json]
+uv run coworld build / certify / upload-coworld
+uv run coworld upload-policy / submit
+```
+
+Auth-backed commands require `uv run softmax login` first. The `auth` extra pulls in `softmax-cli`.
+
+## Validation
+
+Use the narrowest check that covers the touched surface, then broaden when changing shared contracts:
+
+```bash
+uv run metta pytest packages/coworld/tests/test_types.py -v
+uv run metta pytest packages/coworld/tests -v
+uv run metta pytest --changed
+uv run metta lint --fix
+```
+
+When changing manifest Pydantic models or generated schema files, update `types.py` first and regenerate the checked-in
+schema JSON:
+
+```bash
+uv run --project packages/coworld python packages/coworld/scripts/generate_coworld_schemas.py
+uv run metta pytest packages/coworld/tests/test_types.py -v
+```
+
+Do not hand-edit `src/coworld/coworld_manifest_schema.json` or `src/coworld/runner/episode_request_schema.json` as the
+source of truth. They are generated docs and `$schema` targets; `test_types.py` checks that they match `types.py`.
+
+## Source Layout
+
+- `src/coworld/cli.py`, `tournament_cli.py` - Typer command surface for local episodes, uploads, leagues, and hosted
+  tournament inspection.
+- `src/coworld/cli_support.py`, `api_client.py` - shared CLI helpers and the Softmax/Coworld API client.
+- `src/coworld/certifier.py` - `coworld certify` smoke-test pipeline.
+- `src/coworld/manifest_validation.py`, `schema_validation.py`, `manifest_uri.py` - manifest and schema validation.
+- `src/coworld/bundle.py` - episode-bundle assembly around `COGAME_EPISODE_BUNDLE_URI`.
+- `src/coworld/play.py`, `src/coworld/runner/` - local play, local episode runner, and hosted-runner contracts.
+- `src/coworld/starter_policy.py`, `src/coworld/policies/` - packaged starter policy templates.
+- `src/coworld/commissioner/`, `submit.py`, `upload.py` - league round-running, submission, and upload support.
+- `src/coworld/examples/paintarena/` - smallest complete Coworld and reference implementation.
+
+## Documentation Map
+
+- [README.md](README.md) - package landing page, player-first orientation, and navigation.
+- [COOKBOOK.md](COOKBOOK.md) - task recipes for local play, policy upload/submission, tournament results, and
+  Coworld upload.
+- [src/coworld/docs/README.md](src/coworld/docs/README.md) - Coworld concept map, role statuses, artifact flow, and
+  cross-links.
+- [src/coworld/docs/COWORLD_MANIFEST.md](src/coworld/docs/COWORLD_MANIFEST.md) - manifest semantics and schema source
+  of truth.
+- [src/coworld/docs/LIFECYCLE.md](src/coworld/docs/LIFECYCLE.md) - local and hosted episode lifecycle.
+- `src/coworld/docs/roles/*.md` - per-role contracts.
+- `src/coworld/docs/artifacts/*.md` - artifact contracts.
+- `src/coworld/runner/RUNNER_README.md` and `src/coworld/runner/KUBERNETES_RUNNER_README.md` - runner-specific
+  behavior.
+
+## Manifest And Role Contracts
+
+- The schema currently requires `game`, `player`, and `reporter`. `commissioner`, `grader`, `diagnoser`, and
+  `optimizer` are optional today and marked future-required in generated schema metadata.
+- Role semantics belong in `src/coworld/docs/roles/`. Field-level manifest shape belongs in `src/coworld/types.py` and
+  the generated schema JSON, not in duplicated Markdown tables.
+- Manifest role changes usually need matching updates to role docs, Paint Arena templates, generated schemas,
+  certifier/runner tests, and any README links that name the role.
+- Do not describe `coworld hosted-game` as a supported player workflow unless product/runtime support is restored.
+  Current hosted execution means tournament jobs where the platform runs the game and every player container.
+
+## Package Data Gotchas
+
+- Versioning uses `setuptools_scm` from `coworld-v*` git tags (`fallback_version = "0.0.0"`).
+- `pyproject.toml` deliberately excludes Dockerfiles and example READMEs from wheel package data. Non-runtime example
+  edits should not change wheel content or Bazel action keys for downstream `@pyenv` consumers.
+- Antfarm hosts Coworld game containers; keep `packages/antfarm/README.md` aligned when the game-container contract
+  changes.

coworld-0.0.0/BUILD.bazel

@@ -0,0 +1,164 @@
+load("@rules_python//python:defs.bzl", "py_binary", "py_library")
+
+# Build the paintarena example image via the host docker daemon. Tags the
+# image `coworld-paintarena:latest` in the local docker store and writes a
+# digest-pinned reference (`coworld-paintarena@sha256:<digest>`) to the
+# output file so downstream consumers can address the exact build.
+#
+# Tagged `manual` so it stays out of `//...` wildcard builds — CI runners
+# without a docker daemon would otherwise fail the wildcard.
+genrule(
+    name = "paintarena_image",
+    srcs = [
+        "src/coworld/examples/paintarena/Dockerfile",
+        "src/coworld/examples/paintarena/__init__.py",
+    ] + glob([
+        "src/coworld/examples/paintarena/game/**",
+        "src/coworld/examples/paintarena/optimizer/**",
+        "src/coworld/examples/paintarena/player/**",
+        "src/coworld/examples/paintarena/reporter/**",
+        "src/coworld/examples/paintarena/shared/**",
+    ]),
+    outs = ["paintarena_image.ref"],
+    cmd = """
+set -euo pipefail
+# Bazel sanitizes PATH for actions; ensure standard host locations are
+# searched so the host docker (or podman shimming docker) is reachable.
+export PATH="/run/current-system/sw/bin:/usr/local/bin:/usr/bin:/bin$${PATH:+:$$PATH}"
+ctx=$$(dirname $(location src/coworld/examples/paintarena/Dockerfile))
+iidfile=$$(mktemp)
+trap 'rm -f "$$iidfile"' EXIT
+# Cloudflare Containers run amd64; build for that arch so the image is
+# pullable there even when built on an arm64 (Apple Silicon) dev machine.
+docker build --platform linux/amd64 --iidfile "$$iidfile" --tag coworld-paintarena:latest "$$ctx" >&2
+iid=$$(cat "$$iidfile")
+echo "coworld-paintarena@$$iid" > $@
+""",
+    local = 1,
+    tags = ["manual"],
+    visibility = ["//visibility:public"],
+)
+
+# `:coworld_core` is the import-surface every external library consumer
+# (//app_backend, //metta:metta_obs, //worlds) actually needs:
+#
+#   coworld.types, coworld.certifier, coworld.manifest_validation,
+#   coworld.schema_validation, coworld.commissioner.protocol,
+#   coworld.runner.io, coworld.runner.runner — plus the transitive
+#   imports of `coworld.__init__`'s eager facade (certifier, play,
+#   runner.runner, types).
+#
+# Everything else — the CLI (`cli.py`, `tournament_cli.py`,
+# `bundle.py`, `submit.py`, `upload.py`, `starter_policy.py`,
+# `manifest_uri.py`, `__main__.py`), the example servers under
+# `examples/**`, the policy templates under `policies/**`, and the
+# kubernetes runner that only the CLI and tests load — stays in
+# `:coworld`. Action keys for downstream tests that only hit the
+# library surface no longer flip when CLI / example / policy files
+# change.
+#
+# `coworld_manifest_schema.json` and `runner/episode_request_schema.json`
+# are NOT in `data` on either target: nothing reads them at runtime
+# (they're generated dynamically from pydantic via
+# `coworld.types.coworld_manifest_schema()` /
+# `coworld.types.coworld_episode_request_schema()`). The on-disk
+# copies exist only as docs / `$schema` URLs referenced from READMEs.
+_CORE_SRCS = [
+    "src/coworld/__init__.py",
+    "src/coworld/certifier.py",
+    "src/coworld/commissioner/__init__.py",
+    "src/coworld/commissioner/protocol.py",
+    "src/coworld/manifest_validation.py",
+    "src/coworld/play.py",
+    "src/coworld/runner/__init__.py",
+    "src/coworld/runner/io.py",
+    "src/coworld/runner/runner.py",
+    "src/coworld/schema_validation.py",
+    "src/coworld/types.py",
+]
+
+# Test-only runfiles for validating checked-in generated schemas against
+# coworld.types' dynamic Pydantic schema output.
+filegroup(
+    name = "generated_schema_files",
+    srcs = [
+        "src/coworld/coworld_manifest_schema.json",
+        "src/coworld/runner/episode_request_schema.json",
+    ],
+    visibility = ["//packages/coworld/tests:__pkg__"],
+)
+
+py_library(
+    name = "coworld_core",
+    srcs = _CORE_SRCS,
+    data = ["src/coworld/py.typed"],
+    imports = ["src"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "@pypi//httpx",
+        "@pypi//jsonschema",
+        "@pypi//packaging",
+        "@pypi//pydantic",
+        "@pypi//referencing",
+        "@pypi//websockets",
+    ],
+)
+
+py_library(
+    name = "coworld",
+    srcs = glob(
+        ["src/coworld/**/*.py"],
+        exclude = _CORE_SRCS,
+    ),
+    # Runtime data for the CLI and the example servers. Library
+    # consumers don't need any of this; they get `py.typed` via
+    # `:coworld_core` and nothing else.
+    data = glob(
+        [
+            "src/coworld/examples/**/*.py",
+            "src/coworld/examples/**/*.json",
+            "src/coworld/examples/**/*.html",
+            "src/coworld/policies/amongthemstarter/**/*",
+            "src/coworld/policies/amongthemstarter/.dockerignore",
+            "src/coworld/policies/cogs_vs_clips/**/*",
+            "src/coworld/policies/cogs_vs_clips/.dockerignore",
+        ],
+        allow_empty = True,
+    ),
+    imports = ["src"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":coworld_core",
+        "//packages/softmax-cli:softmax",
+        # cogsguard's wheel METADATA used to declare `Requires-Dist: cogames`
+        # but our patch strips that to dodge the @pypi//cogames ghost
+        # reference. cogsguard.missions.machina_1 imports cogames at module
+        # load, so we add cogames explicitly for any consumer of
+        # //packages/coworld:coworld that transits cogsguard.
+        "//packages/cogames:cogames",
+        "@pypi//cogsguard",
+        "@pypi//fastapi",
+        "@pypi//httpx",
+        "@pypi//jsonschema",
+        "@pypi//kubernetes",
+        "//packages/mettagrid/python/src/mettagrid:mettagrid",
+        "@pypi//numpy",
+        "@pypi//pyarrow",
+        "@pypi//pydantic",
+        "@pypi//referencing",
+        "@pypi//requests",
+        "@pypi//rich",
+        "@pypi//typer",
+        "@pypi//uvicorn",
+        "@pypi//websockets",
+    ],
+)
+
+py_binary(
+    name = "coworld_bin",
+    srcs = ["src/coworld/cli.py"],
+    main = "src/coworld/cli.py",
+    imports = ["src"],
+    visibility = ["//visibility:public"],
+    deps = [":coworld"],
+)

coworld-0.0.0/CLAUDE.md

@@ -0,0 +1,98 @@
+# AGENTS.md - coworld
+
+Public CLI and Python package for Softmax v2 tournaments ("Coworlds"). This package owns the user-facing `coworld`
+entrypoint, local episode/play tooling, Coworld uploads, policy uploads/submission helpers, the Paint Arena reference
+Coworld, and the public Coworld docs shipped with the package. It depends on `softmax-cli` for auth-backed commands.
+
+## Before Editing
+
+- Read this file, `LESSONS.md`, the package [README](README.md), and the [Coworld docs map](src/coworld/docs/README.md)
+  before changing user-facing Coworld behavior or docs.
+- Keep package docs public-package-facing. Avoid private Metta backend paths unless the document is intentionally
+  explaining a platform integration boundary.
+- Treat Paint Arena under `src/coworld/examples/paintarena/` as the canonical in-tree example.
+
+## CLI
+
+The package installs the Typer app at `coworld.cli:app`:
+
+```bash
+uv run coworld --help
+uv run coworld leagues
+uv run coworld download <coworld-name-or-id> --output-dir ./coworld
+uv run coworld run-episode <manifest.json> <image:tag>
+uv run coworld play <manifest.json> [image|request.json]
+uv run coworld build / certify / upload-coworld
+uv run coworld upload-policy / submit
+```
+
+Auth-backed commands require `uv run softmax login` first. The `auth` extra pulls in `softmax-cli`.
+
+## Validation
+
+Use the narrowest check that covers the touched surface, then broaden when changing shared contracts:
+
+```bash
+uv run metta pytest packages/coworld/tests/test_types.py -v
+uv run metta pytest packages/coworld/tests -v
+uv run metta pytest --changed
+uv run metta lint --fix
+```
+
+When changing manifest Pydantic models or generated schema files, update `types.py` first and regenerate the checked-in
+schema JSON:
+
+```bash
+uv run --project packages/coworld python packages/coworld/scripts/generate_coworld_schemas.py
+uv run metta pytest packages/coworld/tests/test_types.py -v
+```
+
+Do not hand-edit `src/coworld/coworld_manifest_schema.json` or `src/coworld/runner/episode_request_schema.json` as the
+source of truth. They are generated docs and `$schema` targets; `test_types.py` checks that they match `types.py`.
+
+## Source Layout
+
+- `src/coworld/cli.py`, `tournament_cli.py` - Typer command surface for local episodes, uploads, leagues, and hosted
+  tournament inspection.
+- `src/coworld/cli_support.py`, `api_client.py` - shared CLI helpers and the Softmax/Coworld API client.
+- `src/coworld/certifier.py` - `coworld certify` smoke-test pipeline.
+- `src/coworld/manifest_validation.py`, `schema_validation.py`, `manifest_uri.py` - manifest and schema validation.
+- `src/coworld/bundle.py` - episode-bundle assembly around `COGAME_EPISODE_BUNDLE_URI`.
+- `src/coworld/play.py`, `src/coworld/runner/` - local play, local episode runner, and hosted-runner contracts.
+- `src/coworld/starter_policy.py`, `src/coworld/policies/` - packaged starter policy templates.
+- `src/coworld/commissioner/`, `submit.py`, `upload.py` - league round-running, submission, and upload support.
+- `src/coworld/examples/paintarena/` - smallest complete Coworld and reference implementation.
+
+## Documentation Map
+
+- [README.md](README.md) - package landing page, player-first orientation, and navigation.
+- [COOKBOOK.md](COOKBOOK.md) - task recipes for local play, policy upload/submission, tournament results, and
+  Coworld upload.
+- [src/coworld/docs/README.md](src/coworld/docs/README.md) - Coworld concept map, role statuses, artifact flow, and
+  cross-links.
+- [src/coworld/docs/COWORLD_MANIFEST.md](src/coworld/docs/COWORLD_MANIFEST.md) - manifest semantics and schema source
+  of truth.
+- [src/coworld/docs/LIFECYCLE.md](src/coworld/docs/LIFECYCLE.md) - local and hosted episode lifecycle.
+- `src/coworld/docs/roles/*.md` - per-role contracts.
+- `src/coworld/docs/artifacts/*.md` - artifact contracts.
+- `src/coworld/runner/RUNNER_README.md` and `src/coworld/runner/KUBERNETES_RUNNER_README.md` - runner-specific
+  behavior.
+
+## Manifest And Role Contracts
+
+- The schema currently requires `game`, `player`, and `reporter`. `commissioner`, `grader`, `diagnoser`, and
+  `optimizer` are optional today and marked future-required in generated schema metadata.
+- Role semantics belong in `src/coworld/docs/roles/`. Field-level manifest shape belongs in `src/coworld/types.py` and
+  the generated schema JSON, not in duplicated Markdown tables.
+- Manifest role changes usually need matching updates to role docs, Paint Arena templates, generated schemas,
+  certifier/runner tests, and any README links that name the role.
+- Do not describe `coworld hosted-game` as a supported player workflow unless product/runtime support is restored.
+  Current hosted execution means tournament jobs where the platform runs the game and every player container.
+
+## Package Data Gotchas
+
+- Versioning uses `setuptools_scm` from `coworld-v*` git tags (`fallback_version = "0.0.0"`).
+- `pyproject.toml` deliberately excludes Dockerfiles and example READMEs from wheel package data. Non-runtime example
+  edits should not change wheel content or Bazel action keys for downstream `@pyenv` consumers.
+- Antfarm hosts Coworld game containers; keep `packages/antfarm/README.md` aligned when the game-container contract
+  changes.