0

Spatial Gym

Fresh

SPaRC grid pathfinding puzzles, one move per step

Type
RL Env
License
bsd-3-clause
Published
Oct 2026

Cite

Notes

Only stored in your browser.

Spatial-Gym Environment

Spatial-Gym turns the SPaRC grid puzzles into a step-by-step environment. The agent draws one line from the start node to the exit, one move at a time, and the line has to follow every rule on the board. In the Spatial-Gym paper, humans solve 98.0% of the test puzzles, and the best model, GPT-OSS 120B, solves 16.0%.

Spatial-Gym web playground

The /web playground mid-episode: the board with the line so far, and one button per legal move.

This environment serves Spatial-Gym through OpenEnv. It uses the paper's prompts and scoring, with the polyshape and negative polyshape rules stated the way the puzzles were built, and the reward matches the Prime Intellect version.

One episode

  • reset() loads one puzzle. The observation holds the board, the legal moves, the paper's rules prompt (system_prompt) and the paper's message for the first move (prompt).
  • step(SpatialGymAction(action=...)) makes one move: 0=RIGHT, 1=UP, 2=LEFT, 3=DOWN. A move that is not legal leaves the line where it is but still counts as a step.
  • The episode ends when the line reaches the exit, when no legal move is left, or after max_steps moves.
  • The reward is 1.0 when the episode ends with a line that exactly matches one of the puzzle's stored solutions, and 0.0 otherwise. metadata["rule_status"] shows which rules the line meets so far.

A SPaRC puzzle solved one move per step

A level-5 puzzle solved move by move: the line starts at the big circle and has to reach the exit at the bottom left while following every rule on the board.

Quick start

Install the client:

pip install "git+https://github.com/openenv/OpenEnv.git#subdirectory=envs/spatial_gym_env"

Connect to a running server, then let a model play one puzzle:

from spatial_gym_env import SpatialGymAction, SpatialGymEnv

with SpatialGymEnv(base_url="http://localhost:8000").sync() as env:
    result = env.reset(difficulty=2, seed=0)
    messages = [
        {"role": "system", "content": result.observation.system_prompt},
        {"role": "user", "content": result.observation.prompt},
    ]
    while not result.done:
        reply = my_model(
            messages
        )  # your LLM call; the reply ends with "Final: <action>"
        messages.append({"role": "assistant", "content": reply})
        result = env.step(SpatialGymAction.from_reply(reply))
        if not result.done:
            messages.append({"role": "user", "content": result.observation.prompt})
    print("solved" if result.reward == 1.0 else "not solved")

SpatialGymAction.from_reply reads the move the way the paper did and raises ValueError when the reply has none. To run the environment from its Hugging Face Space image with Docker, use SpatialGymEnv.from_env("<space-id>") instead of base_url.

Reset options

OptionDefaultMeaning
puzzle_idnonePlay this SPaRC puzzle
difficultyall levelsA level from 1 to 5, or a list of levels, to draw the puzzle from
seednoneMakes the draw repeatable
split"test""test" holds the 500 benchmark puzzles, "train" 500 more for training
backtrackingFalseAllow stepping back onto the previous node to undo a move
max_steps100The episode ends after this many moves, as in the paper

Observation

FieldMeaning
puzzle_id, difficultyThe puzzle and its level
stepMoves taken so far
positionCurrent node as [x, y]
pathThe line so far, as [x, y] nodes from the start
legal_actionsMoves allowed from here
gridBoard rows in SPaRC notation; V marks visited nodes and L the current one
system_promptRules and symbol legend from the paper, sent on reset only
promptThe paper's message for the next move, empty once the episode is over
solved, reached_endThe line matches a stored solution; the line ended on the exit
done, rewardEpisode over; 1.0 for a solved puzzle, else 0.0

state() returns the episode's puzzle, options, step count and the full path.

Run it yourself

From envs/spatial_gym_env/, start the server with uv run --project . server (port 8000; set ENABLE_WEB_INTERFACE=true for the playground at /web). Build the image with openenv build, and deploy a Space with openenv push (or openenv push --repo-id my-org/spatial-gym-env). See the openenv push reference for all options.

The tests download the SPaRC dataset and skip themselves when Spatial-Gym is not installed. From the repository root:

PYTHONPATH=src:envs uv run --with "Spatial-Gym>=0.1.5" pytest tests/envs/test_spatial_gym_environment.py -v

The server keeps one environment per WebSocket session, up to MAX_CONCURRENT_ENVS (default 8). It downloads the SPaRC dataset from Hugging Face on the first reset of each split.

Citation

@misc{kaesberg2026spatialgym,
  title  = {Mind the Gap Between Spatial Reasoning and Acting! Step-by-Step Evaluation of Agents With Spatial-Gym},
  author = {Kaesberg, Lars Benedikt and Yang, Tianyu and Bauer, Niklas and Ruas, Terry and Wahle, Jan Philip and Gipp, Bela},
  year   = {2026},
  eprint = {2604.09338},
  archivePrefix = {arXiv}
}

@inproceedings{kaesberg-etal-2025-sparc,
  title     = "{SP}a{RC}: A Spatial Pathfinding Reasoning Challenge",
  author    = "Kaesberg, Lars Benedikt and Wahle, Jan Philip and Ruas, Terry and Gipp, Bela",
  booktitle = "Proceedings of the 2025 Conference on Empirical Methods in Natural Language Processing",
  month     = nov,
  year      = "2025",
  address   = "Suzhou, China",
  publisher = "Association for Computational Linguistics",
  url       = "https://aclanthology.org/2025.emnlp-main.526/",
  doi       = "10.18653/v1/2025.emnlp-main.526",
  pages     = "10359--10390"
}