[lkaesberg]

Summary

Adds envs/spatial_gym_env, which serves Spatial-Gym (paper). One episode is one SPaRC grid puzzle: the agent draws a line from the start node to the exit, one move per step, and the line has to follow every rule on the board. The reward is 1.0 when the line matches one of the puzzle's stored solutions, else 0.0. In the paper, humans solve 98.0% of the test puzzles and the best model, GPT-OSS 120B, 16.0%.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• New environment
• Refactoring

Alignment Checklist

• I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
• I have checked .claude/docs/INVARIANTS.md and no invariants are violated
• I have run the lint commands from .claude/hooks/lint.sh on the new files and the tests

RFC Status

• Not required (new example environment, no new patterns)

Test Plan

• PYTHONPATH=src:envs uv run --with "Spatial-Gym>=0.1.5" pytest tests/envs/test_spatial_gym_environment.py -v: 9 passed. The tests replay a stored solution for one puzzle per difficulty level (reward 1.0), check that a wrong line scores 0.0, that backtracking undoes a move, the reset options, that sessions are independent, and play a full puzzle through SpatialGymEnv over WebSocket. Without Spatial-Gym installed the file is skipped, as in CI.
• Repo-wide checks pass: tests/envs/test_manifest_app_targets.py, test_server_main_args.py, test_discovery.py, test_hub_canonical_dockerfiles.py, tests/discovery (334 passed), and python scripts/sync_env_docs.py --check.
• openenv validate --level static --skip-build passes. openenv build (in-repo mode) builds the image; the container solves a level-4 puzzle in 35 moves for reward 1.0, serves the web UI with the README, and passes openenv validate --url.
• usort check and ruff format --check pass on the new files. server/prompts.py keeps the paper's prompt text byte for byte, so it carries a # ruff: noqa: W291, W293 for the trailing spaces inside the strings.

Notes for review:

• reset() options: puzzle_id, difficulty (a level 1–5 or a list), seed, split (test or train), backtracking, max_steps (default 100, as in the paper). Unknown options raise, because the server would otherwise drop them quietly.
• The observation carries the board, the legal moves, the paper's rules prompt (on reset) and its per-step message, plus the rule status in metadata. SpatialGymAction.from_reply(text) reads a move with the paper's parser, which lives in models.py so clients can use it.
• The SPaRC dataset is downloaded from Hugging Face on the first reset of each split.
• I can provide a playground screenshot for the README if you add it to huggingface/documentation-images, like the other envs.
• I would be glad to see it deployed under the openenv org. Hugging Face now needs a PRO plan for Docker Spaces on a personal account.

Claude Code Review

Prepared with Claude Code. Manual check against .claude/docs/INVARIANTS.md: the client imports only models.py, the server never imports the client, the reward is computed inside the environment, and the agent-facing surface is the observation text only. No MCP tools expose reset(), step() or state(). Pydantic models are used throughout, and reset/step follow the base signatures. Sessions share no mutable state: each episode deep-copies a read-only template of the Spatial-Gym env.

---

Note

Low Risk
Additive example environment with isolated server code; main operational note is runtime dependency on Hugging Face dataset downloads and the external Spatial-Gym package, not changes to core OpenEnv infrastructure.

Overview
Introduces envs/spatial_gym_env, a new OpenEnv environment that wraps Spatial-Gym for step-by-step SPaRC grid pathfinding. Each episode is one puzzle: agents move one direction per step (SpatialGymAction), get the paper’s system_prompt and per-step prompt, and receive 1.0 only when the path matches a stored solution.

The server integrates the underlying Spatial-Gym gymnasium env via deep-copied templates per session, loads lkaesberg/SPaRC on first reset per split, exposes HTTP/WebSocket through create_app, and adds a /web playground (SVG board + legal-move buttons). The client includes SpatialGymAction.from_reply for paper-style Final: parsing.

Documentation is wired in (spatial_gym.md, environments index card, toctree) along with discovery.json, Docker packaging, and tests/envs/test_spatial_gym_environment.py (gold solutions, WebSocket E2E, skipped without Spatial-Gym installed).

^{Reviewed by Cursor Bugbot for commit b2e3e47. Bugbot is set up for automated code reviews on this repo. Configure here.}

[burtenshaw]

Very cool. Do you have any visual to understand these environments?

[lkaesberg]

Thanks! Yes, here is one episode: a level-5 puzzle solved one move per step. The line starts at the big circle and has to reach the exit at the bottom left while following every rule on the board (stones of different colours apart, stars in pairs, the triangle's edge count, the polyomino's shape, the dot).

I also added render_web() and web_actions(), so the /web playground now draws the board with the line so far and offers one button per legal move:

Both images are in the README now. They are hosted in the Spatial-Gym repo; happy to move them to huggingface/documentation-images like the other envs if you prefer.

[lkaesberg]

Hi @burtenshaw, just a small friendly reminder about the Spatial-Gym environment, whenever you find the time. If there's anything you'd like changed, I'm happy to update it. Thanks!

[lkaesberg]

Hi @burtenshaw @sergiopaniego, thanks for the docs fix! I also updated the links to openenv/OpenEnv after the move. Happy to change anything else if needed!