Skip to content

docs: fix README Quick Start so a fresh install actually runs #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sasmith wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: fix README Quick Start so a fresh install actually runs #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd5f6be
chore: update cogames mettagrid to 0.26.19
nishu-builder May 7, 2026
1edf66a
docs: fix README Quick Start so a fresh install actually runs
claude May 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 21 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,16 @@ There's one ALB game right now: Cogs vs Clips.

## Step 1: Install CoGames

Install [cogames](https://pypi.org/project/cogames/) as a Python package.
Install [cogames](https://pypi.org/project/cogames/) as a Python package, along
with the Cogs vs Clips game (`cogsguard`, installed from git) and the `neural`
extras needed to run the `starter` policy.
```bash
pip install cogames
# Use a virtual environment to avoid conflicts with system-managed packages.
python -m venv .venv
source .venv/bin/activate

pip install "cogames[neural]"
pip install "cogsguard @ git+https://github.com/Metta-AI/cogame-cogsguard.git"
```

<details><summary>Using uv</summary>
Expand All @@ -51,8 +58,9 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv .venv
source .venv/bin/activate

# Install cogames
uv pip install cogames
# Install cogames, the neural extras, and the cogsguard game
uv pip install "cogames[neural]"
uv pip install "cogsguard @ git+https://github.com/Metta-AI/cogame-cogsguard.git"
```

</details>
Expand All @@ -64,11 +72,12 @@ FROM python:3.12-slim

# Ensure C/C++ compiler is available
RUN apt-get update && \
apt-get install -y --no-install-recommends build-essential && \
apt-get install -y --no-install-recommends build-essential git && \
rm -rf /var/lib/apt/lists/*

# Install cogames
RUN pip install --no-cache-dir cogames
# Install cogames, the neural extras, and the cogsguard game
RUN pip install --no-cache-dir "cogames[neural]" \
"cogsguard @ git+https://github.com/Metta-AI/cogame-cogsguard.git"
```

</details>
Expand Down Expand Up @@ -111,16 +120,18 @@ Command guide:
```bash
cogames create-bundle -p class=cogames.policy.starter_agent.StarterPolicy -o submission.zip
cogames upload -p ./submission.zip -n "$USER.README-quickstart-starter-policy" --no-submit
cogames submit "$USER.README-quickstart-starter-policy" --season beta-teams-small
cogames submit "$USER.README-quickstart-starter-policy" --season beta-teams-tiny-fixed
```

3. Check your submission status.

```bash
cogames submissions --season beta-teams-small --policy "$USER.README-quickstart-starter-policy"
cogames season matches beta-teams-small --limit 5
cogames submissions --season beta-teams-tiny-fixed --policy "$USER.README-quickstart-starter-policy"
cogames season matches beta-teams-tiny-fixed --limit 5
```

Run `cogames season list` to see other open seasons you can submit to.

# Tutorials

To learn more, see:
Expand Down
6 changes: 3 additions & 3 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ classifiers = [
"Programming Language :: Python :: 3.12",
]
dependencies = [
"mettagrid==0.26.17",
"mettagrid==0.26.19",
"softmax-cli==0.26.7",
"packaging>=24.0.0",
"pydantic>=2.11.5",
Expand Down Expand Up @@ -89,8 +89,8 @@ testpaths = ["tests"]
source = ["cogames"]

[tool.uv.sources]
mettagrid = { workspace = true }
softmax-cli = { workspace = true }
mettagrid = {git = "https://github.com/Metta-AI/mettagrid.git"}
softmax-cli = {git = "https://github.com/Metta-AI/softmax-cli.git"}
diplomacog = { git = "https://github.com/Metta-AI/cogame-diplomacog.git" }
hungercog = { git = "https://github.com/Metta-AI/cogame-hungercog.git" }
overcogged = { git = "https://github.com/Metta-AI/cogame-overcogged.git" }
Expand Down