Deploy geoguesser environment with train/eval splits

.gitattributes

@@ -35,3 +35,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 env/data/geo/detail/roads.json filter=lfs diff=lfs merge=lfs -text
 env/data/geo/detail/urban.json filter=lfs diff=lfs merge=lfs -text
+geoguesser_env/data/geo/detail/roads.json filter=lfs diff=lfs merge=lfs -text
+geoguesser_env/data/geo/detail/urban.json filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -50,9 +50,14 @@ RUN pip install --no-cache-dir \
         "typing_extensions>=4.0.0"
 
 COPY src /app/src
-COPY env /app/env
+# As a package directory, not a bare source root. Modules inside do
+# `from ..models import ...`, which only resolves when `geoguesser_env` itself
+# is the package -- with the sources at /app/env and PYTHONPATH pointing there,
+# `server` becomes top-level and those imports fail with "attempted relative
+# import beyond top-level package".
+COPY env /app/geoguesser_env
 
-ENV PYTHONPATH=/app/env:/app/src
+ENV PYTHONPATH=/app:/app/src
 
 # The web UI is off in core by default; without this the Space serves a 404 at
 # /web and looks broken.
@@ -66,12 +71,12 @@ ENV GEOGUESSER_TASKS_EVAL=/data/tasks/eval_pano_v3.jsonl \
     GEOGUESSER_CACHE=/data/panos \
     GEOGUESSER_ALLOW_FETCH=0 \
     GEOGUESSER_STREET_DETAIL=1 \
-    GEOGUESSER_INDEX=/app/env/tasks/eval_pano_v3.jsonl
+    GEOGUESSER_INDEX=/app/geoguesser_env/tasks/eval_pano_v3.jsonl
 
 # Overpass results cache here, on the container's own writable disk, which is
 # why street labels work even with Mapillary fetching disabled.
-RUN mkdir -p /app/env/data/geo/osm_cache /app/env/data/panos \
-    && chmod -R 777 /app/env/data
+RUN mkdir -p /app/geoguesser_env/data/geo/osm_cache /app/geoguesser_env/data/panos \
+    && chmod -R 777 /app/geoguesser_env/data
 
 EXPOSE 8000
-CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uvicorn", "geoguesser_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

geoguesser_env/.gitignore

@@ -0,0 +1,23 @@
+# Panorama bytes are a runtime cache, not source. They are re-fetchable from
+# the task index, which is committed.
+data/panos/
+data/geo/detail/
+data/geo/osm_cache/
+rollouts/
+
+# The harvested sequence pool: 254 MB of upstream metadata, rebuildable with
+# scripts/harvest_tiles.py and not source.
+data/pool/
+
+# Intermediate build output. eval/train are carved from it by split_tasks.py.
+tasks/pool_offline_5k.jsonl
+
+# The training index is ~20 MB and lives in the Storage Bucket alongside the
+# imagery. The eval index stays committed: it is small, and a frozen benchmark
+# belongs in version control where changes to it are visible in review.
+tasks/train_pano_v3.jsonl
+
+# Superseded eval sets, kept locally until the v3 split is deployed.
+tasks/eval_pano_v1.jsonl
+tasks/eval_pano_v2.jsonl
+tasks/eval_balanced_trial.jsonl

geoguesser_env/.openenvignore

@@ -0,0 +1,4 @@
+data/panos/
+tests/fixtures/panos/
+__pycache__/
+*.pyc

geoguesser_env/DESIGN.md

@@ -0,0 +1,147 @@
+# geoguesser_env — design
+
+A GeoGuessr-style visual geolocation environment: the agent is dropped at an
+unknown street-level location, looks around, walks along the road, pins
+candidate coordinates on a map to check itself, and commits to a final guess.
+Reward is distance-based.
+
+Independent open-source project, unaffiliated with GeoGuessr AB. Imagery is
+openly licensed (CC-BY-SA, Mapillary contributors).
+
+## Why one environment, not three
+
+The task, reward curve, response parser, map renderer and pin loop are
+identical no matter where the imagery comes from. Only the imagery source
+changes, and with it *which tools exist*. So there is one environment and a
+`PanoramaBackend` protocol behind it:
+
+| Backend | `look` | `move` | Licence | Role |
+|---------|--------|--------|---------|------|
+| `mapillary` (this PR) | yes — local reprojection | yes — sequence graph | CC-BY-SA | training + eval |
+| `dataset` (osv5m, later) | no — single fixed view | no | CC-BY-SA-4.0 | 5.1M-image scale |
+| `google` (later) | yes | yes — true pano links | ToS-restricted | eval/demo only |
+
+Capability gaps surface as *unregistered tools*, never as a different
+observation schema — a policy trained against one backend runs unmodified
+against another. Registering a tool that always errors just teaches a policy
+to burn its step budget.
+
+## Determinism contract
+
+```python
+reset(split="eval", index=7)   # exact task, byte-identical  -> GRPO, eval
+reset(seed=42)        # tasks[42 % len(tasks)]                   -> replay
+reset()               # random task, index in metadata           -> UI "next"
+```
+
+Three things make repeats byte-identical: panorama bytes come from local disk
+(never an expiring CDN URL), reprojection is pure numpy with integer
+sampling, and the initial heading is pinned to the panorama's own
+`compass_angle` so `look(0)` is true north in every task.
+
+A GRPO group calls `reset(split=s, index=k)` N times and gets N identical
+starting observations.
+
+## Task API
+
+Tasks are consumed through `openenv.core.harness`, not a bespoke index.
+`GeoGuesserSessionFactory` (see `harness.py`) maps a task dict to
+`reset_kwargs={"task_index": ...}`, which gives us, unchanged:
+
+- `CollectRunner(tasks=...)` — JSONL rollout collection with resume, and
+  `EpisodeRecord.task` recording which task produced each episode.
+- `build_harness_rollout_func(...)` — a TRL-compatible rollout function where
+  each prompt *is* a task.
+- `EvalConfig` / `EvalResult` — `harness_version`, `library_versions` and
+  `dataset` are exactly the provenance an eval score needs.
+
+## Imagery: lazy cache, not a bundled corpus
+
+Mapillary `thumb_*_url` values are expiring signed CDN URLs, so imagery is
+resolved to a local cache and never fetched mid-rollout from a URL stored in
+the index. The task index (`tasks/eval_pano_v3.jsonl`, 1.2 MB, committed) holds
+image ids, coordinates, sequence ids, headings, capture dates, creator
+attribution and a sha256 per start frame.
+
+- Build time: download each task's **start frame** (~29 MB for 100 tasks).
+- Runtime: movement frames fetch on first use and cache to disk.
+- `--prefetch-frames N` warms a task's whole sequence for a frozen eval.
+
+`MAPILLARY_API_KEY` is needed by the builder, and at runtime only on a cache
+miss. A fully warmed cache runs offline.
+
+## Reward
+
+```
+geo     = exp(-haversine_km / 1492.7)          # GeoGuessr's curve, in [0, 1]
+partial = 0.15 * country_hit + 0.10 * region_hit
+cost    = 0.01*looks + 0.01*maps + 0.02*pins + 0.05*moves
+reward  = clip(geo + partial, 0, 1) - cost
+```
+
+An unparseable or out-of-range guess scores `0.0` with feedback, following
+`pelican_svg_env`: extraction failures belong in the score, not hidden in the
+harness.
+
+## The pin loop, and the trap in it
+
+`place_pin(lat, lon)` returns a rendered map plus a description of **what the
+agent pinned** — country, subregion, nearest city with distance and bearing,
+and the distance to its own earlier pins. It reveals *nothing* about the
+target.
+
+If pin feedback carried any signal about the truth (distance, warmer/colder,
+a highlighted region), the optimal policy would be binary search — about
+twenty pins to metre-level accuracy — and the environment would measure
+bisection instead of geographic reasoning. Distance and score arrive only
+from `submit_guess`, which is terminal.
+
+The same reasoning constrains map detail: **detail is a function of zoom
+alone, never of proximity to the answer.** Prefetching high-resolution map
+data around task locations would turn the cache into a ground-truth oracle.
+
+## Measured facts behind these choices
+
+Probed against the live Graph API:
+
+- `camera_type` returns `spherical` — *not* the `equirectangular` the docs
+  claim. Filtering on the documented value matches nothing.
+- Panoramas are true 2:1 equirectangular (`thumb_2048` = 2048x1024,
+  original 7680x3840). Faces and plates arrive pre-blurred.
+- Sequence frames sit ~3.3 m apart (measured mean over 12 frames: 3.3 m,
+  min 3.1, max 3.7) — finer granularity than Street View's ~10 m.
+- Reprojection costs ~23 ms per 640x640 view in numpy.
+- `/images` search is not a bulk endpoint: `limit` does not cap the scan and
+  dense bboxes beyond ~±0.0005 deg fail with "reduce the amount of data".
+  Discovery therefore uses many tiny bboxes.
+- Panorama coverage at Street-View coordinates: any imagery 21/45 locations,
+  360-degree panoramas only 7/45 (16%), heavily clustered. Expect a
+  Europe-weighted task distribution and document it rather than hiding it.
+
+## One guess per episode
+
+`submit_guess` is terminal, so an episode is exactly one guess. The play page's
+five-round game is a wrapper around five separate episodes; nothing in the
+environment accepts a second guess, and the pin loop is deliberately not a
+second chance — it is how a policy checks its own arithmetic before committing.
+
+## Zoom needs the original panorama
+
+Zooming a 2048x1024 panorama is resolution-starved: a 30-degree view samples
+about 170 source pixels, and the measured mean gradient barely moves (6.60 at 90
+degrees, 7.03 at 30). The 7680x3840 original roughly doubles it (10.23, 14.87).
+Each panorama is therefore cached twice, and the field of view selects the
+derivative: wide views render from the 2048 in ~30 ms, views at or below 45
+degrees from the original in ~70 ms. A missing original degrades to a soft view
+rather than failing the step.
+
+## Known gaps versus the real game
+
+Movement is bounded by captured sequences and dead-ends where one does; frame
+spacing varies enormously between sequences, from ~3 m to ~57 m, so `move()`
+reports the distance it actually travelled rather than the distance requested;
+there is no multi-round cumulative score in the environment itself; step budget replaces the wall-clock
+timer; there is no satellite layer on the guess map. NMPZ mode is nearly free
+(register only `place_pin` and `submit_guess`) and should ship as a difficulty
+tier. Coverage hints and web search are deliberately excluded — the first is a
+crutch, the second turns the task into retrieval.

geoguesser_env/HARVEST.md

@@ -0,0 +1,239 @@
+# Harvesting panorama tasks
+
+Measured, not estimated. Every number below came from running the pipeline
+against the live Mapillary Graph API.
+
+## The pipelines, and what actually happened
+
+```
+                    ┌──────────────────────────────────────────────┐
+   seeds            │  road points   cities   osv5m rows   tiles   │
+                    └──────┬──────────┬───────────┬──────────┬─────┘
+                           │          │           │          │
+   discovery         ┌─────▼────┐┌────▼─────┐┌────▼─────┐┌───▼────────┐
+                     │ P1 point ││ P2 city  ││ P3 osv5m ││ P4 vector  │
+                     │  probe   ││ adaptive ││ sequence ││   tiles    │
+                     └─────┬────┘└────┬─────┘└────┬─────┘└───┬────────┘
+                       5% hit     26% hit      0% hit    not needed
+                           │          │           │          │
+                           └──────────┴─────┬─────┴──────────┘
+                                             │
+   expansion                    ┌────────────▼───────────┐
+                                │ group by sequence_id   │
+                                │ 16 sequences per hit   │
+                                └────────────┬───────────┘
+                                             │
+   assembly                     ┌────────────▼───────────┐
+                                │ image_ids?sequence_id  │
+                                │ -> ordered frames      │
+                                │ entity fetch per frame │
+                                └────────────┬───────────┘
+                                             │
+   filtering                    ┌────────────▼───────────┐
+                                │ is_pano, >= N frames   │
+                                │ country known          │
+                                │ per-country cap        │
+                                │ not in train sequences │
+                                │ > 1 km from train      │
+                                └────────────┬───────────┘
+                                             │
+                        ┌────────────────────┴────────────────────┐
+                        │                                         │
+              ┌─────────▼──────────┐                  ┌───────────▼─────────┐
+              │ eval: mirror bytes │                  │ train: index only,  │
+              │ + sha256, frozen   │                  │ imagery lazy        │
+              └────────────────────┘                  └─────────────────────┘
+```
+
+### P1 — point probe (what `build_pano_tasks.py` does)
+
+Sample a coordinate, search a 45 m box, keep the panoramas.
+
+**5% of seeds hit.** 3,600 probes produced 100 tasks over two passes. It works
+but wastes 19 requests in 20.
+
+The failure is not coverage, it is the box. A 45 m box misses a mapped road
+120 m away. That single misreading is why I first told you panorama coverage was
+sparse; it is not.
+
+### P2 — city-seeded adaptive box (recommended)
+
+Seed at populated places, try a 550 m box first and walk down to 220 m then 65 m
+when the server refuses, and pass `is_pano=true`.
+
+| Seeding | Hit rate | Sequences per hit |
+|---------|---------:|------------------:|
+| Street View coordinates, 45 m box | 5% | — |
+| cities jittered ±28 km, adaptive | 3% | 6.0 |
+| cities jittered ±2 km, adaptive | 21% | 6.5 |
+| **city centres, adaptive** | **26%** | **16.0** |
+
+80 city seeds returned 336 sequences in 28 seconds on 10 workers, ~0.34 s per
+seed. Denver alone gave 86 sequences, Ramallah 57, Cuenca 43.
+
+Two facts make this work:
+
+- `is_pano=true` is a **real server-side filter**. One request now answers "are
+  there panoramas here" rather than returning a hundred phone photographs to
+  sift. Verified: 76 results in a dense box, every one `spherical`.
+- Panoramas are **extremely clustered**. A 360 rig drives a route and uploads
+  hundreds of frames, so one hit is a neighbourhood, not a point. Rural Iowa at
+  a 550 m box returned 1,801 panoramas.
+
+### P3 — expand osv5m sequences (dead end)
+
+osv5m is itself Mapillary, and it carries a `sequence` column, so in principle
+its 4.9M rows are free seeds. I probed 40 of its sequences.
+
+**Zero contained a spherical image.** osv5m sampled perspective imagery, which
+is what most of Mapillary is. Useful finding, negative result: do not spend time
+here.
+
+Its sequences are long, though — median 502 frames, up to 2,863 — which is worth
+knowing for movement tasks.
+
+### P4 — vector coverage tiles, sequence layer (the right answer)
+
+I dismissed this at first by looking at the wrong layer. `mly1_public` has three:
+
+| Layer | Zooms | Geometry | Carries |
+|-------|-------|----------|---------|
+| overview | 0-5 | points | `id`, `is_pano`, `captured_at` |
+| **sequence** | **6-14** | **LineString per sequence** | **`id`, `image_id`, `is_pano`, `creator_id`, `quality_score`, `captured_at`** |
+| image | 14 | point per image | the above plus `compass_angle`, `sequence_id` |
+
+The image layer is what made this look infeasible: a z14 tile covers 5.8 km², so
+all land is ~25 million tiles against a 50,000/day budget. But the **sequence
+layer is served from z6**, where a tile covers roughly 600 km on a side and
+carries one feature per sequence — with `is_pano` and an anchor `image_id`
+already on it.
+
+Measured, one request each:
+
+| z6 tile | Sequences | Of which panoramic | Size | Time |
+|---------|----------:|-------------------:|-----:|-----:|
+| Denver | 71,752 | **18,587** | 7.3 MB | 3.5 s |
+| Paris | 85,920 | **11,617** | 8.6 MB | 4.2 s |
+| Nairobi | 8,491 | **1,670** | 0.8 MB | 1.3 s |
+
+So one tile over Denver yields more panorama sequences than a day of probing.
+
+**A full global pass is 1,059 tiles.** The world is 4,096 tiles at z6 and 26%
+intersect land, so at the measured sizes that is roughly 4 GB of tiles and under
+an hour, against a 50,000/day budget — about 2% of it. Recall is complete rather
+than a 26% lottery, and every sequence arrives with an anchor image to expand
+from.
+
+This replaces P2. Keep P2 only for topping up a specific city.
+
+Caveats specific to tiles: features are **clipped to tile boundaries**, so a
+sequence crossing tiles appears in both and must be deduplicated by `id`; the
+z6 geometry is simplified, so treat it as "roughly here" and take exact
+coordinates from the Graph API when assembling frames; and `is_pano` on a
+sequence describes the sequence, so confirm per frame during assembly.
+
+## Caveats worth knowing before you trust a harvest
+
+**The bbox ceiling is about scanned data, not returned data.** A dense city
+rejects a 550 m box with HTTP 500 and "reduce the amount of data", even with
+`is_pano=true`, because the filter is applied after the scan. Hence the ladder.
+`limit` does not help — it caps results, not the scan.
+
+**Clustering biases the set.** 16 sequences per hit are usually one
+contributor's drive on one day. Without a per-country and ideally per-contributor
+cap, a set of 10,000 tasks can be a few hundred drives, and a policy will learn
+those cameras rather than geography.
+
+**Frame spacing varies enormously**, from about 3 m to 57 m between frames in
+the same request. `move()` therefore reports the distance it actually travelled
+rather than the distance asked for.
+
+**Thumbnail URLs expire** and uploads get deleted. Nothing that must be
+reproducible may store a URL — mirror the bytes and hash them.
+
+**Not every image has derivatives.** A successful metadata response can still
+omit `thumb_2048_url`, which raised mid-build until it was handled.
+
+**`camera_type` is `spherical`**, not the `equirectangular` the documentation
+states. Filtering on the documented value silently matches nothing.
+
+**Some capture dates are junk.** A frame in the current eval build reports
+`1980-01`, which is a missing or zero `captured_at` rendered as an epoch date.
+Harmless for scoring, but it breaks a temporal split and it is a visible oddity
+in the UI, so filter to plausible years (Mapillary launched in 2013) when the
+capture date matters.
+
+**Coverage leans European** and 360 contributors cluster harder than Mapillary
+as a whole. Africa and Oceania will be thin whatever the pipeline. Document it
+rather than averaging it away.
+
+## Rate limits
+
+| Endpoint | Limit | Used by |
+|----------|-------|---------|
+| Search `/images` | 10,000/min per app | discovery |
+| Entity `/:id` | 60,000/min per app | frame assembly, thumbnails |
+| Tiles | 50,000/day | P4 only |
+
+Discovery at 10 workers runs about 3 requests/second, three orders of magnitude
+under the search limit. The limit is not the constraint; the bbox ceiling is.
+
+A separate key for harvesting is a good idea anyway: limits are per app, so a
+harvest cannot then starve a training run filling its cache.
+
+## What OSV-5M did, since it is the same source
+
+Their paper is worth copying from. They had the locations of all 1.8 billion
+Mapillary images and:
+
+- defined a **100 m x 100 m global grid** and took one image per cell, rather
+  than probing points
+- sampled with a weight proportional to **local image density to the power
+  −0.75**, which sits between density-proportional sampling (biased to cities)
+  and area-proportional sampling (biased to large countries)
+- filtered on **blurriness** (mean log magnitude spectrum under 120 dB),
+  **radiometry** (too dark, or a purple tint from encoding errors) and
+  **exposure** (70% of pixels above 250 or below 5)
+- separated train from test by removing test images **within 1 km of any train
+  image or sharing a sequence id**
+
+That last rule is exactly what `build_eval_set.py` already enforces, which is
+reassuring. The −0.75 density weighting is the piece worth adopting: it is a
+principled answer to the clustering problem that capped our first eval set at 58
+tasks across only 30 countries.
+
+## Other openly licensed sources
+
+**Panoramax** is a federated, open street-level imagery network with a STAC API
+(`/search`, collections as sequences, items as pictures) under CC-BY-SA, with a
+further grant for non-photographic derivatives under CC-BY or ODbL. Instances
+are small — one reports about 315,000 pictures against Mapillary's 1.8 billion —
+so it is a complement for Europe rather than a replacement, but the licensing is
+cleaner and the API is a standard.
+
+**KartaView** and the `streetlevel` library cover other providers; neither is
+needed while Mapillary supplies this much.
+
+## The plan
+
+1. **Tile enumeration (P4)** — walk the 1,059 land tiles at z6, keep sequence
+   features with `is_pano`, deduplicate by id. About an hour, 4 GB, 2% of the
+   daily tile budget. Output: a global pool of panorama sequences with anchor
+   image ids, `creator_id` and `quality_score`.
+2. **Sample the pool, not the world** — apply OSV-5M's density weighting
+   (`density^-0.75`) plus a per-country and per-`creator_id` cap. Contributor
+   capping matters as much as country capping: 16 sequences per hit are usually
+   one person's drive.
+3. **Eval, 100 tasks** — sample from the pool, cap 2 per country, reject any
+   training sequence and anything within 1 km of one, mirror the bytes with
+   sha256, and add OSV-5M's blur and exposure checks on the downloaded
+   panorama.
+4. **Train, 10k tasks** — same pool, cap ~200 per country, index only and
+   imagery fetched lazily.
+5. **Augment** — derive the initial heading from the episode seed rather than
+   pinning it to `compass_angle`, for 8 to 12 times the effective tasks from
+   imagery already on disk, reproducibly.
+
+The city-probing eval set built while researching this reached 58 of 100 tasks
+across 30 countries before exhausting its 1,300 discovered sequences — which is
+the clearest possible argument for step 1.

geoguesser_env/README.md

@@ -0,0 +1,578 @@
+# GeoGuesser
+
+A GeoGuessr-style visual geolocation environment. The agent is dropped at an
+unknown street-level location, looks around, walks along the road, pins
+candidate coordinates on a map to check itself, and commits to a final guess.
+Reward is distance-based, using the game's own scoring curve.
+
+Independent open-source project, unaffiliated with GeoGuessr AB. Imagery comes
+from Mapillary contributors under CC-BY-SA-4.0.
+
+## Quick start
+
+```bash
+cd envs/geoguesser_env
+
+# The frozen 200-task eval split is committed, so the server runs as-is.
+uv run --project . server            # http://localhost:8000
+
+# To build your own data (needs a free Mapillary token with READ scope):
+export MAPILLARY_API_KEY_TRAIN="MLY|..."
+python scripts/harvest_tiles.py                        # enumerate sequences
+./scripts/build_dataset.sh                             # mirror tasks offline
+python scripts/verify_offline.py tasks/pool_offline_5k.jsonl
+python scripts/split_tasks.py tasks/pool_offline_5k.jsonl --eval 200
+```
+
+```python
+from geoguesser_env import GeoGuesserEnv, GuessAction, LookAction, PinAction
+
+env = GeoGuesserEnv(base_url="http://localhost:8000")
+
+result = env.reset(split="eval", index=7)     # byte-identical on repeat
+print(result.observation.prompt)
+
+result = env.step(LookAction(heading_deg=90, fov_deg=45))
+result = env.step(PinAction(lat=-16.5, lon=-68.1))
+print(result.observation.feedback)
+# Pin 1 placed at -16.5000, -68.1000 - Bolivia (South America).
+# Nearest major city: La Paz, ~5 km E. 10 actions left.
+
+result = env.step(GuessAction(response="Altiplano. <guess>-16.49, -68.12</guess>"))
+print(result.reward, result.observation.distance_km)
+```
+
+## Tools
+
+| Tool | What it does | Cost |
+|------|--------------|------|
+| `look(heading_deg, pitch_deg, fov_deg)` | Render a view. Heading is absolute, `0` is true north | −0.01 |
+| `pan(delta_deg)` | Turn relative to the current heading | −0.01 |
+| `zoom(fov_deg)` | Narrow the field of view; around 30 reads distant signs | −0.01 |
+| `move(direction, meters)` | Walk the captured road; reports distance actually travelled | −0.05 |
+| `place_pin(lat, lon, label)` | Pin a candidate and see where it falls on the map | −0.02 |
+| `view_map(lat, lon, span_deg)` | Pan and zoom the map without pinning | −0.01 |
+| `list_pins()` / `clear_pins()` | Review or drop candidates | free |
+| `measure(lat_a, lon_a, lat_b, lon_b)` | Distance between two of your own points | free |
+| `reverse_geocode(lat, lon)` | Name the country and nearest city at a coordinate | free |
+| `submit_guess(lat, lon, ...)` | Commit the answer. Terminal | — |
+
+Tools the backend cannot serve are **not registered**, so the agent never sees
+a tool that always fails.
+
+### The agent's map and the player's map agree
+
+The player sees live OpenFreeMap tiles; the agent sees an offline Natural Earth
+render. They have to agree about *how precisely a pin can be aimed*, because
+that is what the distance reward measures — a map showing only country outlines
+lets you place a country, not a point within a city.
+
+So the guess map is zoom-aware. `place_pin` takes `span_deg`, and the render
+adds detail as the window tightens:
+
+| Window | What the agent's map shows |
+|--------|----------------------------|
+| wider than ~4 deg | coastlines, borders, country names |
+| under ~4 deg | urban areas, highways, rivers, town names (Natural Earth 10m) |
+| under ~0.35 deg | **real OSM streets**, fetched from Overpass and cached |
+
+Natural Earth tops out at highway level — it shows the motorways around a city
+but not the grid inside it. Below 0.35 degrees the map therefore fetches actual
+ways from Overpass, generalising by zoom the way a real style does: minor
+classes appear only once the window is tight enough to hold them, and widths
+grow as it shrinks. A pin on Abuja at `span_deg=0.05` came back as an 11 km
+window with the full street grid, drawn white-on-pale to read like the
+player's Positron tiles.
+
+Overpass has real limits, and they are the binding constraint on how this
+scales: roughly **10,000 requests and 1 GB per day**, about **2 concurrent
+slots per IP**, a 180 s runtime and 512 MiB memory ceiling per query, HTTP 429
+when rate limited and 504 when a query is too large. Cooldowns lengthen for
+heavy users. So street detail is right for eval, demos and modest training, and
+the cache is what keeps it polite — a run doing millions of pins must pre-warm
+or bundle a Protomaps extract instead.
+
+The first render of a neighbourhood costs 3-16 s; every later one is served
+from `data/geo/osm_cache/` in ~30 ms and is byte-identical. That makes an
+episode deterministic once warm, and a frozen eval should pre-warm the cache
+the same way it pre-warms panoramas — or set
+`GEOGUESSER_STREET_DETAIL=0`, which falls back to Natural Earth and never
+touches the network. Any fetch failure degrades to no streets rather than
+failing the step.
+
+The optional detail layers are fetched once, since 87 MB of GeoJSON does not
+belong in the repo:
+
+```bash
+python scripts/fetch_detail_geo.py     # compacts to ~39 MB, gitignored
+```
+
+Without them the map still renders, with outlines and major cities only.
+
+In the play page the pin carries the zoom you are actually looking at, so the
+"what the agent sees" panel is framed like your own view at the same scale and
+with comparable detail.
+
+Overpass has a usage policy that discourages heavy automated querying, so this
+is right for eval, demos and modest training, and the cache is what keeps it
+polite. A run doing millions of pins should pre-warm or bundle a Protomaps
+extract instead.
+
+### Zoom resolves real detail
+
+Zooming is not cosmetic, but it needs the right source. A 30-degree view of a
+2048x1024 panorama samples only about 170 source pixels, so narrowing the field
+of view barely adds information — measured mean gradient 6.60 at 90 degrees
+against 7.03 at 30. The 7680x3840 original roughly doubles it (10.23 against
+14.87), which is the difference between guessing at a sign and reading it.
+
+So each panorama is cached twice. Wide views render from the 2048 derivative in
+~30 ms; a field of view at or below 45 degrees pulls the original and renders in
+~70 ms. If no original exists the step degrades to a soft view rather than
+failing. Set `GEOGUESSER_HIRES_ZOOM=0` to disable it.
+
+### Pinning tells you where you pointed, not whether you are right
+
+`place_pin` returns a rendered map and a description of the pinned location:
+country, subregion, nearest city with distance and bearing, and the distance
+to the agent's own earlier pins. It reveals nothing about the target.
+
+That restraint is deliberate. Any signal about the truth — a distance, a
+warmer/colder hint — would make binary search the optimal policy, and the
+environment would measure bisection rather than geographic reasoning. Distance
+and score arrive only from `submit_guess`.
+
+## Reward
+
+```
+geo     = exp(-distance_km / 1492.7)           # GeoGuessr's curve, in [0, 1]
+partial = 0.15 * country_hit + 0.10 * region_hit   # when hierarchical
+cost    = 0.01*looks + 0.01*maps + 0.02*pins + 0.05*moves
+reward  = clip(geo + partial, 0, 1) - cost
+```
+
+An unparseable or out-of-range guess scores `0.0` and says why. Parsing
+accepts what models actually emit: decimal pairs, DMS (`48°51'29"N`), labelled
+`lat:`/`lon:`, JSON, and `<guess>` tags.
+
+## Baselines
+
+Measured with `examples/geoguesser_llm_rollout.py` on the committed index,
+tasks 0/7/14/21/28, so the numbers are reproducible rather than illustrative.
+Five episodes is far too few for a leaderboard; they are a smoke test that the
+task is solvable and the reward is discriminative.
+
+| Model | Mode | Mean reward | Median distance | Within 200 km | Parsed |
+|-------|------|------------:|----------------:|--------------:|-------:|
+| `claude-sonnet-5` | single-shot | **0.896** | 98 km | 4/5 | 5/5 |
+| `claude-sonnet-5` | agentic, tasks 0-5 | 0.539-0.653 | 574-660 km | 3/6 | 6/6 |
+| `Qwen/Qwen3.5-9B` | agentic, tasks 0-5 | 0.355 | 1,136 km | 0/5 | 5/6 |
+| `Qwen/Qwen3.5-9B:together` | single-shot | 0.277 | 1,139 km | 1/3 | 3/5 |
+| `Qwen/Qwen3.5-9B:together` | agentic, 6 turns | 0.304 | 579 km | 0/1 | 1/2 |
+| `Qwen/Qwen3.5-9B:together` | agentic, 8k tokens | 0.087 | 2,423 km | 0/1 | **4/4 turns** |
+| `Qwen/Qwen3.5-9B:together` | single-shot, 8 eps, 4 parallel | 0.412 | 787 km | 1/6 | 6/8 |
+
+Sonnet placed two guesses within 2 km. The agentic score sits slightly below
+single-shot on the same tasks because looking around costs reward and the extra
+views did not always pay for themselves — which is the trade-off the
+environment is meant to expose, not a defect.
+
+Qwen does follow the multi-turn protocol: across the agentic runs it produced
+`look`, `move`, `zoom`, `pin` and `guess` actions and navigated up to 68 m down
+a road. Two things had to be right first, and both are prompting or plumbing
+rather than capability:
+
+- **Token budget.** Reasoning models put their chain of thought in a separate
+  `reasoning_content` field and can exhaust the budget before emitting any
+  content, which looks exactly like a model that cannot see images. At 1,024
+  tokens Qwen scored 0/5 with empty replies; at 3,500 it followed the protocol
+  intermittently, failing turns whose reply came back as pure reasoning; at
+  8,000 it parsed 4/4 turns. The example defaults to 3,000 and takes
+  `--max-tokens`.
+- **A deadline.** Left to itself Qwen explored until the turn budget ran out and
+  scored zero. The agentic prompt now warns it explicitly when two turns remain,
+  after which it committed.
+
+What remains is accuracy, not plumbing: its guesses landed 452 km, 579 km and
+2,423 km out against Sonnet's 98 km median. It is also 10x slower — 110-193 s
+per agentic episode against Sonnet's 10-16 s.
+
+```bash
+python examples/geoguesser_llm_rollout.py --provider anthropic \
+    --model claude-sonnet-5 --episodes 5
+python examples/geoguesser_llm_rollout.py --provider hf \
+    --model "Qwen/Qwen3.5-9B:together" --episodes 5 --max-tokens 4000
+python examples/geoguesser_llm_rollout.py --provider anthropic \
+    --mode agentic --episodes 3 --verbose
+```
+
+## Parallel rollouts
+
+An episode is stateful, so concurrent rollouts each need their own environment
+instance over the shared read-only index and cache. `--concurrency` does that:
+
+```bash
+python examples/geoguesser_llm_rollout.py --provider hf \
+    --model "Qwen/Qwen3.5-9B:together" --episodes 8 --concurrency 4
+```
+
+Eight Qwen episodes took 113.6 s wall against 334.0 s of summed latency — a
+**2.94x speedup** on 4 workers, the shortfall being the provider's own queuing
+rather than the environment, which spends ~28 ms on a reset.
+
+## Scaling: what the environment can actually supply
+
+Measured on an 18-core machine with a warm cache and street detail off, one
+environment per worker, with a correctness assertion in the loop so an
+interference bug cannot masquerade as throughput.
+
+Per-step cost is dominated by map rendering, not imagery:
+
+| Step | Cost |
+|------|-----:|
+| reset, or `look` at 90 deg fov | **29 ms** |
+| `look` at 30 deg fov, from the original | 74 ms |
+| `place_pin`, a two-panel map | **207 ms** |
+| `submit_guess` with the reveal map | 278 ms |
+
+That shapes the two configurations:
+
+| Config | Workers | Episodes/s | Notes |
+|--------|--------:|-----------:|-------|
+| training — views only, no pins, no reveal | 8 threads | **31.7** | 158 env steps/s |
+| eval — pins and reveal map | 4 processes | **3.5** | matplotlib is GIL-bound |
+| eval — pins and reveal map | 8 threads | 1.9 | threads do not help here |
+
+Two facts fall out of that. `look` releases the GIL — the reprojection is numpy
+and the encode is Pillow — so **threads scale well for view-only work** and
+processes only add startup cost. Map rendering is pure Python, so it is
+**GIL-bound and needs processes**, which buy about 1.8x before contention.
+
+`GEOGUESSER_REVEAL_MAP=0` is the single biggest throughput lever: a
+training-shaped episode drops from **389 ms to 117 ms**, since the reveal map is
+280 ms that a training run never reads — the reward and the distance are in the
+observation either way. Keep it on for evals, traces and the UI.
+
+Memory is small: about 215 MB for the imports, 100 MB more once the geodata
+caches fill, and **~13 MB per additional environment in the same process**. The
+Natural Earth layers are process-shared through an LRU cache, so threads are far
+cheaper than processes here too.
+
+### Rate limits that actually bind
+
+| API | When it is called | Limit |
+|-----|-------------------|-------|
+| Mapillary | only on a cache miss | 60,000/min entity, 10,000/min search, 50,000/day tiles |
+| Overpass | only a pin below 0.35 deg span | ~10,000/day, 2 concurrent slots per IP |
+| the model | every turn | the real constraint |
+
+With a warm cache the environment makes **no network calls at all**. Default
+pins use a 7 degree span, which is above the street threshold, so they do not
+touch Overpass either — only a deliberately zoomed pin does. For an eval sweep
+set `GEOGUESSER_STREET_DETAIL=0` unless you have pre-warmed, since 100 zoomed
+pins against 2 concurrent slots would throttle immediately.
+
+### 100-task eval
+
+Sonnet agentic measured 13.1 s per episode, so 100 episodes cost about 1,310
+model-seconds and the concurrency you can use is set by the provider, not by
+this environment:
+
+- concurrency 4 → **~5.5 minutes**
+- concurrency 8 → **~2.7 minutes**, if your token-per-minute ceiling allows it
+
+An agentic episode sends roughly five 640x640 views, about 550 tokens each, plus
+a growing text prompt. At a 400k input-tokens-per-minute ceiling that is roughly
+6 episodes in flight before tokens, not latency, become the limit — which is why
+4 to 6 is the practical range for Sonnet. Qwen through the router reached 3.97x
+on 6 workers, so 6 to 8 there.
+
+Meanwhile the environment can supply 3.5 episodes/s in eval configuration
+against the 0.3 to 0.6 episodes/s those concurrencies actually consume, so it
+has roughly ten times the headroom it needs.
+
+### 1000 training steps
+
+For GRPO with 8 prompts and a group of 16, that is 128 episodes per step and
+**128,000 episodes**, or about 640,000 env steps:
+
+- environment time: 128,000 / 31.7 ≈ **1.1 hours total**, spread across workers
+- imagery: nothing, with a warm cache
+- storage: 100 tasks warm is 60 MB; 5,000 tasks would be about 1.5 GB of start
+  frames
+
+So the environment is not the constraint — 640,000 model calls are, which needs
+batched local inference rather than an API. The constraint that *is* ours is
+**task diversity**: 128,000 episodes over 100 tasks means each location is seen
+1,280 times, which is memorisation territory. Before a run that long, either
+harvest more tasks or add seeded heading augmentation, which multiplies
+effective tasks 8 to 12 times from imagery already on disk.
+
+## Readiness audit
+
+`scripts/readiness_check.py` checks the properties that only appear at real
+scale and concurrency, rather than on the four committed fixtures:
+
+```bash
+python scripts/readiness_check.py --full
+```
+
+```
+[PASS] index integrity            100 tasks, 47 countries, 100 unique sequences
+[PASS] all tasks render           100/100 rendered, median reset 28 ms
+[PASS] cross-process determinism  two subprocesses and this process agree
+[PASS] parallel isolation         8 concurrent episodes, each its own task
+[PASS] offline with warm cache    12/12 served with fetching disabled
+[PASS] reward is discriminative   uniform-random 0.029, fixed-point 0.111
+[PASS] step latency               look 29 ms, pin + map 249 ms
+[PASS] one guess per episode      a second guess returns reward=None
+[PASS] pin never leaks the target 60 pins across 20 tasks revealed nothing
+```
+
+The reward check matters most: a uniform-random guesser scores **0.029** and the
+best trivial constant guess **0.111**, against Sonnet's 0.896. The signal is
+measuring geolocation rather than rewarding noise.
+
+## Tracing a rollout
+
+`--trace-dir` records every turn: the image the model saw, what it said, the
+action it chose, the environment's reply, steps left and running cost. A second
+script renders that as one self-contained HTML page, which is the difference
+between knowing the reward and seeing why:
+
+```bash
+python examples/geoguesser_llm_rollout.py --provider anthropic \
+    --mode agentic --episodes 6 --trace-dir rollouts
+python scripts/render_trace.py rollouts/anthropic_agentic
+```
+
+Images are written beside the trace rather than inlined, since six agentic
+episodes carry around 35 views and a JSONL with those in it is neither readable
+nor loadable.
+
+Every step carries an image, including the guess: a guess returns a **reveal
+map** with the guess, the true location and the line between them. Truth is
+drawn only there, after scoring. When the guess is more than 25 degrees out the
+second panel frames the true location instead of both points, because squashing
+a hemisphere into a panel shows nothing.
+
+## Task API
+
+The environment implements the core `TaskProvider` protocol, so the Task API
+routes core already registers become live. Task discovery is metadata only; it
+never starts an episode.
+
+```bash
+curl localhost:8000/geoguesser_env/splits
+# [{"name":"train","type":"train","num_tasks":3452,"default":true},
+#  {"name":"eval","type":"test","num_tasks":200,"default":false}]
+
+curl -X POST localhost:8000/geoguesser_env/num_tasks -d '{"split":"eval"}'
+curl -X POST localhost:8000/geoguesser_env/task      -d '{"split":"eval","index":12}'
+```
+
+```python
+env.list_splits()          # [{"name": "eval", "type": "test", ...}, ...]
+env.num_tasks("eval")      # 200
+env.get_task("eval", 12)   # metadata, no coordinates and no country
+```
+
+**Task specs are deliberately truth-free.** They carry `task_index`, `task_id`,
+`split`, `n_frames`, `provider`, `sequence_id` and `offline_ready` — never
+coordinates and never the country. A spec travels to whatever orchestrates a
+run, and a label sitting in a spec can reach a prompt. The true location is
+revealed in observation metadata after the guess, which is the one place it
+belongs. Per-country eval breakdowns therefore come from finished episodes, not
+from `list_tasks`.
+
+Splits are invisible to the agent. `RESERVED_TOOL_NAMES` blocks a `reset` MCP
+tool, so there is no way for a policy to see or choose its own task — the
+"agents cannot reset" invariant.
+
+## Reproducibility
+
+```python
+env.reset(split="eval", index=7)  # exact task, byte-identical    -> GRPO, eval
+env.reset(split="train", seed=42) # tasks[42 % n_tasks]           -> replay
+env.reset()                       # random task in the default split, split and
+                                  # index both recorded in metadata -> UI
+```
+
+`task_index=` still works as an alias for `index=`, so trajectories recorded
+before splits existed still replay. The split is recorded in observation
+metadata: without it a bare index is ambiguous across three indexes, and a
+trajectory stops being replayable.
+
+Byte-identical repeats hold because panorama bytes come from a local cache
+rather than an expiring CDN URL, reprojection is pure numpy with integer
+sampling, and the initial heading is pinned to each panorama's own
+`compass_angle`.
+
+An eval score is only meaningful alongside its provenance — the env version,
+the task index, and `GEODATA_VERSION` from `server/render/minimap.py`, since
+the bundled vectors determine the reverse-geocode text the agent sees.
+
+## Training and collection
+
+The environment plugs into `openenv.core.harness`, so a rollout function and a
+collector come for free:
+
+```python
+from geoguesser_env import GeoGuesserEnv
+from geoguesser_env.harness import GeoGuesserSessionFactory, load_tasks
+
+tasks = load_tasks("tasks/train_pano_v3.jsonl", repeat=16, split="train")
+factory = GeoGuesserSessionFactory(
+    lambda: GeoGuesserEnv(base_url="http://localhost:8000")
+)
+```
+
+See `examples/geoguesser_rollout.py` for a scripted rollout and
+`examples/geoguesser_collect.py` for JSONL collection with resume.
+
+## Human play
+
+A five-round game, 5,000 points a round on the same curve the environment
+rewards, so a human score is directly comparable to GeoGuessr intuition and to
+the agent's reward (both are shown).
+
+**A round is one episode with one guess.** The five-round game is a UI wrapper
+around five separate episodes; the environment itself never accepts more than
+one guess, because `submit_guess` is terminal.
+
+The page plays through the environment rather than simulating it. It opens the
+same WebSocket session API a client uses, calls `reset(task_index=...)`, and
+sends every pin, look, zoom and move as a real charged step — so the step
+counter, the accumulated cost and the final reward are the environment's own
+numbers, not the browser's. A side panel shows the observation stream an agent
+would receive, including the environment's own rendered map and views.
+
+Note that plain REST `/step` builds a fresh environment per request, so a
+stateful episode has to run over `/ws`; the Python client does this already.
+
+```bash
+uv run --project . server
+# then open http://localhost:8000/geoguesser/play
+```
+
+The page stands alone at `/geoguesser/play` and is also embedded in the Gradio
+playground's **Custom** tab when the web interface is enabled:
+
+```bash
+ENABLE_WEB_INTERFACE=true uv run --project . server   # http://localhost:8000/web/
+```
+
+Pick a split and an episode with the `reset(split=)` and `reset(index=)`
+controls above the game and press
+**load episode**, or **random episode** — the same call an eval harness makes,
+so you can replay exactly the episode an agent saw. Those controls live on the
+Gradio side because choosing a task is orchestration, not something the player
+does mid-round; the page itself reads `?task=` from its URL, so
+`/geoguesser/play?task=42` opens that episode directly.
+
+Drag to look around and scroll to zoom (free, for orientation). The `look()`
+and `zoom(30)` buttons run charged environment steps and show what the agent
+sees. Arrows, or the arrow keys, walk the road — the main view follows, keeping
+your heading. **M** toggles a larger map, **T** the trace panel, **Enter**
+submits and then advances. On submit the map takes the screen and draws the
+line between guess and truth, exactly like the game; the result bar shows
+distance, points, env reward and the true location, and a scoreboard breaks
+down all five rounds at the end.
+
+Panoramas are rendered by Pannellum and the map by MapLibre over OpenFreeMap
+tiles — no API key, no request limits. The imagery credit line names the
+Mapillary contributor, which the CC-BY-SA licence requires.
+
+The page has to be a standalone document rather than a Gradio `gr.HTML`
+fragment: `gr.HTML` inserts markup without executing `<script>` tags, so the
+viewers never initialise and the panel renders blank with no error anywhere.
+
+Extra routes, all local:
+
+| Route | Returns |
+|-------|---------|
+| `/geoguesser/play` | the play page |
+| `/geoguesser/tasks` | `{"n_tasks": N}` |
+| `/geoguesser/task/{i}` | task metadata, including ground truth for the human UI |
+| `/geoguesser/pano/{i}` | the starting equirectangular panorama |
+| `/geoguesser/pano/{i}/{frame}` | one frame's panorama, so the viewer follows `move()` |
+
+The human map uses live tiles; the agent's map stays the offline Natural Earth
+render, so the agent keeps a determinism the browser does not need. Note that
+`/geoguesser/task/{i}` exposes ground truth — it exists for a person playing in
+their own browser, and agent observations still withhold it until the guess.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `GEOGUESSER_TASKS_EVAL` | `tasks/eval_pano_v3.jsonl` | Frozen eval split |
+| `GEOGUESSER_TASKS_TRAIN` | `tasks/train_pano_v3.jsonl` | Training split |
+| `GEOGUESSER_DEFAULT_SPLIT` | `train` | Split `reset()` uses when none is named |
+| `GEOGUESSER_INDEX` | `tasks/pano_v1.jsonl` | Legacy single index, used only when no split resolves |
+| `GEOGUESSER_CACHE` | `data/panos` | Panorama cache directory |
+| `GEOGUESSER_EPISODE_MODE` | `agentic` | `agentic`, `single_shot` or `nmpz` |
+| `GEOGUESSER_MAX_STEPS` | `24` | Actions before the episode is cut off |
+| `GEOGUESSER_REWARD_MODE` | `coords` | `coords` or `country_only` |
+| `GEOGUESSER_HIERARCHICAL` | `0` | Add country and region partial credit |
+| `GEOGUESSER_VIEW_SIZE` | `640` | Edge length of rendered views |
+| `GEOGUESSER_ALLOW_FETCH` | `1` | Whether a cache miss may reach the API |
+| `GEOGUESSER_HIRES_ZOOM` | `1` | Render views at or below 45 deg fov from the original |
+| `GEOGUESSER_STREET_DETAIL` | `1` | Fetch real OSM streets below 0.35 deg. Governs Overpass only, independent of `ALLOW_FETCH`, and caches to local disk |
+| `GEOGUESSER_REVEAL_MAP` | `1` | Draw the guess-versus-truth map; `0` is 3x faster for training |
+| `MAPILLARY_API_KEY` | — | Needed by the builder, and only on a cache miss |
+
+## Data
+
+Three splits, carved from one 3,673-task pool so contamination is enforced
+exactly once, at split time, rather than reasoned about across two harvests:
+
+| Split | Type | Tasks | Countries | Offline |
+|---|---|---|---|---|
+| `eval` | `test` | 200 | 73, capped at 4 each | all 24 frames mirrored |
+| `train` | `train` | 3,452 | 132 | all 24 frames mirrored |
+| `random` | `validation` | 1.2M pool rows | global | no, fetches on demand |
+
+Separation follows the OSV-5M rule: no shared `sequence_id`, and no training
+task within 1 km of an eval task. Frames sit ~3.3 m apart, so holding out an
+image while keeping its neighbour holds out nothing. The split script verifies
+its own work and exits non-zero if either rule is violated — the committed
+split reports 0 shared sequences and a closest train task 1.07 km away.
+
+| | |
+|---|---|
+| Frames per task | 23.2 mean (8 min, 24 max), ~3.3 m apart |
+| Eval index | 1.2 MB, committed |
+| Train index | 20 MB, in the Storage Bucket |
+| Imagery | 22 GB for 86k frames, 0.26 MB mean per frame |
+
+`eval` is committed because a frozen benchmark belongs in version control,
+where a change to it shows up in review. The training index and the imagery
+live in a Storage Bucket, mounted read-only at `/data` on a Space.
+
+The `random` split is **not yet implemented** — the plumbing takes arbitrary
+named splits, but the pool-backed sampler is still to come.
+
+Each index is self-contained: every frame's coordinates, heading and capture
+date live in the JSONL, so the movement graph resolves offline.
+Only image bytes are fetched, and only on a cache miss, because Mapillary
+`thumb_*_url` values are expiring signed URLs that cannot be stored.
+
+Coverage is uneven and worth knowing about. Probing 45 Street-View
+coordinates found any Mapillary imagery at 21 and a 360-degree panorama at
+only 7, heavily clustered. Panorama-first discovery is therefore the only
+approach that works — roughly 5% of probe points yield a usable sequence, so
+reaching 100 tasks took two passes with different seeds, merged by
+`scripts/merge_task_indexes.py`. Africa and Oceania are thin because 360-degree
+contributors are; that is a property of the source, documented rather than
+papered over.
+
+## Known gaps versus the real game
+
+Movement follows captured sequences and stops where one ends. There is no
+multi-round cumulative score, no wall-clock timer (a step budget stands in for
+it), and no satellite layer on the guess map. Coverage hints and web search are
+deliberately excluded: the first is a crutch, the second turns the task into
+retrieval.
+
+See [DESIGN.md](DESIGN.md) for the reasoning behind these choices.

geoguesser_env/__init__.py

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""GeoGuesser: a GeoGuessr-style visual geolocation environment.
+
+Independent open-source project, unaffiliated with GeoGuessr AB. Imagery comes
+from Mapillary contributors under CC-BY-SA-4.0.
+"""
+
+from .client import GeoGuesserEnv
+from .models import (
+    EpisodeMode,
+    from_wire,
+    GeoGuesserAction,
+    GeoGuesserObservation,
+    GeoGuesserState,
+    GuessAction,
+    LookAction,
+    MeasureAction,
+    MoveAction,
+    PanAction,
+    Pin,
+    PinAction,
+    RewardMode,
+    to_wire,
+    TypedAction,
+    ViewMapAction,
+    ZoomAction,
+)
+
+__all__ = [
+    "EpisodeMode",
+    "GeoGuesserAction",
+    "GeoGuesserEnv",
+    "GeoGuesserObservation",
+    "GeoGuesserState",
+    "GuessAction",
+    "LookAction",
+    "MeasureAction",
+    "MoveAction",
+    "PanAction",
+    "Pin",
+    "PinAction",
+    "RewardMode",
+    "TypedAction",
+    "ViewMapAction",
+    "ZoomAction",
+    "from_wire",
+    "to_wire",
+]

geoguesser_env/client.py

@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""HTTP client for the GeoGuesser environment."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from openenv.core.client_types import StepResult
+from openenv.core.env_client import EnvClient
+
+from .models import (
+    GeoGuesserAction,
+    GeoGuesserObservation,
+    GeoGuesserState,
+    to_wire,
+    TypedAction,
+)
+
+
+ENV_NAME = "geoguesser_env"
+"""Task API routes are namespaced by the `env_name` the server registers."""
+
+
+class GeoGuesserEnv(
+    EnvClient[GeoGuesserAction, GeoGuesserObservation, GeoGuesserState]
+):
+    """
+    Client for a running GeoGuesser environment server.
+
+    Examples:
+
+    ```python
+    env = GeoGuesserEnv(base_url="http://localhost:8000")
+    result = env.reset(task_index=0)
+    result = env.step(LookAction(heading_deg=90))
+    result = env.step(GuessAction(response("<guess>55.67, 12.57</guess>")))
+    print(result.reward, result.observation.distance_km)
+    ```
+    """
+
+    def _step_payload(self, action: GeoGuesserAction | TypedAction) -> Dict[str, Any]:
+        """
+        Serialise an action for the `/step` endpoint.
+
+        Typed actions are flattened to the single wire schema the server
+        declares; a wire action passes through unchanged.
+        """
+        wire = action if isinstance(action, GeoGuesserAction) else to_wire(action)
+        return wire.model_dump(exclude_none=True)
+
+    def _parse_result(self, response: Dict[str, Any]) -> StepResult:
+        """Build a [`StepResult`] from a `/step` or `/reset` response."""
+        observation = GeoGuesserObservation(**response["observation"])
+        return StepResult(
+            observation=observation,
+            reward=response.get("reward"),
+            done=response.get("done", False),
+        )
+
+    def _parse_state(self, response: Dict[str, Any]) -> GeoGuesserState:
+        """Build a [`GeoGuesserState`] from a `/state` response."""
+        return GeoGuesserState(**response)
+
+    def reset(
+        self,
+        task_index: int | None = None,
+        split: str | None = None,
+        index: int | None = None,
+        **kwargs: Any,
+    ) -> StepResult:
+        """
+        Start an episode.
+
+        Args:
+            task_index (`int`, *optional*):
+                Deprecated alias for `index`, kept so existing callers and
+                recorded trajectories keep working.
+            split (`str`, *optional*):
+                Which split to draw from, as named by [`list_splits`]. Defaults
+                to the server's default split.
+            index (`int`, *optional*):
+                Exact task to play within `split`. Repeated calls with the same
+                split and index yield byte-identical observations, which is what
+                a GRPO group needs. Omit it, and `seed`, for a random task.
+
+        Returns:
+            [`StepResult`]: The opening observation.
+        """
+        if index is None:
+            index = task_index
+        if split is not None:
+            kwargs["split"] = split
+        if index is not None:
+            kwargs["index"] = index
+        return super().reset(**kwargs)
+
+    def list_splits(self) -> list[dict[str, Any]]:
+        """
+        Which splits the server offers, and how many tasks each holds.
+
+        Core exposes the Task API over HTTP but ships no client for it, so this
+        posts to the routes directly.
+
+        Returns:
+            `list[dict]`: Split descriptors with `name`, `type`, `num_tasks` and
+                `default`.
+        """
+        return self._task_api("splits", method="GET")
+
+    def num_tasks(self, split: str) -> int:
+        """How many tasks a split holds."""
+        return int(self._task_api("num_tasks", {"split": split})["num_tasks"])
+
+    def get_task(self, split: str, index: int) -> dict[str, Any]:
+        """
+        Describe one task without starting an episode.
+
+        The spec carries no coordinates and no country: it is metadata for
+        whatever orchestrates a run, not a label source.
+        """
+        return self._task_api("task", {"split": split, "index": index})["task"]
+
+    def _task_api(
+        self,
+        route: str,
+        payload: dict[str, Any] | None = None,
+        method: str = "POST",
+    ) -> Any:
+        """Call one core Task API route on this environment."""
+        import json
+        import urllib.request
+
+        url = f"{self.base_url.rstrip('/')}/{ENV_NAME}/{route}"
+        data = None if payload is None else json.dumps(payload).encode()
+        request = urllib.request.Request(
+            url,
+            data=data,
+            method=method,
+            headers={"Content-Type": "application/json"},
+        )
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return json.loads(response.read())

geoguesser_env/data/geo/detail/roads.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:96896a1362cb5e831e95361e297970e0ef4d83eea5624ed0b2a955d9619eed29
+size 14390450

geoguesser_env/data/geo/detail/urban.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4ab8f88d498865f719eebb948ce6ffb213b8bcdf29a9a2d48394c707d607cf59
+size 21183581

geoguesser_env/examples/geoguesser_collect.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Collect rollouts into a JSONL dataset via `openenv.core.harness`.
+
+Shows the task API doing the work: tasks come from the frozen index, so each
+episode records which location produced it and a run can resume without losing
+task-to-episode alignment.
+
+    PYTHONPATH=src:envs uv run python \\
+        envs/geoguesser_env/examples/geoguesser_collect.py --episodes 8
+
+Point `--base-url` at a running server. The scripted policy here looks around
+once, pins a guess and submits; swap `model_step` for an LLM to collect real
+trajectories.
+"""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+from typing import Any
+
+from openenv.core.harness import HarnessRunLimits, MCPHarnessAdapter, ModelStepResult
+from openenv.core.harness.collect import CollectRunner, RolloutSerializer
+from openenv.core.llm_client import LLMResponse, ToolCall
+
+from geoguesser_env.client import GeoGuesserEnv
+from geoguesser_env.harness import GeoGuesserSessionFactory, load_tasks
+
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+
+def build_scripted_model_step():
+    """A deterministic stand-in policy: look, pin, guess.
+
+    A `ModelStepResult` wraps an `LLMResponse` carrying `ToolCall`s — the same
+    shape a real model's reply is normalised into — so swapping this for an
+    actual LLM changes only how the response is produced.
+    """
+    turns = {"n": 0}
+
+    def model_step(messages: Any, tools: Any, sampling: Any) -> Any:
+        del messages, sampling
+        step = turns["n"]
+        turns["n"] += 1
+        available = {tool.name for tool in (tools or [])}
+
+        if step == 0 and "look" in available:
+            name, args = "look", {"heading_deg": 90.0}
+            note = "Looking east."
+        elif step <= 1 and "place_pin" in available:
+            name, args = "place_pin", {"lat": 48.85, "lon": 2.29}
+            note = "Checking a candidate near Paris."
+        else:
+            name, args = (
+                "submit_guess",
+                {
+                    "lat": 48.8584,
+                    "lon": 2.2945,
+                    "confidence": 0.4,
+                },
+            )
+            note = "Committing."
+
+        return ModelStepResult(
+            response=LLMResponse(
+                content=note,
+                tool_calls=[ToolCall(id=f"scripted-{step}", name=name, args=args)],
+            )
+        )
+
+    return model_step
+
+
+def main() -> None:
+    """Run the collector."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--base-url", default="http://localhost:8000")
+    parser.add_argument("--episodes", type=int, default=8)
+    parser.add_argument(
+        "--repeat",
+        type=int,
+        default=1,
+        help="Episodes per task; use 16 for a GRPO group.",
+    )
+    parser.add_argument(
+        "--index", type=pathlib.Path, default=ROOT / "tasks" / "pano_v1.jsonl"
+    )
+    parser.add_argument(
+        "--output-dir", type=pathlib.Path, default=pathlib.Path("rollouts/geoguesser")
+    )
+    args = parser.parse_args()
+
+    tasks = load_tasks(args.index, repeat=args.repeat)
+    print(f"{len(tasks)} task slots from {args.index}")
+
+    runner = CollectRunner(
+        session_factory=GeoGuesserSessionFactory(
+            lambda: GeoGuesserEnv(base_url=args.base_url)
+        ),
+        harness_adapter=MCPHarnessAdapter(),
+        serializer=RolloutSerializer(args.output_dir),
+        tasks=tasks,
+        limits=HarnessRunLimits(max_turns=6),
+    )
+    result = runner.run(
+        model_step=build_scripted_model_step(),
+        num_episodes=args.episodes,
+        episode_id_prefix="gg",
+    )
+    print(
+        f"collected={result.num_collected} skipped={result.num_skipped} "
+        f"failed={result.num_failed} avg_reward={result.avg_reward:.3f}"
+    )
+    print(f"dataset: {args.output_dir}")
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/examples/geoguesser_llm_rollout.py

@@ -0,0 +1,658 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Run real rollouts against a vision model and report the rewards.
+
+Two providers, one action protocol, so the same episode can be compared across
+models:
+
+- `anthropic` talks to the Messages API directly.
+- `hf` talks to any OpenAI-compatible endpoint, defaulting to the Hugging Face
+  router, which serves open models such as Qwen.
+
+Two modes:
+
+- `single_shot` is one view, one guess. This is the shape a GRPO run wants and
+  the cheapest way to compare models.
+- `agentic` gives the model the tool surface and lets it look around, walk,
+  and pin candidates before committing, one JSON action per turn.
+
+Usage:
+    export ANTHROPIC_API_KEY=... HF_TOKEN=...
+
+    python examples/geoguesser_llm_rollout.py \\
+        --provider anthropic --model claude-sonnet-5 --episodes 5
+
+    python examples/geoguesser_llm_rollout.py \\
+        --provider hf --model "Qwen/Qwen3.5-9B:together" --episodes 5
+
+    python examples/geoguesser_llm_rollout.py \\
+        --provider anthropic --mode agentic --episodes 3 --max-turns 8
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import concurrent.futures
+import json
+import os
+import pathlib
+import re
+import statistics
+import sys
+import threading
+import time
+from typing import Any
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
+
+from geoguesser_env.models import (  # noqa: E402
+    GuessAction,
+    LookAction,
+    MoveAction,
+    PinAction,
+    to_wire,
+    ViewMapAction,
+    ZoomAction,
+)
+from geoguesser_env.server.geoguesser_environment import (  # noqa: E402
+    GeoGuesserEnvironment,
+)
+
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+SINGLE_SHOT_PROMPT = """You are playing a geolocation game. This is a street-level
+photograph taken somewhere in the world. Work out where it was taken.
+
+Reason briefly about the evidence: language and script on signage, which side of
+the road traffic drives on, vegetation and climate, road markings, architecture,
+utility poles, vehicle number plates, terrain.
+
+Then give your answer as coordinates on the last line, exactly like this:
+<guess>LATITUDE, LONGITUDE</guess>"""
+
+AGENTIC_PROMPT = """You are playing a geolocation game. You have been dropped at
+an unknown street-level location and must work out where you are.
+
+Reply with exactly one JSON object per turn, and nothing else:
+
+  {{"action": "look", "heading_deg": 90, "fov_deg": 90}}   look in a direction
+  {{"action": "zoom", "fov_deg": 30}}                      zoom to read signage
+  {{"action": "move", "direction": "forward", "meters": 20}} walk along the road
+  {{"action": "pin", "lat": 12.34, "lon": 56.78, "span_deg": 2}} check a candidate;
+      span_deg is the map zoom, and below about 4 you get roads and town names
+  {{"action": "guess", "lat": 12.34, "lon": 56.78}}        commit, ends the episode
+
+Looking, zooming and pinning each cost a little reward, so gather what you need
+and then commit.
+
+Pinning is worth using before you guess: it tells you what is actually at a
+coordinate — the country, the nearest city, and how far your candidate is from
+your previous one — which catches a coordinate that lands in the sea or in the
+wrong country. It does not tell you whether you are right.
+
+You have {max_turns} turns. Available tools: {tools}
+
+Output rules, which matter more than they look:
+- Reply with the JSON object and nothing else. No explanation, no markdown, no
+  code fence, no commentary before or after.
+- One action per turn. An action that does not parse wastes the turn.
+- Coordinates are decimal degrees, negative for south and west."""
+
+
+# ---------------------------------------------------------------- providers
+
+
+def media_type(image_b64: str) -> str:
+    """
+    Detect an encoded image's media type from its own bytes.
+
+    Views come back as JPEG and maps as PNG, so a hardcoded type is wrong half
+    the time — and Anthropic rejects a mislabelled image outright rather than
+    sniffing it.
+
+    Args:
+        image_b64 (`str`):
+            Base64-encoded image.
+
+    Returns:
+        `str`: Either `"image/png"` or `"image/jpeg"`.
+    """
+    try:
+        head = base64.b64decode(image_b64[:24], validate=False)
+    except Exception:  # noqa: BLE001 - fall back rather than fail a rollout
+        return "image/jpeg"
+    return "image/png" if head.startswith(b"\x89PNG") else "image/jpeg"
+
+
+class AnthropicChat:
+    """Thin wrapper over the Anthropic Messages API."""
+
+    def __init__(self, model: str, max_tokens: int = 1024):
+        from anthropic import Anthropic
+
+        self._client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
+        self._model = model
+        self._max_tokens = max_tokens
+
+    @property
+    def name(self) -> str:
+        return f"anthropic/{self._model}"
+
+    def __call__(self, prompt: str, images: list[str]) -> str:
+        content: list[dict[str, Any]] = []
+        for image in images:
+            content.append(
+                {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": media_type(image),
+                        "data": image,
+                    },
+                }
+            )
+        content.append({"type": "text", "text": prompt})
+        message = self._client.messages.create(
+            model=self._model,
+            max_tokens=self._max_tokens,
+            messages=[{"role": "user", "content": content}],
+        )
+        return "".join(
+            block.text
+            for block in message.content
+            if getattr(block, "type", "") == "text"
+        )
+
+
+class OpenAICompatChat:
+    """Thin wrapper over any OpenAI-compatible chat endpoint."""
+
+    def __init__(
+        self,
+        model: str,
+        base_url: str = "https://router.huggingface.co/v1",
+        api_key_env: str = "HF_TOKEN",
+        max_tokens: int = 1024,
+    ):
+        from openai import OpenAI
+
+        self._client = OpenAI(base_url=base_url, api_key=os.environ[api_key_env])
+        self._model = model
+        self._max_tokens = max_tokens
+        self._base_url = base_url
+        self.last_finish_reason = None
+
+    @property
+    def name(self) -> str:
+        return f"{self._base_url.split('//')[-1].split('/')[0]}/{self._model}"
+
+    def __call__(self, prompt: str, images: list[str]) -> str:
+        content: list[dict[str, Any]] = [{"type": "text", "text": prompt}]
+        for image in images:
+            content.append(
+                {
+                    "type": "image_url",
+                    "image_url": {"url": f"data:{media_type(image)};base64,{image}"},
+                }
+            )
+        completion = self._client.chat.completions.create(
+            model=self._model,
+            max_tokens=self._max_tokens,
+            messages=[{"role": "user", "content": content}],
+        )
+        choice = completion.choices[0]
+        text = choice.message.content or ""
+        # Reasoning models put their chain of thought in a separate field and
+        # can exhaust the token budget before emitting any content at all, so a
+        # short max_tokens looks exactly like a model that cannot see images.
+        # Fall back to the reasoning text, which usually still carries the
+        # answer, and say so when the budget was the limit.
+        if not text.strip():
+            reasoning = getattr(choice.message, "reasoning_content", None) or getattr(
+                choice.message, "reasoning", None
+            )
+            if reasoning:
+                text = str(reasoning)
+            elif choice.finish_reason == "length":
+                text = ""
+        self.last_finish_reason = choice.finish_reason
+        return text
+
+
+def build_chat(args: argparse.Namespace):
+    """Construct the provider named on the command line."""
+    if args.provider == "anthropic":
+        return AnthropicChat(args.model, max_tokens=args.max_tokens)
+    return OpenAICompatChat(
+        args.model,
+        base_url=args.base_url,
+        api_key_env=args.api_key_env,
+        max_tokens=args.max_tokens,
+    )
+
+
+# ------------------------------------------------------------------ rollouts
+
+
+_JSON_OBJECT = re.compile(r"\{[^{}]*\}", re.DOTALL)
+
+
+def parse_action(reply: str) -> dict[str, Any] | None:
+    """
+    Pull the intended JSON action out of a model reply.
+
+    A fenced block wins, since a model that formats its answer means it. Failing
+    that, the *last* action object in the text is taken rather than the first:
+    when the reply is a reasoning trace, earlier objects are usually drafts the
+    model then argued itself out of, and the decision comes last.
+
+    Args:
+        reply (`str`):
+            The raw model reply, possibly a chain of thought.
+
+    Returns:
+        `dict` or `None`: The action object, or `None` when none is present.
+    """
+    fenced = re.findall(r"```(?:json)?\s*(\{.*?\})\s*```", reply, re.DOTALL)
+    for candidate in reversed(fenced):
+        try:
+            parsed = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict) and "action" in parsed:
+            return parsed
+
+    for candidate in reversed(_JSON_OBJECT.findall(reply)):
+        try:
+            parsed = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict) and "action" in parsed:
+            return parsed
+    return None
+
+
+def to_env_action(spec: dict[str, Any]):
+    """Translate a model action into a typed environment action."""
+    kind = str(spec.get("action", "")).lower()
+    if kind == "look":
+        return LookAction(
+            heading_deg=float(spec.get("heading_deg", 0.0)),
+            pitch_deg=float(spec.get("pitch_deg", 0.0)),
+            fov_deg=float(spec.get("fov_deg", 90.0)),
+        )
+    if kind == "zoom":
+        return ZoomAction(fov_deg=float(spec.get("fov_deg", 30.0)))
+    if kind == "move":
+        return MoveAction(
+            direction=str(spec.get("direction", "forward")),
+            meters=float(spec.get("meters", 20.0)),
+        )
+    if kind == "pin":
+        return PinAction(
+            lat=float(spec["lat"]),
+            lon=float(spec["lon"]),
+            span_deg=float(spec.get("span_deg", 7.0)),
+        )
+    if kind == "view_map":
+        return ViewMapAction(
+            lat=float(spec["lat"]),
+            lon=float(spec["lon"]),
+            span_deg=float(spec.get("span_deg", 7.0)),
+        )
+    if kind == "guess":
+        return GuessAction(
+            lat=float(spec["lat"]),
+            lon=float(spec["lon"]),
+            confidence=spec.get("confidence"),
+            reasoning=spec.get("reasoning"),
+        )
+    raise ValueError(f"unknown action: {kind!r}")
+
+
+def _turn_record(
+    index: int,
+    action: Any,
+    reply: str,
+    observation: Any,
+) -> dict[str, Any]:
+    """One row of a trace: what the model saw, said, did and got back."""
+    return {
+        "turn": index,
+        "reply": reply.strip(),
+        "action": action,
+        "feedback": getattr(observation, "feedback", ""),
+        "heading_deg": getattr(observation, "heading_deg", None),
+        "fov_deg": getattr(observation, "fov_deg", None),
+        "steps_remaining": getattr(observation, "steps_remaining", None),
+        "action_cost": getattr(observation, "action_cost", None),
+        "image_kind": getattr(observation, "image_kind", "none"),
+        "image_base64": getattr(observation, "image_base64", None),
+        "reward": getattr(observation, "reward", None),
+        "distance_km": getattr(observation, "distance_km", None),
+    }
+
+
+def run_single_shot(env, chat, task_index: int, verbose: bool) -> dict[str, Any]:
+    """One view, one guess."""
+    observation = env.reset(task_index=task_index)
+    opening = _turn_record(0, {"action": "reset"}, "", observation)
+    started = time.time()
+    reply = chat(SINGLE_SHOT_PROMPT, [observation.image_base64])
+    latency = time.time() - started
+    result = env.step(to_wire(GuessAction(response=reply)))
+    trace = [opening, _turn_record(1, {"action": "guess"}, reply, result)]
+    return {
+        "trace": trace,
+        "task_index": task_index,
+        "country": env._task.country,
+        "reward": result.reward or 0.0,
+        "distance_km": result.distance_km,
+        "parsed_ok": result.parsed_ok,
+        "latency_s": latency,
+        "turns": 1,
+        "reply": reply.strip(),
+    }
+
+
+def run_agentic(
+    env, chat, task_index: int, max_turns: int, verbose: bool
+) -> dict[str, Any]:
+    """Let the model look around and pin before committing."""
+    observation = env.reset(task_index=task_index)
+    trace: list[dict[str, Any]] = [
+        _turn_record(0, {"action": "reset"}, "", observation)
+    ]
+    transcript: list[str] = []
+    started = time.time()
+    turns = 0
+
+    for turn in range(max_turns):
+        turns = turn + 1
+        prompt = AGENTIC_PROMPT.format(
+            max_turns=max_turns - turn,
+            tools=", ".join(observation.available_tools),
+        )
+        if transcript:
+            prompt += "\n\nWhat has happened so far:\n" + "\n".join(transcript[-8:])
+        prompt += (
+            f"\n\nYou are facing {observation.heading_deg:.0f} degrees with a "
+            f"{observation.fov_deg:.0f} degree field of view. "
+            f"{observation.steps_remaining} actions remain."
+        )
+        turns_left = max_turns - turn
+        if turns_left <= 2:
+            # Exploring until the budget runs out scores zero, which is a
+            # prompting failure rather than a capability one. Open models
+            # routinely need to be told the deadline is now.
+            prompt += (
+                f"\n\nWARNING: only {turns_left} turn(s) left. You must reply "
+                'with {"action": "guess", "lat": ..., "lon": ...} now, or you '
+                "score zero. Give your best estimate even if you are unsure."
+            )
+
+        images = [observation.image_base64] if observation.image_base64 else []
+        reply = chat(prompt, images)
+        spec = parse_action(reply)
+        if spec is None:
+            transcript.append(f"turn {turns}: reply was not a JSON action, ignored")
+            if verbose:
+                print(
+                    f"    turn {turns}: unparseable -> {reply.strip()[:90]!r}",
+                    flush=True,
+                )
+            continue
+
+        try:
+            action = to_env_action(spec)
+        except (KeyError, ValueError, TypeError) as exc:
+            transcript.append(f"turn {turns}: invalid action {spec} ({exc})")
+            if verbose:
+                print(
+                    f"    turn {turns}: invalid   {spec} ({exc})",
+                    flush=True,
+                )
+            continue
+
+        result = env.step(to_wire(action))
+        observation = result
+        trace.append(_turn_record(turns, spec, reply, result))
+        transcript.append(f"turn {turns}: {spec} -> {result.feedback}")
+        if verbose:
+            print(
+                f"    turn {turns}: {spec.get('action'):9s} {result.feedback[:88]}",
+                flush=True,
+            )
+        if result.done:
+            return {
+                "trace": trace,
+                "task_index": task_index,
+                "country": env._task.country,
+                "reward": result.reward or 0.0,
+                "distance_km": result.distance_km,
+                "parsed_ok": result.parsed_ok,
+                "latency_s": time.time() - started,
+                "turns": turns,
+                "action_cost": result.action_cost,
+                "reply": reply.strip(),
+            }
+
+    # Out of turns without a guess: score it, because a policy that never
+    # commits should not be rewarded with a missing sample.
+    result = env.step(to_wire(GuessAction(response="")))
+    trace.append(_turn_record(turns + 1, {"action": "forced guess"}, "", result))
+    return {
+        "trace": trace,
+        "task_index": task_index,
+        "country": env._task.country,
+        "reward": result.reward or 0.0,
+        "distance_km": result.distance_km,
+        "parsed_ok": False,
+        "latency_s": time.time() - started,
+        "turns": turns,
+        "action_cost": result.action_cost,
+        "reply": "never committed to a guess",
+    }
+
+
+class Worker:
+    """One environment and one chat client, owned by a single thread.
+
+    An episode is stateful, so concurrent rollouts cannot share an environment
+    instance — they would interleave resets and steps into one episode. Each
+    worker therefore builds its own environment over the same read-only task
+    index and panorama cache, which is how a distributed rollout is arranged
+    too.
+    """
+
+    def __init__(self, args: argparse.Namespace):
+        self.env = GeoGuesserEnvironment(
+            index_path=str(args.index),
+            cache_dir=str(args.cache),
+            episode_mode="agentic" if args.mode == "agentic" else "single_shot",
+            max_steps=args.max_turns,
+        )
+        self.chat = build_chat(args)
+
+
+def run_episodes(args: argparse.Namespace, tasks: list[int]) -> list[dict[str, Any]]:
+    """
+    Run every task, optionally several at a time.
+
+    Args:
+        args (`argparse.Namespace`):
+            Parsed command line.
+        tasks (`list[int]`):
+            Task indices to play, one episode each.
+
+    Returns:
+        `list[dict]`: One record per episode, in task order.
+    """
+    local = threading.local()
+    lock = threading.Lock()
+    finished = {"n": 0}
+
+    def worker() -> Worker:
+        if not hasattr(local, "worker"):
+            local.worker = Worker(args)
+        return local.worker
+
+    def play(task_index: int) -> dict[str, Any]:
+        own = worker()
+        if args.mode == "single_shot":
+            record = run_single_shot(own.env, own.chat, task_index, args.verbose)
+        else:
+            record = run_agentic(
+                own.env, own.chat, task_index, args.max_turns, args.verbose
+            )
+        with lock:
+            finished["n"] += 1
+            distance = record["distance_km"]
+            shown = "unparsed" if not record["parsed_ok"] else f"{distance:8.0f} km"
+            print(
+                f"[{finished['n']:>3}/{len(tasks)}] task {record['task_index']:3d}  "
+                f"{record['country'][:20]:20s} reward {record['reward']:.3f}  "
+                f"{shown}  {record['turns']} turn(s)  {record['latency_s']:5.1f}s",
+                flush=True,
+            )
+        return record
+
+    if args.concurrency <= 1:
+        return [play(task_index) for task_index in tasks]
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=args.concurrency) as pool:
+        return list(pool.map(play, tasks))
+
+
+def main() -> None:
+    """Run the rollouts and print a summary."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--provider", choices=["anthropic", "hf"], default="anthropic")
+    parser.add_argument("--model", default="claude-sonnet-5")
+    parser.add_argument("--base-url", default="https://router.huggingface.co/v1")
+    parser.add_argument("--api-key-env", default="HF_TOKEN")
+    parser.add_argument(
+        "--mode", choices=["single_shot", "agentic"], default="single_shot"
+    )
+    parser.add_argument("--episodes", type=int, default=5)
+    parser.add_argument("--start-task", type=int, default=0)
+    parser.add_argument("--stride", type=int, default=7)
+    parser.add_argument("--max-turns", type=int, default=8)
+    parser.add_argument(
+        "--max-tokens",
+        type=int,
+        default=3000,
+        help="Reasoning models need several thousand; 1024 truncates them mid-thought.",
+    )
+    parser.add_argument(
+        "--index", type=pathlib.Path, default=ROOT / "tasks" / "pano_v1.jsonl"
+    )
+    parser.add_argument("--cache", type=pathlib.Path, default=ROOT / "data" / "panos")
+    parser.add_argument(
+        "--concurrency",
+        type=int,
+        default=1,
+        help="Episodes to run at once; each gets its own environment.",
+    )
+    parser.add_argument(
+        "--trace-dir",
+        type=pathlib.Path,
+        default=pathlib.Path("rollouts"),
+        help="Where to write per-turn traces and their images.",
+    )
+    parser.add_argument("--verbose", action="store_true")
+    args = parser.parse_args()
+
+    probe = GeoGuesserEnvironment(
+        index_path=str(args.index), cache_dir=str(args.cache), allow_fetch=False
+    )
+    n_tasks = probe._backend.n_tasks
+    tasks = [
+        (args.start_task + i * args.stride) % n_tasks for i in range(args.episodes)
+    ]
+
+    print(
+        f"{args.provider}/{args.model}  mode={args.mode}  "
+        f"episodes={len(tasks)}  concurrency={args.concurrency}  "
+        f"tasks={tasks}",
+        flush=True,
+    )
+    print("-" * 88, flush=True)
+
+    wall_start = time.time()
+    records = run_episodes(args, tasks)
+    wall = time.time() - wall_start
+    rewards = [r["reward"] for r in records]
+    distances = [r["distance_km"] for r in records if r["distance_km"] is not None]
+    parsed = sum(1 for r in records if r["parsed_ok"])
+    print("-" * 88)
+    print(f"mean reward     {statistics.mean(rewards):.3f}")
+    if len(rewards) > 1:
+        print(f"stdev reward    {statistics.stdev(rewards):.3f}")
+    if distances:
+        print(f"median distance {statistics.median(distances):.0f} km")
+        print(
+            f"within 200 km   {sum(1 for d in distances if d < 200)}/{len(distances)}"
+        )
+        print(
+            f"within 1000 km  {sum(1 for d in distances if d < 1000)}/{len(distances)}"
+        )
+    print(f"parsed          {parsed}/{len(records)}")
+    latencies = [r["latency_s"] for r in records]
+    print(f"wall clock      {wall:.1f}s for {len(records)} episodes")
+    print(f"sum of latency  {sum(latencies):.1f}s")
+    if args.concurrency > 1:
+        print(f"speedup         {sum(latencies) / max(wall, 1e-9):.2f}x")
+
+    slug = f"{args.provider}_{args.mode}"
+    out_dir = pathlib.Path(args.trace_dir) / slug
+    images_dir = out_dir / "images"
+    images_dir.mkdir(parents=True, exist_ok=True)
+
+    # Images live beside the trace rather than inside it: a six-episode agentic
+    # run carries about 30 views, and inlining them makes the JSONL unreadable
+    # and unloadable.
+    manifest = []
+    for record in records:
+        trace = record.pop("trace", [])
+        rows = []
+        for row in trace:
+            payload = row.pop("image_base64", None)
+            if payload:
+                name = f"t{record['task_index']:03d}_turn{row['turn']:02d}.jpg"
+                suffix = ".png" if row.get("image_kind") == "map" else ".jpg"
+                name = name.replace(".jpg", suffix)
+                (images_dir / name).write_bytes(base64.b64decode(payload))
+                row["image"] = f"images/{name}"
+            rows.append(row)
+        record["trace"] = rows
+        manifest.append(record)
+
+    out = out_dir / "trace.jsonl"
+    with out.open("w") as handle:
+        for record in manifest:
+            handle.write(json.dumps(record) + "\n")
+    summary = {
+        "provider": args.provider,
+        "model": args.model,
+        "mode": args.mode,
+        "episodes": len(manifest),
+        "concurrency": args.concurrency,
+        "max_turns": args.max_turns,
+        "mean_reward": statistics.mean(rewards),
+        "median_distance_km": statistics.median(distances) if distances else None,
+        "within_200km": sum(1 for d in distances if d < 200),
+        "within_1000km": sum(1 for d in distances if d < 1000),
+        "parsed": parsed,
+        "wall_clock_s": wall,
+        "sum_latency_s": sum(latencies),
+    }
+    (out_dir / "summary.json").write_text(json.dumps(summary, indent=2))
+    print(f"trace -> {out}  ({len(list(images_dir.iterdir()))} images)")
+    print(f"render it with: python scripts/render_trace.py {out_dir}")
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/examples/geoguesser_rollout.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""A scripted rollout, end to end, with no model in the loop.
+
+Runs in process against the committed fixtures, so it needs no server and no
+network:
+
+    PYTHONPATH=src:envs uv run python \\
+        envs/geoguesser_env/examples/geoguesser_rollout.py
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from geoguesser_env.models import (
+    GuessAction,
+    LookAction,
+    MeasureAction,
+    MoveAction,
+    PinAction,
+    to_wire,
+)
+from geoguesser_env.server.geoguesser_environment import GeoGuesserEnvironment
+
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+FIXTURES = ROOT / "tests" / "fixtures"
+
+
+def main() -> None:
+    """Play one episode with a fixed script and print the trace."""
+    env = GeoGuesserEnvironment(
+        index_path=str(FIXTURES / "pano_v1.jsonl"),
+        cache_dir=str(FIXTURES / "panos"),
+        allow_fetch=False,
+    )
+
+    observation = env.reset(index=0)
+    print(
+        f"task {observation.metadata['task_index']} "
+        f"({observation.metadata['task_id']}), "
+        f"captured {observation.captured_at}"
+    )
+    print(f"tools: {', '.join(observation.available_tools)}\n")
+
+    script = [
+        LookAction(heading_deg=0),
+        LookAction(heading_deg=90),
+        LookAction(heading_deg=180, fov_deg=30),
+        MoveAction(direction="forward", meters=20),
+        PinAction(lat=39.7, lon=-104.9, label="Colorado?"),
+        MeasureAction(lat_a=39.7, lon_a=-104.9, lat_b=38.9, lon_b=-104.8),
+        PinAction(lat=38.87, lon=-104.79, label="Colorado Springs?"),
+    ]
+    for action in script:
+        observation = env.step(to_wire(action))
+        image = len(observation.image_base64 or "")
+        print(
+            f"{type(action).__name__:14s} [{observation.image_kind:4s} "
+            f"{image:>7d}B] {observation.feedback[:96]}"
+        )
+
+    result = env.step(
+        to_wire(
+            GuessAction(
+                response=(
+                    "Wide roads, US plates, front range foothills.\n"
+                    "<guess>38.87, -104.79</guess>"
+                ),
+                confidence=0.6,
+            )
+        )
+    )
+    print(f"\n{result.feedback}")
+    print(
+        f"reward {result.reward:.3f}  "
+        f"score {result.score:.3f}  "
+        f"cost {result.action_cost:.2f}  "
+        f"distance {result.distance_km:.1f} km"
+    )
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/harness.py

@@ -0,0 +1,440 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Harness-oriented GeoGuesser session adapters.
+
+Follows the pattern in `reasoning_gym_env.harness`: expose a `GeoGuesserEnv`
+client as a `ResourceSession` driven through MCP-style tools, so it plugs into
+`openenv.core.harness` unchanged.
+
+That single adapter is what makes the rest work without extra code:
+
+- `CollectRunner(tasks=...)` walks a task list into a JSONL rollout dataset,
+  with resume, recording which task produced each episode.
+- `build_harness_rollout_func(...)` yields a TRL-compatible rollout function
+  where each prompt *is* a task — the GRPO path.
+- `EvalConfig` / `EvalResult` carry the provenance an eval score needs.
+
+A task is a plain dict, so it survives serialisation into an `EpisodeRecord`:
+
+```python
+{"task_index": 7, "task_id": "mly-0007"}
+```
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any, Callable, Iterator
+
+from openenv.core.env_server.mcp_types import Tool
+from openenv.core.harness import (
+    ResourceSessionFactory,
+    StepEnvSessionAdapter,
+    ToolResult,
+    VerifyResult,
+)
+
+from .client import GeoGuesserEnv
+from .models import (
+    GuessAction,
+    LookAction,
+    MeasureAction,
+    MoveAction,
+    PanAction,
+    PinAction,
+    to_wire,
+    ViewMapAction,
+    ZoomAction,
+)
+
+
+def _number(description: str) -> dict[str, Any]:
+    return {"type": "number", "description": description}
+
+
+GEOGUESSER_TOOLS: list[Tool] = [
+    Tool(
+        name="look",
+        description=(
+            "Look in a direction from where you stand. heading_deg is "
+            "absolute, 0 being true north. Smaller fov_deg zooms in."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "heading_deg": _number("Compass heading in degrees."),
+                "pitch_deg": _number("Vertical angle; positive looks up."),
+                "fov_deg": _number("Field of view in degrees, 10 to 120."),
+            },
+            "required": ["heading_deg"],
+        },
+    ),
+    Tool(
+        name="pan",
+        description="Turn relative to your current heading; positive turns right.",
+        input_schema={
+            "type": "object",
+            "properties": {"delta_deg": _number("Degrees to turn.")},
+            "required": ["delta_deg"],
+        },
+    ),
+    Tool(
+        name="zoom",
+        description="Change field of view without turning. Around 30 reads distant signs.",
+        input_schema={
+            "type": "object",
+            "properties": {"fov_deg": _number("New field of view in degrees.")},
+            "required": ["fov_deg"],
+        },
+    ),
+    Tool(
+        name="move",
+        description=(
+            "Walk along the captured road. Reports how far you actually "
+            "travelled, since frame spacing is irregular."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "direction": {
+                    "type": "string",
+                    "enum": ["forward", "backward"],
+                    "description": "Which way to walk.",
+                },
+                "meters": _number("Requested distance in metres."),
+            },
+            "required": ["direction"],
+        },
+    ),
+    Tool(
+        name="place_pin",
+        description=(
+            "Pin a candidate coordinate and see where it falls on the map. "
+            "Tells you what is at that coordinate. It says nothing about "
+            "whether you are right."
+        ),
+        input_schema={
+            "type": "object",
+            "properties": {
+                "lat": _number("Latitude of the candidate."),
+                "lon": _number("Longitude of the candidate."),
+                "label": {"type": "string", "description": "Optional note."},
+                "span_deg": _number(
+                    "Half-width of the returned map in degrees. Below about 4 "
+                    "the map adds roads, urban areas and town names."
+                ),
+            },
+            "required": ["lat", "lon"],
+        },
+    ),
+    Tool(
+        name="view_map",
+        description="Pan and zoom the map without placing a pin.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "lat": _number("Latitude at the centre of the view."),
+                "lon": _number("Longitude at the centre of the view."),
+                "span_deg": _number("Half-width of the window in degrees."),
+            },
+            "required": ["lat", "lon"],
+        },
+    ),
+    Tool(
+        name="measure",
+        description="Distance in km between two coordinates of your own choosing. Free.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "lat_a": _number("Latitude of the first point."),
+                "lon_a": _number("Longitude of the first point."),
+                "lat_b": _number("Latitude of the second point."),
+                "lon_b": _number("Longitude of the second point."),
+            },
+            "required": ["lat_a", "lon_a", "lat_b", "lon_b"],
+        },
+    ),
+    Tool(
+        name="submit_guess",
+        description="Commit your final answer. This ends the episode.",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "lat": _number("Latitude of your guess."),
+                "lon": _number("Longitude of your guess."),
+                "country": {
+                    "type": "string",
+                    "description": "Optional ISO-3166 alpha-2 code or country name.",
+                },
+                "confidence": _number("Optional confidence in [0, 1]."),
+                "reasoning": {
+                    "type": "string",
+                    "description": "Optional rationale, recorded but not scored.",
+                },
+            },
+            "required": ["lat", "lon"],
+        },
+    ),
+]
+
+_ACTION_BY_TOOL: dict[str, Callable[[dict[str, Any]], Any]] = {
+    "look": lambda a: LookAction(
+        heading_deg=float(a["heading_deg"]),
+        pitch_deg=float(a.get("pitch_deg", 0.0)),
+        fov_deg=float(a.get("fov_deg", 90.0)),
+    ),
+    "pan": lambda a: PanAction(delta_deg=float(a["delta_deg"])),
+    "zoom": lambda a: ZoomAction(fov_deg=float(a["fov_deg"])),
+    "move": lambda a: MoveAction(
+        direction=str(a["direction"]), meters=float(a.get("meters", 10.0))
+    ),
+    "place_pin": lambda a: PinAction(
+        lat=float(a["lat"]),
+        lon=float(a["lon"]),
+        label=a.get("label") or None,
+        span_deg=float(a.get("span_deg", 7.0)),
+    ),
+    "view_map": lambda a: ViewMapAction(
+        lat=float(a["lat"]),
+        lon=float(a["lon"]),
+        span_deg=float(a.get("span_deg", 7.0)),
+    ),
+    "measure": lambda a: MeasureAction(
+        lat_a=float(a["lat_a"]),
+        lon_a=float(a["lon_a"]),
+        lat_b=float(a["lat_b"]),
+        lon_b=float(a["lon_b"]),
+    ),
+    "submit_guess": lambda a: GuessAction(
+        lat=float(a["lat"]),
+        lon=float(a["lon"]),
+        country=a.get("country") or None,
+        confidence=(
+            float(a["confidence"]) if a.get("confidence") is not None else None
+        ),
+        reasoning=a.get("reasoning") or None,
+    ),
+}
+
+
+def load_tasks(
+    index_path: str | pathlib.Path,
+    repeat: int = 1,
+    split: str | None = None,
+) -> list[dict[str, Any]]:
+    """
+    Read a frozen task index into harness task dicts.
+
+    Args:
+        index_path (`str` or `pathlib.Path`):
+            The JSONL index written by `scripts/build_tasks.py`.
+        repeat (`int`, *optional*, defaults to `1`):
+            Emit each task this many times consecutively. `repeat=16` gives a
+            GRPO group of 16 rollouts per location.
+        split (`str`, *optional*):
+            Split name to record on every task, so the session factory selects
+            from the right index server-side. Required whenever the server
+            serves more than one split, because an index alone does not say
+            which one it is.
+
+    Returns:
+        `list[dict]`: One dict per episode, each with `task_index`, `task_id`,
+        `country` and, when given, `split`.
+
+    Examples:
+
+    ```python
+    tasks = load_tasks("tasks/eval_pano_v3.jsonl", split="eval")
+    tasks = load_tasks("tasks/train_pano_v3.jsonl", repeat=16, split="train")
+    ```
+    """
+    rows = []
+    for line in pathlib.Path(index_path).read_text().splitlines():
+        if not line.strip():
+            continue
+        row = json.loads(line)
+        task = {
+            "task_index": int(row["task_index"]),
+            "task_id": str(row["task_id"]),
+            "country": str(row.get("country", "")),
+        }
+        if split is not None:
+            task["split"] = split
+        rows.extend([dict(task) for _ in range(repeat)])
+    return rows
+
+
+def cycle_tasks(tasks: list[dict[str, Any]]) -> Iterator[dict[str, Any]]:
+    """Yield tasks forever, so `num_episodes` may exceed the index size."""
+    while True:
+        for task in tasks:
+            yield dict(task)
+
+
+def _initial_messages(result: Any, task: Any) -> list[dict[str, Any]]:
+    """Opening message: the prompt plus the first view, as an image part."""
+    observation = result.observation
+    content: list[dict[str, Any]] = [{"type": "text", "text": observation.prompt}]
+    if observation.image_base64:
+        content.append(
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": f"data:image/jpeg;base64,{observation.image_base64}"
+                },
+            }
+        )
+    return [{"role": "user", "content": content}]
+
+
+def _tool_result(
+    tool_name: str, arguments: dict[str, Any], result: Any, state: Any
+) -> ToolResult:
+    """Feed the observation back as text plus, when present, an image."""
+    observation = result.observation
+    data: dict[str, Any] = {
+        "feedback": observation.feedback,
+        "heading_deg": observation.heading_deg,
+        "fov_deg": observation.fov_deg,
+        "steps_remaining": observation.steps_remaining,
+        "pins": [p.model_dump() for p in observation.pins],
+    }
+    if observation.image_base64:
+        data["image_base64"] = observation.image_base64
+        data["image_kind"] = observation.image_kind
+    if observation.distance_km is not None:
+        data["distance_km"] = observation.distance_km
+    return ToolResult(
+        data=data,
+        done=bool(result.done),
+        metadata={
+            "reward": result.reward,
+            "tool": tool_name,
+            "state": state.model_dump() if hasattr(state, "model_dump") else state,
+        },
+    )
+
+
+def _verify(
+    transcript: list[dict[str, Any]],
+    final_state: Any,
+    last_result: Any,
+    task: Any,
+) -> VerifyResult:
+    """
+    Summarise a finished episode for the collector.
+
+    `env_reward` forwards the reward the environment itself computed. Domain
+    knowledge belongs inside the environment, so nothing here recomputes or
+    adjusts it; the extra fields are derived statistics only.
+    """
+    observation = getattr(last_result, "observation", None)
+    distance = getattr(observation, "distance_km", None)
+    env_reward = getattr(last_result, "reward", None)
+    metrics: dict[str, Any] = {
+        "distance_km": float(distance) if distance is not None else -1.0,
+        "parsed_ok": float(bool(getattr(observation, "parsed_ok", False))),
+        "guessed": float(distance is not None),
+        "within_200km": float(distance is not None and distance < 200.0),
+        "within_25km": float(distance is not None and distance < 25.0),
+    }
+    if isinstance(task, dict) and task.get("task_index") is not None:
+        metrics["task_index"] = float(task["task_index"])
+    return VerifyResult(
+        env_reward=float(env_reward) if env_reward is not None else None,
+        done=bool(getattr(last_result, "done", False)),
+        metrics=metrics,
+    )
+
+
+class GeoGuesserSessionFactory(ResourceSessionFactory):
+    """Create GeoGuesser-backed resource sessions for harness rollouts.
+
+    Args:
+        client_factory (`Callable[[], GeoGuesserEnv]`):
+            Builds a client per session, so concurrent sessions stay isolated.
+        include_navigation (`bool`, *optional*, defaults to `True`):
+            Advertise `move` in the tool list. Set `False` for a task index
+            whose backend cannot walk, so the model never sees a dead tool.
+
+    Examples:
+
+    ```python
+    factory = GeoGuesserSessionFactory(
+        lambda: GeoGuesserEnv(base_url="http://localhost:8000")
+    )
+    session = factory.create(task={"task_index": 7})
+    ```
+    """
+
+    def __init__(
+        self,
+        client_factory: Callable[[], GeoGuesserEnv],
+        *,
+        include_navigation: bool = True,
+    ):
+        self._client_factory = client_factory
+        self._tools = [
+            tool
+            for tool in GEOGUESSER_TOOLS
+            if include_navigation or tool.name != "move"
+        ]
+
+    def create(
+        self,
+        task: Any = None,
+        seed: int | None = None,
+        episode_id: str | None = None,
+    ) -> StepEnvSessionAdapter:
+        """
+        Open a session on one task.
+
+        The task's `split` and `task_index` are passed through `reset_kwargs`,
+        which is what makes a rollout reproducible: the same task always starts
+        from the same panorama at the same heading. Without the split, an index
+        is ambiguous once the server serves more than one.
+
+        Args:
+            task (`dict`, *optional*):
+                Task dict with a `task_index` and optionally a `split`. `None`
+                selects randomly from the server's default split.
+            seed (`int`, *optional*):
+                Fallback selector when no task is given.
+            episode_id (`str`, *optional*):
+                Episode identifier recorded by the collector.
+
+        Returns:
+            `StepEnvSessionAdapter`: The session, ready to be driven.
+        """
+        reset_kwargs: dict[str, Any] = {}
+        if isinstance(task, dict):
+            if task.get("split"):
+                reset_kwargs["split"] = str(task["split"])
+            if task.get("task_index") is not None:
+                reset_kwargs["index"] = int(task["task_index"])
+        elif isinstance(task, int):
+            reset_kwargs["index"] = task
+
+        return StepEnvSessionAdapter(
+            client=self._client_factory(),
+            task=task,
+            seed=seed,
+            episode_id=episode_id,
+            tool_specs=list(self._tools),
+            action_builder=lambda name, arguments: to_wire(
+                _ACTION_BY_TOOL[name](arguments)
+            ),
+            initial_messages_builder=_initial_messages,
+            tool_result_builder=_tool_result,
+            verify_builder=_verify,
+            reset_kwargs=reset_kwargs,
+        )
+
+
+__all__ = [
+    "GEOGUESSER_TOOLS",
+    "GeoGuesserSessionFactory",
+    "cycle_tasks",
+    "load_tasks",
+]

geoguesser_env/models.py

@@ -0,0 +1,458 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Data models for the GeoGuesser environment.
+
+An episode places the agent at an unknown street-level location. It may look
+around, walk along the road, and pin candidate coordinates on a map before
+committing to a final guess. Only the final guess is scored.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Literal
+
+from openenv.core.env_server import Action, Observation, State
+from pydantic import BaseModel, Field
+
+
+class EpisodeMode(str, Enum):
+    """How much of the tool surface an episode exposes.
+
+    Attributes:
+        SINGLE_SHOT:
+            One view, one guess. No pin loop, no navigation.
+        AGENTIC:
+            The full tool surface, subject to what the backend supports.
+        NMPZ:
+            No move, pan or zoom — the competitive "NMPZ" mode. Only pinning
+            and guessing.
+    """
+
+    SINGLE_SHOT = "single_shot"
+    AGENTIC = "agentic"
+    NMPZ = "nmpz"
+
+
+class RewardMode(str, Enum):
+    """Which ground-truth granularity the reward is computed against."""
+
+    COORDS = "coords"
+    COUNTRY_ONLY = "country_only"
+
+
+# =============================================================================
+# Actions
+# =============================================================================
+
+
+class TypedAction(Action):
+    """Base class for the ergonomic, per-operation action types.
+
+    These are what callers construct in Python. They are converted to the flat
+    [`GeoGuesserAction`] wire type by the client, because an HTTP environment
+    declares exactly one action schema and `Action` forbids unknown fields.
+    """
+
+
+class LookAction(TypedAction):
+    """Render a perspective view out of the current panorama.
+
+    Args:
+        heading_deg (`float`):
+            Absolute compass heading in degrees, `0` being true north.
+        pitch_deg (`float`, *optional*, defaults to `0.0`):
+            Vertical angle in degrees; positive looks up.
+        fov_deg (`float`, *optional*, defaults to `90.0`):
+            Horizontal field of view. Smaller values zoom in.
+    """
+
+    heading_deg: float = Field(default=0.0, ge=-3600.0, le=3600.0)
+    pitch_deg: float = Field(default=0.0, ge=-90.0, le=90.0)
+    fov_deg: float = Field(default=90.0, ge=10.0, le=120.0)
+
+
+class PanAction(TypedAction):
+    """Turn relative to the current heading.
+
+    Args:
+        delta_deg (`float`):
+            Degrees to turn; positive turns right.
+    """
+
+    delta_deg: float = Field(ge=-3600.0, le=3600.0)
+
+
+class ZoomAction(TypedAction):
+    """Change the field of view without turning.
+
+    Args:
+        fov_deg (`float`):
+            New horizontal field of view in degrees.
+    """
+
+    fov_deg: float = Field(ge=10.0, le=120.0)
+
+
+class MoveAction(TypedAction):
+    """Walk along the captured sequence.
+
+    Args:
+        direction (`str`):
+            Either `"forward"` or `"backward"` along the sequence.
+        meters (`float`, *optional*, defaults to `10.0`):
+            Requested distance. Frame spacing is irregular, so the observation
+            reports how far the move actually travelled.
+    """
+
+    direction: str = Field(pattern="^(forward|backward)$")
+    meters: float = Field(default=10.0, gt=0.0, le=500.0)
+
+
+class PinAction(TypedAction):
+    """Place a candidate pin and receive a map of where it landed.
+
+    The response describes the pinned location only. It carries no information
+    about the true location.
+
+    Args:
+        lat (`float`):
+            Latitude of the candidate.
+        lon (`float`):
+            Longitude of the candidate.
+        label (`str`, *optional*):
+            Free-text note carried back in the pin list.
+        span_deg (`float`, *optional*, defaults to `7.0`):
+            Half-width in degrees of the map window returned with the pin.
+            Choosing the zoom matters: below roughly 4 degrees the map adds
+            roads, urban areas and town names, which is what makes aiming
+            within a city possible rather than guessing at its centre.
+    """
+
+    lat: float = Field(ge=-90.0, le=90.0)
+    lon: float = Field(ge=-180.0, le=180.0)
+    label: str | None = None
+    span_deg: float = Field(default=7.0, gt=0.02, le=180.0)
+
+
+class ViewMapAction(TypedAction):
+    """Pan and zoom the map without committing a pin.
+
+    Args:
+        lat (`float`):
+            Latitude at the centre of the view.
+        lon (`float`):
+            Longitude at the centre of the view.
+        span_deg (`float`, *optional*, defaults to `7.0`):
+            Half-width of the window in degrees.
+    """
+
+    lat: float = Field(ge=-90.0, le=90.0)
+    lon: float = Field(ge=-180.0, le=180.0)
+    span_deg: float = Field(default=7.0, gt=0.05, le=180.0)
+
+
+class MeasureAction(TypedAction):
+    """Great-circle distance between two of the agent's own coordinates."""
+
+    lat_a: float = Field(ge=-90.0, le=90.0)
+    lon_a: float = Field(ge=-180.0, le=180.0)
+    lat_b: float = Field(ge=-90.0, le=90.0)
+    lon_b: float = Field(ge=-180.0, le=180.0)
+
+
+class GuessAction(TypedAction):
+    """Commit a final guess. Terminal.
+
+    Either supply `response` and let the environment parse it, or supply
+    `lat`/`lon` directly. Passing the raw reply keeps extraction failures
+    visible in the score rather than hidden in the harness.
+
+    Args:
+        response (`str`, *optional*):
+            The model's unedited reply. Coordinates are extracted from it.
+        lat (`float`, *optional*):
+            Latitude, when the caller has already parsed the reply.
+        lon (`float`, *optional*):
+            Longitude, when the caller has already parsed the reply.
+        country (`str`, *optional*):
+            ISO-3166 alpha-2 code or country name, scored for partial credit.
+        confidence (`float`, *optional*):
+            Self-reported confidence in [0, 1], recorded for calibration.
+        reasoning (`str`, *optional*):
+            Free-text rationale, recorded but not scored.
+    """
+
+    response: str | None = None
+    lat: float | None = Field(default=None, ge=-90.0, le=90.0)
+    lon: float | None = Field(default=None, ge=-180.0, le=180.0)
+    country: str | None = None
+    confidence: float | None = Field(default=None, ge=0.0, le=1.0)
+    reasoning: str | None = None
+
+
+# =============================================================================
+# Wire action
+# =============================================================================
+
+
+class GeoGuesserAction(Action):
+    """The single action schema the server accepts.
+
+    An HTTP environment declares one action class, so every operation travels
+    as this flat record with an `op` discriminator. Callers normally build a
+    [`TypedAction`] subclass instead and let the client convert.
+
+    Attributes:
+        op (`str`):
+            Which operation to perform: `"look"`, `"pan"`, `"zoom"`, `"move"`,
+            `"pin"`, `"view_map"`, `"measure"` or `"guess"`.
+    """
+
+    op: Literal["look", "pan", "zoom", "move", "pin", "view_map", "measure", "guess"]
+
+    heading_deg: float | None = None
+    pitch_deg: float | None = None
+    fov_deg: float | None = None
+    delta_deg: float | None = None
+    direction: str | None = None
+    meters: float | None = None
+    lat: float | None = None
+    lon: float | None = None
+    label: str | None = None
+    span_deg: float | None = None
+    lat_a: float | None = None
+    lon_a: float | None = None
+    lat_b: float | None = None
+    lon_b: float | None = None
+    response: str | None = None
+    country: str | None = None
+    confidence: float | None = None
+    reasoning: str | None = None
+
+
+_OP_BY_TYPE: dict[type, str] = {}
+_TYPE_BY_OP: dict[str, type] = {}
+
+
+def _register_ops() -> None:
+    pairs = [
+        (LookAction, "look"),
+        (PanAction, "pan"),
+        (ZoomAction, "zoom"),
+        (MoveAction, "move"),
+        (PinAction, "pin"),
+        (ViewMapAction, "view_map"),
+        (MeasureAction, "measure"),
+        (GuessAction, "guess"),
+    ]
+    for cls, op in pairs:
+        _OP_BY_TYPE[cls] = op
+        _TYPE_BY_OP[op] = cls
+
+
+_register_ops()
+
+
+def to_wire(action: TypedAction) -> GeoGuesserAction:
+    """
+    Convert a typed action into the flat wire action.
+
+    Args:
+        action ([`TypedAction`]):
+            The action to convert.
+
+    Returns:
+        [`GeoGuesserAction`]: The same action, flattened, with `op` set.
+    """
+    op = _OP_BY_TYPE.get(type(action))
+    if op is None:
+        raise TypeError(f"No wire op registered for {type(action).__name__}")
+    payload = action.model_dump(exclude_none=True, exclude={"metadata"})
+    return GeoGuesserAction(op=op, **payload)
+
+
+def from_wire(action: GeoGuesserAction) -> TypedAction:
+    """
+    Rebuild the typed action a wire action stands for.
+
+    Args:
+        action ([`GeoGuesserAction`]):
+            The received wire action.
+
+    Returns:
+        [`TypedAction`]: The corresponding typed action, validated.
+    """
+    cls = _TYPE_BY_OP.get(action.op)
+    if cls is None:
+        raise ValueError(f"Unknown op: {action.op!r}")
+    fields = set(cls.model_fields) - {"metadata"}
+    payload = {
+        k: v for k, v in action.model_dump(exclude_none=True).items() if k in fields
+    }
+    return cls(**payload)
+
+
+# =============================================================================
+# Observation
+# =============================================================================
+
+
+class Pin(BaseModel):
+    """One candidate pin and what the environment could say about it.
+
+    Attributes:
+        index (`int`):
+            1-based position in the pin list.
+        lat (`float`):
+            Latitude of the candidate.
+        lon (`float`):
+            Longitude of the candidate.
+        label (`str` or `None`):
+            The note the agent attached, if any.
+        description (`str`):
+            What the environment could say about the pinned coordinate. Never
+            anything about the target.
+    """
+
+    index: int
+    lat: float
+    lon: float
+    label: str | None = None
+    description: str = ""
+
+
+class GeoGuesserObservation(Observation):
+    """What the agent sees after a reset or a step.
+
+    The schema is identical across backends. A capability the backend lacks
+    shows up as an unregistered tool and an empty field, never as a different
+    shape, so one policy runs against every backend.
+
+    Attributes:
+        prompt (`str`):
+            Instructions, populated on reset.
+        image_base64 (`str` or `None`):
+            The most recent rendered image as base64 PNG or JPEG — a
+            perspective view, or a map after a pin.
+        image_kind (`str`):
+            Either `"view"`, `"map"` or `"none"`, saying what the image shows.
+        heading_deg (`float`):
+            Current compass heading in degrees.
+        pitch_deg (`float`):
+            Current vertical angle in degrees.
+        fov_deg (`float`):
+            Current field of view in degrees.
+        moved_meters (`float`):
+            Distance actually travelled by the last move.
+        total_moved_meters (`float`):
+            Cumulative distance travelled this episode.
+        can_move_forward (`bool`):
+            Whether a forward frame exists on the sequence.
+        can_move_backward (`bool`):
+            Whether a backward frame exists on the sequence.
+        available_tools (`list[str]`):
+            Tool names this backend actually registered.
+        steps_remaining (`int`):
+            Actions left before the episode is cut off.
+        pins (`list[Pin]`):
+            Candidates placed so far, in order.
+        feedback (`str`):
+            Text describing the result of the last action. For a pin, this
+            describes the pinned location and nothing about the target.
+        captured_at (`str`):
+            Capture date of the current panorama, `YYYY-MM` — a legitimate
+            meta clue, as in the real game.
+        distance_km (`float` or `None`):
+            Distance from guess to truth. Populated only after a guess.
+        score (`float` or `None`):
+            Distance score in [0, 1], before action costs. After a guess only.
+        action_cost (`float`):
+            Reward already spent on information gathering this episode. Visible
+            throughout, not only after the guess, so a policy can see what it
+            has committed.
+        true_lat (`float` or `None`):
+            Ground truth latitude, revealed only after a guess.
+        true_lon (`float` or `None`):
+            Ground truth longitude, revealed only after a guess.
+        parsed_ok (`bool`):
+            Whether coordinates could be extracted from the guess.
+    """
+
+    prompt: str = ""
+    image_base64: str | None = None
+    image_kind: str = "none"
+
+    heading_deg: float = 0.0
+    pitch_deg: float = 0.0
+    fov_deg: float = 90.0
+
+    moved_meters: float = 0.0
+    total_moved_meters: float = 0.0
+    can_move_forward: bool = False
+    can_move_backward: bool = False
+
+    available_tools: list[str] = Field(default_factory=list)
+    steps_remaining: int = 0
+    pins: list[Pin] = Field(default_factory=list)
+    feedback: str = ""
+    captured_at: str = ""
+
+    distance_km: float | None = None
+    score: float | None = None
+    action_cost: float | None = None
+    true_lat: float | None = None
+    true_lon: float | None = None
+    parsed_ok: bool = True
+
+
+# =============================================================================
+# State
+# =============================================================================
+
+
+class GeoGuesserState(State):
+    """Internal episode state. Never sent to the agent verbatim.
+
+    Attributes:
+        task_index (`int`):
+            Index into the frozen task list, `-1` before the first reset.
+        task_id (`str`):
+            Stable identifier of the sampled task.
+        frame_index (`int`):
+            Position within the task's sequence.
+        heading_deg (`float`):
+            Current heading in degrees.
+        pitch_deg (`float`):
+            Current pitch in degrees.
+        fov_deg (`float`):
+            Current field of view in degrees.
+        n_looks (`int`):
+            Count of view renders, for action cost.
+        n_maps (`int`):
+            Count of map renders that were not pins.
+        n_pins (`int`):
+            Count of pins placed.
+        n_moves (`int`):
+            Count of moves taken.
+        total_moved_meters (`float`):
+            Cumulative distance travelled.
+        submitted (`bool`):
+            Whether the single allowed guess has been made.
+        pins (`list[dict]`):
+            Pins placed so far.
+    """
+
+    task_index: int = -1
+    task_id: str = ""
+    frame_index: int = 0
+    heading_deg: float = 0.0
+    pitch_deg: float = 0.0
+    fov_deg: float = 90.0
+    n_looks: int = 0
+    n_maps: int = 0
+    n_pins: int = 0
+    n_moves: int = 0
+    total_moved_meters: float = 0.0
+    submitted: bool = False
+    pins: list[dict[str, Any]] = Field(default_factory=list)

geoguesser_env/openenv.yaml

@@ -0,0 +1,22 @@
+spec_version: 1
+name: geoguesser_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+
+# Applied as Space variables when this environment is deployed. The paths point
+# at a Storage Bucket mounted read-only at /data, because ~31 GB of panoramas
+# cannot live in the Space image: Space disk is ephemeral and capped well below
+# that. Locally these are unset and the server falls back to repo-relative
+# defaults, so the same image serves both.
+variables:
+  GEOGUESSER_TASKS_EVAL: /data/tasks/eval_pano_v3.jsonl
+  GEOGUESSER_TASKS_TRAIN: /data/tasks/train_pano_v3.jsonl
+  GEOGUESSER_DEFAULT_SPLIT: train
+  GEOGUESSER_CACHE: /data/panos
+  # A mounted bucket makes the dataset complete, so a cache miss is a bug
+  # rather than something to paper over with a network call.
+  GEOGUESSER_ALLOW_FETCH: "0"
+  # The street overlay is fetched per agent pin, so it cannot be pre-warmed.
+  GEOGUESSER_STREET_DETAIL: "0"

geoguesser_env/openenv_geoguesser_env.egg-info/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: openenv-geoguesser-env
+Version: 0.1.0
+Summary: GeoGuessr-style visual geolocation environment for OpenEnv
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openenv>=0.3.1
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: matplotlib>=3.7.0
+Provides-Extra: ui
+Requires-Dist: gradio>=4.0.0; extra == "ui"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# GeoGuesser
+
+A GeoGuessr-style visual geolocation environment. The agent is dropped at an
+unknown street-level location, looks around, walks along the road, pins
+candidate coordinates on a map to check itself, and commits to a final guess.
+Reward is distance-based, using the game's own scoring curve.
+
+Independent open-source project, unaffiliated with GeoGuessr AB. Imagery comes
+from Mapillary contributors under CC-BY-SA-4.0.
+
+## Quick start
+
+```bash
+# 1. Build a task index (needs a free Mapillary token with READ scope)
+export MAPILLARY_API_KEY="MLY|..."
+cd envs/geoguesser_env
+uv run python scripts/build_pano_tasks.py --tasks 100 --frames 24
+
+# 2. Run the server
+uv run --project . server            # http://localhost:8000
+```
+
+```python
+from geoguesser_env import GeoGuesserEnv, GuessAction, LookAction, PinAction
+
+env = GeoGuesserEnv(base_url="http://localhost:8000")
+
+result = env.reset(task_index=7)              # byte-identical on repeat
+print(result.observation.prompt)
+
+result = env.step(LookAction(heading_deg=90, fov_deg=45))
+result = env.step(PinAction(lat=-16.5, lon=-68.1))
+print(result.observation.feedback)
+# Pin 1 placed at -16.5000, -68.1000 - Bolivia (South America).
+# Nearest major city: La Paz, ~5 km E. 10 actions left.
+
+result = env.step(GuessAction(response="Altiplano. <guess>-16.49, -68.12</guess>"))
+print(result.reward, result.observation.distance_km)
+```
+
+## Tools
+
+| Tool | What it does | Cost |
+|------|--------------|------|
+| `look(heading_deg, pitch_deg, fov_deg)` | Render a view. Heading is absolute, `0` is true north | −0.01 |
+| `pan(delta_deg)` | Turn relative to the current heading | −0.01 |
+| `zoom(fov_deg)` | Narrow the field of view; around 30 reads distant signs | −0.01 |
+| `move(direction, meters)` | Walk the captured road; reports distance actually travelled | −0.05 |
+| `place_pin(lat, lon, label)` | Pin a candidate and see where it falls on the map | −0.02 |
+| `view_map(lat, lon, span_deg)` | Pan and zoom the map without pinning | −0.01 |
+| `list_pins()` / `clear_pins()` | Review or drop candidates | free |
+| `measure(lat_a, lon_a, lat_b, lon_b)` | Distance between two of your own points | free |
+| `reverse_geocode(lat, lon)` | Name the country and nearest city at a coordinate | free |
+| `submit_guess(lat, lon, ...)` | Commit the answer. Terminal | — |
+
+Tools the backend cannot serve are **not registered**, so the agent never sees
+a tool that always fails.
+
+### Pinning tells you where you pointed, not whether you are right
+
+`place_pin` returns a rendered map and a description of the pinned location:
+country, subregion, nearest city with distance and bearing, and the distance
+to the agent's own earlier pins. It reveals nothing about the target.
+
+That restraint is deliberate. Any signal about the truth — a distance, a
+warmer/colder hint — would make binary search the optimal policy, and the
+environment would measure bisection rather than geographic reasoning. Distance
+and score arrive only from `submit_guess`.
+
+## Reward
+
+```
+geo     = exp(-distance_km / 1492.7)           # GeoGuessr's curve, in [0, 1]
+partial = 0.15 * country_hit + 0.10 * region_hit   # when hierarchical
+cost    = 0.01*looks + 0.01*maps + 0.02*pins + 0.05*moves
+reward  = clip(geo + partial, 0, 1) - cost
+```
+
+An unparseable or out-of-range guess scores `0.0` and says why. Parsing
+accepts what models actually emit: decimal pairs, DMS (`48°51'29"N`), labelled
+`lat:`/`lon:`, JSON, and `<guess>` tags.
+
+## Reproducibility
+
+```python
+env.reset(task_index=7)   # exact task, byte-identical observation -> GRPO, eval
+env.reset(seed=42)        # tasks[42 % n_tasks]                     -> replay
+env.reset()               # random task, index in metadata          -> UI
+```
+
+Byte-identical repeats hold because panorama bytes come from a local cache
+rather than an expiring CDN URL, reprojection is pure numpy with integer
+sampling, and the initial heading is pinned to each panorama's own
+`compass_angle`.
+
+An eval score is only meaningful alongside its provenance — the env version,
+the task index, and `GEODATA_VERSION` from `server/render/minimap.py`, since
+the bundled vectors determine the reverse-geocode text the agent sees.
+
+## Training and collection
+
+The environment plugs into `openenv.core.harness`, so a rollout function and a
+collector come for free:
+
+```python
+from geoguesser_env import GeoGuesserEnv
+from geoguesser_env.harness import GeoGuesserSessionFactory, load_tasks
+
+tasks = load_tasks("tasks/pano_v1.jsonl", repeat=16)   # GRPO group of 16
+factory = GeoGuesserSessionFactory(
+    lambda: GeoGuesserEnv(base_url="http://localhost:8000")
+)
+```
+
+See `examples/geoguesser_rollout.py` for a scripted rollout and
+`examples/geoguesser_collect.py` for JSONL collection with resume.
+
+## Human play
+
+A five-round game, 5,000 points a round on the same curve the environment
+rewards, so a human score is directly comparable to GeoGuessr intuition and to
+the agent's reward (both are shown).
+
+```bash
+uv run --project . server
+# then open http://localhost:8000/geoguesser/play
+```
+
+The page stands alone at `/geoguesser/play` and is also embedded in the Gradio
+playground's **Custom** tab when the web interface is enabled:
+
+```bash
+ENABLE_WEB_INTERFACE=true uv run --project . server   # http://localhost:8000/web/
+```
+
+Drag to look around, scroll to zoom, **M** toggles a larger map, **Enter**
+submits and then advances. On submit the map takes the screen and draws the
+line between guess and truth, exactly like the game; the result bar shows
+distance, points, env reward and the true location, and a scoreboard breaks
+down all five rounds at the end.
+
+Panoramas are rendered by Pannellum and the map by MapLibre over OpenFreeMap
+tiles — no API key, no request limits. The imagery credit line names the
+Mapillary contributor, which the CC-BY-SA licence requires.
+
+The page has to be a standalone document rather than a Gradio `gr.HTML`
+fragment: `gr.HTML` inserts markup without executing `<script>` tags, so the
+viewers never initialise and the panel renders blank with no error anywhere.
+
+Extra routes, all local:
+
+| Route | Returns |
+|-------|---------|
+| `/geoguesser/play` | the play page |
+| `/geoguesser/tasks` | `{"n_tasks": N}` |
+| `/geoguesser/task/{i}` | task metadata, including ground truth for the human UI |
+| `/geoguesser/pano/{i}` | the raw equirectangular panorama |
+
+The human map uses live tiles; the agent's map stays the offline Natural Earth
+render, so the agent keeps a determinism the browser does not need. Note that
+`/geoguesser/task/{i}` exposes ground truth — it exists for a person playing in
+their own browser, and agent observations still withhold it until the guess.
+
+## Configuration
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `GEOGUESSER_INDEX` | `tasks/pano_v1.jsonl` | Task index to load |
+| `GEOGUESSER_CACHE` | `data/panos` | Panorama cache directory |
+| `GEOGUESSER_EPISODE_MODE` | `agentic` | `agentic`, `single_shot` or `nmpz` |
+| `GEOGUESSER_MAX_STEPS` | `12` | Actions before the episode is cut off |
+| `GEOGUESSER_REWARD_MODE` | `coords` | `coords` or `country_only` |
+| `GEOGUESSER_HIERARCHICAL` | `0` | Add country and region partial credit |
+| `GEOGUESSER_VIEW_SIZE` | `640` | Edge length of rendered views |
+| `GEOGUESSER_ALLOW_FETCH` | `1` | Whether a cache miss may reach the API |
+| `MAPILLARY_API_KEY` | — | Needed by the builder, and only on a cache miss |
+
+## Data
+
+The committed index holds **100 tasks across 47 countries and all six
+continents**, one per Mapillary sequence, captured between 2017 and 2026:
+
+| | |
+|---|---|
+| Tasks | 100 (`task_index` 0-99) |
+| Countries | 47, capped at 4 tasks each |
+| Continents | Europe 34, Asia 27, South America 23, North America 11, Oceania 3, Africa 2 |
+| Frames per task | 23.2 mean (3 min, 24 max), ~3.3 m apart |
+| Index size | 417 KB, committed |
+| Cache | 37 MB for the 100 start frames; ~0.6 GB fully warmed |
+
+The index is self-contained: every frame's coordinates, heading and capture
+date live in `tasks/pano_v1.jsonl`, so the movement graph resolves offline.
+Only image bytes are fetched, and only on a cache miss, because Mapillary
+`thumb_*_url` values are expiring signed URLs that cannot be stored.
+
+Coverage is uneven and worth knowing about. Probing 45 Street-View
+coordinates found any Mapillary imagery at 21 and a 360-degree panorama at
+only 7, heavily clustered. Panorama-first discovery is therefore the only
+approach that works — roughly 5% of probe points yield a usable sequence, so
+reaching 100 tasks took two passes with different seeds, merged by
+`scripts/merge_task_indexes.py`. Africa and Oceania are thin because 360-degree
+contributors are; that is a property of the source, documented rather than
+papered over.
+
+## Known gaps versus the real game
+
+Movement follows captured sequences and stops where one ends. There is no
+multi-round cumulative score, no wall-clock timer (a step budget stands in for
+it), and no satellite layer on the guess map. Coverage hints and web search are
+deliberately excluded: the first is a crutch, the second turns the task into
+retrieval.
+
+See [DESIGN.md](DESIGN.md) for the reasoning behind these choices.

geoguesser_env/openenv_geoguesser_env.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+README.md
+pyproject.toml
+openenv_geoguesser_env.egg-info/PKG-INFO
+openenv_geoguesser_env.egg-info/SOURCES.txt
+openenv_geoguesser_env.egg-info/dependency_links.txt
+openenv_geoguesser_env.egg-info/entry_points.txt
+openenv_geoguesser_env.egg-info/requires.txt
+openenv_geoguesser_env.egg-info/top_level.txt
+server/__init__.py
+server/app.py
+server/geoguesser_environment.py
+server/gradio_ui.py
+server/parser.py
+server/scoring.py
+server/backends/__init__.py
+server/backends/base.py
+server/backends/panorama.py
+server/render/__init__.py
+server/render/minimap.py
+server/render/pano.py
+tests/test_geoguesser_env.py

geoguesser_env/openenv_geoguesser_env.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

geoguesser_env/openenv_geoguesser_env.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+server = server.app:main

geoguesser_env/openenv_geoguesser_env.egg-info/requires.txt

@@ -0,0 +1,14 @@
+openenv>=0.3.1
+fastapi>=0.115.0
+pydantic>=2.0.0
+uvicorn>=0.24.0
+fastmcp>=2.0.0
+pillow>=10.0.0
+numpy>=1.24.0
+matplotlib>=3.7.0
+
+[dev]
+pytest>=8.0.0
+
+[ui]
+gradio>=4.0.0

geoguesser_env/openenv_geoguesser_env.egg-info/top_level.txt

@@ -0,0 +1 @@
+server

geoguesser_env/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-geoguesser-env"
+version = "0.1.0"
+description = "GeoGuessr-style visual geolocation environment for OpenEnv"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv dependencies (required for server functionality).
+    "openenv>=0.3.1",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0.0",
+    "uvicorn>=0.24.0",
+    "fastmcp>=2.0.0",
+    # Environment-specific: panorama reprojection and the offline guess map.
+    "pillow>=10.0.0",
+    "numpy>=1.24.0",
+    "matplotlib>=3.7.0",
+]
+
+[project.optional-dependencies]
+ui = ["gradio>=4.0.0"]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.scripts]
+server = "server.app:main"
+
+[tool.setuptools]
+packages = ["server", "server.backends", "server.render"]

geoguesser_env/scripts/benchmark_throughput.py

@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Measure how many episodes the environment itself can supply.
+
+Answers the question a training or eval run actually needs: is the environment
+the bottleneck, or the model? Runs an agentic-shaped episode — reset, three
+looks, optionally a pin, a guess — across a range of worker counts, both as
+threads and as processes, and reports episodes and steps per second.
+
+Every worker gets its own environment, because an episode is stateful; sharing
+one interleaves resets and silently produces nonsense. A perfect guess is
+asserted to score zero distance, so an interference bug fails loudly instead of
+reporting excellent throughput.
+
+Usage:
+    python scripts/benchmark_throughput.py threads 32
+    REVEAL=0 PIN=0 python scripts/benchmark_throughput.py threads 64
+    python scripts/benchmark_throughput.py processes 32
+
+Environment variables:
+    REVEAL=0   skip the guess reveal map, as a training run would
+    PIN=0      skip the pin, leaving view renders only
+"""
+
+import concurrent.futures as cf
+import os
+import pathlib
+import statistics
+import sys
+import threading
+import time
+
+_LOCAL = threading.local()
+
+_ROOT = pathlib.Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(_ROOT))
+sys.path.insert(0, str(_ROOT.parent / "src"))
+
+INDEX = str(_ROOT / "geoguesser_env" / "tasks" / "pano_v1.jsonl")
+CACHE = str(_ROOT / "geoguesser_env" / "data" / "panos")
+
+
+def episode(task_index: int) -> tuple[float, int]:
+    """One agentic-shaped episode: reset, 3 looks, 1 pin, 1 guess."""
+    from geoguesser_env.models import GuessAction, LookAction, PinAction, to_wire
+    from geoguesser_env.server.geoguesser_environment import GeoGuesserEnvironment
+    from geoguesser_env.server.render import minimap
+
+    minimap.set_street_detail(False)  # training config: never touch Overpass
+    # An episode is stateful, so every worker needs its own environment. Sharing
+    # one through a module global interleaves resets between threads and silently
+    # produces nonsense — which is exactly what the first version of this
+    # benchmark measured.
+    if not hasattr(_LOCAL, "env"):
+        _LOCAL.env = GeoGuesserEnvironment(
+            index_path=INDEX,
+            cache_dir=CACHE,
+            allow_fetch=False,
+            view_size=640,
+            reveal_map=os.environ.get("REVEAL", "1") == "1",
+        )
+    env = _LOCAL.env
+    started = time.perf_counter()
+    env.reset(task_index=task_index)
+    steps = 1
+    for heading in (0, 120, 240):
+        env.step(to_wire(LookAction(heading_deg=heading, fov_deg=90)))
+        steps += 1
+    if os.environ.get("PIN", "1") == "1":
+        env.step(to_wire(PinAction(lat=10.0, lon=10.0, span_deg=7.0)))
+        steps += 1
+    truth = env._task.truth
+    result = env.step(to_wire(GuessAction(lat=truth[0], lon=truth[1])))
+    steps += 1
+    # A perfect guess must score ~1 minus costs. If workers interfered, this
+    # fails instead of quietly reporting a great throughput number.
+    assert result.distance_km is not None and result.distance_km < 0.01, (
+        f"cross-worker interference: task {task_index} scored "
+        f"{result.distance_km} km on a perfect guess"
+    )
+    return time.perf_counter() - started, steps
+
+
+def run(pool_cls, workers: int, episodes: int) -> dict:
+    tasks = [i % 100 for i in range(episodes)]
+    wall0 = time.perf_counter()
+    with pool_cls(max_workers=workers) as pool:
+        results = list(pool.map(episode, tasks))
+    wall = time.perf_counter() - wall0
+    latencies = [r[0] for r in results]
+    total_steps = sum(r[1] for r in results)
+    return {
+        "workers": workers,
+        "episodes": episodes,
+        "wall_s": wall,
+        "episodes_per_s": episodes / wall,
+        "steps_per_s": total_steps / wall,
+        "median_episode_s": statistics.median(latencies),
+    }
+
+
+if __name__ == "__main__":
+    kind = sys.argv[1]
+    episodes = int(sys.argv[2]) if len(sys.argv) > 2 else 24
+    pool = cf.ThreadPoolExecutor if kind == "threads" else cf.ProcessPoolExecutor
+    print(f"{kind}, {os.cpu_count()} cpus, warm cache, street detail off")
+    print(f"{'workers':>7} {'eps/s':>7} {'steps/s':>8} {'wall':>7} {'median ep':>10}")
+    for workers in (1, 2, 4, 8, 16):
+        r = run(pool, workers, episodes)
+        print(
+            f"{r['workers']:>7} {r['episodes_per_s']:>7.2f} {r['steps_per_s']:>8.1f} "
+            f"{r['wall_s']:>6.1f}s {r['median_episode_s']:>9.2f}s"
+        )

geoguesser_env/scripts/build_dataset.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: BSD-3-Clause
+#
+# Build the offline task pool: every frame of every task mirrored to disk, so
+# both training and eval run with the network off.
+#
+# Eval is NOT carved here. Sample it afterwards with split_tasks.py, which
+# enforces the separation (shared sequences, plus a 1 km buffer) in one place
+# rather than trusting two independent builds not to collide.
+#
+# Usage:
+#   ./scripts/build_dataset.sh              # 5000 tasks, the default
+#   TASKS=100 ./scripts/build_dataset.sh    # trial
+#   ./scripts/build_dataset.sh --seed 12    # extra args reach build_tasks.py
+#
+# Resumable: Ctrl-C and re-run the identical command. It continues where it
+# stopped and skips every sequence already used.
+
+set -euo pipefail
+
+TASKS="${TASKS:-5000}"
+FRAMES="${FRAMES:-24}"
+
+# Only reject sequences too short to navigate at all. Demanding a full 24
+# everywhere would drop ~22% of candidates, and short sequences cluster in
+# sparsely mapped regions, so that filter quietly costs geographic diversity.
+# Tasks therefore carry 8-24 frames; filter to 24 when sampling eval, where a
+# uniform movement budget is what makes scores comparable.
+MIN_FRAMES="${MIN_FRAMES:-8}"
+
+# workers x frame-workers is the concurrent fetch count. Measured on an
+# 18-core machine: 24->7.7 img/s, 48->16.1, 96->27.0, 144->37.0, zero failures,
+# and 144 sits at ~7% of Mapillary's 60k/min entity limit.
+WORKERS="${WORKERS:-12}"
+FRAME_WORKERS="${FRAME_WORKERS:-12}"
+
+# Loose country cap: this pool feeds training, where breadth beats balance, and
+# eval balance is enforced at sampling time instead. The per-creator cap stays
+# tight because one contributor holds 99,167 pool sequences (8% of the pool).
+PER_COUNTRY="${PER_COUNTRY:-150}"
+PER_CREATOR="${PER_CREATOR:-25}"
+
+OUT="${OUT:-tasks/pool_offline_5k.jsonl}"
+
+cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")/.."
+ENV_DIR="$PWD"
+REPO_ROOT="$(cd ../.. && pwd)"
+PYTHON="${PYTHON:-$REPO_ROOT/.venv/bin/python}"
+
+if [ ! -x "$PYTHON" ]; then
+  echo "no interpreter at $PYTHON — run 'uv sync --all-extras' first, or set PYTHON=" >&2
+  exit 1
+fi
+
+# Read the token in Python, never by sourcing .env: the "|" in "MLY|..." is a
+# pipe to the shell, which leaks the token into the terminal.
+if [ -z "${MAPILLARY_API_KEY_TRAIN:-}" ] && [ -z "${MAPILLARY_API_KEY:-}" ]; then
+  MAPILLARY_API_KEY_TRAIN="$("$PYTHON" - "$REPO_ROOT/.env" <<'PY'
+import pathlib, sys
+path = pathlib.Path(sys.argv[1])
+if path.exists():
+    for line in path.read_text().splitlines():
+        for name in ("MAPILLARY_API_KEY_TRAIN", "MAPILLARY_API_KEY"):
+            if line.startswith(name + "="):
+                print(line.split("=", 1)[1].strip().strip('"').strip("'"))
+                sys.exit()
+PY
+)"
+  export MAPILLARY_API_KEY_TRAIN
+fi
+if [ -z "${MAPILLARY_API_KEY_TRAIN:-}" ] && [ -z "${MAPILLARY_API_KEY:-}" ]; then
+  echo "no Mapillary token: set MAPILLARY_API_KEY_TRAIN or add it to $REPO_ROOT/.env" >&2
+  exit 1
+fi
+
+"$PYTHON" -c "import matplotlib, rich, PIL, numpy" 2>/dev/null || {
+  echo "missing dependencies — install with:" >&2
+  echo "  uv pip install --python $PYTHON matplotlib rich pillow numpy" >&2
+  exit 1
+}
+
+POOL="$ENV_DIR/data/pool/sequences.jsonl"
+if [ ! -s "$POOL" ]; then
+  echo "no sequence pool at $POOL — run scripts/harvest_tiles.py first" >&2
+  exit 1
+fi
+
+DONE=0
+[ -f "$OUT" ] && DONE=$(grep -c . "$OUT" || true)
+TODO=$((TASKS - DONE))
+
+# 0.52 s/task and 0.256 MB/frame, both measured on the 200-task build.
+"$PYTHON" - "$TODO" "$FRAMES" "$((WORKERS * FRAME_WORKERS))" "$DONE" <<'PY'
+import sys
+todo, frames, conc, done = (int(v) for v in sys.argv[1:5])
+if done:
+    print(f"resuming: {done} tasks already built")
+if todo <= 0:
+    raise SystemExit(0)
+secs = todo * 0.52
+print(
+    f"{todo} tasks to build · {frames} frames each · {conc} concurrent fetches\n"
+    f"estimated {secs / 60:.0f} min "
+    f"({int(secs // 3600)}h{int(secs % 3600 // 60):02d}m) "
+    f"and {todo * frames * 0.256 / 1000:.1f} GB of imagery"
+)
+PY
+
+echo "pool: $(grep -c . "$POOL") sequences · out: $OUT"
+echo
+
+"$PYTHON" scripts/build_tasks.py \
+  --tasks "$TASKS" \
+  --frames "$FRAMES" \
+  --min-frames "$MIN_FRAMES" \
+  --mirror all \
+  --workers "$WORKERS" \
+  --frame-workers "$FRAME_WORKERS" \
+  --per-country "$PER_COUNTRY" \
+  --per-creator "$PER_CREATOR" \
+  --out "$OUT" \
+  "$@"
+
+echo
+"$PYTHON" - "$OUT" "$ENV_DIR/data/panos" <<'PY'
+import collections, json, pathlib, sys
+
+tasks = [
+    json.loads(line)
+    for line in pathlib.Path(sys.argv[1]).read_text().splitlines()
+    if line.strip()
+]
+cache = pathlib.Path(sys.argv[2])
+if not tasks:
+    raise SystemExit("no tasks were written")
+
+missing = [
+    frame["image_id"]
+    for task in tasks
+    for frame in task["frames"]
+    if not (cache / f"{frame['image_id']}.jpg").exists()
+]
+countries = collections.Counter(task["country"] for task in tasks)
+creators = collections.Counter(task["attribution"]["creator_id"] for task in tasks)
+full = sum(1 for task in tasks if len(task["frames"]) >= 24)
+total_frames = sum(len(task["frames"]) for task in tasks)
+
+print(f"{len(tasks)} tasks · {len(countries)} countries · {len(creators)} contributors")
+print(f"frames: {total_frames} total · {full} tasks have the full 24")
+top, top_n = countries.most_common(1)[0]
+print(f"largest country: {top} at {top_n} ({100 * top_n / len(tasks):.1f}%)")
+print(f"largest contributor: {creators.most_common(1)[0][1]} tasks")
+print(f"eval candidates with 24 frames: {full}")
+
+if missing:
+    raise SystemExit(f"NOT fully offline: {len(missing)} frames absent from the cache")
+print(f"fully offline: all {total_frames} frames are on disk")
+PY
+
+echo
+echo "next: sample eval out of the pool, which enforces the separation:"
+echo "  $PYTHON scripts/split_tasks.py $OUT --eval 200"

geoguesser_env/scripts/build_eval_set.py

@@ -0,0 +1,511 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Build a frozen evaluation set of 360-degree panorama tasks.
+
+Discovery is city-seeded and adaptive, which measured far better than the
+road-point probing in `build_pano_tasks.py`:
+
+    45 m probe boxes at Street View coordinates ..........  5% of seeds hit
+    adaptive box, jittered 28 km around cities ...........  3%
+    adaptive box, ±2 km around cities .................... 21%
+    adaptive box, city centres ........................... 26%, 16 sequences/hit
+
+Two things drive that. Panoramas are extremely clustered — one hit typically
+yields a dozen or more sequences from the same contributor's drive — so the
+useful unit of discovery is a neighbourhood, not a point. And `is_pano=true` is
+a real server-side filter, so one request answers "are there panoramas here"
+instead of returning a hundred phone photographs to sift.
+
+An eval set is not a training pool, so this applies three extra rules:
+
+- **balance over size**: capped per country, because at n=100 balance decides
+  what the number means
+- **disjoint from training**: any sequence already in the training index is
+  rejected, and so is anything within a spatial buffer of it, since frames sit
+  about 3.3 m apart and holding out an image holds out nothing
+- **mirrored and checksummed**: the imagery is downloaded and hashed, because
+  Mapillary thumbnail URLs expire and uploads get deleted, and an eval whose
+  images can change is not an eval
+
+Usage:
+    python scripts/build_eval_set.py --tasks 100 --per-country 2
+    python scripts/build_eval_set.py --tasks 100 --exclude tasks/pano_v1.jsonl
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import functools
+import hashlib
+import json
+import logging
+import math
+import pathlib
+import random
+import sys
+import urllib.request
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+
+from build_pano_tasks import (  # noqa: E402
+    _get,
+    _month,
+    _token,
+    frame_detail,
+    sequence_frames,
+    TIMEOUT_S,
+)
+from matplotlib.path import Path as MplPath  # noqa: E402
+from server.render.minimap import locate  # noqa: E402
+
+
+# Boxes are tried widest first; a dense city rejects the wide ones with a 500
+# because the scan happens before the filter, so the ladder walks down.
+BBOX_LADDER = (0.005, 0.002, 0.0006)
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger("build_eval_set")
+
+
+def _box(lat: float, lon: float, half: float) -> str:
+    return f"{lon - half},{lat - half},{lon + half},{lat + half}"
+
+
+def _haversine_km(lat_a: float, lon_a: float, lat_b: float, lon_b: float) -> float:
+    phi_a, phi_b = math.radians(lat_a), math.radians(lat_b)
+    d_phi, d_lambda = phi_b - phi_a, math.radians(lon_b - lon_a)
+    h = (
+        math.sin(d_phi / 2) ** 2
+        + math.cos(phi_a) * math.cos(phi_b) * math.sin(d_lambda / 2) ** 2
+    )
+    return 2 * 6371.0088 * math.asin(math.sqrt(min(1.0, h)))
+
+
+@functools.lru_cache(maxsize=1)
+def _country_polygons() -> list[tuple[str, MplPath]]:
+    """Country name and outline for every admin-0 polygon, loaded once."""
+    root = pathlib.Path(__file__).resolve().parents[1]
+    features = json.loads(
+        (root / "data" / "geo" / "ne_110m_admin_0_countries.geojson").read_text()
+    )["features"]
+    out = []
+    for feature in features:
+        geometry = feature["geometry"]
+        rings = (
+            [geometry["coordinates"][0]]
+            if geometry["type"] == "Polygon"
+            else [poly[0] for poly in geometry["coordinates"]]
+        )
+        for ring in rings:
+            out.append((feature["properties"]["ADMIN"], MplPath(ring)))
+    return out
+
+
+def _country_of(lat: float, lon: float) -> str | None:
+    """Country containing a coordinate, or `None` over water.
+
+    Cheaper than `locate()`, which also scans every populated place for the
+    nearest city — needless when only the country is wanted for seeding.
+    """
+    for name, path in _country_polygons():
+        if path.contains_point((lon, lat)):
+            return name
+    return None
+
+
+def load_seeds(
+    geo_dir: pathlib.Path, limit: int, seed: int, stratify: bool = True
+) -> list[tuple[str, float, float]]:
+    """
+    City seeds, ordered to spread across countries.
+
+    Panorama coverage clusters hard: a first run probed 900 cities and found
+    1,300 sequences, but from only 30 countries — so a per-country cap ran out
+    of countries long before it ran out of sequences, and the set stopped at 58
+    of 100. Round-robin ordering by country means the first N probes touch N
+    different countries instead of hammering whichever metros the shuffle picked.
+
+    Args:
+        geo_dir (`pathlib.Path`):
+            Directory holding the bundled Natural Earth files.
+        limit (`int`):
+            How many seeds to return.
+        seed (`int`):
+            Seed for the shuffle within each country.
+        stratify (`bool`, *optional*, defaults to `True`):
+            Order round-robin by country rather than at random.
+
+    Returns:
+        `list[tuple[str, float, float]]`: `(name, lat, lon)` seeds.
+    """
+    detail = geo_dir / "detail" / "places.json"
+    if detail.exists():
+        rows = json.loads(detail.read_text())
+        points = [(r.get("n") or "", r["c"][1], r["c"][0]) for r in rows]
+    else:
+        features = json.loads((geo_dir / "ne_50m_populated_places.geojson").read_text())
+        points = [
+            (
+                f["properties"]["name"],
+                f["geometry"]["coordinates"][1],
+                f["geometry"]["coordinates"][0],
+            )
+            for f in features["features"]
+        ]
+    rng = random.Random(seed)
+    rng.shuffle(points)
+    if not stratify:
+        return points[:limit]
+
+    by_country: dict[str | None, list] = {}
+    for name, lat, lon in points:
+        by_country.setdefault(_country_of(lat, lon), []).append((name, lat, lon))
+    by_country.pop(None, None)
+
+    buckets = list(by_country.values())
+    rng.shuffle(buckets)
+    ordered: list[tuple[str, float, float]] = []
+    depth = 0
+    while len(ordered) < limit and any(len(b) > depth for b in buckets):
+        for bucket in buckets:
+            if len(bucket) > depth:
+                ordered.append(bucket[depth])
+                if len(ordered) >= limit:
+                    break
+        depth += 1
+    logger.info(
+        "seeded %d cities round-robin across %d countries", len(ordered), len(buckets)
+    )
+    return ordered
+
+
+def discover(token: str, seeds, workers: int) -> dict[str, dict]:
+    """Probe each seed and return one anchor image per panorama sequence."""
+
+    def probe(seed):
+        name, lat, lon = seed
+        for half in BBOX_LADDER:
+            result = _get(
+                token,
+                "images",
+                bbox=_box(lat, lon, half),
+                fields="id,sequence,camera_type,quality_score,computed_geometry",
+                is_pano="true",
+            )
+            if "__error" not in result:
+                return name, result.get("data", [])
+        return name, []
+
+    found: dict[str, dict] = {}
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as pool:
+        for index, (name, images) in enumerate(pool.map(probe, seeds), 1):
+            for image in images:
+                sequence = image.get("sequence")
+                if not sequence or sequence in found:
+                    continue
+                if image.get("camera_type") != "spherical":
+                    continue
+                found[sequence] = {**image, "__seed": name}
+            if index % 50 == 0:
+                logger.info(
+                    "  %d/%d seeds probed, %d sequences", index, len(seeds), len(found)
+                )
+    return found
+
+
+def mirror_frames(
+    token: str, image_ids: list[str], cache_dir: pathlib.Path, workers: int
+) -> dict[str, str]:
+    """
+    Download and hash a task's frames, in parallel.
+
+    An eval that prefetches all 24 frames so `move()` can be evaluated offline
+    was spending 24 sequential round trips per task — about 30 s of the 34 s a
+    task cost. Fetching them concurrently makes mirroring roughly free next to
+    frame assembly.
+
+    Args:
+        token (`str`):
+            Mapillary access token.
+        image_ids (`list[str]`):
+            Frames to mirror.
+        cache_dir (`pathlib.Path`):
+            Where the JPEGs live.
+        workers (`int`):
+            Concurrent downloads.
+
+    Returns:
+        `dict[str, str]`: sha256 by image id, for every frame that landed.
+    """
+
+    def fetch_one(image_id: str) -> tuple[str, str | None]:
+        path = cache_dir / f"{image_id}.jpg"
+        if not path.exists():
+            meta = _get(token, image_id, fields="thumb_2048_url")
+            url = meta.get("thumb_2048_url") if "__error" not in meta else None
+            if not url:
+                return image_id, None
+            try:
+                with urllib.request.urlopen(url, timeout=TIMEOUT_S) as response:
+                    path.write_bytes(response.read())
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("  fetch failed for %s: %r", image_id, exc)
+                return image_id, None
+        return image_id, hashlib.sha256(path.read_bytes()).hexdigest()
+
+    checksums: dict[str, str] = {}
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as pool:
+        for image_id, digest in pool.map(fetch_one, image_ids):
+            if digest:
+                checksums[image_id] = digest
+    return checksums
+
+
+def load_exclusions(
+    paths: list[pathlib.Path],
+) -> tuple[set[str], list[tuple[float, float]]]:
+    """Sequences and coordinates that a new task must stay away from."""
+    sequences: set[str] = set()
+    points: list[tuple[float, float]] = []
+    for path in paths:
+        if not path.exists():
+            logger.warning("exclusion file missing, skipping: %s", path)
+            continue
+        for line in path.read_text().splitlines():
+            if not line.strip():
+                continue
+            row = json.loads(line)
+            if row.get("sequence_id"):
+                sequences.add(row["sequence_id"])
+            for frame in row.get("frames", []):
+                points.append((frame["lat"], frame["lon"]))
+    return sequences, points
+
+
+def build(args: argparse.Namespace) -> None:
+    """Discover, filter, mirror and write the eval set."""
+    token = _token()
+    root = pathlib.Path(__file__).resolve().parents[1]
+    out_dir = args.out
+    cache_dir = args.cache
+    out_dir.mkdir(parents=True, exist_ok=True)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    excluded_sequences, excluded_points = load_exclusions(args.exclude)
+    logger.info(
+        "excluding %d training sequences and staying %.1f km from %d of their frames",
+        len(excluded_sequences),
+        args.buffer_km,
+        len(excluded_points),
+    )
+
+    seeds = load_seeds(
+        root / "data" / "geo", args.seeds, args.seed, stratify=not args.no_stratify
+    )
+    logger.info("probing %d city seeds with %d workers", len(seeds), args.workers)
+    candidates = discover(token, seeds, args.workers)
+    logger.info("found %d panorama sequences", len(candidates))
+
+    order = sorted(
+        candidates.items(),
+        key=lambda kv: -(kv[1].get("quality_score") or 0.0),
+    )
+    per_country: dict[str, int] = {}
+    tasks: list[dict] = []
+
+    rejected_early = 0
+    for sequence_id, anchor in order:
+        if len(tasks) >= args.tasks:
+            break
+        if sequence_id in excluded_sequences:
+            continue
+
+        # Reject before assembling, not after. Discovery already returned the
+        # anchor's coordinates, so the country cap and the training buffer can
+        # both be checked for free — and with coverage as clustered as it is,
+        # most candidates fall in an already-full country. Assembling 25
+        # requests' worth of frames first made a task cost 14.4 s instead of 5.
+        geometry = anchor.get("computed_geometry") or anchor.get("geometry")
+        if geometry:
+            anchor_lon, anchor_lat = geometry["coordinates"]
+            country_guess = _country_of(anchor_lat, anchor_lon)
+            if (
+                country_guess is None
+                or per_country.get(country_guess, 0) >= args.per_country
+            ):
+                rejected_early += 1
+                continue
+            if any(
+                _haversine_km(anchor_lat, anchor_lon, lat, lon) < args.buffer_km
+                for lat, lon in excluded_points
+            ):
+                rejected_early += 1
+                continue
+
+        ids = sequence_frames(token, sequence_id)
+        if len(ids) < args.min_frames:
+            continue
+        anchor_id = str(anchor["id"])
+        position = ids.index(anchor_id) if anchor_id in ids else 0
+        low = max(0, position - args.frames // 2)
+        window = ids[low : low + args.frames]
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=args.workers) as pool:
+            details = list(pool.map(lambda i: frame_detail(token, i), window))
+
+        frames = []
+        for detail in details:
+            if not detail or not detail.get("is_pano"):
+                continue
+            geometry = detail.get("computed_geometry") or detail.get("geometry")
+            if not geometry:
+                continue
+            lon, lat = geometry["coordinates"]
+            frames.append(
+                {
+                    "image_id": str(detail["id"]),
+                    "lat": lat,
+                    "lon": lon,
+                    "compass_angle": detail.get("computed_compass_angle")
+                    or detail.get("compass_angle")
+                    or 0.0,
+                    "captured_at": _month(detail.get("captured_at")),
+                    "is_pano": True,
+                }
+            )
+        if len(frames) < args.min_frames:
+            continue
+
+        # A missing captured_at renders as an epoch date, which is harmless for
+        # scoring but breaks a temporal split and looks wrong in the UI.
+        # Mapillary launched in 2013.
+        frames = [
+            f for f in frames if not f["captured_at"] or f["captured_at"][:4] >= "2010"
+        ]
+        if len(frames) < args.min_frames:
+            continue
+
+        start = min(len(frames) // 2, len(frames) - 1)
+        start_frame = frames[start]
+
+        too_close = any(
+            _haversine_km(start_frame["lat"], start_frame["lon"], lat, lon)
+            < args.buffer_km
+            for lat, lon in excluded_points
+        )
+        if too_close:
+            continue
+
+        place = locate(start_frame["lat"], start_frame["lon"])
+        country = place.country or "unknown"
+        if country == "unknown" or per_country.get(country, 0) >= args.per_country:
+            continue
+
+        anchor_detail = next(
+            (d for d in details if d and str(d["id"]) == start_frame["image_id"]), {}
+        )
+        creator = anchor_detail.get("creator", {}) or {}
+
+        # Mirror the imagery. An eval whose pictures can change upstream is not
+        # an eval, and Mapillary thumbnail URLs expire.
+        wanted = [f["image_id"] for f in frames[: args.prefetch]]
+        if start_frame["image_id"] not in wanted:
+            wanted.append(start_frame["image_id"])
+        checksums = mirror_frames(token, wanted, cache_dir, args.workers)
+
+        if start_frame["image_id"] not in checksums:
+            continue
+
+        per_country[country] = per_country.get(country, 0) + 1
+        tasks.append(
+            {
+                "task_index": len(tasks),
+                "task_id": f"eval-{len(tasks):04d}",
+                "country": country,
+                "sequence_id": sequence_id,
+                "provider": "mapillary",
+                "start_frame": start,
+                "frames": frames,
+                "attribution": {
+                    "creator_username": creator.get("username", ""),
+                    "creator_id": creator.get("id", ""),
+                    "licence": "CC-BY-SA-4.0",
+                    "source": "Mapillary",
+                },
+                "meta": {
+                    "seed_name": anchor.get("__seed", ""),
+                    "camera_make": anchor_detail.get("make", ""),
+                    "camera_model": anchor_detail.get("model", ""),
+                    "quality_score": anchor_detail.get("quality_score"),
+                    "continent": place.continent,
+                    "subregion": place.subregion,
+                    "nearest_city": place.nearest_city,
+                    "sha256": checksums,
+                    "mirrored_frames": len(checksums),
+                },
+            }
+        )
+        logger.info(
+            "  eval %3d  %-24s %-8s %2d frames  %d mirrored",
+            len(tasks) - 1,
+            country[:24],
+            start_frame["captured_at"],
+            len(frames),
+            len(checksums),
+        )
+
+    index_path = out_dir / args.name
+    with index_path.open("w") as handle:
+        for task in tasks:
+            handle.write(json.dumps(task) + "\n")
+
+    logger.info(
+        "rejected %d candidates before assembly, on country cap or buffer",
+        rejected_early,
+    )
+    countries = sorted(per_country.items(), key=lambda kv: -kv[1])
+    logger.info(
+        "\nwrote %d eval tasks to %s (%.0f KB)",
+        len(tasks),
+        index_path,
+        index_path.stat().st_size / 1024,
+    )
+    logger.info("countries: %d -> %s", len(countries), dict(countries[:12]))
+    mirrored = sum(t["meta"]["mirrored_frames"] for t in tasks)
+    logger.info("mirrored %d images into %s", mirrored, cache_dir)
+
+
+def main() -> None:
+    """Command-line entry point."""
+    root = pathlib.Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--tasks", type=int, default=100)
+    parser.add_argument("--per-country", type=int, default=2)
+    parser.add_argument("--frames", type=int, default=24)
+    parser.add_argument("--min-frames", type=int, default=8)
+    parser.add_argument("--prefetch", type=int, default=1)
+    parser.add_argument("--seeds", type=int, default=900)
+    parser.add_argument("--workers", type=int, default=10)
+    parser.add_argument("--seed", type=int, default=1234)
+    parser.add_argument(
+        "--no-stratify",
+        action="store_true",
+        help="Probe cities in random order instead of round-robin by country.",
+    )
+    parser.add_argument("--buffer-km", type=float, default=1.0)
+    parser.add_argument("--name", default="eval_pano_v1.jsonl")
+    parser.add_argument(
+        "--exclude",
+        nargs="*",
+        type=pathlib.Path,
+        default=[root / "tasks" / "pano_v1.jsonl"],
+    )
+    parser.add_argument("--out", type=pathlib.Path, default=root / "tasks")
+    parser.add_argument("--cache", type=pathlib.Path, default=root / "data" / "panos")
+    build(parser.parse_args())
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/build_pano_tasks.py

@@ -0,0 +1,404 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Build a frozen task index of Mapillary 360-degree panoramas.
+
+Discovery is panorama-first. Sampling coordinates and hoping for coverage does
+not work: probing 45 Street-View locations found any Mapillary imagery at 21
+and a 360-degree panorama at only 7. So this script probes many candidate
+points, keeps whatever panoramas exist, and defines tasks there.
+
+Two API constraints shape the implementation. The `/images` search is not a
+bulk endpoint — `limit` does not cap the scan and dense bounding boxes fail
+with "reduce the amount of data" — so probes use very small boxes. And
+`camera_type` returns `spherical`, not the `equirectangular` the documentation
+claims, so filtering on the documented value silently matches nothing.
+
+Usage:
+    python scripts/build_pano_tasks.py --tasks 100 --frames 24
+    python scripts/build_pano_tasks.py --tasks 8 --frames 6 --out tests/fixtures
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import hashlib
+import json
+import logging
+import os
+import pathlib
+import random
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+
+from server.render.minimap import _cities, locate  # noqa: E402
+
+
+GRAPH_API = "https://graph.mapillary.com"
+PROBE_HALF_DEG = 0.0004
+TIMEOUT_S = 30.0
+
+SEARCH_FIELDS = "id,is_pano,camera_type,sequence,quality_score"
+FRAME_FIELDS = (
+    "id,geometry,computed_geometry,compass_angle,computed_compass_angle,"
+    "captured_at,is_pano,camera_type,quality_score,creator,make,model,width,height"
+)
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger("build_pano_tasks")
+
+
+# Rate limits are per application, so harvesting on its own key means a bulk
+# harvest cannot starve a training run that is filling its panorama cache.
+DATA_KEY_NAMES = ("MAPILLARY_API_KEY_TRAIN", "MAPILLARY_API_KEY")
+RUNTIME_KEY_NAMES = ("MAPILLARY_API_KEY",)
+
+
+def _read_env_file(names: tuple[str, ...]) -> str | None:
+    env_file = pathlib.Path(__file__).resolve().parents[3] / ".env"
+    if not env_file.exists():
+        return None
+    values = {}
+    for line in env_file.read_text().splitlines():
+        if "=" in line and not line.lstrip().startswith("#"):
+            key, value = line.split("=", 1)
+            values[key.strip()] = value.strip().strip('"').strip("'")
+    for name in names:
+        if values.get(name):
+            return values[name]
+    return None
+
+
+def _token(names: tuple[str, ...] = DATA_KEY_NAMES) -> str:
+    """
+    Return a Mapillary token, preferring the harvesting key.
+
+    Args:
+        names (`tuple[str, ...]`, *optional*):
+            Environment variable names to try, in order. Defaults to the
+            harvesting key first, then the runtime key.
+
+    Returns:
+        `str`: The token.
+    """
+    for name in names:
+        if os.environ.get(name):
+            return os.environ[name]
+    token = _read_env_file(names)
+    if not token:
+        raise SystemExit(
+            "No Mapillary token found. Set one of "
+            + ", ".join(names)
+            + ". Register an application at "
+            "https://www.mapillary.com/dashboard/developers (READ scope only)."
+        )
+    return token
+
+
+def _get(token: str, path: str, **params) -> dict:
+    params["access_token"] = token
+    url = f"{GRAPH_API}/{path}?" + urllib.parse.urlencode(params)
+    try:
+        with urllib.request.urlopen(url, timeout=TIMEOUT_S) as response:
+            return json.loads(response.read())
+    except urllib.error.HTTPError as exc:
+        return {"__error": exc.code, "__body": exc.read().decode()[:160]}
+    except Exception as exc:  # network flake, DNS, timeout
+        return {"__error": -1, "__body": repr(exc)[:160]}
+
+
+def _month(captured_at_ms: int | None) -> str:
+    if not captured_at_ms:
+        return ""
+    return time.strftime("%Y-%m", time.gmtime(captured_at_ms / 1000))
+
+
+def seed_points(count: int, seed: int = 0) -> list[tuple[str, float, float]]:
+    """
+    Candidate probe points, drawn from the bundled populated-places file.
+
+    Using committed data keeps the builder reproducible and avoids a hardcoded
+    list of favourite cities. Each point is jittered so repeated runs explore
+    slightly different streets.
+
+    Args:
+        count (`int`):
+            How many probe points to return.
+        seed (`int`, *optional*, defaults to `0`):
+            Seed for the jitter and the shuffle.
+
+    Returns:
+        `list[tuple[str, float, float]]`: `(name, lat, lon)` triples.
+    """
+    rng = random.Random(seed)
+    cities = list(_cities())
+    rng.shuffle(cities)
+    points = []
+    while len(points) < count:
+        for name, lat, lon in cities:
+            if len(points) >= count:
+                break
+            # Later passes over the same city jitter further out, so a dense
+            # metro contributes several distinct streets rather than one point.
+            spread = 0.01 + 0.02 * (len(points) // max(1, len(cities)))
+            points.append(
+                (
+                    name,
+                    lat + rng.uniform(-spread, spread),
+                    lon + rng.uniform(-spread, spread),
+                )
+            )
+    return points
+
+
+def probe(token: str, point: tuple[str, float, float]) -> dict | None:
+    """Return the best spherical panorama near one probe point, if any."""
+    name, lat, lon = point
+    d = PROBE_HALF_DEG
+    bbox = f"{lon - d},{lat - d},{lon + d},{lat + d}"
+    result = _get(token, "images", bbox=bbox, fields=SEARCH_FIELDS)
+    if "__error" in result:
+        return None
+    panos = [
+        image
+        for image in result.get("data", [])
+        if image.get("is_pano") and image.get("camera_type") == "spherical"
+    ]
+    if not panos:
+        return None
+    best = max(panos, key=lambda image: image.get("quality_score") or 0.0)
+    best["__seed_name"] = name
+    return best
+
+
+def sequence_frames(token: str, sequence_id: str) -> list[str]:
+    """Ordered image ids making up a sequence."""
+    result = _get(token, "image_ids", sequence_id=sequence_id)
+    if "__error" in result:
+        return []
+    return [str(row["id"]) for row in result.get("data", [])]
+
+
+def frame_detail(token: str, image_id: str) -> dict | None:
+    """Full entity for one frame, or `None` when the request fails."""
+    result = _get(token, str(image_id), fields=FRAME_FIELDS)
+    return None if "__error" in result else result
+
+
+def build(
+    n_tasks: int,
+    n_frames: int,
+    out_dir: pathlib.Path,
+    cache_dir: pathlib.Path,
+    max_per_country: int,
+    n_seeds: int,
+    workers: int,
+    prefetch_frames: int,
+    seed: int,
+    require_country: bool = True,
+) -> None:
+    """Discover panoramas, assemble tasks and write the index."""
+    token = _token()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    points = seed_points(n_seeds, seed=seed)
+    logger.info("probing %d candidate points with %d workers", len(points), workers)
+
+    found: list[dict] = []
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as pool:
+        for i, hit in enumerate(pool.map(lambda p: probe(token, p), points), 1):
+            if hit:
+                found.append(hit)
+            if i % 25 == 0:
+                logger.info("  %d/%d probed, %d panoramas", i, len(points), len(found))
+    logger.info("found %d panoramas from %d probes", len(found), len(points))
+
+    seen_sequences: set[str] = set()
+    per_country: dict[str, int] = {}
+    tasks: list[dict] = []
+
+    for hit in found:
+        if len(tasks) >= n_tasks:
+            break
+        sequence_id = hit.get("sequence")
+        if not sequence_id or sequence_id in seen_sequences:
+            continue
+        seen_sequences.add(sequence_id)
+
+        ids = sequence_frames(token, sequence_id)
+        if len(ids) < 2:
+            continue
+        anchor = ids.index(str(hit["id"])) if str(hit["id"]) in ids else 0
+        lo = max(0, anchor - n_frames // 2)
+        window = ids[lo : lo + n_frames]
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as pool:
+            details = list(pool.map(lambda i: frame_detail(token, i), window))
+
+        frames = []
+        for detail in details:
+            if not detail:
+                continue
+            geometry = detail.get("computed_geometry") or detail.get("geometry")
+            if not geometry:
+                continue
+            lon, lat = geometry["coordinates"]
+            frames.append(
+                {
+                    "image_id": str(detail["id"]),
+                    "lat": lat,
+                    "lon": lon,
+                    "compass_angle": detail.get("computed_compass_angle")
+                    or detail.get("compass_angle")
+                    or 0.0,
+                    "captured_at": _month(detail.get("captured_at")),
+                    "is_pano": bool(detail.get("is_pano")),
+                }
+            )
+        frames = [f for f in frames if f["is_pano"]]
+        if len(frames) < 2:
+            continue
+
+        start = min(len(frames) // 2, len(frames) - 1)
+        start_frame = frames[start]
+        place = locate(start_frame["lat"], start_frame["lon"])
+        country = place.country or "unknown"
+        if require_country and country == "unknown":
+            # The coordinate fell outside the coarse 110m polygons, usually a
+            # coastline or small island. Country partial credit would be
+            # meaningless there, so leave it out of the index.
+            continue
+        if per_country.get(country, 0) >= max_per_country:
+            continue
+
+        anchor_detail = next(
+            (d for d in details if d and str(d["id"]) == start_frame["image_id"]), {}
+        )
+        creator = anchor_detail.get("creator", {}) or {}
+
+        checksums: dict[str, str] = {}
+        to_cache = [start_frame["image_id"]]
+        if prefetch_frames:
+            to_cache = [f["image_id"] for f in frames[:prefetch_frames]]
+        for image_id in to_cache:
+            path = cache_dir / f"{image_id}.jpg"
+            if not path.exists():
+                detail = _get(token, image_id, fields="thumb_2048_url")
+                thumb_url = detail.get("thumb_2048_url")
+                if "__error" in detail or not thumb_url:
+                    # A successful response can still omit the thumbnail, for
+                    # images whose derivatives have not been generated.
+                    logger.warning("  no thumbnail available for %s", image_id)
+                    continue
+                try:
+                    with urllib.request.urlopen(
+                        thumb_url, timeout=TIMEOUT_S
+                    ) as response:
+                        path.write_bytes(response.read())
+                except Exception as exc:
+                    logger.warning("  fetch failed for %s: %r", image_id, exc)
+                    continue
+            checksums[image_id] = hashlib.sha256(path.read_bytes()).hexdigest()
+
+        if start_frame["image_id"] not in checksums:
+            continue
+
+        per_country[country] = per_country.get(country, 0) + 1
+        tasks.append(
+            {
+                "task_index": len(tasks),
+                "task_id": f"mly-{len(tasks):04d}",
+                "country": country,
+                "sequence_id": sequence_id,
+                "provider": "mapillary",
+                "start_frame": start,
+                "frames": frames,
+                "attribution": {
+                    "creator_username": creator.get("username", ""),
+                    "creator_id": creator.get("id", ""),
+                    "licence": "CC-BY-SA-4.0",
+                    "source": "Mapillary",
+                },
+                "meta": {
+                    "seed_name": hit.get("__seed_name", ""),
+                    "camera_make": anchor_detail.get("make", ""),
+                    "camera_model": anchor_detail.get("model", ""),
+                    "quality_score": anchor_detail.get("quality_score"),
+                    "continent": place.continent,
+                    "subregion": place.subregion,
+                    "nearest_city": place.nearest_city,
+                    "sha256": checksums,
+                },
+            }
+        )
+        logger.info(
+            "  task %3d  %-22s %-16s %2d frames  %s",
+            len(tasks) - 1,
+            country[:22],
+            start_frame["captured_at"],
+            len(frames),
+            anchor_detail.get("model", "")[:18],
+        )
+
+    index_path = out_dir / "pano_v1.jsonl"
+    with index_path.open("w") as handle:
+        for task in tasks:
+            handle.write(json.dumps(task) + "\n")
+
+    countries = sorted(per_country.items(), key=lambda kv: -kv[1])
+    logger.info(
+        "\nwrote %d tasks to %s (%.0f KB)",
+        len(tasks),
+        index_path,
+        index_path.stat().st_size / 1024,
+    )
+    logger.info("countries: %s", ", ".join(f"{c}:{n}" for c, n in countries))
+    cached = list(cache_dir.glob("*.jpg"))
+    logger.info(
+        "cache: %d images, %.0f MB",
+        len(cached),
+        sum(p.stat().st_size for p in cached) / 1e6,
+    )
+
+
+def main() -> None:
+    """Command-line entry point."""
+    root = pathlib.Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--tasks", type=int, default=100)
+    parser.add_argument("--frames", type=int, default=24)
+    parser.add_argument("--seeds", type=int, default=900)
+    parser.add_argument("--max-per-country", type=int, default=4)
+    parser.add_argument("--workers", type=int, default=8)
+    parser.add_argument("--prefetch-frames", type=int, default=0)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument(
+        "--allow-unknown-country",
+        action="store_true",
+        help="Keep tasks whose coordinate falls outside the country polygons.",
+    )
+    parser.add_argument("--out", type=pathlib.Path, default=root / "tasks")
+    parser.add_argument("--cache", type=pathlib.Path, default=root / "data" / "panos")
+    args = parser.parse_args()
+    build(
+        n_tasks=args.tasks,
+        n_frames=args.frames,
+        out_dir=args.out,
+        cache_dir=args.cache,
+        max_per_country=args.max_per_country,
+        n_seeds=args.seeds,
+        workers=args.workers,
+        prefetch_frames=args.prefetch_frames,
+        seed=args.seed,
+        require_country=not args.allow_unknown_country,
+    )
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/build_tasks.py

@@ -0,0 +1,560 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Assemble tasks from a harvested sequence pool.
+
+`harvest_tiles.py` enumerates panorama sequences worldwide; this turns a
+selection of them into playable tasks. The two steps are separate because
+harvesting is fast and assembly is not: a task costs about 27 Graph API
+requests, so you harvest once and sample from the pool as often as you like.
+
+Balance is enforced before assembly, not after. Panorama coverage clusters
+hard — sixteen sequences from one hit are usually one contributor's drive — so
+candidates are capped per country *and* per creator using the anchor
+coordinates the pool already carries, before a single frame is fetched. Doing it
+the other way round cost 14.4 s per accepted task instead of 3.
+
+Offline mode: `--mirror all` downloads every frame, so the finished dataset
+needs no network at rollout time at all. Rough sizes at 2,500 tasks:
+
+    --mirror start                ~0.7 GB    guessing only
+    --mirror all                   ~16 GB    look and move offline
+    --mirror all --originals       ~20 GB    plus sharp zoom at the start frame
+
+Measured over 964 cached files: mean 0.26 MB per 2048x1024 derivative (median
+0.24, p90 0.34) and 1.8 MB per full-resolution original.
+
+The run is resumable. Tasks are appended to the index as they complete, and a
+restart with the same --out picks up where it stopped, skipping every sequence
+already used. A 2,500-task build costs ~68,000 Graph API requests; losing that
+to a dropped connection at task 2,400 is not acceptable.
+
+Usage:
+    export MAPILLARY_API_KEY_TRAIN="MLY|..."
+    python scripts/build_tasks.py --tasks 2500 --mirror all --workers 8
+    python scripts/build_tasks.py --tasks 50 --mirror start   # quick trial
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import concurrent.futures
+import functools
+import hashlib
+import json
+import logging
+import pathlib
+import random
+import shutil
+import sys
+import threading
+import urllib.request
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+
+from build_pano_tasks import (  # noqa: E402
+    _get,
+    _month,
+    _token,
+    frame_detail,
+    sequence_frames,
+    TIMEOUT_S,
+)
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger("build_tasks")
+
+
+@functools.lru_cache(maxsize=1)
+def _country_paths():
+    """Country name and outline for each admin-0 polygon."""
+    from matplotlib.path import Path as MplPath
+
+    root = pathlib.Path(__file__).resolve().parents[1]
+    features = json.loads(
+        (root / "data" / "geo" / "ne_110m_admin_0_countries.geojson").read_text()
+    )["features"]
+    out = []
+    for feature in features:
+        geometry = feature["geometry"]
+        rings = (
+            [geometry["coordinates"][0]]
+            if geometry["type"] == "Polygon"
+            else [poly[0] for poly in geometry["coordinates"]]
+        )
+        for ring in rings:
+            out.append((feature["properties"]["ADMIN"], MplPath(ring)))
+    return out
+
+
+def country_of(lat: float, lon: float) -> str | None:
+    """Country containing a coordinate, or `None` over water."""
+    for name, path in _country_paths():
+        if path.contains_point((lon, lat)):
+            return name
+    return None
+
+
+def choose_candidates(
+    pool: list[dict],
+    wanted: int,
+    per_country: int,
+    per_creator: int,
+    density_exponent: float,
+    seed: int,
+    already: list[dict] | None = None,
+) -> list[dict]:
+    """
+    Order the pool so the first N candidates are worth assembling.
+
+    Applies the sampling weight from the OSV-5M paper: proportional to local
+    image density raised to `density_exponent`, negative by default, which sits
+    between density-proportional sampling (biased to cities) and
+    area-proportional sampling (biased to large countries). Then caps per
+    country and per creator, which matters as much: without a creator cap a
+    "global" set can be a few hundred drives.
+
+    Args:
+        pool (`list[dict]`):
+            Harvested sequences with `lat`, `lon`, `creator_id`.
+        wanted (`int`):
+            How many candidates to return, before assembly losses.
+        per_country (`int`):
+            Maximum tasks per country.
+        per_creator (`int`):
+            Maximum tasks per contributor.
+        density_exponent (`float`):
+            Exponent on local density; `-0.75` follows OSV-5M.
+        seed (`int`):
+            Seed for the weighted draw.
+        already (`list[dict]`, *optional*):
+            Tasks a resumed run already holds. Their countries and creators
+            count against the caps, so resuming cannot exceed a limit that a
+            single run would have respected.
+
+    Returns:
+        `list[dict]`: Candidates in the order they should be assembled.
+    """
+    rng = random.Random(seed)
+    cells = collections.Counter((round(row["lat"]), round(row["lon"])) for row in pool)
+    weighted = []
+    for row in pool:
+        cell = (round(row["lat"]), round(row["lon"]))
+        weight = cells[cell] ** density_exponent
+        # One exponential draw per item, ordered ascending, is a weighted
+        # sample without replacement.
+        weighted.append((rng.expovariate(1.0) / max(weight, 1e-9), row))
+    weighted.sort(key=lambda pair: pair[0])
+
+    country_count: collections.Counter = collections.Counter(
+        task["country"] for task in already or []
+    )
+    creator_count: collections.Counter = collections.Counter(
+        task["attribution"]["creator_id"] for task in already or []
+    )
+    chosen: list[dict] = []
+    unknown = 0
+    for _, row in weighted:
+        if len(chosen) >= wanted:
+            break
+        country = country_of(row["lat"], row["lon"])
+        if country is None:
+            unknown += 1
+            continue
+        creator = str(row.get("creator_id") or "")
+        if country_count[country] >= per_country:
+            continue
+        if creator and creator_count[creator] >= per_creator:
+            continue
+        country_count[country] += 1
+        creator_count[creator] += 1
+        row["__country"] = country
+        chosen.append(row)
+    logger.info(
+        "selected %d candidates across %d countries and %d creators "
+        "(%d anchors fell over water)",
+        len(chosen),
+        len(country_count),
+        len(creator_count),
+        unknown,
+    )
+    return chosen
+
+
+def mirror(
+    token: str,
+    image_ids: list[str],
+    cache: pathlib.Path,
+    workers: int,
+    originals: bool = False,
+) -> dict[str, str]:
+    """Download and hash frames concurrently; returns sha256 by image id."""
+
+    def one(image_id: str) -> tuple[str, str | None]:
+        path = cache / f"{image_id}.jpg"
+        if not path.exists():
+            fields = "thumb_2048_url"
+            meta = _get(token, image_id, fields=fields)
+            url = meta.get(fields) if "__error" not in meta else None
+            if not url:
+                return image_id, None
+            try:
+                with urllib.request.urlopen(url, timeout=TIMEOUT_S) as response:
+                    path.write_bytes(response.read())
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("  %s: %r", image_id, exc)
+                return image_id, None
+        return image_id, hashlib.sha256(path.read_bytes()).hexdigest()
+
+    checksums: dict[str, str] = {}
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as pool:
+        for image_id, digest in pool.map(one, image_ids):
+            if digest:
+                checksums[image_id] = digest
+
+    if originals and image_ids:
+        # Only the starting frame gets its full-resolution original: zoom needs
+        # it, and every frame would be 3.3 MB each.
+        first = image_ids[0]
+        path = cache / f"{first}.orig.jpg"
+        if not path.exists():
+            meta = _get(token, first, fields="thumb_original_url")
+            url = meta.get("thumb_original_url") if "__error" not in meta else None
+            if url:
+                try:
+                    with urllib.request.urlopen(url, timeout=TIMEOUT_S) as response:
+                        path.write_bytes(response.read())
+                except Exception as exc:  # noqa: BLE001
+                    logger.warning("  original for %s: %r", first, exc)
+    return checksums
+
+
+def assemble(token: str, candidate: dict, args: argparse.Namespace) -> dict | None:
+    """Turn one candidate sequence into a task, or `None` if it does not qualify."""
+    sequence_id = candidate["sequence_id"]
+    ids = sequence_frames(token, sequence_id)
+    if len(ids) < args.min_frames:
+        return None
+    anchor_id = str(candidate.get("image_id") or "")
+    position = ids.index(anchor_id) if anchor_id in ids else len(ids) // 2
+    low = max(0, position - args.frames // 2)
+    window = ids[low : low + args.frames]
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=args.frame_workers) as pool:
+        details = list(pool.map(lambda i: frame_detail(token, i), window))
+
+    frames = []
+    for detail in details:
+        if not detail or not detail.get("is_pano"):
+            continue
+        geometry = detail.get("computed_geometry") or detail.get("geometry")
+        if not geometry:
+            continue
+        lon, lat = geometry["coordinates"]
+        captured = _month(detail.get("captured_at"))
+        if captured and captured[:4] < "2010":
+            continue  # a zero captured_at renders as 1980 and breaks temporal splits
+        frames.append(
+            {
+                "image_id": str(detail["id"]),
+                "lat": lat,
+                "lon": lon,
+                "compass_angle": detail.get("computed_compass_angle")
+                or detail.get("compass_angle")
+                or 0.0,
+                "captured_at": captured,
+                "is_pano": True,
+            }
+        )
+    if len(frames) < args.min_frames:
+        return None
+
+    start = min(len(frames) // 2, len(frames) - 1)
+    start_frame = frames[start]
+    anchor_detail = next(
+        (d for d in details if d and str(d["id"]) == start_frame["image_id"]), {}
+    )
+
+    if args.mirror == "all":
+        wanted = [start_frame["image_id"]] + [
+            f["image_id"] for f in frames if f["image_id"] != start_frame["image_id"]
+        ]
+    else:
+        wanted = [start_frame["image_id"]]
+    checksums = mirror(
+        token, wanted, args.cache, args.frame_workers, originals=args.originals
+    )
+    if start_frame["image_id"] not in checksums:
+        return None
+
+    creator = anchor_detail.get("creator", {}) or {}
+    return {
+        "country": candidate["__country"],
+        "sequence_id": sequence_id,
+        "provider": "mapillary",
+        "start_frame": start,
+        "frames": frames,
+        "attribution": {
+            "creator_username": creator.get("username", ""),
+            "creator_id": creator.get("id", "") or candidate.get("creator_id", ""),
+            "licence": "CC-BY-SA-4.0",
+            "source": "Mapillary",
+        },
+        "meta": {
+            "camera_make": anchor_detail.get("make", ""),
+            "camera_model": anchor_detail.get("model", ""),
+            "quality_score": anchor_detail.get("quality_score")
+            or candidate.get("quality_score"),
+            "pool_tile": candidate.get("tile", ""),
+            "sha256": checksums,
+            "mirrored_frames": len(checksums),
+            "offline_ready": len(checksums) >= len(frames),
+        },
+    }
+
+
+MEAN_FRAME_BYTES = 0.26e6
+"""Mean size of a 2048x1024 derivative, measured over 964 cached files."""
+
+MEAN_ORIGINAL_BYTES = 1.8e6
+"""Mean size of a full-resolution original, measured over 29 cached files."""
+
+
+def resume(out: pathlib.Path) -> list[dict]:
+    """
+    Return the tasks already written to an index, ignoring a torn last line.
+
+    A run killed mid-write can leave a partial JSON object at the end of the
+    file. That line is dropped rather than raising, because the alternative is
+    discarding a complete 40-minute build over one truncated task.
+    """
+    if not out.exists():
+        return []
+    tasks = []
+    for number, line in enumerate(out.read_text().splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            tasks.append(json.loads(line))
+        except json.JSONDecodeError:
+            logger.warning("dropping torn line %d of %s", number, out)
+    for index, task in enumerate(tasks):
+        task["task_index"] = index
+        task["task_id"] = f"mly-{index:05d}"
+    return tasks
+
+
+def task_bytes(task: dict, cache: pathlib.Path) -> int:
+    """Bytes this task added to the cache, counted from its own frames only."""
+    total = 0
+    for frame in task["frames"]:
+        for name in (f"{frame['image_id']}.jpg", f"{frame['image_id']}.orig.jpg"):
+            path = cache / name
+            if path.exists():
+                total += path.stat().st_size
+    return total
+
+
+def check_disk(cache: pathlib.Path, remaining: int, args) -> None:
+    """
+    Refuse to start a mirror that cannot fit, before spending any API quota.
+
+    Raises:
+        SystemExit: When projected growth exceeds free space minus a 10 GB
+            headroom margin.
+    """
+    per_task = MEAN_FRAME_BYTES * (args.frames if args.mirror == "all" else 1)
+    if args.originals:
+        per_task += MEAN_ORIGINAL_BYTES
+    projected = per_task * remaining
+    free = shutil.disk_usage(cache).free
+    logger.info(
+        "mirror '%s' projects %.1f GB for %d tasks; %.1f GB free on %s",
+        args.mirror,
+        projected / 1e9,
+        remaining,
+        free / 1e9,
+        cache,
+    )
+    if projected + 10e9 > free:
+        raise SystemExit(
+            f"not enough space: need ~{projected / 1e9:.0f} GB plus 10 GB "
+            f"headroom, have {free / 1e9:.0f} GB free. Use --mirror start, "
+            f"lower --frames, or point --cache at a larger volume."
+        )
+
+
+def build(args: argparse.Namespace) -> None:
+    """Select, assemble and write the task index."""
+    token = _token()
+    args.cache.mkdir(parents=True, exist_ok=True)
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+
+    pool = [
+        json.loads(line) for line in args.pool.read_text().splitlines() if line.strip()
+    ]
+    logger.info("pool holds %d panorama sequences", len(pool))
+
+    done_tasks = resume(args.out)
+    if done_tasks:
+        logger.info(
+            "resuming: %d tasks already in %s, need %d more",
+            len(done_tasks),
+            args.out,
+            max(0, args.tasks - len(done_tasks)),
+        )
+        used = {t["sequence_id"] for t in done_tasks}
+        pool = [entry for entry in pool if entry["sequence_id"] not in used]
+
+    remaining = args.tasks - len(done_tasks)
+    if remaining <= 0:
+        logger.info("%s already holds %d tasks; nothing to do", args.out, args.tasks)
+        return
+    check_disk(args.cache, remaining, args)
+
+    # Over-select: some candidates lose their sequence listing, fall short on
+    # frames, or fail to mirror.
+    candidates = choose_candidates(
+        pool,
+        int(remaining * args.oversample),
+        args.per_country,
+        args.per_creator,
+        args.density_exponent,
+        args.seed,
+        already=done_tasks,
+    )
+
+    results: list[dict] = list(done_tasks)
+    lock = threading.Lock()
+    stats = {"tried": 0, "failed": 0, "mirrored": 0, "bytes": 0}
+    handle = args.out.open("a")
+
+    def work(candidate):
+        with lock:
+            if len(results) >= args.tasks:
+                return None
+        task = assemble(token, candidate, args)
+        with lock:
+            stats["tried"] += 1
+            if task is None:
+                stats["failed"] += 1
+                return None
+            if len(results) >= args.tasks:
+                return None
+            task["task_index"] = len(results)
+            task["task_id"] = f"mly-{len(results):05d}"
+            results.append(task)
+            stats["mirrored"] += task["meta"]["mirrored_frames"]
+            stats["bytes"] += task_bytes(task, args.cache)
+            # Append-and-flush so a killed run loses at most one task.
+            handle.write(json.dumps(task) + "\n")
+            handle.flush()
+        return task
+
+    from rich.progress import (
+        BarColumn,
+        MofNCompleteColumn,
+        Progress,
+        TextColumn,
+        TimeElapsedColumn,
+        TimeRemainingColumn,
+    )
+
+    progress = Progress(
+        TextColumn("[cyan]assembling tasks"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TextColumn(
+            "rejected={task.fields[failed]} · images={task.fields[mirrored]} · "
+            "{task.fields[gb]:.2f} GB"
+        ),
+        TimeElapsedColumn(),
+        TimeRemainingColumn(),
+    )
+    with progress:
+        task_id = progress.add_task(
+            "tasks",
+            total=args.tasks,
+            completed=len(results),
+            failed=0,
+            mirrored=0,
+            gb=0.0,
+        )
+        with concurrent.futures.ThreadPoolExecutor(max_workers=args.workers) as pool_x:
+            for _ in pool_x.map(work, candidates):
+                done = len(results)
+                progress.update(
+                    task_id,
+                    completed=min(done, args.tasks),
+                    failed=stats["failed"],
+                    mirrored=stats["mirrored"],
+                    gb=stats["bytes"] / 1e9,
+                )
+                if done >= args.tasks:
+                    break
+    handle.close()
+
+    results.sort(key=lambda t: t["task_index"])
+    args.out.write_text("".join(json.dumps(task) + "\n" for task in results))
+
+    countries = collections.Counter(t["country"] for t in results)
+    creators = {t["attribution"]["creator_id"] for t in results}
+    offline = sum(1 for t in results if t["meta"]["offline_ready"])
+    logger.info(
+        "\nwrote %d tasks to %s (%.0f KB)",
+        len(results),
+        args.out,
+        args.out.stat().st_size / 1024,
+    )
+    logger.info(
+        "countries %d · creators %d · fully offline %d/%d · candidates rejected %d",
+        len(countries),
+        len(creators),
+        offline,
+        len(results),
+        stats["failed"],
+    )
+    logger.info(
+        "cache now %.2f GB",
+        sum(p.stat().st_size for p in args.cache.glob("*.jpg")) / 1e9,
+    )
+    logger.info("next: python scripts/split_tasks.py %s --eval 200", args.out)
+
+
+def main() -> None:
+    """Command-line entry point."""
+    root = pathlib.Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--tasks", type=int, default=2500)
+    parser.add_argument("--per-country", type=int, default=60)
+    parser.add_argument("--per-creator", type=int, default=25)
+    parser.add_argument("--frames", type=int, default=24)
+    parser.add_argument("--min-frames", type=int, default=8)
+    parser.add_argument("--mirror", choices=["start", "all"], default="all")
+    parser.add_argument(
+        "--originals",
+        action="store_true",
+        help="Also mirror the start frame's 7680px original, so zoom works offline.",
+    )
+    parser.add_argument(
+        "--workers", type=int, default=8, help="Tasks assembled at once."
+    )
+    parser.add_argument(
+        "--frame-workers", type=int, default=6, help="Fetches within a task."
+    )
+    parser.add_argument("--oversample", type=float, default=2.0)
+    parser.add_argument("--density-exponent", type=float, default=-0.75)
+    parser.add_argument("--seed", type=int, default=7)
+    parser.add_argument(
+        "--pool", type=pathlib.Path, default=root / "data" / "pool" / "sequences.jsonl"
+    )
+    parser.add_argument(
+        "--out", type=pathlib.Path, default=root / "tasks" / "pool_v1.jsonl"
+    )
+    parser.add_argument("--cache", type=pathlib.Path, default=root / "data" / "panos")
+    build(parser.parse_args())
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/deploy_hub.py

@@ -0,0 +1,427 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Deploy the GeoGuesser environment to the Hugging Face Hub.
+
+Three artifacts, split by what each is good at:
+
+    bucket   HuggingEnvs/geoguesser-panos   22 GB of imagery + both indexes
+    dataset  HuggingEnvs/geoguesser-tasks    the indexes alone, versioned
+    space    HuggingEnvs/geoguesser-env      the running environment
+
+The bucket exists because Space disk is ephemeral and capped well below 22 GB,
+and because buckets are mutable object storage rather than git. The dataset repo
+exists because a bucket is *not* versioned: a frozen benchmark needs a place
+where a change to it is visible in history. The Space mounts the bucket
+read-only at /data, so the same image serves a local checkout and the Hub with
+nothing but environment variables between them.
+
+`openenv push` is deliberately not used: it cannot attach a bucket volume, and
+its default excludes would upload 22 GB of panoramas into git.
+
+Usage:
+    export HF_TOKEN=hf_...
+    python scripts/deploy_hub.py --all
+    python scripts/deploy_hub.py --space          # code only, fast iteration
+    python scripts/deploy_hub.py --verify         # check a live deployment
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import pathlib
+import shutil
+import sys
+import tempfile
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger("deploy_hub")
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+REPO_ROOT = ROOT.parents[1]
+
+ORG = os.getenv("GEOGUESSER_HF_ORG", "HuggingEnvs")
+SPACE_ID = f"{ORG}/geoguesser-env"
+BUCKET_ID = f"{ORG}/geoguesser-panos"
+DATASET_ID = f"{ORG}/geoguesser-tasks"
+MOUNT_PATH = "/data"
+
+EVAL_INDEX = "eval_pano_v3.jsonl"
+TRAIN_INDEX = "train_pano_v3.jsonl"
+
+# Anything matching these never reaches the Space repo. The panorama cache and
+# the sequence pool are the dangerous ones: 22 GB and 254 MB respectively.
+SPACE_EXCLUDES = (
+    "geoguesser_env/data/panos/*",
+    "geoguesser_env/data/pool/*",
+    f"geoguesser_env/tasks/{TRAIN_INDEX}",
+    "geoguesser_env/tasks/pool_offline_5k.jsonl",
+    "geoguesser_env/tasks/eval_pano_v1.jsonl",
+    "geoguesser_env/tasks/eval_pano_v2.jsonl",
+    "geoguesser_env/tasks/eval_balanced_trial.jsonl",
+    "geoguesser_env/rollouts/*",
+    "geoguesser_env/tests/*",
+    "geoguesser_env/.venv/*",
+    "**/__pycache__/*",
+    "**/*.pyc",
+    "src/**/__pycache__/*",
+)
+
+SPACE_VARIABLES = {
+    "ENABLE_WEB_INTERFACE": "true",
+    "GEOGUESSER_TASKS_EVAL": f"{MOUNT_PATH}/tasks/{EVAL_INDEX}",
+    "GEOGUESSER_TASKS_TRAIN": f"{MOUNT_PATH}/tasks/{TRAIN_INDEX}",
+    "GEOGUESSER_DEFAULT_SPLIT": "train",
+    "GEOGUESSER_CACHE": f"{MOUNT_PATH}/panos",
+    # The mirror is complete, so a cache miss is a bug worth hearing about
+    # rather than something to paper over with a network call.
+    "GEOGUESSER_ALLOW_FETCH": "0",
+    # Overpass only, and it caches to the container's own disk, so labelled
+    # streets work even with imagery fetching disabled.
+    "GEOGUESSER_STREET_DETAIL": "1",
+    "GEOGUESSER_MAX_STEPS": "24",
+}
+
+CARD_FRONTMATTER = """---
+title: Geoguesser Environment
+emoji: 🌍
+colorFrom: green
+colorTo: blue
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
+  - reinforcement-learning
+  - geolocation
+  - mcp-server
+---
+
+"""
+
+
+def token() -> str:
+    """Resolve an HF token from the environment or the repo `.env`."""
+    for name in ("HF_TOKEN", "HUGGING_FACE_HUB_TOKEN"):
+        value = os.getenv(name)
+        if value:
+            return value
+    env_file = REPO_ROOT / ".env"
+    if env_file.exists():
+        for line in env_file.read_text().splitlines():
+            if line.startswith("HF_TOKEN="):
+                return line.split("=", 1)[1].strip().strip('"').strip("'")
+    raise SystemExit("no HF_TOKEN; export it or add it to the repo .env")
+
+
+def stage_space(staging: pathlib.Path) -> None:
+    """
+    Assemble the Space repository layout.
+
+    The Space is self-contained: it vendors `src/openenv` rather than installing
+    a release, because the Gradio tab naming this environment uses is newer than
+    the published package.
+    """
+    shutil.copytree(
+        REPO_ROOT / "src",
+        staging / "src",
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.egg-info"),
+    )
+    shutil.copytree(
+        ROOT,
+        staging / "geoguesser_env",
+        ignore=shutil.ignore_patterns(
+            "__pycache__",
+            "*.pyc",
+            ".venv",
+            "panos",
+            "pool",
+            "rollouts",
+            "tests",
+            "space",
+            "osm_cache",
+            TRAIN_INDEX,
+            "pool_offline_5k.jsonl",
+            "eval_pano_v1.jsonl",
+            "eval_pano_v2.jsonl",
+            "eval_balanced_trial.jsonl",
+        ),
+    )
+    shutil.copy(ROOT / "space" / "Dockerfile", staging / "Dockerfile")
+    # The card is the env README with Space frontmatter prepended, so the Hub
+    # page and the repo documentation cannot drift apart.
+    body = (ROOT / "README.md").read_text()
+    if body.startswith("---"):
+        body = body.split("---", 2)[-1].lstrip()
+    (staging / "README.md").write_text(CARD_FRONTMATTER + body)
+
+    # The detail vectors drive the labelled maps and are gitignored locally, so
+    # confirm they made it rather than shipping a Space with bare maps.
+    detail = staging / "geoguesser_env" / "data" / "geo" / "detail"
+    present = sorted(p.name for p in detail.glob("*.json")) if detail.exists() else []
+    missing = {"places.json", "roads.json", "rivers.json", "urban.json"} - set(present)
+    if missing:
+        logger.warning(
+            "detail vectors missing from the staged Space: %s -- agent maps will "
+            "have no towns or roads. Run scripts/fetch_detail_geo.py first.",
+            sorted(missing),
+        )
+    size = sum(p.stat().st_size for p in staging.rglob("*") if p.is_file())
+    logger.info(
+        "staged %d files, %.1f MB",
+        sum(1 for p in staging.rglob("*") if p.is_file()),
+        size / 1e6,
+    )
+    if size > 500e6:
+        raise SystemExit(
+            f"staged Space is {size / 1e6:.0f} MB, which means an exclude did "
+            "not match. Refusing to push."
+        )
+
+
+def push_space(hf_token: str) -> None:
+    """Create the Space if needed, upload the code, and wire up its runtime."""
+    from huggingface_hub import HfApi, Volume
+
+    api = HfApi(token=hf_token)
+    api.create_repo(
+        SPACE_ID, repo_type="space", space_sdk="docker", private=False, exist_ok=True
+    )
+
+    with tempfile.TemporaryDirectory() as tmp:
+        staging = pathlib.Path(tmp) / "space"
+        staging.mkdir()
+        stage_space(staging)
+        logger.info("uploading to %s", SPACE_ID)
+        api.upload_folder(
+            repo_id=SPACE_ID,
+            repo_type="space",
+            folder_path=str(staging),
+            ignore_patterns=list(SPACE_EXCLUDES),
+            commit_message="Deploy geoguesser environment with train/eval splits",
+        )
+
+    for key, value in SPACE_VARIABLES.items():
+        api.add_space_variable(repo_id=SPACE_ID, key=key, value=value)
+    logger.info("set %d Space variables", len(SPACE_VARIABLES))
+
+    # set_space_volumes REPLACES the whole list, so anything already attached
+    # has to be carried forward or it is silently unmounted.
+    existing = []
+    try:
+        existing = list(api.get_space_runtime(SPACE_ID).volumes or [])
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("could not read current volumes: %r", exc)
+    keep = [
+        v
+        for v in existing
+        if getattr(v, "mount_path", None) != MOUNT_PATH
+        and getattr(v, "source", None) != BUCKET_ID
+    ]
+    api.set_space_volumes(
+        repo_id=SPACE_ID,
+        volumes=keep
+        + [
+            Volume(
+                type="bucket",
+                source=BUCKET_ID,
+                mount_path=MOUNT_PATH,
+                read_only=True,
+            )
+        ],
+    )
+    logger.info("mounted %s read-only at %s", BUCKET_ID, MOUNT_PATH)
+    logger.info("space: https://huggingface.co/spaces/%s", SPACE_ID)
+
+
+def push_dataset(hf_token: str) -> None:
+    """Publish the task indexes and a card describing how they were built."""
+    from huggingface_hub import HfApi
+
+    api = HfApi(token=hf_token)
+    api.create_repo(DATASET_ID, repo_type="dataset", private=False, exist_ok=True)
+
+    eval_path = ROOT / "tasks" / EVAL_INDEX
+    train_path = ROOT / "tasks" / TRAIN_INDEX
+    stats = {}
+    for name, path in (("eval", eval_path), ("train", train_path)):
+        if not path.exists():
+            logger.warning("%s missing, skipping: %s", name, path)
+            continue
+        rows = [
+            json.loads(line) for line in path.read_text().splitlines() if line.strip()
+        ]
+        stats[name] = {
+            "tasks": len(rows),
+            "countries": len({r["country"] for r in rows}),
+            "frames": sum(len(r["frames"]) for r in rows),
+            "offline": sum(1 for r in rows if r["meta"].get("offline_ready")),
+        }
+
+    with tempfile.TemporaryDirectory() as tmp:
+        staging = pathlib.Path(tmp)
+        for path in (eval_path, train_path):
+            if path.exists():
+                shutil.copy(path, staging / path.name)
+        (staging / "README.md").write_text(dataset_card(stats))
+        api.upload_folder(
+            repo_id=DATASET_ID,
+            repo_type="dataset",
+            folder_path=str(staging),
+            commit_message="GeoGuesser task splits",
+        )
+    logger.info("dataset: https://huggingface.co/datasets/%s", DATASET_ID)
+
+
+def dataset_card(stats: dict) -> str:
+    """Render the dataset card from measured figures, never hardcoded ones."""
+    rows = "\n".join(
+        f"| `{name}` | {s['tasks']} | {s['countries']} | {s['frames']} | "
+        f"{s['offline']}/{s['tasks']} |"
+        for name, s in stats.items()
+    )
+    return f"""---
+license: cc-by-sa-4.0
+task_categories:
+  - image-classification
+tags:
+  - geolocation
+  - openenv
+  - reinforcement-learning
+pretty_name: GeoGuesser Task Splits
+---
+
+# GeoGuesser Task Splits
+
+Task indexes for the [GeoGuesser OpenEnv environment](https://huggingface.co/spaces/{SPACE_ID}).
+Each line is one episode: an ordered list of panorama frames with coordinates,
+headings and capture dates, plus the sequence and contributor it came from.
+
+| Split | Tasks | Countries | Frames | Fully mirrored |
+|---|---|---|---|---|
+{rows}
+
+## What a task is
+
+These files carry **metadata only**, not imagery. Every frame's coordinates,
+heading and capture date are here, so the movement graph resolves with no
+network access; only image bytes need fetching, and Mapillary's `thumb_*_url`
+values are expiring signed CDN URLs that cannot be stored. Resolve them from
+`image_id` through the Mapillary Graph API, or mirror them once with
+`scripts/build_tasks.py` from the environment repository.
+
+## How the split was made
+
+Both splits are carved from one 3,673-task pool, so contamination is enforced
+exactly once rather than reasoned about across two separate harvests. The rules
+follow the OSV-5M paper, which built its train/test split from the same
+Mapillary source:
+
+- no shared `sequence_id` between splits
+- no training task within **1 km** of an eval task
+
+The buffer matters because frames sit about 3.3 m apart: holding out an image
+while keeping its neighbour holds out nothing. The split script verifies its own
+output and exits non-zero if either rule is violated.
+
+Eval is carved first, balanced by country and capped at 4 tasks each, because at
+a couple of hundred tasks the balance decides what the score means. An earlier
+unbalanced attempt put 28% of the set in one country.
+
+## Provenance
+
+Imagery is from [Mapillary](https://www.mapillary.com), CC BY-SA 4.0. Each task
+records its contributor in `attribution`, which the environment displays. Only
+360-degree panoramas are included (`camera_type == "spherical"`; note that the
+documented value `equirectangular` does not appear in practice).
+
+Sequences were discovered by enumerating Mapillary's `mly1_public` vector tiles
+at zoom 6, where the sequence layer carries `is_pano` — 1.2 million panorama
+sequences worldwide. Candidates are sampled with weight proportional to local
+image density raised to **-0.75**, the OSV-5M weighting, then capped per country
+and per contributor: one contributor alone holds 8% of the pool.
+
+## Reproducing
+
+```bash
+git clone https://github.com/huggingface/OpenEnv
+cd OpenEnv/envs/geoguesser_env
+export MAPILLARY_API_KEY_TRAIN="MLY|..."
+
+python scripts/harvest_tiles.py                 # enumerate sequences worldwide
+./scripts/build_dataset.sh                      # assemble and mirror tasks
+python scripts/verify_offline.py tasks/pool_offline_5k.jsonl
+python scripts/split_tasks.py tasks/pool_offline_5k.jsonl --eval 200
+```
+
+A rebuild will not reproduce these exact tasks — the pool is sampled and
+upstream coverage changes — which is precisely why the split is published rather
+than left to be regenerated.
+"""
+
+
+def verify(hf_token: str) -> int:
+    """Exercise a deployed Space the way a client would. Returns an exit code."""
+    import urllib.error
+    import urllib.request
+
+    base = f"https://{ORG.lower()}-geoguesser-env.hf.space"
+    logger.info("verifying %s", base)
+    failures = []
+
+    def get(path: str) -> object:
+        request = urllib.request.Request(
+            base + path, headers={"Authorization": f"Bearer {hf_token}"}
+        )
+        with urllib.request.urlopen(request, timeout=60) as response:
+            return json.loads(response.read())
+
+    try:
+        get("/health")
+        logger.info("  [PASS] /health")
+    except Exception as exc:  # noqa: BLE001
+        failures.append(f"/health: {exc!r}")
+        logger.error("  [FAIL] /health: %r", exc)
+        return 1
+
+    try:
+        splits = get("/geoguesser_env/splits")
+        names = {s["name"]: s["num_tasks"] for s in splits}
+        logger.info("  [PASS] /splits -> %s", names)
+        if "eval" not in names:
+            failures.append("no eval split; is the bucket mounted?")
+    except Exception as exc:  # noqa: BLE001
+        failures.append(f"/splits: {exc!r}")
+        logger.error("  [FAIL] /splits: %r", exc)
+
+    for failure in failures:
+        logger.error("  %s", failure)
+    return 1 if failures else 0
+
+
+def main() -> None:
+    """Command-line entry point."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--all", action="store_true", help="Space and dataset.")
+    parser.add_argument("--space", action="store_true")
+    parser.add_argument("--dataset", action="store_true")
+    parser.add_argument("--verify", action="store_true")
+    args = parser.parse_args()
+
+    if not any((args.all, args.space, args.dataset, args.verify)):
+        parser.error("pick at least one of --all, --space, --dataset, --verify")
+
+    hf_token = token()
+    if args.all or args.dataset:
+        push_dataset(hf_token)
+    if args.all or args.space:
+        push_space(hf_token)
+    if args.verify:
+        sys.exit(verify(hf_token))
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/fetch_detail_geo.py

@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Fetch the optional detail layers the guess map draws when zoomed in.
+
+Without these the agent's map shows country outlines and major cities only,
+which is enough to place a country but not to choose a point within a city. The
+human's map is street-level, so the two disagree about how precisely a pin can
+be aimed — and precision is exactly what the distance reward measures.
+
+The layers are Natural Earth 10m: roads, urban areas, river centrelines and
+populated places. They total ~87 MB as raw GeoJSON, too large to commit, so
+they are fetched once and compacted here into small arrays holding only the
+geometry and the name, with coordinates rounded to 4 decimals (about 11 m,
+finer than the panorama spacing).
+
+Usage:
+    python scripts/fetch_detail_geo.py
+    python scripts/fetch_detail_geo.py --layers roads places
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import urllib.request
+
+BASE = "https://raw.githubusercontent.com/nvkelso/natural-earth-vector/master/geojson"
+
+LAYERS: dict[str, tuple[str, str | None]] = {
+    # name: (source file, property holding a label)
+    "roads": ("ne_10m_roads", None),
+    "urban": ("ne_10m_urban_areas", None),
+    "rivers": ("ne_10m_rivers_lake_centerlines", None),
+    "places": ("ne_10m_populated_places_simple", "name"),
+}
+
+PRECISION = 4
+
+
+def _round(coordinates):
+    """Round coordinates in place, at any nesting depth."""
+    if isinstance(coordinates[0], (int, float)):
+        return [
+            round(float(coordinates[0]), PRECISION),
+            round(float(coordinates[1]), PRECISION),
+        ]
+    return [_round(part) for part in coordinates]
+
+
+def compact(features: list[dict], label: str | None) -> list[dict]:
+    """Strip a Natural Earth layer to geometry plus one optional label."""
+    out = []
+    for feature in features:
+        geometry = feature.get("geometry")
+        if not geometry or not geometry.get("coordinates"):
+            continue
+        row = {
+            "t": geometry["type"],
+            "c": _round(geometry["coordinates"]),
+        }
+        if label:
+            row["n"] = feature.get("properties", {}).get(label) or ""
+        out.append(row)
+    return out
+
+
+def fetch(names: list[str], out_dir: pathlib.Path) -> None:
+    """Download and compact each requested layer."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for name in names:
+        source, label = LAYERS[name]
+        url = f"{BASE}/{source}.geojson"
+        print(f"{name}: downloading {source}.geojson", flush=True)
+        with urllib.request.urlopen(url, timeout=300) as response:
+            payload = json.loads(response.read())
+        rows = compact(payload["features"], label)
+        target = out_dir / f"{name}.json"
+        target.write_text(json.dumps(rows, separators=(",", ":")))
+        print(
+            f"{name}: {len(rows):,} features -> {target.name} "
+            f"({target.stat().st_size / 1e6:.1f} MB)",
+            flush=True,
+        )
+
+
+def main() -> None:
+    """Command-line entry point."""
+    root = pathlib.Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--layers", nargs="+", choices=sorted(LAYERS), default=sorted(LAYERS)
+    )
+    parser.add_argument(
+        "--out", type=pathlib.Path, default=root / "data" / "geo" / "detail"
+    )
+    args = parser.parse_args()
+    fetch(args.layers, args.out)
+    print(
+        "\nThe guess map will now draw roads, towns and urban areas when zoomed in. "
+        "Delete the directory to go back to outlines only."
+    )
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/harvest_tiles.py

@@ -0,0 +1,330 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Enumerate panorama sequences worldwide from Mapillary coverage tiles.
+
+This replaces point probing. Probing a coordinate and searching a small box
+finds a panorama about 5% of the time at 45 m boxes and 26% at city centres,
+and each request answers for one spot. A single z6 tile from the `mly1_public`
+**sequence** layer instead returns every sequence crossing roughly 600 km of
+ground, each feature already carrying `is_pano`, an anchor `image_id`,
+`creator_id` and `quality_score`. Measured, one request each:
+
+    Denver   z6   71,752 sequences   18,587 panoramic   7.3 MB   3.5 s
+    Paris    z6   85,920 sequences   11,617 panoramic   8.6 MB   4.2 s
+    Nairobi  z6    8,491 sequences    1,670 panoramic   0.8 MB   1.3 s
+
+The world is 4,096 tiles at z6 and 1,059 of them intersect land, so a complete
+pass is about 4 GB and uses 2% of the 50,000/day tile budget — with full recall
+rather than a lottery.
+
+Output is a pool of candidate sequences, not tasks. Assembling frames is a
+separate, slower step, and keeping them apart means you can harvest once and
+sample from the pool as often as you like.
+
+Usage:
+    export MAPILLARY_API_KEY="MLY|..."
+    python scripts/harvest_tiles.py                    # whole world, z6
+    python scripts/harvest_tiles.py --zoom 6 --workers 6
+    python scripts/harvest_tiles.py --bbox -10 35 30 60    # Europe only
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import functools
+import json
+import logging
+import math
+import pathlib
+import sys
+import threading
+import time
+import urllib.request
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+
+from build_pano_tasks import _token  # noqa: E402
+
+
+TILE_URL = "https://tiles.mapillary.com/maps/vtp/mly1_public/2/{z}/{x}/{y}"
+SEQUENCE_LAYER = "sequence"
+USER_AGENT = "openenv-geoguesser-env/0.1 (research environment)"
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger("harvest_tiles")
+
+
+def tile_bounds(z: int, x: int, y: int) -> tuple[float, float, float, float]:
+    """Return `(west, south, east, north)` in degrees for one tile."""
+    n = 2**z
+    west = x / n * 360.0 - 180.0
+    east = (x + 1) / n * 360.0 - 180.0
+    north = math.degrees(math.atan(math.sinh(math.pi * (1 - 2 * y / n))))
+    south = math.degrees(math.atan(math.sinh(math.pi * (1 - 2 * (y + 1) / n))))
+    return west, south, east, north
+
+
+@functools.lru_cache(maxsize=1)
+def _land_paths():
+    """Country outlines from the bundled Natural Earth file."""
+    from matplotlib.path import Path as MplPath
+
+    root = pathlib.Path(__file__).resolve().parents[1]
+    features = json.loads(
+        (root / "data" / "geo" / "ne_110m_admin_0_countries.geojson").read_text()
+    )["features"]
+    paths = []
+    for feature in features:
+        geometry = feature["geometry"]
+        rings = (
+            [geometry["coordinates"][0]]
+            if geometry["type"] == "Polygon"
+            else [poly[0] for poly in geometry["coordinates"]]
+        )
+        paths.extend(MplPath(ring) for ring in rings)
+    return paths
+
+
+def land_tiles(
+    zoom: int, bbox: tuple[float, float, float, float] | None
+) -> list[tuple[int, int]]:
+    """Tiles that intersect land, optionally restricted to a bounding box.
+
+    A tile counts as land if its centre or any corner falls inside a country
+    polygon. Antarctica and the high Arctic are skipped — no imagery, and they
+    would be a fifth of the work.
+    """
+    paths = _land_paths()
+    n = 2**zoom
+    keep = []
+    for x in range(n):
+        for y in range(n):
+            west, south, east, north = tile_bounds(zoom, x, y)
+            if north < -58 or south > 78:
+                continue
+            if bbox:
+                if (
+                    east < bbox[0]
+                    or west > bbox[2]
+                    or north < bbox[1]
+                    or south > bbox[3]
+                ):
+                    continue
+            probes = [
+                ((west + east) / 2, (south + north) / 2),
+                (west, south),
+                (east, south),
+                (west, north),
+                (east, north),
+            ]
+            if any(path.contains_point(p) for p in probes for path in paths):
+                keep.append((x, y))
+    return keep
+
+
+def fetch_tile(token: str, zoom: int, x: int, y: int, retries: int = 2) -> bytes | None:
+    """Fetch one coverage tile, or `None` when it cannot be had."""
+    url = TILE_URL.format(z=zoom, x=x, y=y) + f"?access_token={token}"
+    for attempt in range(retries + 1):
+        try:
+            request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+            with urllib.request.urlopen(request, timeout=90) as response:
+                return response.read()
+        except Exception as exc:  # noqa: BLE001 - a lost tile is not fatal
+            if attempt == retries:
+                logger.warning("tile %d/%d/%d failed: %r", zoom, x, y, exc)
+                return None
+            time.sleep(1.5 * (attempt + 1))
+    return None
+
+
+def sequences_in_tile(raw: bytes, zoom: int, x: int, y: int) -> list[dict]:
+    """Decode a tile and return its panoramic sequence features.
+
+    Tile geometry is in local integer coordinates, so the first vertex of each
+    LineString is converted back to longitude and latitude. That position is
+    approximate — low-zoom geometry is simplified — and is used only for
+    sampling and country capping; exact coordinates come from the Graph API when
+    frames are assembled.
+    """
+    import mapbox_vector_tile
+
+    try:
+        decoded = mapbox_vector_tile.decode(raw)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("tile %d/%d/%d did not decode: %r", zoom, x, y, exc)
+        return []
+
+    layer = decoded.get(SEQUENCE_LAYER)
+    if not layer:
+        return []
+    extent = layer.get("extent", 4096)
+    west, south, east, north = tile_bounds(zoom, x, y)
+
+    out = []
+    for feature in layer.get("features", []):
+        properties = feature.get("properties", {})
+        if properties.get("is_pano") not in (True, 1, "true"):
+            continue
+        geometry = feature.get("geometry", {})
+        coords = geometry.get("coordinates") or []
+        while coords and isinstance(coords[0], (list, tuple)):
+            coords = coords[0]
+        if len(coords) < 2:
+            continue
+        local_x, local_y = float(coords[0]), float(coords[1])
+        lon = west + (local_x / extent) * (east - west)
+        lat = south + (local_y / extent) * (north - south)
+        if not (-90 <= lat <= 90 and -180 <= lon <= 180):
+            continue
+        out.append(
+            {
+                "sequence_id": properties.get("id"),
+                "image_id": properties.get("image_id"),
+                "creator_id": properties.get("creator_id"),
+                "quality_score": properties.get("quality_score"),
+                "captured_at": properties.get("captured_at"),
+                "lat": round(lat, 5),
+                "lon": round(lon, 5),
+                "tile": f"{zoom}/{x}/{y}",
+            }
+        )
+    return out
+
+
+def harvest(args: argparse.Namespace) -> None:
+    """Walk the tiles and write the sequence pool."""
+    token = _token()
+    tiles = land_tiles(args.zoom, tuple(args.bbox) if args.bbox else None)
+    if args.limit:
+        tiles = tiles[: args.limit]
+    logger.info(
+        "z%d: %d tiles to fetch, %d workers, budget is 50,000 tiles/day (%.1f%% of it)",
+        args.zoom,
+        len(tiles),
+        args.workers,
+        100 * len(tiles) / 50_000,
+    )
+
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    seen: set[str] = set()
+    lock = threading.Lock()
+    stats = {"tiles": 0, "bytes": 0, "features": 0, "kept": 0, "failed": 0}
+    handle = args.out.open("w")
+
+    def work(tile):
+        x, y = tile
+        raw = fetch_tile(token, args.zoom, x, y)
+        if raw is None:
+            with lock:
+                stats["failed"] += 1
+            return
+        rows = sequences_in_tile(raw, args.zoom, x, y)
+        with lock:
+            stats["tiles"] += 1
+            stats["bytes"] += len(raw)
+            stats["features"] += len(rows)
+            for row in rows:
+                sequence_id = row["sequence_id"]
+                # Sequences cross tile boundaries and appear in every tile they
+                # touch, so the pool is deduplicated as it is written.
+                if not sequence_id or sequence_id in seen:
+                    continue
+                seen.add(sequence_id)
+                handle.write(json.dumps(row) + "\n")
+                stats["kept"] += 1
+
+    try:
+        from rich.progress import (
+            BarColumn,
+            MofNCompleteColumn,
+            Progress,
+            TextColumn,
+            TimeElapsedColumn,
+            TimeRemainingColumn,
+        )
+
+        progress = Progress(
+            TextColumn("[cyan]harvesting tiles"),
+            BarColumn(),
+            MofNCompleteColumn(),
+            TextColumn(
+                "sequences={task.fields[kept]} · {task.fields[mb]:.0f} MB · "
+                "failed={task.fields[failed]}"
+            ),
+            TimeElapsedColumn(),
+            TimeRemainingColumn(),
+        )
+        with progress:
+            task_id = progress.add_task(
+                "tiles", total=len(tiles), kept=0, mb=0.0, failed=0
+            )
+            with concurrent.futures.ThreadPoolExecutor(
+                max_workers=args.workers
+            ) as pool:
+                for _ in pool.map(work, tiles):
+                    progress.update(
+                        task_id,
+                        advance=1,
+                        kept=stats["kept"],
+                        mb=stats["bytes"] / 1e6,
+                        failed=stats["failed"],
+                    )
+    except ImportError:  # pragma: no cover - rich ships with openenv
+        logger.info("rich not installed, falling back to plain logging")
+        with concurrent.futures.ThreadPoolExecutor(max_workers=args.workers) as pool:
+            for index, _ in enumerate(pool.map(work, tiles), 1):
+                if index % 25 == 0:
+                    logger.info(
+                        "  %d/%d tiles, %d sequences, %.0f MB",
+                        index,
+                        len(tiles),
+                        stats["kept"],
+                        stats["bytes"] / 1e6,
+                    )
+    finally:
+        handle.close()
+
+    logger.info(
+        "\n%d unique panorama sequences -> %s (%.1f MB)",
+        stats["kept"],
+        args.out,
+        args.out.stat().st_size / 1e6,
+    )
+    logger.info(
+        "read %d tiles (%d failed), %.1f GB of tiles, %d raw features before dedupe",
+        stats["tiles"],
+        stats["failed"],
+        stats["bytes"] / 1e9,
+        stats["features"],
+    )
+    logger.info("next: python scripts/build_tasks.py --tasks 2500")
+
+
+def main() -> None:
+    """Command-line entry point."""
+    root = pathlib.Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--zoom", type=int, default=6, help="Sequence layer is served from z6."
+    )
+    parser.add_argument("--workers", type=int, default=6)
+    parser.add_argument(
+        "--limit", type=int, default=0, help="Stop after this many tiles."
+    )
+    parser.add_argument(
+        "--bbox",
+        nargs=4,
+        type=float,
+        metavar=("WEST", "SOUTH", "EAST", "NORTH"),
+        help="Restrict to a bounding box, for a quick trial run.",
+    )
+    parser.add_argument(
+        "--out", type=pathlib.Path, default=root / "data" / "pool" / "sequences.jsonl"
+    )
+    harvest(parser.parse_args())
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/merge_task_indexes.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Merge task indexes from several discovery passes into one frozen index.
+
+Panorama discovery has a low hit rate — roughly 5% of probe points yield a
+360-degree panorama — so reaching a target task count usually takes more than
+one pass with different seeds. Merging is not a plain concatenation: sequences
+must not repeat across passes, per-country caps must hold over the union, and
+`task_index` must come out contiguous from zero because the backend requires
+that.
+
+Usage:
+    python scripts/merge_task_indexes.py pass1.jsonl pass2.jsonl \\
+        --out tasks/pano_v1.jsonl --limit 100 --max-per-country 4
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import json
+import pathlib
+
+
+def load(path: pathlib.Path) -> list[dict]:
+    """Read one JSONL index."""
+    return [json.loads(line) for line in path.read_text().splitlines() if line.strip()]
+
+
+def merge(
+    sources: list[pathlib.Path],
+    limit: int,
+    max_per_country: int,
+    require_country: bool,
+) -> list[dict]:
+    """
+    Combine indexes, dropping duplicates and re-numbering.
+
+    Args:
+        sources (`list[pathlib.Path]`):
+            Index files, in priority order — earlier files win a tie.
+        limit (`int`):
+            Maximum number of tasks to keep.
+        max_per_country (`int`):
+            Cap per country across the union, so one well-mapped country
+            cannot dominate the set.
+        require_country (`bool`):
+            Drop tasks whose coordinate fell outside the country polygons.
+
+    Returns:
+        `list[dict]`: Merged rows with contiguous `task_index` and rewritten
+        `task_id`.
+    """
+    seen_sequences: set[str] = set()
+    seen_images: set[str] = set()
+    per_country: collections.Counter = collections.Counter()
+    merged: list[dict] = []
+
+    for path in sources:
+        for row in load(path):
+            if len(merged) >= limit:
+                break
+            country = row.get("country", "unknown")
+            if require_country and country == "unknown":
+                continue
+            sequence = row.get("sequence_id", "")
+            if sequence in seen_sequences:
+                continue
+            start_image = row["frames"][row["start_frame"]]["image_id"]
+            if start_image in seen_images:
+                continue
+            if per_country[country] >= max_per_country:
+                continue
+
+            seen_sequences.add(sequence)
+            seen_images.add(start_image)
+            per_country[country] += 1
+            row["task_index"] = len(merged)
+            row["task_id"] = f"mly-{len(merged):04d}"
+            merged.append(row)
+
+    return merged
+
+
+def main() -> None:
+    """Command-line entry point."""
+    root = pathlib.Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("sources", nargs="+", type=pathlib.Path)
+    parser.add_argument(
+        "--out", type=pathlib.Path, default=root / "tasks" / "pano_v1.jsonl"
+    )
+    parser.add_argument("--limit", type=int, default=100)
+    parser.add_argument("--max-per-country", type=int, default=4)
+    parser.add_argument("--allow-unknown-country", action="store_true")
+    args = parser.parse_args()
+
+    merged = merge(
+        args.sources,
+        limit=args.limit,
+        max_per_country=args.max_per_country,
+        require_country=not args.allow_unknown_country,
+    )
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    with args.out.open("w") as handle:
+        for row in merged:
+            handle.write(json.dumps(row) + "\n")
+
+    countries = collections.Counter(row["country"] for row in merged)
+    continents = collections.Counter(row["meta"].get("continent") for row in merged)
+    print(f"merged {len(merged)} tasks into {args.out}")
+    print(f"  countries : {len(countries)}")
+    print(f"  continents: {dict(continents)}")
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/readiness_check.py

@@ -0,0 +1,352 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Audit whether the environment is fit to train against.
+
+The unit tests cover behaviour on four committed fixtures. This checks the
+properties that only show up at the scale and concurrency of a real run:
+
+- every task in the index actually renders, so a rollout cannot die on task 87
+- observations are byte-identical across separate processes, not just repeated
+  resets in one, which is what a distributed GRPO group depends on
+- concurrent episodes stay isolated, so parallel rollouts do not interleave
+- a warm cache needs no network, so training can run air-gapped
+- reward is discriminative: a random guesser must score near zero and a
+  land-centroid guesser only slightly better, or the signal is not measuring
+  geolocation
+- per-step latency, so a rollout budget can be estimated
+
+Usage:
+    python scripts/readiness_check.py
+    python scripts/readiness_check.py --full        # render every task
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import hashlib
+import json
+import math
+import pathlib
+import random
+import statistics
+import subprocess
+import sys
+import time
+
+# The environment package uses relative imports, so it has to be imported as
+# `geoguesser_env.*` with the envs directory on the path, exactly as the tests
+# and examples do.
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2]))
+
+from geoguesser_env.models import (  # noqa: E402
+    GuessAction,
+    LookAction,
+    PinAction,
+    to_wire,
+)
+from geoguesser_env.server.geoguesser_environment import (  # noqa: E402
+    GeoGuesserEnvironment,
+)
+from geoguesser_env.server.scoring import distance_score, haversine_km  # noqa: E402
+
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+_CANDIDATE_INDEXES = (
+    ROOT / "tasks" / "eval_pano_v3.jsonl",
+    ROOT / "tasks" / "pano_v1.jsonl",
+)
+INDEX = next((p for p in _CANDIDATE_INDEXES if p.exists()), _CANDIDATE_INDEXES[-1])
+"""Audit the frozen eval split when it exists.
+
+Auditing a stale index is worse than not auditing: the numbers look reassuring
+and describe a set nothing runs against.
+"""
+CACHE = ROOT / "data" / "panos"
+
+PASS = "PASS"
+FAIL = "FAIL"
+WARN = "WARN"
+
+results: list[tuple[str, str, str]] = []
+
+
+def record(name: str, ok: bool | str, detail: str) -> None:
+    """Record one check outcome."""
+    status = ok if isinstance(ok, str) else (PASS if ok else FAIL)
+    results.append((status, name, detail))
+    print(f"  [{status}] {name}: {detail}", flush=True)
+
+
+def make_env(**kwargs) -> GeoGuesserEnvironment:
+    options = {"index_path": str(INDEX), "cache_dir": str(CACHE)}
+    options.update(kwargs)
+    return GeoGuesserEnvironment(**options)
+
+
+# ---------------------------------------------------------------- the checks
+
+
+def check_index_integrity() -> None:
+    """Every row parses, indices are contiguous, no sequence repeats."""
+    rows = [json.loads(line) for line in INDEX.read_text().splitlines() if line.strip()]
+    indices = [r["task_index"] for r in rows]
+    sequences = {r["sequence_id"] for r in rows}
+    countries = {r["country"] for r in rows}
+    contiguous = indices == list(range(len(rows)))
+    record(
+        "index integrity",
+        contiguous and len(sequences) == len(rows) and "unknown" not in countries,
+        f"{len(rows)} tasks, {len(countries)} countries, "
+        f"{len(sequences)} unique sequences, contiguous={contiguous}",
+    )
+
+
+def check_all_tasks_render(sample: int | None) -> None:
+    """A rollout must not die because one task cannot produce a view."""
+    env = make_env(allow_fetch=True, view_size=256)
+    total = env._backend.n_tasks
+    order = list(range(total))
+    if sample and sample < total:
+        order = random.Random(0).sample(order, sample)
+    failures, latencies = [], []
+    for task_index in order:
+        try:
+            started = time.time()
+            observation = env.reset(task_index=task_index)
+            latencies.append(time.time() - started)
+            if not observation.image_base64:
+                failures.append((task_index, "no image"))
+        except Exception as exc:  # noqa: BLE001 - report, do not abort the audit
+            failures.append((task_index, f"{type(exc).__name__}: {exc}"))
+    record(
+        "all tasks render",
+        not failures,
+        f"{len(order) - len(failures)}/{len(order)} rendered, "
+        f"median reset {statistics.median(latencies) * 1000:.0f} ms"
+        + (f", failures: {failures[:3]}" if failures else ""),
+    )
+
+
+def check_cross_process_determinism() -> None:
+    """The same task must produce the same bytes in a fresh interpreter."""
+    snippet = (
+        "import sys, hashlib, pathlib; "
+        f"sys.path.insert(0, {str(ROOT.parent)!r}); "
+        "from geoguesser_env.server.geoguesser_environment import "
+        "GeoGuesserEnvironment; "
+        f"env = GeoGuesserEnvironment(index_path={str(INDEX)!r}, "
+        f"cache_dir={str(CACHE)!r}, allow_fetch=False); "
+        "print(hashlib.sha256("
+        "env.reset(task_index=3).image_base64.encode()).hexdigest())"
+    )
+    digests = []
+    for _ in range(2):
+        completed = subprocess.run(
+            [sys.executable, "-c", snippet],
+            capture_output=True,
+            text=True,
+            cwd=str(ROOT),
+        )
+        if completed.returncode != 0:
+            record("cross-process determinism", False, completed.stderr[-160:])
+            return
+        digests.append(completed.stdout.strip())
+    same_in_process = hashlib.sha256(
+        make_env(allow_fetch=False).reset(task_index=3).image_base64.encode()
+    ).hexdigest()
+    record(
+        "cross-process determinism",
+        len(set(digests)) == 1 and digests[0] == same_in_process,
+        f"two subprocesses and this process agree: {digests[0][:16]}",
+    )
+
+
+def check_parallel_isolation(workers: int = 4) -> None:
+    """Concurrent episodes must not interleave into one another."""
+
+    def play(task_index: int) -> tuple[int, float, int]:
+        env = make_env(allow_fetch=False)
+        env.reset(task_index=task_index)
+        env.step(to_wire(LookAction(heading_deg=90)))
+        env.step(to_wire(PinAction(lat=0.0, lon=0.0)))
+        truth = env._task.truth
+        result = env.step(to_wire(GuessAction(lat=truth[0], lon=truth[1])))
+        return task_index, result.reward, result.metadata["task_index"]
+
+    tasks = list(range(workers * 2))
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as pool:
+        outcomes = list(pool.map(play, tasks))
+
+    # A perfect guess scores 1.0 minus 0.03 of gathering, on every episode.
+    mismatched = [o for o in outcomes if o[0] != o[2]]
+    wrong_reward = [o for o in outcomes if abs(o[1] - 0.97) > 1e-6]
+    record(
+        f"parallel isolation ({workers} workers)",
+        not mismatched and not wrong_reward,
+        f"{len(outcomes)} concurrent episodes, all returned their own task "
+        f"and reward 0.970"
+        + (f", mismatched: {mismatched[:2]}" if mismatched else "")
+        + (f", wrong reward: {wrong_reward[:2]}" if wrong_reward else ""),
+    )
+
+
+def check_offline() -> None:
+    """A warm cache must need no network at all."""
+    env = make_env(allow_fetch=False, hires_zoom=False)
+    failures = 0
+    for task_index in range(min(12, env._backend.n_tasks)):
+        try:
+            env.reset(task_index=task_index)
+        except Exception:  # noqa: BLE001
+            failures += 1
+    record(
+        "offline with warm cache",
+        failures == 0,
+        f"{12 - failures}/12 start frames served with fetching disabled",
+    )
+
+
+def check_reward_is_discriminative(trials: int = 300) -> None:
+    """A random guesser must score near zero, or reward measures nothing."""
+    env = make_env(allow_fetch=False)
+    rng = random.Random(7)
+    truths = []
+    for task_index in range(env._backend.n_tasks):
+        truths.append(env._backend.task(task_index).truth)
+
+    def score_for(guess_fn) -> float:
+        scores = []
+        for _ in range(trials):
+            lat, lon = truths[rng.randrange(len(truths))]
+            guess_lat, guess_lon = guess_fn()
+            scores.append(distance_score(haversine_km(guess_lat, guess_lon, lat, lon)))
+        return statistics.mean(scores)
+
+    uniform = score_for(
+        lambda: (
+            math.degrees(math.asin(rng.uniform(-1, 1))),
+            rng.uniform(-180, 180),
+        )
+    )
+    # Guessing a fixed populous point is the strongest trivial baseline.
+    centroid = score_for(lambda: (30.0, 20.0))
+    perfect = 1.0
+    record(
+        "reward is discriminative",
+        uniform < 0.10 and centroid < 0.30,
+        f"uniform-random {uniform:.3f}, fixed-point {centroid:.3f}, "
+        f"perfect {perfect:.3f} (Sonnet measured 0.896)",
+    )
+
+
+def check_step_latency() -> None:
+    """Per-step cost, so a rollout budget can be estimated."""
+    env = make_env(allow_fetch=False)
+    env.reset(task_index=0)
+    timings: dict[str, float] = {}
+    for label, action in (
+        ("look 90deg", LookAction(heading_deg=45, fov_deg=90)),
+        ("pin + map", PinAction(lat=10.0, lon=10.0)),
+    ):
+        started = time.time()
+        env.step(to_wire(action))
+        timings[label] = (time.time() - started) * 1000
+    detail = ", ".join(f"{k} {v:.0f} ms" for k, v in timings.items())
+    record("step latency", all(v < 2000 for v in timings.values()), detail)
+
+
+def check_one_guess_per_episode() -> None:
+    """An episode accepts exactly one guess; the second must not score."""
+    env = make_env(allow_fetch=False)
+    env.reset(task_index=0)
+    truth = env._task.truth
+    first = env.step(to_wire(GuessAction(lat=truth[0], lon=truth[1])))
+    second = env.step(to_wire(GuessAction(lat=0.0, lon=0.0)))
+    third = env.step(to_wire(LookAction(heading_deg=0)))
+    record(
+        "one guess per episode",
+        first.done
+        and first.reward is not None
+        and second.reward is None
+        and second.done
+        and third.done,
+        f"first guess scored {first.reward:.3f} and ended the episode; "
+        f"a second returned reward={second.reward} "
+        f"({second.feedback.split('.')[0]})",
+    )
+
+
+def check_pin_never_leaks() -> None:
+    """Pin feedback must reveal nothing about the target, at any coordinate."""
+    env = make_env(allow_fetch=False)
+    leaks = []
+    for task_index in range(min(20, env._backend.n_tasks)):
+        env.reset(task_index=task_index)
+        true_lat, true_lon = env._task.truth
+        country = env._task.country
+        for lat, lon in ((0.0, 0.0), (true_lat, true_lon), (-40.0, 160.0)):
+            observation = env.step(to_wire(PinAction(lat=lat, lon=lon)))
+            text = f"{observation.feedback} {observation.pins[-1].description}"
+            if observation.distance_km is not None or observation.true_lat is not None:
+                leaks.append((task_index, "distance or truth field populated"))
+            # A pin *at* the truth naturally names that country; the leak we
+            # care about is a pin elsewhere revealing it.
+            if (lat, lon) != (true_lat, true_lon) and country.lower() in text.lower():
+                leaks.append((task_index, f"named {country} from a distant pin"))
+    record(
+        "pin never leaks the target",
+        not leaks,
+        "60 pins across 20 tasks revealed nothing"
+        + (f"; leaks: {leaks[:2]}" if leaks else ""),
+    )
+
+
+def main() -> None:
+    """Run the audit."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--full", action="store_true", help="Render every task, not a sample."
+    )
+    parser.add_argument("--sample", type=int, default=25)
+    parser.add_argument(
+        "--index",
+        type=pathlib.Path,
+        default=None,
+        help="Index to audit. Defaults to the eval split when present.",
+    )
+    args = parser.parse_args()
+
+    if args.index is not None:
+        if not args.index.exists():
+            raise SystemExit(f"no such index: {args.index}")
+        global INDEX
+        INDEX = args.index
+
+    print("geoguesser_env readiness audit")
+    print("=" * 78)
+    print(f"  index: {INDEX}")
+    check_index_integrity()
+    check_all_tasks_render(None if args.full else args.sample)
+    check_cross_process_determinism()
+    check_parallel_isolation()
+    check_offline()
+    check_reward_is_discriminative()
+    check_step_latency()
+    check_one_guess_per_episode()
+    check_pin_never_leaks()
+    print("=" * 78)
+
+    failed = [r for r in results if r[0] == FAIL]
+    warned = [r for r in results if r[0] == WARN]
+    print(
+        f"{len(results) - len(failed) - len(warned)} passed, "
+        f"{len(warned)} warned, {len(failed)} failed"
+    )
+    for status, name, detail in failed + warned:
+        print(f"  {status}: {name} - {detail}")
+    sys.exit(1 if failed else 0)
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/render_trace.py

@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Render a rollout trace as a single HTML page you can scroll through.
+
+A JSONL trace answers "what was the reward"; it does not show you *why*. This
+lays each episode out as a filmstrip: the view the model was looking at, what it
+said, the action it chose, what the environment replied, and the running cost —
+ending with the reveal and the score.
+
+Usage:
+    python scripts/render_trace.py rollouts/anthropic_agentic
+    python scripts/render_trace.py rollouts/hf_agentic --out qwen.html
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import html
+import json
+import pathlib
+
+
+def _data_uri(path: pathlib.Path) -> str:
+    """Inline an image so the report is a single portable file."""
+    if not path.exists():
+        return ""
+    mime = "image/png" if path.suffix == ".png" else "image/jpeg"
+    return f"data:{mime};base64,{base64.b64encode(path.read_bytes()).decode()}"
+
+
+def _fmt_distance(km: float | None) -> str:
+    if km is None:
+        return "—"
+    return f"{km * 1000:.0f} m" if km < 10 else f"{km:,.0f} km"
+
+
+def _verdict(km: float | None) -> str:
+    if km is None:
+        return "no guess"
+    if km < 0.025:
+        return "perfect"
+    if km < 25:
+        return "pinpoint"
+    if km < 200:
+        return "close"
+    if km < 1500:
+        return "right region"
+    return "wrong continent"
+
+
+def render(trace_dir: pathlib.Path, out: pathlib.Path) -> None:
+    """Write one HTML report for a trace directory."""
+    records = [
+        json.loads(line)
+        for line in (trace_dir / "trace.jsonl").read_text().splitlines()
+        if line.strip()
+    ]
+    summary_path = trace_dir / "summary.json"
+    summary = json.loads(summary_path.read_text()) if summary_path.exists() else {}
+
+    episodes = []
+    for record in records:
+        turns = []
+        for row in record.get("trace", []):
+            image = ""
+            if row.get("image"):
+                image = _data_uri(trace_dir / row["image"])
+            action = row.get("action") or {}
+            kind = (
+                action.get("action", "reset")
+                if isinstance(action, dict)
+                else str(action)
+            )
+            args = (
+                ", ".join(
+                    f"{key}={value}" for key, value in action.items() if key != "action"
+                )
+                if isinstance(action, dict)
+                else ""
+            )
+            turns.append(
+                {
+                    "turn": row.get("turn"),
+                    "kind": kind,
+                    "args": args,
+                    "reply": row.get("reply") or "",
+                    "feedback": row.get("feedback") or "",
+                    "steps": row.get("steps_remaining"),
+                    "cost": row.get("action_cost"),
+                    "image": image,
+                    "image_kind": row.get("image_kind", "none"),
+                }
+            )
+        episodes.append({"record": record, "turns": turns})
+
+    parts = [
+        _HEAD.replace(
+            "__TITLE__", html.escape(str(summary.get("model", trace_dir.name)))
+        )
+    ]
+    parts.append(_summary_block(summary, records))
+    for episode in episodes:
+        parts.append(_episode_block(episode))
+    parts.append("</body></html>")
+    out.write_text("".join(parts))
+    print(f"wrote {out} ({out.stat().st_size / 1e6:.1f} MB, {len(episodes)} episodes)")
+
+
+def _summary_block(summary: dict, records: list[dict]) -> str:
+    rows = "".join(
+        f"<div class='stat'><span>{html.escape(label)}</span><b>{html.escape(str(value))}</b></div>"
+        for label, value in [
+            ("model", summary.get("model", "—")),
+            ("mode", summary.get("mode", "—")),
+            ("episodes", summary.get("episodes", len(records))),
+            ("mean reward", f"{summary.get('mean_reward', 0):.3f}"),
+            ("median distance", _fmt_distance(summary.get("median_distance_km"))),
+            ("within 200 km", f"{summary.get('within_200km', 0)}/{len(records)}"),
+            ("parsed", f"{summary.get('parsed', 0)}/{len(records)}"),
+            ("wall clock", f"{summary.get('wall_clock_s', 0):.1f}s"),
+        ]
+    )
+    return f"<header><h1>rollout trace</h1><div class='stats'>{rows}</div></header>"
+
+
+def _episode_block(episode: dict) -> str:
+    record = episode["record"]
+    km = record.get("distance_km")
+    reward = record.get("reward") or 0.0
+    head = (
+        f"<h2>episode {record.get('task_index')} "
+        f"<span class='country'>{html.escape(str(record.get('country', '')))}</span>"
+        f"<span class='verdict v-{_verdict(km).replace(' ', '-')}'>{_verdict(km)}</span>"
+        f"<span class='num'>{_fmt_distance(km)}</span>"
+        f"<span class='num'>reward {reward:.3f}</span>"
+        f"<span class='num'>{record.get('turns', 0)} turns</span>"
+        f"<span class='num'>{record.get('latency_s', 0):.1f}s</span></h2>"
+    )
+    cards = []
+    for turn in episode["turns"]:
+        image = (
+            f"<img src='{turn['image']}' alt='observation at turn {turn['turn']}'>"
+            if turn["image"]
+            else "<div class='noimg'>no image</div>"
+        )
+        reply = html.escape(turn["reply"][:1400])
+        meta = []
+        if turn["steps"] is not None:
+            meta.append(f"{turn['steps']} steps left")
+        if turn["cost"] is not None:
+            meta.append(f"cost {turn['cost']:.2f}")
+        cards.append(
+            f"""<div class='turn {"map" if turn["image_kind"] == "map" else ""}'>
+  <div class='thumb'>{image}</div>
+  <div class='body'>
+    <div class='act'><b>{html.escape(str(turn["kind"]))}</b>
+      <span>{html.escape(turn["args"])}</span>
+      <span class='meta'>{html.escape(" · ".join(meta))}</span></div>
+    <div class='fb'>{html.escape(turn["feedback"])}</div>
+    {f"<details><summary>model reply</summary><pre>{reply}</pre></details>" if reply else ""}
+  </div>
+</div>"""
+        )
+    return f"<section>{head}<div class='turns'>{''.join(cards)}</div></section>"
+
+
+_HEAD = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>__TITLE__ — rollout trace</title>
+<style>
+  :root {
+    --ground:#eef1f4; --panel:#fff; --edge:#d3dae0; --ink:#1d2328;
+    --soft:#5c666e; --faint:#8b959c; --wire:#4a7d99; --pin:#c4332a; --good:#3f7a55;
+  }
+  @media (prefers-color-scheme:dark){ :root{
+    --ground:#12171b; --panel:#191f24; --edge:#2b343b; --ink:#e6ebef;
+    --soft:#a3aeb6; --faint:#6e7a83; --wire:#7fb3cc; --pin:#e8695e; --good:#79b892; } }
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--ground);color:var(--ink);
+    font:14px/1.6 ui-monospace,"SF Mono",Menlo,monospace;padding:24px 18px 60px}
+  header{max-width:1180px;margin:0 auto 26px}
+  h1{font-size:19px;margin:0 0 12px;font-weight:600;letter-spacing:.02em}
+  .stats{display:flex;flex-wrap:wrap;gap:18px}
+  .stat{background:var(--panel);border:1px solid var(--edge);border-radius:4px;
+    padding:7px 12px;min-width:118px}
+  .stat span{display:block;font-size:9.5px;letter-spacing:.12em;
+    text-transform:uppercase;color:var(--faint)}
+  .stat b{font-size:15px;font-weight:500;font-variant-numeric:tabular-nums}
+  section{max-width:1180px;margin:0 auto 30px;background:var(--panel);
+    border:1px solid var(--edge);border-radius:5px;overflow:hidden}
+  h2{margin:0;padding:11px 15px;font-size:13px;font-weight:600;
+    border-bottom:1px solid var(--edge);display:flex;align-items:center;
+    gap:12px;flex-wrap:wrap}
+  h2 .country{color:var(--soft);font-weight:400}
+  h2 .num{margin-left:auto;font-weight:400;color:var(--soft);font-size:11.5px;
+    font-variant-numeric:tabular-nums}
+  h2 .num + .num{margin-left:0}
+  .verdict{font-size:10px;letter-spacing:.1em;text-transform:uppercase;
+    padding:2px 7px;border-radius:3px;border:1px solid var(--edge);color:var(--soft)}
+  .v-pinpoint,.v-perfect{color:var(--good);border-color:var(--good)}
+  .v-wrong-continent,.v-no-guess{color:var(--pin);border-color:var(--pin)}
+  .turns{display:flex;flex-direction:column}
+  .turn{display:flex;gap:14px;padding:12px 15px;border-bottom:1px solid var(--edge)}
+  .turn:last-child{border-bottom:none}
+  .turn.map{background:color-mix(in srgb,var(--wire) 7%,transparent)}
+  .thumb{flex:0 0 200px}
+  .thumb img{width:200px;border-radius:3px;display:block;border:1px solid var(--edge)}
+  .noimg{width:200px;height:96px;border:1px dashed var(--edge);border-radius:3px;
+    display:flex;align-items:center;justify-content:center;color:var(--faint);font-size:11px}
+  .body{flex:1;min-width:0}
+  .act b{color:var(--wire)}
+  .act span{color:var(--soft);font-size:12px;margin-left:6px}
+  .act .meta{float:right;color:var(--faint);font-size:11px}
+  .fb{margin-top:5px;color:var(--soft);font-size:12.5px}
+  details{margin-top:8px}
+  summary{cursor:pointer;font-size:11px;color:var(--faint)}
+  pre{white-space:pre-wrap;font-size:11.5px;background:var(--ground);
+    border:1px solid var(--edge);border-radius:3px;padding:9px;margin:7px 0 0;
+    max-height:260px;overflow:auto}
+</style></head><body>
+"""
+
+
+def main() -> None:
+    """Command-line entry point."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("trace_dir", type=pathlib.Path)
+    parser.add_argument("--out", type=pathlib.Path)
+    args = parser.parse_args()
+    out = args.out or (args.trace_dir / "trace.html")
+    render(args.trace_dir, out)
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/split_tasks.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Split one harvested pool into a frozen eval set and a training pool.
+
+Splitting after harvesting is the safer order. If the two sets are harvested
+separately you have to reason about contamination across two runs; if they come
+from one pool you can enforce disjointness exactly once, here, and check it.
+
+Two rules, both from the OSV-5M paper, which built its train/test split from the
+same Mapillary source:
+
+- no shared `sequence_id`
+- no eval task within `--buffer-km` of any training task
+
+The buffer matters because frames sit about 3.3 m apart. Holding out an image
+while keeping its neighbour holds out nothing at all.
+
+Eval is carved first and balanced by country, because at a couple of hundred
+tasks balance decides what the number means. Training takes everything left over
+that clears the buffer.
+
+Usage:
+    python scripts/split_tasks.py tasks/pool_v1.jsonl --eval 200
+    python scripts/split_tasks.py tasks/pool_v1.jsonl --eval 200 --buffer-km 2
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import json
+import logging
+import math
+import pathlib
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger("split_tasks")
+
+
+def haversine_km(lat_a: float, lon_a: float, lat_b: float, lon_b: float) -> float:
+    """Great-circle distance in kilometres."""
+    phi_a, phi_b = math.radians(lat_a), math.radians(lat_b)
+    d_phi, d_lambda = phi_b - phi_a, math.radians(lon_b - lon_a)
+    h = (
+        math.sin(d_phi / 2) ** 2
+        + math.cos(phi_a) * math.cos(phi_b) * math.sin(d_lambda / 2) ** 2
+    )
+    return 2 * 6371.0088 * math.asin(math.sqrt(min(1.0, h)))
+
+
+def start_point(task: dict) -> tuple[float, float]:
+    """The coordinate a task is scored against."""
+    frame = task["frames"][task["start_frame"]]
+    return frame["lat"], frame["lon"]
+
+
+def renumber(tasks: list[dict], prefix: str) -> list[dict]:
+    """Rewrite indices so the backend's contiguity requirement holds."""
+    out = []
+    for index, task in enumerate(tasks):
+        task = dict(task)
+        task["task_index"] = index
+        task["task_id"] = f"{prefix}-{index:05d}"
+        out.append(task)
+    return out
+
+
+def split(args: argparse.Namespace) -> None:
+    """Carve the eval set, then hand the remainder to training."""
+    pool = [
+        json.loads(line) for line in args.pool.read_text().splitlines() if line.strip()
+    ]
+    logger.info("pool holds %d tasks", len(pool))
+
+    # Eval first, balanced by country. Ordering is by completeness before
+    # quality: a task missing frames is unusable in a set whose whole purpose is
+    # to run with the network off, and no quality score compensates for that.
+    def eval_rank(task: dict) -> tuple[int, float]:
+        complete = 1 if task["meta"].get("offline_ready") else 0
+        return (-complete, -(task["meta"].get("quality_score") or 0.0))
+
+    incomplete = sum(1 for t in pool if not t["meta"].get("offline_ready"))
+    if incomplete:
+        logger.info(
+            "%d pool tasks are not fully mirrored; they sort last for eval "
+            "(run scripts/verify_offline.py to repair)",
+            incomplete,
+        )
+    by_quality = sorted(pool, key=eval_rank)
+    per_country: collections.Counter = collections.Counter()
+    eval_tasks: list[dict] = []
+    for task in by_quality:
+        if len(eval_tasks) >= args.eval:
+            break
+        country = task["country"]
+        if per_country[country] >= args.eval_per_country:
+            continue
+        per_country[country] += 1
+        eval_tasks.append(task)
+
+    eval_sequences = {t["sequence_id"] for t in eval_tasks}
+    eval_points = [start_point(t) for t in eval_tasks]
+
+    train_tasks: list[dict] = []
+    dropped_sequence = 0
+    dropped_buffer = 0
+    for task in pool:
+        if task["sequence_id"] in eval_sequences:
+            dropped_sequence += 1
+            continue
+        lat, lon = start_point(task)
+        if any(
+            haversine_km(lat, lon, e_lat, e_lon) < args.buffer_km
+            for e_lat, e_lon in eval_points
+        ):
+            dropped_buffer += 1
+            continue
+        train_tasks.append(task)
+
+    eval_out = args.out_dir / args.eval_name
+    train_out = args.out_dir / args.train_name
+    for path, tasks, prefix in (
+        (eval_out, eval_tasks, "eval"),
+        (train_out, train_tasks, "train"),
+    ):
+        with path.open("w") as handle:
+            for task in renumber(tasks, prefix):
+                handle.write(json.dumps(task) + "\n")
+
+    # Verify rather than assert in a comment.
+    train_sequences = {t["sequence_id"] for t in train_tasks}
+    overlap = eval_sequences & train_sequences
+    closest = min(
+        (
+            haversine_km(*start_point(t), *point)
+            for t in train_tasks
+            for point in eval_points
+        ),
+        default=float("inf"),
+    )
+
+    countries_eval = collections.Counter(t["country"] for t in eval_tasks)
+    logger.info(
+        "\neval  %4d tasks -> %s  (%d countries, max %d per country)",
+        len(eval_tasks),
+        eval_out.name,
+        len(countries_eval),
+        max(countries_eval.values()) if countries_eval else 0,
+    )
+    logger.info(
+        "train %4d tasks -> %s  (dropped %d on shared sequence, %d on the %.1f km buffer)",
+        len(train_tasks),
+        train_out.name,
+        dropped_sequence,
+        dropped_buffer,
+        args.buffer_km,
+    )
+    logger.info(
+        "\ncontamination check: %d shared sequences, closest train task is %.2f km "
+        "from an eval task",
+        len(overlap),
+        closest,
+    )
+    if overlap or closest < args.buffer_km:
+        raise SystemExit("split failed its own contamination check")
+    mirrored = sum(1 for t in eval_tasks if t["meta"].get("offline_ready"))
+    logger.info(
+        "eval tasks fully mirrored for offline use: %d/%d", mirrored, len(eval_tasks)
+    )
+    if mirrored < len(eval_tasks):
+        raise SystemExit(
+            f"{len(eval_tasks) - mirrored} eval tasks are not fully mirrored. "
+            "A frozen eval set must run offline; repair with "
+            "scripts/verify_offline.py or lower --eval."
+        )
+
+
+def main() -> None:
+    """Command-line entry point."""
+    root = pathlib.Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("pool", type=pathlib.Path)
+    parser.add_argument("--eval", type=int, default=200)
+    parser.add_argument("--eval-per-country", type=int, default=4)
+    parser.add_argument("--buffer-km", type=float, default=1.0)
+    parser.add_argument("--eval-name", default="eval_pano_v3.jsonl")
+    parser.add_argument("--train-name", default="train_pano_v3.jsonl")
+    parser.add_argument("--out-dir", type=pathlib.Path, default=root / "tasks")
+    split(parser.parse_args())
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/scripts/verify_offline.py

@@ -0,0 +1,206 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Check that a task index is fully mirrored, and top up whatever is missing.
+
+An interrupted build leaves tasks whose start frame is cached but whose later
+frames are not, so the episode is playable but `move` walks into a hole. The
+`offline_ready` flag in the index records what was true at build time, which
+stops being true the moment a build is interrupted or a frame is deleted, so
+this checks the filesystem instead of trusting the flag -- and rewrites the flag
+to match what it found.
+
+Run it before syncing to a bucket. `GEOGUESSER_ALLOW_FETCH=0` turns a missing
+frame into a hard error at rollout time, which is the point, but it is a much
+better error to hit here.
+
+Usage:
+    python scripts/verify_offline.py tasks/pool_offline_5k.jsonl
+    python scripts/verify_offline.py tasks/pool_offline_5k.jsonl --check
+"""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import concurrent.futures
+import json
+import logging
+import pathlib
+import sys
+import threading
+import urllib.request
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+
+from build_pano_tasks import _get, _token, TIMEOUT_S  # noqa: E402
+
+logging.basicConfig(level=logging.INFO, format="%(message)s")
+logger = logging.getLogger("verify_offline")
+
+
+def missing_frames(tasks: list[dict], cache: pathlib.Path) -> dict[int, list[str]]:
+    """
+    Map task index to the image ids absent from the cache.
+
+    Args:
+        tasks (`list[dict]`):
+            Parsed task index.
+        cache (`pathlib.Path`):
+            Directory holding `<image_id>.jpg`.
+
+    Returns:
+        `dict[int, list[str]]`: Only tasks with at least one absent frame.
+    """
+    gaps: dict[int, list[str]] = {}
+    for task in tasks:
+        absent = [
+            frame["image_id"]
+            for frame in task["frames"]
+            if not (cache / f"{frame['image_id']}.jpg").exists()
+        ]
+        if absent:
+            gaps[task["task_index"]] = absent
+    return gaps
+
+
+def fetch_one(token: str, image_id: str, cache: pathlib.Path) -> bool:
+    """Download one frame into the cache. Returns whether it landed."""
+    path = cache / f"{image_id}.jpg"
+    if path.exists():
+        return True
+    field = "thumb_2048_url"
+    meta = _get(token, image_id, fields=field)
+    url = meta.get(field) if "__error" not in meta else None
+    if not url:
+        return False
+    try:
+        with urllib.request.urlopen(url, timeout=TIMEOUT_S) as response:
+            payload = response.read()
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("  %s: %r", image_id, exc)
+        return False
+    # Write via a temporary name so an interrupted download cannot leave a
+    # truncated JPEG that later looks like a cache hit.
+    tmp = path.with_suffix(".partial")
+    tmp.write_bytes(payload)
+    tmp.replace(path)
+    return True
+
+
+def repair(
+    tasks: list[dict], gaps: dict[int, list[str]], cache: pathlib.Path, workers: int
+) -> set[str]:
+    """Fetch every absent frame concurrently. Returns the ids still missing."""
+    wanted = sorted({image_id for ids in gaps.values() for image_id in ids})
+    token = _token()
+    still: set[str] = set()
+    lock = threading.Lock()
+    done = 0
+
+    def one(image_id: str) -> None:
+        nonlocal done
+        ok = fetch_one(token, image_id, cache)
+        with lock:
+            done += 1
+            if not ok:
+                still.add(image_id)
+            if done % 25 == 0 or done == len(wanted):
+                logger.info("  %d/%d fetched", done, len(wanted))
+
+    logger.info("fetching %d missing frames with %d workers", len(wanted), workers)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as pool:
+        list(pool.map(one, wanted))
+    return still
+
+
+def main() -> None:
+    """Command-line entry point."""
+    root = pathlib.Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("index", type=pathlib.Path)
+    parser.add_argument("--cache", type=pathlib.Path, default=root / "data" / "panos")
+    parser.add_argument("--workers", type=int, default=12)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Report only; never fetch and never rewrite the index.",
+    )
+    args = parser.parse_args()
+
+    tasks = [
+        json.loads(line) for line in args.index.read_text().splitlines() if line.strip()
+    ]
+    total_frames = sum(len(t["frames"]) for t in tasks)
+    gaps = missing_frames(tasks, args.cache)
+    absent = sum(len(v) for v in gaps.values())
+    logger.info(
+        "%d tasks · %d frames · %d tasks incomplete · %d frames absent",
+        len(tasks),
+        total_frames,
+        len(gaps),
+        absent,
+    )
+
+    starts = [
+        t["task_index"]
+        for t in tasks
+        if not (
+            args.cache / f"{t['frames'][t['start_frame']]['image_id']}.jpg"
+        ).exists()
+    ]
+    if starts:
+        logger.warning(
+            "%d tasks are missing their START frame and cannot be played "
+            "offline at all: %s",
+            len(starts),
+            starts[:10],
+        )
+
+    if not gaps:
+        logger.info("index is fully mirrored")
+        return
+
+    if args.check:
+        for index, ids in sorted(gaps.items())[:20]:
+            logger.info("  task %5d: %d absent", index, len(ids))
+        raise SystemExit(f"{absent} frames absent from {args.cache}")
+
+    still = repair(tasks, gaps, args.cache, args.workers)
+
+    # Rewrite offline_ready from what is actually on disk, so downstream
+    # consumers -- the eval split especially -- can trust the flag.
+    remaining = missing_frames(tasks, args.cache)
+    changed = 0
+    for task in tasks:
+        ready = task["task_index"] not in remaining
+        if task["meta"].get("offline_ready") != ready:
+            task["meta"]["offline_ready"] = ready
+            changed += 1
+    args.index.write_text("".join(json.dumps(t) + "\n" for t in tasks))
+
+    ready_now = sum(1 for t in tasks if t["meta"]["offline_ready"])
+    logger.info(
+        "\nrepaired: %d frames still absent · %d tasks still incomplete",
+        sum(len(v) for v in remaining.values()),
+        len(remaining),
+    )
+    logger.info(
+        "offline_ready %d/%d (%d flags corrected)", ready_now, len(tasks), changed
+    )
+    if still:
+        by_task = collections.Counter(
+            task["task_index"]
+            for task in tasks
+            for frame in task["frames"]
+            if frame["image_id"] in still
+        )
+        logger.warning(
+            "unfetchable frames belong to tasks %s -- these are usually images "
+            "deleted upstream; exclude them from eval",
+            sorted(by_task)[:10],
+        )
+
+
+if __name__ == "__main__":
+    main()

geoguesser_env/server/Dockerfile

@@ -0,0 +1,26 @@
+# syntax=docker/dockerfile:1
+FROM openenv-base:latest
+
+WORKDIR /app
+
+# The task index and bundled Natural Earth vectors are small and belong in the
+# image. Panorama bytes are not: they are cached at runtime under
+# /app/geoguesser_env/data/panos, which should be a mounted volume so the cache survives
+# container restarts.
+# A package directory: modules inside use `from ..models import ...`, which
+# needs `geoguesser_env` to be the package rather than `server`.
+COPY envs/geoguesser_env /app/geoguesser_env
+RUN mkdir -p /app/geoguesser_env/data/panos
+
+ENV PYTHONPATH=/app:/app/src
+# Legacy single-index fallback, used when no split resolves. pano_v1.jsonl is
+# committed, so the image always has something playable.
+ENV GEOGUESSER_INDEX=/app/geoguesser_env/tasks/pano_v1.jsonl
+ENV GEOGUESSER_CACHE=/app/geoguesser_env/data/panos
+# Split indexes as copied into the image. A Space overrides all three to point
+# at a mounted bucket instead, because the imagery cannot fit in the image.
+ENV GEOGUESSER_TASKS_TRAIN=/app/geoguesser_env/tasks/train_pano_v3.jsonl
+ENV GEOGUESSER_TASKS_EVAL=/app/geoguesser_env/tasks/eval_pano_v3.jsonl
+
+EXPOSE 8000
+CMD ["uvicorn", "geoguesser_env.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

geoguesser_env/server/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Server-side implementation of the GeoGuesser environment."""

geoguesser_env/server/app.py

@@ -0,0 +1,340 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""FastAPI application for the GeoGuesser environment.
+
+Configuration comes from the process environment so one image can serve every
+variant. `MAPILLARY_API_KEY` is needed only to fill cache misses; with a warm
+cache the server runs with no network access at all.
+
+Usage:
+    uv run --project . server
+    uvicorn server.app:app --host 0.0.0.0 --port 8000
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import os
+import pathlib
+
+from openenv.core.env_server.http_server import create_app
+
+try:
+    from geoguesser_env.models import GeoGuesserAction, GeoGuesserObservation
+    from geoguesser_env.server.geoguesser_environment import GeoGuesserEnvironment
+except ImportError:  # running uvicorn from inside envs/geoguesser_env
+    from models import GeoGuesserAction, GeoGuesserObservation
+
+    from .geoguesser_environment import GeoGuesserEnvironment
+
+
+logger = logging.getLogger(__name__)
+
+_ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+INDEX_PATH = os.getenv("GEOGUESSER_INDEX", str(_ROOT / "tasks" / "pano_v1.jsonl"))
+CACHE_DIR = os.getenv("GEOGUESSER_CACHE", str(_ROOT / "data" / "panos"))
+# Named splits, as (environment variable, repo-relative default). Each is
+# optional and a split whose file is absent is simply not offered, so the same
+# image serves a checkout with the indexes committed, a Space with a bucket
+# mounted at /data, and a deployment carrying only the eval set.
+SPLIT_SOURCES = {
+    "train": ("GEOGUESSER_TASKS_TRAIN", "tasks/train_pano_v3.jsonl"),
+    "eval": ("GEOGUESSER_TASKS_EVAL", "tasks/eval_pano_v3.jsonl"),
+}
+DEFAULT_SPLIT = os.getenv("GEOGUESSER_DEFAULT_SPLIT", "")
+EPISODE_MODE = os.getenv("GEOGUESSER_EPISODE_MODE", "agentic")
+REWARD_MODE = os.getenv("GEOGUESSER_REWARD_MODE", "coords")
+MAX_STEPS = int(os.getenv("GEOGUESSER_MAX_STEPS", "24"))
+VIEW_SIZE = int(os.getenv("GEOGUESSER_VIEW_SIZE", "640"))
+HIERARCHICAL = os.getenv("GEOGUESSER_HIERARCHICAL", "0") in {"1", "true", "True"}
+ALLOW_FETCH = os.getenv("GEOGUESSER_ALLOW_FETCH", "1") in {"1", "true", "True"}
+HIRES_ZOOM = os.getenv("GEOGUESSER_HIRES_ZOOM", "1") in {"1", "true", "True"}
+REVEAL_MAP = os.getenv("GEOGUESSER_REVEAL_MAP", "1") in {"1", "true", "True"}
+STREET_DETAIL = os.getenv("GEOGUESSER_STREET_DETAIL", "1") in {"1", "true", "True"}
+MAX_CONCURRENT = int(os.getenv("MAX_CONCURRENT_ENVS", "4"))
+
+
+try:
+    from .render.minimap import set_street_detail
+except ImportError:  # running uvicorn from inside envs/geoguesser_env
+    from render.minimap import set_street_detail
+
+# Deliberately independent of ALLOW_FETCH. That flag governs Mapillary imagery,
+# which a mirrored dataset must never reach for; street detail comes from
+# Overpass and caches to the container's own writable disk, so a fully mirrored
+# deployment can still draw labelled streets. Coupling the two silently gave a
+# Space unlabelled agent maps while a local run had labelled ones.
+set_street_detail(STREET_DETAIL)
+
+
+def resolve_splits() -> tuple[dict[str, str], str]:
+    """
+    Work out which named splits this deployment actually serves.
+
+    A split is offered only when its environment variable is set *and* the file
+    exists, because a Space that mounts a bucket read-only should degrade to the
+    splits it really has rather than failing to start. When none are configured
+    the legacy single `GEOGUESSER_INDEX` becomes one `train` split, so existing
+    containers behave exactly as before.
+
+    Returns:
+        `tuple` of:
+            - `dict[str, str]`: Split name to index path.
+            - `str`: Name of the default split.
+    """
+    splits: dict[str, str] = {}
+    for name, (variable, relative) in SPLIT_SOURCES.items():
+        override = os.getenv(variable)
+        path = override or str(_ROOT / relative)
+        if not pathlib.Path(path).exists():
+            # Only complain when someone asked for it explicitly. A missing
+            # default just means this checkout has not built that split yet.
+            if override:
+                logger.warning(
+                    "%s points at %s, which does not exist; "
+                    "the %r split will not be offered",
+                    variable,
+                    path,
+                    name,
+                )
+            continue
+        splits[name] = path
+
+    if not splits:
+        return {"train": INDEX_PATH}, "train"
+
+    default = DEFAULT_SPLIT or ("train" if "train" in splits else next(iter(splits)))
+    if default not in splits:
+        logger.warning(
+            "GEOGUESSER_DEFAULT_SPLIT=%r is not among %s; using %r",
+            DEFAULT_SPLIT,
+            sorted(splits),
+            next(iter(splits)),
+        )
+        default = next(iter(splits))
+    return splits, default
+
+
+SPLITS, ACTIVE_DEFAULT_SPLIT = resolve_splits()
+
+
+def create_geoguesser_environment() -> GeoGuesserEnvironment:
+    """Factory: a fresh environment per WebSocket session."""
+    return GeoGuesserEnvironment(
+        splits=SPLITS,
+        default_split=ACTIVE_DEFAULT_SPLIT,
+        cache_dir=CACHE_DIR,
+        episode_mode=EPISODE_MODE,
+        max_steps=MAX_STEPS,
+        reward_mode=REWARD_MODE,
+        hierarchical_reward=HIERARCHICAL,
+        view_size=VIEW_SIZE,
+        allow_fetch=ALLOW_FETCH,
+        hires_zoom=HIRES_ZOOM,
+        reveal_map=REVEAL_MAP,
+    )
+
+
+def _build_app():
+    """Create the app, attaching the Gradio tab when this openenv supports it."""
+    kwargs = dict(
+        env_name="geoguesser_env",
+        max_concurrent_envs=MAX_CONCURRENT,
+    )
+    signature = inspect.signature(create_app)
+    # Land people on the game, not the raw action form.
+    if "custom_tab_primary" in signature.parameters:
+        kwargs["custom_tab_primary"] = True
+    if "custom_tab_name" in signature.parameters:
+        kwargs["custom_tab_name"] = "Try Environment"
+    if "default_tab_name" in signature.parameters:
+        kwargs["default_tab_name"] = "MCP Playground"
+    if "title_override" in signature.parameters:
+        kwargs["title_override"] = "Geoguesser Environment"
+    if "gradio_builder" in signature.parameters:
+        try:
+            from .gradio_ui import build_geoguesser_gradio_app
+
+            kwargs["gradio_builder"] = build_geoguesser_gradio_app
+        except Exception as exc:  # pragma: no cover - optional UI dependency
+            logger.warning("Gradio UI unavailable: %r", exc)
+    else:
+        logger.warning(
+            "Installed openenv does not support gradio_builder; "
+            "the GeoGuessr-style play tab will not be available."
+        )
+    return create_app(
+        create_geoguesser_environment,
+        GeoGuesserAction,
+        GeoGuesserObservation,
+        **kwargs,
+    )
+
+
+def _attach_play_routes(application) -> None:
+    """Serve panoramas and task metadata to the browser-side viewers.
+
+    The Pannellum viewer needs the raw equirectangular JPEG, which the agent
+    never receives — it only ever sees reprojected views. Ground truth is
+    exposed here because these routes exist for a human playing a round in
+    their own browser; the agent's observations still withhold it until it
+    guesses.
+    """
+    from fastapi import HTTPException, Query
+    from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+
+    # One environment, reused for metadata only. Its per-split backends share
+    # the process-wide parsed index cache, so this is cheap.
+    catalog = create_geoguesser_environment()
+
+    def _backend(split: str | None):
+        """Resolve a split name to its backend, as a 404 rather than a 500."""
+        try:
+            return catalog._backend_for(split or ACTIVE_DEFAULT_SPLIT)
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+    @application.get(
+        "/geoguesser/task/{task_index}",
+        tags=["geoguesser"],
+        response_class=JSONResponse,
+    )
+    async def geoguesser_task(task_index: int, split: str | None = Query(None)):
+        """Metadata for one task, for the play UI."""
+        try:
+            task = _backend(split).task(task_index)
+        except IndexError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        frame = task.frames[task.start_frame]
+        return JSONResponse(
+            {
+                "task_index": task.task_index,
+                "task_id": task.task_id,
+                "lat": frame.lat,
+                "lon": frame.lon,
+                "country": task.country,
+                "compass_angle": frame.compass_angle,
+                "captured_at": frame.captured_at,
+                "attribution": task.attribution,
+                "n_frames": len(task.frames),
+                "start_frame": task.start_frame,
+                # Per-frame headings only. Coordinates are withheld for frames
+                # other than the start, which is the one the guess is scored
+                # against and therefore already revealed to a human player.
+                "frames": [
+                    {
+                        "index": i,
+                        "compass_angle": f.compass_angle,
+                        "captured_at": f.captured_at,
+                    }
+                    for i, f in enumerate(task.frames)
+                ],
+            }
+        )
+
+    def _pano_response(task_index: int, frame_index: int | None, split: str | None):
+        """Resolve one frame's panorama file, fetching it if necessary."""
+        resolved = _backend(split)
+        try:
+            task = resolved.task(task_index)
+        except IndexError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        position = task.start_frame if frame_index is None else frame_index
+        if not 0 <= position < len(task.frames):
+            raise HTTPException(
+                status_code=404,
+                detail=(
+                    f"frame {position} out of range for task {task_index} "
+                    f"with {len(task.frames)} frames"
+                ),
+            )
+        frame = task.frames[position]
+        try:
+            resolved.load_pano(frame.image_id)
+        except Exception as exc:
+            raise HTTPException(status_code=503, detail=str(exc)) from exc
+        return FileResponse(
+            pathlib.Path(CACHE_DIR) / f"{frame.image_id}.jpg",
+            media_type="image/jpeg",
+        )
+
+    @application.get(
+        "/geoguesser/pano/{task_index}",
+        tags=["geoguesser"],
+        response_class=FileResponse,
+    )
+    async def geoguesser_pano(task_index: int, split: str | None = Query(None)):
+        """The task's starting panorama, for the browser viewer."""
+        return _pano_response(task_index, None, split)
+
+    @application.get(
+        "/geoguesser/pano/{task_index}/{frame_index}",
+        tags=["geoguesser"],
+        response_class=FileResponse,
+    )
+    async def geoguesser_pano_frame(
+        task_index: int, frame_index: int, split: str | None = Query(None)
+    ):
+        """One specific frame's panorama, so the viewer can follow `move()`."""
+        return _pano_response(task_index, frame_index, split)
+
+    @application.get(
+        "/geoguesser/play", tags=["geoguesser"], response_class=HTMLResponse
+    )
+    async def geoguesser_play(split: str | None = Query(None)):
+        """The standalone play page, also embedded in the Gradio tab."""
+        from .gradio_ui import play_page_html
+
+        return HTMLResponse(play_page_html(catalog.list_splits(), split))
+
+    @application.get(
+        "/geoguesser/tasks", tags=["geoguesser"], response_class=JSONResponse
+    )
+    async def geoguesser_tasks():
+        """Which splits exist and how many tasks each holds."""
+        splits = catalog.list_splits()
+        return JSONResponse(
+            {
+                "splits": splits,
+                "default_split": ACTIVE_DEFAULT_SPLIT,
+                # Kept so an older play page still finds a count.
+                "n_tasks": next(
+                    s["num_tasks"] for s in splits if s["name"] == ACTIVE_DEFAULT_SPLIT
+                ),
+            }
+        )
+
+
+app = _build_app()
+
+try:
+    _attach_play_routes(app)
+except Exception as exc:  # pragma: no cover - index may be absent in CI
+    logger.warning("play routes unavailable: %r", exc)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000) -> None:
+    """
+    Entry point for running the server without Docker.
+
+    Args:
+        host (`str`, *optional*, defaults to `"0.0.0.0"`):
+            Address to bind.
+        port (`int`, *optional*, defaults to `8000`):
+            Port to listen on.
+    """
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--host", default="0.0.0.0")
+    args = parser.parse_args()
+    main(host=args.host, port=args.port)

geoguesser_env/server/backends/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Imagery backends for the GeoGuesser environment."""
+
+from .base import Frame, PanoramaBackend, Task
+
+__all__ = ["Frame", "PanoramaBackend", "Task"]

geoguesser_env/server/backends/base.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""The contract every imagery backend implements.
+
+Backends differ only in where pixels come from and whether the location can be
+walked. Everything above them — scoring, parsing, the pin loop, the map — is
+shared, so a policy trained against one backend runs unmodified against
+another.
+
+A backend that cannot do something reports it through `supports_look` or
+`supports_move`; the environment then simply does not register the
+corresponding tools. Registering a tool that always fails would only teach a
+policy to spend its step budget discovering that.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from PIL import Image
+
+
+@dataclass(frozen=True)
+class Frame:
+    """One captured position within a sequence.
+
+    Attributes:
+        image_id (`str`):
+            Provider-side identifier, also the cache filename.
+        lat (`float`):
+            Latitude in degrees.
+        lon (`float`):
+            Longitude in degrees.
+        compass_angle (`float`):
+            Heading the camera faced, in degrees clockwise from true north.
+        captured_at (`str`):
+            Capture month as `YYYY-MM`.
+        is_pano (`bool`, *optional*, defaults to `True`):
+            Whether this frame is a full 360-degree panorama.
+    """
+
+    image_id: str
+    lat: float
+    lon: float
+    compass_angle: float
+    captured_at: str
+    is_pano: bool = True
+
+
+@dataclass(frozen=True)
+class Task:
+    """One episode's location, frozen at index build time.
+
+    Attributes:
+        task_index (`int`):
+            Position in the task list. Stable, and what `reset` selects on.
+        task_id (`str`):
+            Human-readable identifier, unique within the index.
+        frames (`list[Frame]`):
+            Ordered frames of the captured sequence, walkable with `move`.
+        start_frame (`int`):
+            Index into `frames` where the episode begins.
+        country (`str`):
+            ISO-3166 alpha-2 code of the true location. Ground truth — never
+            placed in an observation before the guess.
+        sequence_id (`str`):
+            Provider-side sequence identifier.
+        provider (`str`, *optional*, defaults to `"mapillary"`):
+            Which backend can resolve this task's imagery.
+        attribution (`dict`, *optional*):
+            Creator credit, required by the CC-BY-SA licence on the imagery.
+        meta (`dict`, *optional*):
+            Anything else the builder recorded — camera make and model,
+            quality score, checksums.
+    """
+
+    task_index: int
+    task_id: str
+    frames: list[Frame]
+    start_frame: int
+    country: str
+    sequence_id: str
+    provider: str = "mapillary"
+    attribution: dict[str, Any] = field(default_factory=dict)
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def truth(self) -> tuple[float, float]:
+        """Ground-truth `(lat, lon)` of the starting frame."""
+        frame = self.frames[self.start_frame]
+        return frame.lat, frame.lon
+
+
+@runtime_checkable
+class PanoramaBackend(Protocol):
+    """Resolves tasks to imagery and answers what the agent may do."""
+
+    @property
+    def n_tasks(self) -> int:
+        """Number of tasks in the frozen index."""
+        ...
+
+    @property
+    def supports_look(self) -> bool:
+        """Whether views can be rendered at arbitrary headings."""
+        ...
+
+    @property
+    def supports_move(self) -> bool:
+        """Whether the location can be walked along a sequence."""
+        ...
+
+    def task(self, task_index: int) -> Task:
+        """Return the task at `task_index`."""
+        ...
+
+    def render_view(
+        self,
+        task: Task,
+        frame_index: int,
+        heading_deg: float,
+        pitch_deg: float,
+        fov_deg: float,
+    ) -> Image.Image:
+        """Render what the camera sees from one frame."""
+        ...

geoguesser_env/server/backends/panorama.py

@@ -0,0 +1,399 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Mapillary-backed panoramas, read from a frozen index and a local cache.
+
+The index (`tasks/pano_v1.jsonl`) is self-contained: it carries every frame's
+coordinates, heading and capture date, so the movement graph resolves with no
+network access at all. Only image *bytes* may need fetching, and only on a
+cache miss, because Mapillary's `thumb_*_url` values are expiring signed CDN
+URLs and cannot be stored in the index.
+
+Once a task's frames are cached, episodes are byte-identical on repeat — the
+property a GRPO group depends on.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import pathlib
+import urllib.parse
+import urllib.request
+
+from PIL import Image
+
+from ..render.pano import look
+from .base import Frame, Task
+
+
+logger = logging.getLogger(__name__)
+
+GRAPH_API = "https://graph.mapillary.com"
+FETCH_TIMEOUT_S = 60.0
+
+# Zooming into a 2048x1024 panorama is resolution-starved: a 30-degree view
+# samples only ~170 source pixels, so narrowing the field of view barely adds
+# detail (measured mean gradient 6.60 at 90 degrees against 7.03 at 30). The
+# 7680x3840 original roughly doubles it instead (10.23 against 14.87), which is
+# what makes reading a distant sign possible at all.
+#
+# So two derivatives are cached per panorama: the 2048 for wide views, which
+# renders in ~30 ms, and the original for zoomed views at ~70 ms and 3.3 MB.
+THUMB_VARIANT = "thumb_2048_url"
+ORIGINAL_VARIANT = "thumb_original_url"
+HIRES_FOV_DEG = 45.0
+
+
+class MissingImageError(RuntimeError):
+    """A frame is absent from the cache and cannot be fetched."""
+
+
+_INDEX_CACHE: dict[tuple[str, float, int], list[Task]] = {}
+"""Parsed indexes keyed by path, mtime and size, so edits invalidate the entry."""
+
+
+def load_index(index_path: str | pathlib.Path) -> list[Task]:
+    """
+    Parse a task index, reusing an already-parsed copy when possible.
+
+    The Task API routes construct a throwaway environment per request and a
+    5,000-task index is roughly 31 MB, so re-parsing it on every call is not
+    affordable. Keying on mtime and size means rebuilding an index in place
+    invalidates the entry instead of serving stale tasks.
+
+    Args:
+        index_path (`str` or `pathlib.Path`):
+            JSONL index written by `scripts/build_tasks.py`.
+
+    Returns:
+        `list[Task]`: Tasks ordered by `task_index`. The list is shared between
+            callers, so treat it as read-only.
+
+    Raises:
+        FileNotFoundError: When the index does not exist.
+        ValueError: When the index is empty, or its task indices are not
+            contiguous from zero.
+    """
+    path = pathlib.Path(index_path)
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Task index not found: {path}. Build one with scripts/build_tasks.py."
+        )
+    stat = path.stat()
+    key = (str(path.resolve()), stat.st_mtime, stat.st_size)
+    cached = _INDEX_CACHE.get(key)
+    if cached is not None:
+        return cached
+
+    tasks: list[Task] = []
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        row = json.loads(line)
+        frames = [
+            Frame(
+                image_id=str(f["image_id"]),
+                lat=float(f["lat"]),
+                lon=float(f["lon"]),
+                compass_angle=float(f.get("compass_angle", 0.0)),
+                captured_at=str(f.get("captured_at", "")),
+                is_pano=bool(f.get("is_pano", True)),
+            )
+            for f in row["frames"]
+        ]
+        tasks.append(
+            Task(
+                task_index=int(row["task_index"]),
+                task_id=str(row["task_id"]),
+                frames=frames,
+                start_frame=int(row.get("start_frame", 0)),
+                country=str(row.get("country", "")),
+                sequence_id=str(row.get("sequence_id", "")),
+                provider=str(row.get("provider", "mapillary")),
+                attribution=row.get("attribution", {}),
+                meta=row.get("meta", {}),
+            )
+        )
+    if not tasks:
+        raise ValueError(f"Task index {path} is empty.")
+    tasks.sort(key=lambda t: t.task_index)
+    for position, task in enumerate(tasks):
+        if task.task_index != position:
+            raise ValueError(
+                "Task indices must be contiguous from 0; found "
+                f"{task.task_index} at position {position}."
+            )
+    _INDEX_CACHE[key] = tasks
+    return tasks
+
+
+class PanoramaBackend:
+    """Serve panoramas from a frozen task index plus a disk cache.
+
+    Args:
+        index_path (`str` or `pathlib.Path`):
+            JSONL task index produced by `scripts/build_pano_tasks.py`.
+        cache_dir (`str` or `pathlib.Path`):
+            Directory holding cached JPEGs, named `<image_id>.jpg`.
+        access_token (`str`, *optional*):
+            Mapillary token, used only to fill cache misses. When absent, a
+            miss raises [`MissingImageError`] instead of reaching the network.
+        allow_fetch (`bool`, *optional*, defaults to `True`):
+            Set `False` to guarantee an episode never touches the network.
+        hires_zoom (`bool`, *optional*, defaults to `True`):
+            Render fields of view at or below `hires_fov_deg` from the
+            full-resolution original, so zooming actually resolves detail.
+            Falls back to the 2048 derivative when no original exists.
+        hires_fov_deg (`float`, *optional*, defaults to `45.0`):
+            Field of view at or below which the original is used.
+        verify_checksums (`bool`, *optional*, defaults to `False`):
+            Verify each cached start frame against the sha256 recorded at build
+            time. Used by frozen evals to detect drift.
+
+    Examples:
+
+    ```python
+    backend = PanoramaBackend("tasks/pano_v1.jsonl", "data/panos")
+    task = backend.task(0)
+    view = backend.render_view(task, task.start_frame, 90.0, 0.0, 90.0)
+    ```
+    """
+
+    def __init__(
+        self,
+        index_path: str | pathlib.Path,
+        cache_dir: str | pathlib.Path,
+        access_token: str | None = None,
+        allow_fetch: bool = True,
+        verify_checksums: bool = False,
+        hires_zoom: bool = True,
+        hires_fov_deg: float = HIRES_FOV_DEG,
+    ):
+        self._index_path = pathlib.Path(index_path)
+        self._cache_dir = pathlib.Path(cache_dir)
+        self._cache_dir.mkdir(parents=True, exist_ok=True)
+        self._token = access_token or os.environ.get("MAPILLARY_API_KEY")
+        self._allow_fetch = allow_fetch
+        self._verify_checksums = verify_checksums
+        self._hires_zoom = hires_zoom
+        self._hires_fov_deg = hires_fov_deg
+        self._tasks = self._load_index()
+        logger.info(
+            "loaded %d tasks from %s (cache: %s, fetch: %s)",
+            len(self._tasks),
+            self._index_path,
+            self._cache_dir,
+            "on" if self._allow_fetch and self._token else "off",
+        )
+
+    # -- index ------------------------------------------------------------
+
+    def _load_index(self) -> list[Task]:
+        return load_index(self._index_path)
+
+    # -- capabilities -----------------------------------------------------
+
+    @property
+    def n_tasks(self) -> int:
+        """Number of tasks in the frozen index."""
+        return len(self._tasks)
+
+    @property
+    def supports_look(self) -> bool:
+        """True — every task in this index is a 360-degree panorama."""
+        return True
+
+    @property
+    def supports_move(self) -> bool:
+        """Whether any task has more than one frame to walk between."""
+        return any(len(t.frames) > 1 for t in self._tasks)
+
+    def task(self, task_index: int) -> Task:
+        """
+        Return the task at `task_index`.
+
+        Args:
+            task_index (`int`):
+                Position in the frozen index.
+
+        Returns:
+            [`Task`]: The task, including its full frame list.
+        """
+        if not 0 <= task_index < len(self._tasks):
+            raise IndexError(
+                f"task_index {task_index} out of range for {len(self._tasks)} tasks."
+            )
+        return self._tasks[task_index]
+
+    # -- imagery ----------------------------------------------------------
+
+    def _cache_path(self, image_id: str, hires: bool = False) -> pathlib.Path:
+        suffix = ".orig.jpg" if hires else ".jpg"
+        return self._cache_dir / f"{image_id}{suffix}"
+
+    def _fetch(self, image_id: str, hires: bool = False) -> bytes:
+        if not self._allow_fetch:
+            raise MissingImageError(
+                f"Image {image_id} is not cached and fetching is disabled. "
+                "Warm the cache with scripts/build_pano_tasks.py --prefetch-frames."
+            )
+        if not self._token:
+            raise MissingImageError(
+                f"Image {image_id} is not cached and MAPILLARY_API_KEY is unset, "
+                "so it cannot be fetched."
+            )
+        variant = ORIGINAL_VARIANT if hires else THUMB_VARIANT
+        meta_url = f"{GRAPH_API}/{image_id}?" + urllib.parse.urlencode(
+            {"fields": variant, "access_token": self._token}
+        )
+        with urllib.request.urlopen(meta_url, timeout=FETCH_TIMEOUT_S) as response:
+            thumb_url = json.loads(response.read()).get(variant)
+        if not thumb_url:
+            raise MissingImageError(
+                f"Mapillary returned no {variant} for {image_id}; its "
+                "derivatives may have been removed."
+            )
+        with urllib.request.urlopen(thumb_url, timeout=FETCH_TIMEOUT_S) as response:
+            return response.read()
+
+    def load_pano(
+        self,
+        image_id: str,
+        expected_sha256: str | None = None,
+        hires: bool = False,
+    ) -> Image.Image:
+        """
+        Return a panorama, fetching and caching it if necessary.
+
+        Args:
+            image_id (`str`):
+                Provider-side image identifier.
+            expected_sha256 (`str`, *optional*):
+                Checksum recorded at build time. Verified only when the backend
+                was constructed with `verify_checksums=True`, and only for
+                the 2048 derivative, which is what the index records.
+            hires (`bool`, *optional*, defaults to `False`):
+                Load the full-resolution original instead of the 2048
+                derivative.
+
+        Returns:
+            `PIL.Image.Image`: The equirectangular panorama.
+        """
+        path = self._cache_path(image_id, hires=hires)
+        if not path.exists():
+            payload = self._fetch(image_id, hires=hires)
+            path.write_bytes(payload)
+            logger.info(
+                "cached %s%s (%.0f KB)",
+                image_id,
+                " at full resolution" if hires else "",
+                len(payload) / 1024,
+            )
+        if self._verify_checksums and expected_sha256 and not hires:
+            actual = hashlib.sha256(path.read_bytes()).hexdigest()
+            if actual != expected_sha256:
+                raise MissingImageError(
+                    f"Checksum mismatch for {image_id}: index recorded "
+                    f"{expected_sha256[:12]}, cache holds {actual[:12]}. The "
+                    "upstream image changed; this task is no longer comparable."
+                )
+        return Image.open(path)
+
+    def render_view(
+        self,
+        task: Task,
+        frame_index: int,
+        heading_deg: float,
+        pitch_deg: float = 0.0,
+        fov_deg: float = 90.0,
+    ) -> Image.Image:
+        """
+        Render what the camera sees from one frame of a task.
+
+        Headings are absolute: `0` is true north, obtained by offsetting the
+        request by the frame's own `compass_angle`. That keeps `look(0)`
+        meaning the same thing in every task.
+
+        Args:
+            task ([`Task`]):
+                The task being played.
+            frame_index (`int`):
+                Which frame of the sequence the agent stands on.
+            heading_deg (`float`):
+                Absolute compass heading in degrees.
+            pitch_deg (`float`, *optional*, defaults to `0.0`):
+                Vertical angle in degrees.
+            fov_deg (`float`, *optional*, defaults to `90.0`):
+                Horizontal field of view in degrees.
+
+        Returns:
+            `PIL.Image.Image`: The rendered view.
+        """
+        frame = task.frames[frame_index]
+        checksums = task.meta.get("sha256", {})
+        want_hires = self._hires_zoom and fov_deg <= self._hires_fov_deg
+        try:
+            pano = self.load_pano(
+                frame.image_id, checksums.get(frame.image_id), hires=want_hires
+            )
+        except MissingImageError:
+            if not want_hires:
+                raise
+            # A missing original must not end an episode; a soft view beats a
+            # failed step.
+            logger.warning(
+                "no full-resolution original for %s; zooming on the 2048 "
+                "derivative instead",
+                frame.image_id,
+            )
+            pano = self.load_pano(frame.image_id, checksums.get(frame.image_id))
+        return look(pano, heading_deg + frame.compass_angle, pitch_deg, fov_deg)
+
+    # -- navigation -------------------------------------------------------
+
+    def step_along(
+        self, task: Task, frame_index: int, direction: str, meters: float
+    ) -> tuple[int, float]:
+        """
+        Walk the sequence and report where the agent actually ended up.
+
+        Frame spacing is irregular — measured around 3.3 m on Mapillary
+        sequences — so the requested distance is consumed frame by frame and
+        the realised distance is returned rather than assumed.
+
+        Args:
+            task ([`Task`]):
+                The task being played.
+            frame_index (`int`):
+                Current position in `task.frames`.
+            direction (`str`):
+                `"forward"` or `"backward"`.
+            meters (`float`):
+                Requested distance in metres.
+
+        Returns:
+            `tuple[int, float]` with:
+                - the new frame index, unchanged at a dead end
+                - metres actually travelled
+        """
+        from ..scoring import haversine_km
+
+        step = 1 if direction == "forward" else -1
+        current = frame_index
+        travelled = 0.0
+        while travelled < meters:
+            nxt = current + step
+            if not 0 <= nxt < len(task.frames):
+                break
+            a, b = task.frames[current], task.frames[nxt]
+            travelled += haversine_km(a.lat, a.lon, b.lat, b.lon) * 1000.0
+            current = nxt
+        return current, travelled
+
+    def can_move(self, task: Task, frame_index: int, direction: str) -> bool:
+        """Whether a frame exists in `direction` from the current position."""
+        step = 1 if direction == "forward" else -1
+        return 0 <= frame_index + step < len(task.frames)

geoguesser_env/server/geoguesser_environment.py

@@ -0,0 +1,883 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""The GeoGuesser environment.
+
+Exposes its tools over MCP so an agent can look around, walk, and check
+candidate coordinates on a map before committing to a guess. Non-MCP
+structured actions route through `_step_impl`, which is what makes single-shot
+GRPO and the agentic loop the same environment rather than two.
+
+Two rules are load-bearing:
+
+- Pin feedback describes only where the agent pointed. Any signal about the
+  target would make binary search optimal, and the benchmark would measure
+  bisection instead of geography.
+- Tools the backend cannot serve are never registered, rather than registered
+  and failing, so a policy does not learn to spend steps on dead ends.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import uuid
+from typing import Any
+
+from fastmcp import FastMCP
+from openenv.core.env_server.mcp_environment import MCPEnvironment
+from openenv.core.env_server.types import Action, Observation
+
+from ..models import (
+    EpisodeMode,
+    from_wire,
+    GeoGuesserAction,
+    GeoGuesserObservation,
+    GeoGuesserState,
+    GuessAction,
+    LookAction,
+    MeasureAction,
+    MoveAction,
+    PanAction,
+    Pin,
+    PinAction,
+    RewardMode,
+    TypedAction,
+    ViewMapAction,
+    ZoomAction,
+)
+from .backends.base import Task
+from .backends.panorama import PanoramaBackend
+from .parser import parse_guess
+from .render.minimap import describe_pin, locate, render_map
+from .render.pano import to_base64
+from .scoring import action_cost, compute_reward, haversine_km, verdict
+
+
+logger = logging.getLogger(__name__)
+
+PROMPT = (
+    "You are dropped at an unknown street-level location somewhere in the "
+    "world. Work out where you are.\n\n"
+    "Available tools: {tools}\n\n"
+    "Looking around and checking the map cost a little reward each, so gather "
+    "the evidence you need and then commit. You have {steps} actions. "
+    "Placing a pin shows you where on the map that coordinate falls - it "
+    "tells you nothing about whether you are right. Finish with "
+    "submit_guess."
+)
+
+
+class UnknownSplitError(KeyError, IndexError):
+    """A split name that is not configured.
+
+    Inherits both exception types deliberately. `KeyError` is what a Python
+    caller expects from a bad name, while the core Task API dispatcher maps
+    only `NotImplementedError` and `IndexError` onto HTTP status codes -- so
+    without `IndexError` an unknown split surfaces as a 500 instead of a 400.
+    """
+
+
+class GeoGuesserEnvironment(MCPEnvironment):
+    """A GeoGuessr-style geolocation episode.
+
+    Args:
+        index_path (`str`):
+            JSONL task index built by `scripts/build_pano_tasks.py`.
+        cache_dir (`str`):
+            Directory of cached panorama JPEGs.
+        episode_mode (`str`, *optional*, defaults to `"agentic"`):
+            One of `"agentic"`, `"single_shot"` or `"nmpz"`.
+        max_steps (`int`, *optional*, defaults to `24`):
+            Actions allowed before the episode is cut off. Twelve is tight
+            for an agentic episode: looking in four directions and walking
+            a block spends most of it before any reasoning about the map.
+        reward_mode (`str`, *optional*, defaults to `"coords"`):
+            `"coords"` scores distance; `"country_only"` scores the country.
+        hierarchical_reward (`bool`, *optional*, defaults to `False`):
+            Add country and region partial credit to the distance score.
+        view_size (`int`, *optional*, defaults to `640`):
+            Edge length in pixels of rendered views.
+        allow_fetch (`bool`, *optional*, defaults to `True`):
+            Whether a cache miss may reach the Mapillary API.
+        hires_zoom (`bool`, *optional*, defaults to `True`):
+            Render zoomed views from the full-resolution original, so a narrow
+            field of view actually resolves detail such as distant signage.
+        reveal_map (`bool`, *optional*, defaults to `True`):
+            Draw a map of the guess against the truth on the terminal
+            observation. Costs about 280 ms, which is the single largest cost in
+            an episode, and a training run does not read it — the reward and the
+            distance are in the observation either way. Leave it on for evals,
+            demos and traces; turn it off for throughput.
+
+    Examples:
+
+    ```python
+    env = GeoGuesserEnvironment("tasks/pano_v1.jsonl", "data/panos")
+    observation = env.reset(task_index=0)
+    result = env.step(LookAction(heading_deg=90))
+    ```
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    def __init__(
+        self,
+        index_path: str | None = None,
+        cache_dir: str = "",
+        episode_mode: str = EpisodeMode.AGENTIC.value,
+        max_steps: int = 24,
+        reward_mode: str = RewardMode.COORDS.value,
+        hierarchical_reward: bool = False,
+        view_size: int = 640,
+        allow_fetch: bool = True,
+        hires_zoom: bool = True,
+        reveal_map: bool = True,
+        splits: dict[str, str] | None = None,
+        default_split: str = "train",
+    ):
+        if splits:
+            self._split_paths = {name: str(path) for name, path in splits.items()}
+        elif index_path:
+            # Single-index callers keep working: one nameless index becomes the
+            # default split, so existing tests, harness runs and the play UI
+            # need no change.
+            self._split_paths = {default_split: str(index_path)}
+        else:
+            raise ValueError("Provide either splits= or index_path=.")
+        if default_split not in self._split_paths:
+            raise ValueError(
+                f"default_split {default_split!r} is not one of "
+                f"{sorted(self._split_paths)}."
+            )
+        self._default_split = default_split
+        self._cache_dir = cache_dir
+        self._allow_fetch = allow_fetch
+        self._hires_zoom = hires_zoom
+        self._backends: dict[str, PanoramaBackend] = {}
+        self._split = default_split
+        self._backend = self._backend_for(default_split)
+        self._reveal_map = reveal_map
+        self._mode = EpisodeMode(episode_mode)
+        self._max_steps = max_steps
+        self._reward_mode = RewardMode(reward_mode)
+        self._hierarchical = hierarchical_reward
+        self._view_size = (view_size, view_size)
+        self._state = GeoGuesserState()
+        self._task = None
+        self._rng = random.Random()
+
+        mcp = FastMCP("geoguesser_env")
+        self._register_tools(mcp)
+        super().__init__(mcp)
+
+    # -- splits ------------------------------------------------------------
+
+    def _backend_for(self, split: str) -> PanoramaBackend:
+        """
+        Return the backend serving one split, building it on first use.
+
+        Splits are built lazily so a deployment that only mounts the eval index
+        is not forced to carry a training one, and because the parsed index is
+        cached process-wide anyway.
+
+        Args:
+            split (`str`):
+                Split name.
+
+        Returns:
+            [`PanoramaBackend`]: Backend for that split.
+
+        Raises:
+            UnknownSplitError: When the split is not configured.
+        """
+        if split not in self._split_paths:
+            raise UnknownSplitError(
+                f"Unknown split {split!r}. Available: {sorted(self._split_paths)}."
+            )
+        backend = self._backends.get(split)
+        if backend is None:
+            backend = PanoramaBackend(
+                self._split_paths[split],
+                self._cache_dir,
+                allow_fetch=self._allow_fetch,
+                hires_zoom=self._hires_zoom,
+            )
+            self._backends[split] = backend
+        return backend
+
+    @staticmethod
+    def _split_type(split: str) -> str:
+        """
+        Map a split name onto the type vocabulary the core Task API knows.
+
+        Core normalises anything outside `{train, validation, test}` to
+        `validation`, so `eval` is declared as `test` explicitly rather than
+        being silently downgraded.
+        """
+        if split == "train":
+            return "train"
+        if split in {"eval", "test"}:
+            return "test"
+        return "validation"
+
+    def _task_spec(self, split: str, task: Task) -> dict[str, Any]:
+        """
+        Describe one task for the Task API.
+
+        Deliberately truth-free: no coordinates and no country. Task specs
+        travel to whatever orchestrates training, and the moment a label sits
+        in a spec someone can build a prompt from it. The true location is
+        revealed in the observation metadata after the guess, which is the one
+        place it belongs.
+        """
+        return {
+            "task_index": task.task_index,
+            "task_id": task.task_id,
+            "split": split,
+            "n_frames": len(task.frames),
+            "provider": task.provider,
+            "sequence_id": task.sequence_id,
+            "offline_ready": bool(task.meta.get("offline_ready", False)),
+        }
+
+    def list_splits(self) -> list[dict[str, Any]]:
+        """
+        Task API: describe every configured split.
+
+        Returns:
+            `list[dict]` with keys:
+                - `name` (`str`):
+                    Split name, as accepted by `reset(split=)`.
+                - `type` (`str`):
+                    One of `train`, `test` or `validation`.
+                - `num_tasks` (`int`):
+                    Task count in the split.
+                - `default` (`bool`):
+                    Whether `reset()` uses this split when none is given.
+        """
+        return [
+            {
+                "name": name,
+                "type": self._split_type(name),
+                "num_tasks": self._backend_for(name).n_tasks,
+                "default": name == self._default_split,
+            }
+            for name in self._split_paths
+        ]
+
+    def num_tasks(self, split: str) -> int:
+        """Task API: how many tasks a split holds."""
+        return self._backend_for(split).n_tasks
+
+    def get_task(self, split: str, index: int) -> dict[str, Any]:
+        """Task API: describe one task by split and index."""
+        return self._task_spec(split, self._backend_for(split).task(index))
+
+    def list_tasks(self, split: str) -> list[dict[str, Any]]:
+        """Task API: describe every task in a split."""
+        backend = self._backend_for(split)
+        return [
+            self._task_spec(split, backend.task(index))
+            for index in range(backend.n_tasks)
+        ]
+
+    def get_task_range(
+        self, split: str, start: int | None = None, stop: int | None = None
+    ) -> list[dict[str, Any]]:
+        """Task API: describe a slice-style range of tasks in a split."""
+        backend = self._backend_for(split)
+        indices = range(*slice(start, stop).indices(backend.n_tasks))
+        return [self._task_spec(split, backend.task(index)) for index in indices]
+
+    # -- capability-aware tool registration --------------------------------
+
+    def _navigational(self) -> bool:
+        return self._mode is EpisodeMode.AGENTIC and self._backend.supports_move
+
+    def _can_look(self) -> bool:
+        return self._mode is EpisodeMode.AGENTIC and self._backend.supports_look
+
+    def _can_gather(self) -> bool:
+        """Whether the episode has an investigation phase at all.
+
+        `single_shot` deliberately has none: one view, one guess, which is the
+        shape a VLM GRPO run wants. `nmpz` keeps the map but takes the camera
+        away, mirroring the game's own hardest mode.
+        """
+        return self._mode is not EpisodeMode.SINGLE_SHOT
+
+    def _register_tools(self, mcp: FastMCP) -> None:
+        """Register only the tools this configuration can actually serve."""
+        if self._can_look():
+
+            @mcp.tool
+            def look(
+                heading_deg: float, pitch_deg: float = 0.0, fov_deg: float = 90.0
+            ) -> str:
+                """Look in a direction. heading_deg is absolute, 0 = true north.
+
+                Args:
+                    heading_deg: Compass heading in degrees.
+                    pitch_deg: Vertical angle; positive looks up.
+                    fov_deg: Field of view; smaller values zoom in.
+                """
+                return self._apply(
+                    LookAction(
+                        heading_deg=heading_deg, pitch_deg=pitch_deg, fov_deg=fov_deg
+                    )
+                ).feedback
+
+            @mcp.tool
+            def pan(delta_deg: float) -> str:
+                """Turn relative to the current heading; positive turns right.
+
+                Args:
+                    delta_deg: Degrees to turn.
+                """
+                return self._apply(PanAction(delta_deg=delta_deg)).feedback
+
+            @mcp.tool
+            def zoom(fov_deg: float) -> str:
+                """Change field of view without turning. 30 reads distant signs.
+
+                Args:
+                    fov_deg: New field of view in degrees.
+                """
+                return self._apply(ZoomAction(fov_deg=fov_deg)).feedback
+
+        if self._navigational():
+
+            @mcp.tool
+            def move(direction: str, meters: float = 10.0) -> str:
+                """Walk along the road. Reports how far you actually travelled.
+
+                Args:
+                    direction: Either "forward" or "backward".
+                    meters: Requested distance in metres.
+                """
+                return self._apply(
+                    MoveAction(direction=direction, meters=meters)
+                ).feedback
+
+        if self._can_gather():
+            self._register_map_tools(mcp)
+        self._register_guess_tool(mcp)
+
+    def _register_map_tools(self, mcp: FastMCP) -> None:
+        """Register the map and pin tools, which every gathering mode has."""
+
+        @mcp.tool
+        def place_pin(
+            lat: float, lon: float, label: str = "", span_deg: float = 7.0
+        ) -> str:
+            """Pin a candidate and see where it falls on the map.
+
+            Tells you what is at that coordinate. Says nothing about whether
+            you are right.
+
+            Args:
+                lat: Latitude of the candidate.
+                lon: Longitude of the candidate.
+                label: Optional note.
+                span_deg: Half-width of the map window in degrees. Below about
+                    4 the map adds roads, urban areas and town names, which is
+                    how you aim within a city rather than at its centre.
+            """
+            return self._apply(
+                PinAction(lat=lat, lon=lon, label=label or None, span_deg=span_deg)
+            ).feedback
+
+        @mcp.tool
+        def view_map(lat: float, lon: float, span_deg: float = 7.0) -> str:
+            """Pan and zoom the map without placing a pin.
+
+            Args:
+                lat: Latitude at the centre of the view.
+                lon: Longitude at the centre of the view.
+                span_deg: Half-width of the window in degrees.
+            """
+            return self._apply(
+                ViewMapAction(lat=lat, lon=lon, span_deg=span_deg)
+            ).feedback
+
+        @mcp.tool
+        def list_pins() -> str:
+            """List the candidates pinned so far. Free."""
+            if not self._state.pins:
+                return "No pins placed yet."
+            return "\n".join(
+                f"{i}. {p['lat']:.4f}, {p['lon']:.4f} - {p['description']}"
+                for i, p in enumerate(self._state.pins, 1)
+            )
+
+        @mcp.tool
+        def clear_pins() -> str:
+            """Remove all pins. Free."""
+            self._state.pins = []
+            return "Pins cleared."
+
+        @mcp.tool
+        def measure(lat_a: float, lon_a: float, lat_b: float, lon_b: float) -> str:
+            """Distance in km between two coordinates of your own choosing. Free.
+
+            Args:
+                lat_a: Latitude of the first point.
+                lon_a: Longitude of the first point.
+                lat_b: Latitude of the second point.
+                lon_b: Longitude of the second point.
+            """
+            km = haversine_km(lat_a, lon_a, lat_b, lon_b)
+            return f"{km:.0f} km between those two points."
+
+        @mcp.tool
+        def reverse_geocode(lat: float, lon: float) -> str:
+            """Name the country and nearest city at a coordinate. Free.
+
+            Args:
+                lat: Latitude in degrees.
+                lon: Longitude in degrees.
+            """
+            place = locate(lat, lon)
+            where = place.country or "open water"
+            return (
+                f"{lat:.4f}, {lon:.4f} is in {where}. Nearest major city: "
+                f"{place.nearest_city}, ~{place.city_distance_km:.0f} km "
+                f"{place.city_bearing}."
+            )
+
+    def _register_guess_tool(self, mcp: FastMCP) -> None:
+        """Register the terminal action, which every mode has."""
+
+        @mcp.tool
+        def submit_guess(
+            lat: float,
+            lon: float,
+            country: str = "",
+            confidence: float = -1.0,
+            reasoning: str = "",
+        ) -> str:
+            """Commit your final answer. Ends the episode.
+
+            Args:
+                lat: Latitude of your guess.
+                lon: Longitude of your guess.
+                country: Optional ISO-3166 alpha-2 code or country name.
+                confidence: Optional self-reported confidence in [0, 1].
+                reasoning: Optional rationale, recorded but not scored.
+            """
+            observation = self._apply(
+                GuessAction(
+                    lat=lat,
+                    lon=lon,
+                    country=country or None,
+                    confidence=None if confidence < 0 else confidence,
+                    reasoning=reasoning or None,
+                )
+            )
+            return observation.feedback
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def reset(
+        self,
+        seed: int | None = None,
+        episode_id: str | None = None,
+        split: str | None = None,
+        index: int | None = None,
+        task_index: int | None = None,
+        **kwargs: Any,
+    ) -> GeoGuesserObservation:
+        """
+        Start an episode.
+
+        Selection is explicit, because training and demoing want opposite
+        things. `index` picks one exact task and is byte-identical on repeat,
+        which is what a GRPO group needs. `seed` picks `tasks[seed % n_tasks]`.
+        Neither means a random task; omitting both does, and the chosen split
+        and index are always reported in the observation metadata so a random
+        episode stays replayable.
+
+        Args:
+            seed (`int`, *optional*):
+                Deterministic selector, `tasks[seed % n_tasks]`.
+            episode_id (`str`, *optional*):
+                Caller-supplied episode identifier.
+            split (`str`, *optional*):
+                Which split to draw from. Defaults to the environment's default
+                split.
+            index (`int`, *optional*):
+                Exact task to play, within `split`. Takes precedence over
+                `seed`.
+            task_index (`int`, *optional*):
+                Deprecated alias for `index`, kept so existing callers and
+                saved trajectories keep working.
+
+        Returns:
+            [`GeoGuesserObservation`]: The opening view and prompt.
+
+        Raises:
+            UnknownSplitError: When `split` is not configured.
+        """
+        self._split = split or self._default_split
+        self._backend = self._backend_for(self._split)
+
+        if index is None:
+            index = task_index
+        n = self._backend.n_tasks
+        if index is not None:
+            chosen = int(index) % n
+        elif seed is not None:
+            chosen = int(seed) % n
+        else:
+            chosen = self._rng.randrange(n)
+
+        self._task = self._backend.task(chosen)
+        start = self._task.frames[self._task.start_frame]
+        self._state = GeoGuesserState(
+            episode_id=episode_id or str(uuid.uuid4()),
+            task_index=chosen,
+            task_id=self._task.task_id,
+            frame_index=self._task.start_frame,
+            heading_deg=0.0,
+            pitch_deg=0.0,
+            fov_deg=90.0,
+        )
+
+        observation = self._render_view_observation()
+        observation.prompt = PROMPT.format(
+            tools=", ".join(self._tool_names()), steps=self._max_steps
+        )
+        observation.feedback = "Episode started."
+        observation.captured_at = start.captured_at
+        observation.metadata = self._metadata()
+        return observation
+
+    @property
+    def state(self) -> GeoGuesserState:
+        """Current internal state."""
+        return self._state
+
+    def _step_impl(self, action: Action, **kwargs: Any) -> Observation:
+        """Handle structured, non-MCP actions.
+
+        Accepts either the flat wire action the HTTP layer delivers or a typed
+        action constructed in process, so tests and the harness can bypass
+        serialisation without a second code path.
+        """
+        if isinstance(action, GeoGuesserAction):
+            return self._apply(from_wire(action))
+        if isinstance(action, TypedAction):
+            return self._apply(action)
+        raise TypeError(f"Unsupported action type: {type(action).__name__}")
+
+    # -- the actual mechanics ---------------------------------------------
+
+    def _tool_names(self) -> list[str]:
+        """Names of the tools this configuration actually registered."""
+        names: list[str] = []
+        if self._can_look():
+            names += ["look", "pan", "zoom"]
+        if self._navigational():
+            names.append("move")
+        if self._can_gather():
+            names += [
+                "place_pin",
+                "view_map",
+                "list_pins",
+                "clear_pins",
+                "measure",
+                "reverse_geocode",
+            ]
+        names.append("submit_guess")
+        return names
+
+    def _steps_used(self) -> int:
+        s = self._state
+        return s.n_looks + s.n_maps + s.n_pins + s.n_moves
+
+    def _steps_remaining(self) -> int:
+        return max(0, self._max_steps - self._steps_used())
+
+    def _cost(self) -> float:
+        s = self._state
+        return action_cost(
+            n_looks=s.n_looks, n_maps=s.n_maps, n_pins=s.n_pins, n_moves=s.n_moves
+        )
+
+    def _metadata(self) -> dict[str, Any]:
+        return {
+            "split": self._split,
+            "task_index": self._state.task_index,
+            "task_id": self._state.task_id,
+            "backend": "mapillary",
+            "episode_mode": self._mode.value,
+            "frame_index": self._state.frame_index,
+            "captured_at": self._task.frames[self._state.frame_index].captured_at,
+            "attribution": self._task.attribution,
+        }
+
+    def _base_observation(self) -> GeoGuesserObservation:
+        s = self._state
+        return GeoGuesserObservation(
+            heading_deg=s.heading_deg % 360,
+            pitch_deg=s.pitch_deg,
+            fov_deg=s.fov_deg,
+            total_moved_meters=s.total_moved_meters,
+            can_move_forward=self._navigational()
+            and self._backend.can_move(self._task, s.frame_index, "forward"),
+            can_move_backward=self._navigational()
+            and self._backend.can_move(self._task, s.frame_index, "backward"),
+            available_tools=self._tool_names(),
+            steps_remaining=self._steps_remaining(),
+            action_cost=self._cost(),
+            pins=[Pin(**p) for p in s.pins],
+            captured_at=self._task.frames[s.frame_index].captured_at,
+            metadata=self._metadata(),
+        )
+
+    def _render_view_observation(self) -> GeoGuesserObservation:
+        s = self._state
+        view = self._backend.render_view(
+            self._task, s.frame_index, s.heading_deg, s.pitch_deg, s.fov_deg
+        )
+        if view.size != self._view_size:
+            view = view.resize(self._view_size)
+        observation = self._base_observation()
+        observation.image_base64 = to_base64(view, "JPEG")
+        observation.image_kind = "view"
+        return observation
+
+    def _render_map_observation(
+        self,
+        pins: list[tuple[float, float]],
+        focus,
+        span: float,
+        truth: tuple[float, float] | None = None,
+    ) -> GeoGuesserObservation:
+        image = render_map(pins, focus=focus, span_deg=span, truth=truth)
+        observation = self._base_observation()
+        observation.image_base64 = to_base64(image, "PNG")
+        observation.image_kind = "map"
+        return observation
+
+    def _apply(self, action: Action) -> GeoGuesserObservation:
+        """Execute one action and produce the resulting observation."""
+        if self._task is None:
+            raise RuntimeError("reset() must be called before step().")
+
+        s = self._state
+        s.step_count += 1
+
+        if s.submitted:
+            observation = self._base_observation()
+            observation.done = True
+            observation.feedback = "The episode is over; the guess was already made."
+            return observation
+
+        if isinstance(action, GuessAction):
+            return self._finish(action)
+
+        if self._steps_remaining() <= 0:
+            observation = self._base_observation()
+            observation.feedback = (
+                "Out of actions. Call submit_guess with your best estimate."
+            )
+            return observation
+
+        if isinstance(action, LookAction):
+            s.heading_deg = action.heading_deg
+            s.pitch_deg = action.pitch_deg
+            s.fov_deg = action.fov_deg
+            s.n_looks += 1
+            observation = self._render_view_observation()
+            observation.feedback = (
+                f"Facing {s.heading_deg % 360:.0f} deg, {s.fov_deg:.0f} deg field of "
+                f"view. {self._steps_remaining()} actions left."
+            )
+            return observation
+
+        if isinstance(action, PanAction):
+            s.heading_deg = (s.heading_deg + action.delta_deg) % 360
+            s.n_looks += 1
+            observation = self._render_view_observation()
+            observation.feedback = (
+                f"Turned to {s.heading_deg:.0f} deg. "
+                f"{self._steps_remaining()} actions left."
+            )
+            return observation
+
+        if isinstance(action, ZoomAction):
+            s.fov_deg = action.fov_deg
+            s.n_looks += 1
+            observation = self._render_view_observation()
+            observation.feedback = (
+                f"Field of view now {s.fov_deg:.0f} deg. "
+                f"{self._steps_remaining()} actions left."
+            )
+            return observation
+
+        if isinstance(action, MoveAction):
+            new_index, travelled = self._backend.step_along(
+                self._task, s.frame_index, action.direction, action.meters
+            )
+            s.n_moves += 1
+            if new_index == s.frame_index:
+                observation = self._render_view_observation()
+                observation.feedback = (
+                    f"Cannot go {action.direction} - the captured road ends here. "
+                    f"{self._steps_remaining()} actions left."
+                )
+                return observation
+            s.frame_index = new_index
+            s.total_moved_meters += travelled
+            observation = self._render_view_observation()
+            observation.moved_meters = travelled
+            observation.feedback = (
+                f"Moved {travelled:.0f} m {action.direction} "
+                f"({s.total_moved_meters:.0f} m total). "
+                f"{self._steps_remaining()} actions left."
+            )
+            return observation
+
+        if isinstance(action, PinAction):
+            previous = (s.pins[-1]["lat"], s.pins[-1]["lon"]) if s.pins else None
+            description = describe_pin(
+                len(s.pins) + 1, action.lat, action.lon, previous=previous
+            )
+            s.pins.append(
+                {
+                    "index": len(s.pins) + 1,
+                    "lat": action.lat,
+                    "lon": action.lon,
+                    "label": action.label,
+                    "description": description,
+                }
+            )
+            s.n_pins += 1
+            pins = [(p["lat"], p["lon"]) for p in s.pins]
+            observation = self._render_map_observation(
+                pins, (action.lat, action.lon), action.span_deg
+            )
+            observation.feedback = (
+                f"{description} {self._steps_remaining()} actions left."
+            )
+            return observation
+
+        if isinstance(action, ViewMapAction):
+            s.n_maps += 1
+            pins = [(p["lat"], p["lon"]) for p in s.pins]
+            observation = self._render_map_observation(
+                pins, (action.lat, action.lon), action.span_deg
+            )
+            place = locate(action.lat, action.lon)
+            observation.feedback = (
+                f"Map centred on {action.lat:.3f}, {action.lon:.3f} "
+                f"({place.country or 'open water'}), "
+                f"{action.span_deg * 2:.0f} deg across. "
+                f"{self._steps_remaining()} actions left."
+            )
+            return observation
+
+        if isinstance(action, MeasureAction):
+            km = haversine_km(action.lat_a, action.lon_a, action.lat_b, action.lon_b)
+            observation = self._base_observation()
+            observation.feedback = f"{km:.0f} km between those two points."
+            return observation
+
+        raise TypeError(f"Unsupported action type: {type(action).__name__}")
+
+    def _finish(self, action: GuessAction) -> GeoGuesserObservation:
+        """Score the final guess and end the episode."""
+        s = self._state
+        s.submitted = True
+        true_lat, true_lon = self._task.truth
+
+        if action.lat is not None and action.lon is not None:
+            lat, lon, parsed_ok, note = action.lat, action.lon, True, ""
+        else:
+            parsed = parse_guess(action.response or "")
+            lat, lon, parsed_ok, note = parsed.lat, parsed.lon, parsed.ok, parsed.note
+
+        cost = self._cost()
+        observation = self._base_observation()
+        observation.done = True
+        observation.parsed_ok = parsed_ok
+        observation.true_lat = true_lat
+        observation.true_lon = true_lon
+        observation.action_cost = cost
+
+        if not parsed_ok:
+            observation.reward = 0.0
+            observation.score = 0.0
+            observation.feedback = f"No usable guess. {note} Scored 0."
+            observation.metadata = {**self._metadata(), "parse_failure": True}
+            return observation
+
+        distance = haversine_km(lat, lon, true_lat, true_lon)
+
+        # A guess previously returned no image at all, which left the outcome
+        # invisible in a trace and gave a policy nothing to learn the shape of
+        # its error from. Truth is only ever drawn here, after scoring.
+        if not self._reveal_map:
+            observation.image_kind = "none"
+        separation = max(abs(lat - true_lat), abs(lon - true_lon))
+        if self._reveal_map and separation > 25.0:
+            # Framing both points would squash a hemisphere into the panel and
+            # tell you nothing. The useful second view is where it actually was.
+            reveal_focus = (true_lat, true_lon)
+            reveal_span = 12.0
+        elif self._reveal_map:
+            reveal_focus = ((lat + true_lat) / 2, (lon + true_lon) / 2)
+            reveal_span = max(0.05, separation * 0.75 + 0.4)
+        if self._reveal_map:
+            reveal = self._render_map_observation(
+                [(lat, lon)], reveal_focus, reveal_span, truth=(true_lat, true_lon)
+            )
+            observation.image_base64 = reveal.image_base64
+            observation.image_kind = "map"
+
+        truth_place = locate(true_lat, true_lon)
+        guess_place = locate(lat, lon)
+        country_hit = bool(
+            truth_place.country and truth_place.country == guess_place.country
+        )
+        region_hit = bool(
+            truth_place.subregion and truth_place.subregion == guess_place.subregion
+        )
+
+        if self._reward_mode is RewardMode.COUNTRY_ONLY:
+            reward = max(0.0, float(country_hit) - cost)
+            score = float(country_hit)
+        else:
+            score = compute_reward(
+                distance,
+                cost=0.0,
+                country_hit=country_hit,
+                region_hit=region_hit,
+                hierarchical=self._hierarchical,
+            )
+            reward = max(0.0, score - cost)
+
+        observation.distance_km = distance
+        observation.score = score
+        observation.reward = reward
+        observation.feedback = (
+            f"{verdict(distance)} - {distance:.0f} km away. True location "
+            f"{true_lat:.4f}, {true_lon:.4f} "
+            f"({truth_place.country or 'open water'}). "
+            f"Score {score:.3f} minus {cost:.2f} action cost = {reward:.3f}."
+        )
+        observation.metadata = {
+            **self._metadata(),
+            "distance_km": distance,
+            "country_hit": country_hit,
+            "region_hit": region_hit,
+            "confidence": action.confidence,
+            "reasoning": action.reasoning,
+            "n_looks": s.n_looks,
+            "n_maps": s.n_maps,
+            "n_pins": s.n_pins,
+            "n_moves": s.n_moves,
+            "total_moved_meters": s.total_moved_meters,
+        }
+        return observation

geoguesser_env/server/gradio_ui.py

@@ -0,0 +1,1044 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""The human-play page: a GeoGuessr-style game in the browser.
+
+Two viewers, both driven by the environment's own data:
+
+- Pannellum shows the equirectangular panorama, so a person drags to look
+  around exactly where the agent calls `look()`.
+- MapLibre shows the guess map over OpenFreeMap tiles. No API key, no request
+  limits, commercial use permitted, and self-hostable if the public instance
+  ever goes away.
+
+The page is served as its own document at `/geoguesser/play` and embedded in
+the Gradio tab through an iframe, because `gr.HTML` inserts markup without
+executing `<script>` tags — styles apply, but neither viewer initialises, which
+looks like a blank panel and reports no error anywhere.
+
+A human sees live tiles; the agent's map stays the offline Natural Earth
+render. They agree on geometry, which is what matters, and the agent keeps a
+determinism the browser does not need.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import urllib.parse
+from typing import Any, Dict, List, Optional
+
+import gradio as gr
+
+
+MAPLIBRE_JS = "https://cdnjs.cloudflare.com/ajax/libs/maplibre-gl/5.24.0/maplibre-gl.js"
+MAPLIBRE_CSS = (
+    "https://cdnjs.cloudflare.com/ajax/libs/maplibre-gl/5.24.0/maplibre-gl.css"
+)
+PANNELLUM_JS = "https://cdnjs.cloudflare.com/ajax/libs/pannellum/2.5.6/pannellum.js"
+PANNELLUM_CSS = "https://cdnjs.cloudflare.com/ajax/libs/pannellum/2.5.6/pannellum.css"
+OPENFREEMAP_STYLE = "https://tiles.openfreemap.org/styles/positron"
+
+# The real game scores a round out of 5000 on this curve. Showing points
+# rather than the RL reward makes a score comparable to GeoGuessr intuition;
+# the reward is shown beside it so the two are never confused. There is no
+# multi-round game here, because an episode is exactly one guess.
+MAX_POINTS_PER_ROUND = 5000
+
+_TEMPLATE = r"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>geoguesser_env - play</title>
+<link rel="stylesheet" href="__MAPLIBRE_CSS__">
+<link rel="stylesheet" href="__PANNELLUM_CSS__">
+<style>
+  :root {
+    --panel: rgba(18, 23, 28, .92);
+    --edge: #2c353d;
+    --ink: #e8ecef;
+    --ink-soft: #9aa5ad;
+    --ink-faint: #6e7a83;
+    --pin: #c4332a;
+    --good: #5aa06e;
+    --wire: #7fb3cc;
+  }
+  * { box-sizing: border-box; }
+  html, body {
+    margin: 0; height: 100%; overflow: hidden; background: #10151a;
+    color: var(--ink);
+    font-family: ui-monospace, "SF Mono", "IBM Plex Mono", Menlo, monospace;
+  }
+  #stage { position: absolute; inset: 0; }
+  #pano { position: absolute; inset: 0; }
+  .pnlm-zoom-controls, .pnlm-orientation-button, .pnlm-panorama-info,
+  .pnlm-compass { display: none !important; }
+  .pnlm-load-box { background: #10151a !important; }
+
+  .hud {
+    position: absolute; z-index: 5; background: var(--panel);
+    border: 1px solid var(--edge); border-radius: 4px;
+    font-size: 12px; padding: 7px 11px; backdrop-filter: blur(8px);
+    line-height: 1.5;
+  }
+  .hud b { color: #fff; font-weight: 500; }
+  .hud span { color: var(--ink-soft); }
+  #top { top: 12px; left: 12px; }
+  #top .ep { color: var(--wire); }
+  #compass { top: 12px; left: 50%; transform: translateX(-50%); letter-spacing: .1em; }
+  #score { top: 12px; right: 12px; text-align: right; }
+  #score .pts { font-size: 15px; color: #fff; }
+  #credit {
+    top: 74px; right: 12px; font-size: 10.5px; color: var(--ink-soft);
+    max-width: 34vw; text-align: right; z-index: 14;
+  }
+  #credit a { color: #8fb8cc; text-decoration: none; }
+  #actions {
+    bottom: 12px; left: 50%; transform: translateX(-50%); display: flex;
+    gap: 6px; align-items: center; transition: opacity .3s ease;
+  }
+  #actions {
+    gap: 0; padding: 0; display: flex; align-items: stretch; overflow: hidden;
+    bottom: 12px; left: 12px; transform: none;
+  }
+  /* One group per kind of environment action, each labelled, each showing what
+     it costs through its tooltip rather than shouting a number. A group whose
+     tool is not registered is removed rather than greyed: a control you cannot
+     use is noise. */
+  .pad {
+    display: flex; flex-direction: column; gap: 4px; padding: 8px 14px;
+    justify-content: center;
+  }
+  .pad + .pad { border-left: 1px solid var(--edge); }
+  .pad.gone { display: none; }
+  .padlabel {
+    font-size: 9.5px; letter-spacing: .14em; text-transform: uppercase;
+    color: var(--ink-faint);
+  }
+  .padlabel b { color: var(--ink); font-weight: 500; letter-spacing: 0; }
+  .btns { display: flex; align-items: center; gap: 5px; }
+  #actions button {
+    font-family: inherit; cursor: pointer; color: var(--ink);
+    background: #232c33; border: 1px solid var(--edge); border-radius: 4px;
+    display: flex; flex-direction: column; align-items: center; gap: 1px;
+    min-width: 46px; padding: 5px 7px; line-height: 1;
+  }
+  #actions button .glyph { font-size: 12px; }
+  #actions button .tag {
+    font-size: 8.5px; letter-spacing: .06em; color: var(--ink-soft);
+  }
+  #actions button:hover {
+    border-color: #6d8493; background: #2b353d; color: #fff;
+  }
+  #actions button:hover .tag { color: var(--ink); }
+  #actions button:active { background: #1c242a; }
+  #actions button:focus-visible { outline: 2px solid var(--wire); outline-offset: 1px; }
+  #actions button.gone { display: none; }
+  #actions.working { opacity: .55; }
+  #actions.working button { cursor: progress; }
+  #actions.working #padBudget b { color: var(--wire); }
+  #actions button.preset {
+    font-size: 10px; letter-spacing: .04em; min-width: 44px; padding: 7px 8px;
+  }
+  #actions button.preset.on { border-color: var(--wire); color: #fff; }
+  #fovRange { width: 104px; accent-color: var(--wire); margin-left: 4px; }
+  .budget { gap: 4px; font-size: 10px; color: var(--ink-faint); white-space: nowrap; }
+  .budget .sep { color: var(--edge); margin: 0 3px; }
+  .budget b {
+    font-size: 14px; color: var(--ink); font-weight: 500;
+    font-variant-numeric: tabular-nums;
+  }
+
+  /* ---- rollout trace: the observation stream the agent would receive ---- */
+  /* The trace lives on the left and the guess map on the right, so an
+     expanded map can never cover the observation stream. */
+  #trace {
+    position: absolute; top: 58px; left: 12px; width: 310px; z-index: 7;
+    max-height: calc(100% - 130px); display: flex; flex-direction: column;
+    background: var(--panel); border: 1px solid var(--edge); border-radius: 4px;
+    backdrop-filter: blur(8px); overflow: hidden;
+  }
+  #trace.hidden { display: none; }
+  #trace h4 {
+    margin: 0; padding: 8px 11px; font-size: 10.5px; font-weight: 500;
+    letter-spacing: .12em; text-transform: uppercase; color: var(--wire);
+    border-bottom: 1px solid var(--edge); display: flex;
+    justify-content: space-between;
+  }
+  #trace h4 em { color: var(--ink-faint); font-style: normal; letter-spacing: 0; }
+  #trace h4 > span:last-child { display: flex; align-items: center; gap: 8px; }
+  #collapse {
+    font-family: inherit; font-size: 13px; line-height: 1; cursor: pointer;
+    background: #232c33; border: 1px solid var(--edge); border-radius: 3px;
+    color: var(--ink); width: 22px; height: 19px; padding: 0;
+  }
+  #expand {
+    font-family: inherit; font-size: 11px; line-height: 1; cursor: pointer;
+    background: #232c33; border: 1px solid var(--edge); border-radius: 3px;
+    color: var(--ink); padding: 5px 9px;
+  }
+  #collapse:hover, #expand:hover { border-color: #5b6b78; color: #fff; }
+  /* With the trace hidden, a small control stays where it was. */
+  #expandWrap {
+    position: absolute; top: 58px; left: 12px; z-index: 7; display: none;
+    padding: 4px 5px;
+  }
+  #expandWrap.show { display: block; }
+  #steps { overflow-y: auto; padding: 4px 0; font-size: 11px; }
+  .step { padding: 6px 11px; border-bottom: 1px solid #1e262c; line-height: 1.5; }
+  .step:last-child { border-bottom: none; }
+  .step .op { color: var(--wire); }
+  .step .rw { float: right; color: var(--ink-faint); }
+  .step .fb { color: var(--ink-soft); display: block; margin-top: 2px; }
+  #agentview { border-top: 1px solid var(--edge); padding: 8px 11px; }
+  #agentview .cap {
+    font-size: 9.5px; letter-spacing: .1em; text-transform: uppercase;
+    color: var(--ink-faint); margin-bottom: 5px;
+  }
+  #agentview img { width: 100%; display: block; border-radius: 3px; }
+
+  /* ---- guess map ------------------------------------------------------- */
+  #mapwrap {
+    position: absolute; right: 12px; bottom: 12px; z-index: 6;
+    width: 300px; height: 210px; border: 1px solid var(--edge);
+    border-radius: 5px; overflow: hidden; opacity: .9; background: #191f24;
+    transition: width .24s ease, height .24s ease, opacity .24s ease,
+                right .24s ease, bottom .24s ease;
+  }
+  #mapwrap:hover, #mapwrap.big {
+    width: min(560px, 48vw); height: min(400px, 58vh); opacity: 1;
+  }
+  #mapwrap.reveal {
+    right: 50%; bottom: 50%; transform: translate(50%, 50%);
+    width: min(1000px, 86vw); height: min(600px, 72vh); opacity: 1;
+  }
+  /* The reveal is the whole point of the round, so it may cover the trace. */
+  #mapwrap.reveal { z-index: 13; }
+  #map { position: absolute; inset: 0; }
+  #submit {
+    position: absolute; left: 0; right: 0; bottom: 0; z-index: 3; width: 100%;
+    font-family: inherit; font-size: 12px; letter-spacing: .07em;
+    text-transform: uppercase; padding: 10px; border: none;
+    border-top: 1px solid var(--edge); background: #2b3540; color: #7e8b96;
+    cursor: not-allowed;
+  }
+  #submit.ready { background: var(--pin); color: #fff; cursor: pointer; }
+  #submit.ready:hover { background: #d64236; }
+  #mapwrap.reveal #submit { display: none; }
+
+  /* ---- result bar ------------------------------------------------------ */
+  #result {
+    position: absolute; left: 0; right: 0; bottom: 0; z-index: 12; display: none;
+    background: rgba(14, 18, 22, .96); border-top: 1px solid var(--edge);
+    padding: 13px 20px; backdrop-filter: blur(8px);
+  }
+  #result.show { display: block; }
+  #result .inner {
+    max-width: 1180px; margin: 0 auto; display: flex; align-items: center;
+    gap: 22px; flex-wrap: wrap;
+  }
+  #verdict { font-size: 17px; color: #fff; min-width: 140px; }
+  .stat { font-size: 10.5px; color: var(--ink-soft); }
+  .stat b {
+    display: block; font-size: 14px; color: var(--ink); font-weight: 500;
+    font-variant-numeric: tabular-nums; margin-top: 2px;
+  }
+  .stat.env b { color: var(--wire); }
+  #bar { flex: 1 1 140px; min-width: 100px; height: 6px; background: #232b32;
+         border-radius: 4px; overflow: hidden; }
+  #bar i { display: block; height: 100%; background: var(--good); width: 0; }
+  #advance {
+    font-family: inherit; font-size: 12px; text-transform: uppercase;
+    letter-spacing: .06em; padding: 10px 18px; background: #232b32;
+    color: var(--ink); border: 1px solid var(--edge); border-radius: 3px;
+    cursor: pointer;
+  }
+  #advance:hover { border-color: #465360; color: #fff; }
+
+  .dot {
+    display: inline-block; width: 7px; height: 7px; border-radius: 50%;
+    margin-right: 7px; background: var(--ink-faint);
+    vertical-align: 1px;
+  }
+  .dot.live { background: var(--good); }
+  .dot.bad { background: var(--pin); }
+</style>
+</head>
+<body>
+<div id="stage">
+  <div id="pano"></div>
+
+  <div class="hud" id="top">
+    <i id="conn" class="dot" title="environment session"></i><b>geoguesser_env</b>
+    <span>episode</span> <b class="ep" id="task">-</b>
+    <span>· frame</span> <b id="frame">-</b>
+    <span>· steps</span> <b id="stepsLeft">-</b>
+  </div>
+  <div class="hud" id="compass"><span>facing</span> <b id="heading">-</b>
+    <span>· fov</span> <b id="fov">-</b>
+    <span>· map</span> <b id="mapspan">-</b></div>
+  <div class="hud" id="score">
+    <div class="pts"><b id="total">0</b><span> pts</span></div>
+    <span id="played">0 episodes</span> · <span id="captured"></span>
+  </div>
+  <div class="hud" id="credit"></div>
+  <div class="hud" id="actions">
+    <div class="pad" id="padTurn">
+      <span class="padlabel">look</span>
+      <div class="btns">
+        <button id="turn-left" title="Turn 45° left and look (costs 0.01) — key: A or ←">
+          <span class="glyph">&#9664;</span><span class="tag">left</span></button>
+        <button id="look-now" title="Look again where you are facing (costs 0.01) — key: L">
+          <span class="glyph">&#9678;</span><span class="tag">look</span></button>
+        <button id="turn-right" title="Turn 45° right and look (costs 0.01) — key: D or →">
+          <span class="glyph">&#9654;</span><span class="tag">right</span></button>
+      </div>
+    </div>
+
+    <div class="pad" id="padMove">
+      <span class="padlabel">walk</span>
+      <div class="btns">
+        <button id="move-fwd" title="Walk 15 m forward (costs 0.05) — key: W or ↑">
+          <span class="glyph">&#9650;</span><span class="tag">forward</span></button>
+        <button id="move-back" title="Walk 15 m back (costs 0.05) — key: S or ↓">
+          <span class="glyph">&#9660;</span><span class="tag">back</span></button>
+      </div>
+    </div>
+
+    <div class="pad" id="padZoom">
+      <span class="padlabel">zoom &middot; <b id="fovValue">90&deg;</b></span>
+      <div class="btns">
+        <button class="preset" data-fov="90" title="Wide view, 90° (costs 0.01)">wide</button>
+        <button class="preset" data-fov="50" title="Street level, 50° (costs 0.01)">street</button>
+        <button class="preset" data-fov="30" title="Read a sign, 30° (costs 0.01)">sign</button>
+        <input id="fovRange" type="range" min="20" max="110" step="5" value="90"
+          aria-label="field of view in degrees">
+      </div>
+    </div>
+
+    <div class="pad" id="padBudget">
+      <span class="padlabel">budget</span>
+      <div class="btns budget">
+        <b id="stepsBudget">12</b><span>left</span>
+        <span class="sep">&middot;</span>
+        <b id="costBudget">0.00</b><span>spent</span>
+      </div>
+    </div>
+  </div>
+
+  <div class="hud" id="expandWrap">
+    <button id="expand" title="show the rollout trace (T)">+ trace</button>
+  </div>
+
+  <div id="trace">
+    <h4>
+      <span>rollout trace</span>
+      <span><em id="cost">cost 0.00</em>
+        <button id="collapse" title="hide the trace (T)">&#8211;</button></span>
+    </h4>
+    <div id="steps"></div>
+    <div id="agentview" style="display:none">
+      <div class="cap">what the agent sees</div>
+      <img id="agentimg" alt="the environment's own rendered observation">
+    </div>
+  </div>
+
+  <div id="mapwrap">
+    <div id="map"></div>
+    <button id="submit">click the map to place a pin</button>
+  </div>
+
+  <div id="result">
+    <div class="inner">
+      <div id="verdict">-</div>
+      <div class="stat">distance<b id="dist">-</b></div>
+      <div class="stat">points<b id="points">-</b></div>
+      <div class="stat env">env reward<b id="reward">-</b></div>
+      <div class="stat">score - cost<b id="breakdown2">-</b></div>
+      <div class="stat">true location<b id="truth">-</b></div>
+      <div id="bar"><i></i></div>
+      <button id="advance">load another episode</button>
+    </div>
+  </div>
+
+</div>
+
+<script src="__MAPLIBRE_JS__"></script>
+<script src="__PANNELLUM_JS__"></script>
+<script>
+(function () {
+  "use strict";
+  const N_TASKS = __N_TASKS__;
+  const SPLIT = __SPLIT__;
+  const MAX_POINTS = __MAX_POINTS__;
+  // Every task-scoped request has to name its split, or index 12 of eval and
+  // index 12 of train are indistinguishable and the page reveals the wrong
+  // ground truth.
+  const q = (extra) => "?split=" + encodeURIComponent(SPLIT) + (extra || "");
+  const $ = (id) => document.getElementById(id);
+
+  let socket = null, ready = false, pending = null;
+  let viewer = null, map = null, guessMarker = null, truthMarker = null;
+  let lineAdded = false, guess = null, taskIndex = 0, compass = 0;
+  let taskMeta = null, frameIndex = 0;
+  let total = 0, played = 0, busy = false, cost = 0;
+
+  const DIRS = ["N", "NE", "E", "SE", "S", "SW", "W", "NW"];
+  const fmt = (la, lo) => la.toFixed(4) + ", " + lo.toFixed(4);
+  const yaw = () => (viewer ? ((viewer.getYaw() % 360) + 360) % 360 : 0);
+  const hfov = () => (viewer ? viewer.getHfov() : 90);
+
+  // ---- the environment, over the same WebSocket session API a client uses --
+  // Plain REST /step builds a fresh environment per request, so a stateful
+  // episode has to run over /ws. This page therefore plays exactly the
+  // rollout an agent would: one reset, a few charged steps, one terminal guess.
+  function connect() {
+    const scheme = location.protocol === "https:" ? "wss:" : "ws:";
+    socket = new WebSocket(scheme + "//" + location.host + "/ws");
+    socket.onopen = function () {
+      ready = true;
+      $("conn").className = "dot live";
+      $("conn").title = "environment session: connected";
+      startRound(requestedTask());
+    };
+    socket.onclose = function () {
+      ready = false;
+      $("conn").className = "dot bad";
+      $("conn").title = "environment session: disconnected";
+    };
+    socket.onerror = function () {
+      $("conn").className = "dot bad";
+      $("conn").title = "environment session: error";
+    };
+    socket.onmessage = function (event) {
+      const message = JSON.parse(event.data);
+      if (message.type === "error") {
+        addStep("error", message.data ? JSON.stringify(message.data) : "", null);
+        setBusy(false);
+        return;
+      }
+      if (message.type !== "observation") return;
+      // The wire format nests the observation and carries reward and done as
+      // siblings: {observation: {...}, reward, done, metadata}. Flatten it so
+      // callers read one object.
+      const payload = message.data || {};
+      const observation = Object.assign(
+        {}, payload.observation || payload,
+        { reward: payload.reward, done: payload.done }
+      );
+      const handler = pending;
+      pending = null;
+      if (handler) handler(observation);
+    };
+  }
+
+  function send(type, data, handler) {
+    if (!ready) return;
+    pending = handler || null;
+    socket.send(JSON.stringify({ type: type, data: data || {} }));
+  }
+
+  // ---- trace ------------------------------------------------------------
+  function addStep(op, feedback, observation) {
+    const row = document.createElement("div");
+    row.className = "step";
+    let right = "";
+    if (observation && observation.steps_remaining !== undefined) {
+      right = "<span class='rw'>" + observation.steps_remaining + " left</span>";
+    }
+    row.innerHTML = "<span class='op'>" + op + "</span>" + right +
+                    "<span class='fb'>" + (feedback || "") + "</span>";
+    $("steps").appendChild(row);
+    $("steps").scrollTop = $("steps").scrollHeight;
+    if (observation && observation.image_base64) {
+      const mime = observation.image_kind === "map" ? "png" : "jpeg";
+      $("agentimg").src = "data:image/" + mime + ";base64," + observation.image_base64;
+      $("agentview").style.display = "block";
+    }
+  }
+
+  function applyObservation(observation) {
+    if (!observation) return;
+    if (observation.steps_remaining !== undefined) {
+      $("stepsLeft").textContent = observation.steps_remaining;
+      $("stepsBudget").textContent = observation.steps_remaining;
+    }
+    if (observation.action_cost !== null && observation.action_cost !== undefined) {
+      cost = observation.action_cost;
+      $("cost").textContent = "cost " + cost.toFixed(2);
+      $("costBudget").textContent = cost.toFixed(2);
+    }
+    setControls(observation);
+  }
+
+  // ---- rounds -----------------------------------------------------------
+  function loadPano(index) {
+    fetch("/geoguesser/task/" + index + q())
+      .then((response) => response.json())
+      .then((meta) => {
+        taskMeta = meta;
+        frameIndex = meta.start_frame || 0;
+        const who = (meta.attribution || {}).creator_username;
+        $("credit").innerHTML =
+          "imagery &copy; " + (who ? who : "Mapillary contributor") +
+          " via <a href='https://www.mapillary.com' target='_blank' rel='noopener'>Mapillary</a>" +
+          ", <a href='https://creativecommons.org/licenses/by-sa/4.0/' target='_blank' rel='noopener'>CC BY-SA 4.0</a>";
+        showFrame(frameIndex, 0, 90);
+      });
+  }
+
+  /**
+   * Point the main viewer at one frame of the sequence.
+   *
+   * Called on reset and again after every move(), so walking forward actually
+   * changes what you are looking at rather than only what the trace shows.
+   * Heading and zoom carry over, because losing your orientation on every step
+   * would make navigation useless.
+   */
+  function showFrame(index, keepYaw, keepHfov) {
+    frameIndex = index;
+    const frames = (taskMeta && taskMeta.frames) || [];
+    const frame = frames[index] || {};
+    compass = frame.compass_angle || 0;
+    if (frame.captured_at) {
+      $("captured").textContent = "captured " + frame.captured_at;
+    }
+    $("frame").textContent = index + "/" + Math.max(0, frames.length - 1);
+    if (viewer) { viewer.destroy(); viewer = null; }
+    viewer = pannellum.viewer("pano", {
+      type: "equirectangular",
+      panorama: "/geoguesser/pano/" + taskIndex + "/" + index + q(),
+      autoLoad: true, showControls: false, northOffset: compass,
+      yaw: keepYaw, hfov: keepHfov,
+      minHfov: 20, maxHfov: 110, compass: false, friction: 0.15,
+    });
+    viewer.on("mouseup", updateHud);
+    viewer.on("touchend", updateHud);
+    viewer.on("zoomchange", updateHud);
+    viewer.on("load", updateHud);
+    setTimeout(updateHud, 400);
+  }
+
+  function setControls(observation) {
+    if (!observation) return;
+    const tools = observation.available_tools || [];
+    const canLook = tools.indexOf("look") !== -1;
+    const canMove = tools.indexOf("move") !== -1;
+    $("padTurn").classList.toggle("gone", !canLook);
+    $("padZoom").classList.toggle("gone", !canLook);
+    $("look-now").classList.toggle("gone", !canLook);
+    $("padMove").classList.toggle(
+      "gone",
+      !canMove ||
+        (!observation.can_move_forward && !observation.can_move_backward)
+    );
+    $("move-fwd").classList.toggle("gone", !observation.can_move_forward);
+    $("move-back").classList.toggle("gone", !observation.can_move_backward);
+    if (observation.fov_deg) {
+      const fov = Math.round(observation.fov_deg);
+      $("fovRange").value = String(fov);
+      $("fovValue").textContent = fov + "\u00b0";
+      markPreset(fov);
+    }
+  }
+
+  function updateHud() {
+    if (!viewer) return;
+    const y = yaw();
+    $("heading").textContent = DIRS[Math.round(y / 45) % 8] + " " + y.toFixed(0) + "°";
+    $("fov").textContent = hfov().toFixed(0) + "°";
+  }
+
+  // ---- charged actions, executed by the environment ---------------------
+  function setBusy(value) {
+    busy = value;
+    $("actions").classList.toggle("working", value);
+    if (value) {
+      $("stepsBudget").textContent = "\u2026";
+    }
+  }
+
+  function step(op, data, label) {
+    if (busy || !ready) return;
+    setBusy(true);
+    send("step", Object.assign({ op: op }, data), function (observation) {
+      setBusy(false);
+      applyObservation(observation);
+      addStep(label, observation.feedback, observation);
+      const meta = observation.metadata || {};
+      if (op === "move" && meta.frame_index !== undefined &&
+          meta.frame_index !== frameIndex) {
+        // Keep the player facing the same way through the step.
+        showFrame(meta.frame_index, yaw(), hfov());
+      }
+      if (op === "look" && data && data.fov_deg && viewer) {
+        // The main view and the agent's view should never disagree.
+        viewer.setHfov(data.fov_deg);
+        if (data.heading_deg !== undefined) viewer.setYaw(data.heading_deg);
+      }
+      if (op === "guess") reveal(observation);
+    });
+  }
+
+  // The pad is the agent's action set, not a viewer control: every button is a
+  // charged environment step, and the panorama follows the result. Dragging the
+  // scene stays free, for orientation only.
+  function lookAt(heading, fov) {
+    const wrapped = ((Math.round(heading) % 360) + 360) % 360;
+    step(
+      "look",
+      { heading_deg: wrapped, pitch_deg: 0, fov_deg: Math.round(fov) },
+      "look(heading=" + wrapped + ", fov=" + Math.round(fov) + ")"
+    );
+  }
+
+  $("turn-left").onclick = function () { lookAt(yaw() - 45, hfov()); };
+  $("turn-right").onclick = function () { lookAt(yaw() + 45, hfov()); };
+  $("look-now").onclick = function () { lookAt(yaw(), hfov()); };
+
+  Array.prototype.forEach.call(
+    document.querySelectorAll("#padZoom .preset"),
+    function (button) {
+      button.onclick = function () {
+        const fov = parseInt(button.dataset.fov, 10);
+        $("fovRange").value = String(fov);
+        $("fovValue").textContent = fov + "\u00b0";
+        markPreset(fov);
+        lookAt(yaw(), fov);
+      };
+    }
+  );
+
+  function markPreset(fov) {
+    Array.prototype.forEach.call(
+      document.querySelectorAll("#padZoom .preset"),
+      function (button) {
+        button.classList.toggle("on", parseInt(button.dataset.fov, 10) === fov);
+      }
+    );
+  }
+  $("move-fwd").onclick = function () {
+    step("move", { direction: "forward", meters: 15 }, "move(forward, 15m)");
+  };
+  $("move-back").onclick = function () {
+    step("move", { direction: "backward", meters: 15 }, "move(backward, 15m)");
+  };
+
+  // The slider reads out live but only spends a step on release, so dragging it
+  // does not burn the budget.
+  $("fovRange").addEventListener("input", function () {
+    const fov = parseInt($("fovRange").value, 10);
+    $("fovValue").textContent = fov + "\u00b0";
+    markPreset(fov);
+  });
+  $("fovRange").addEventListener("change", function () {
+    lookAt(yaw(), parseInt($("fovRange").value, 10));
+  });
+  function setTrace(visible) {
+    $("trace").classList.toggle("hidden", !visible);
+    $("expandWrap").classList.toggle("show", !visible);
+  }
+  $("collapse").onclick = function () { setTrace(false); };
+  $("expand").onclick = function () { setTrace(true); };
+
+  // The picker is the human equivalent of reset(task_index=k): the same call an
+  // eval harness makes, so a person can replay exactly the episode an agent saw.
+  /** Task index requested in the page URL, when the host supplied one. */
+  function requestedTask() {
+    const value = new URLSearchParams(location.search).get("task");
+    if (value === null || value === "" || value === "random") return undefined;
+    const parsed = parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+
+  function startRound(index) {
+    cost = 0;
+    $("cost").textContent = "cost 0.00";
+    $("steps").innerHTML = "";
+    $("agentview").style.display = "none";
+    clearRound();
+    const wanted = index === undefined
+      ? Math.floor(Math.random() * N_TASKS)
+      : ((index % N_TASKS) + N_TASKS) % N_TASKS;
+    taskIndex = wanted;
+    send("reset", { split: SPLIT, index: wanted }, function (observation) {
+      const meta = observation.metadata || {};
+      taskIndex = meta.task_index !== undefined ? meta.task_index : wanted;
+      $("task").textContent = taskIndex;
+      $("captured").textContent = "captured " + (observation.captured_at || "unknown");
+      applyObservation(observation);
+      addStep(
+        "reset(split='" + SPLIT + "', index=" + taskIndex + ")",
+        "episode started · " + (observation.available_tools || []).length +
+        " tools registered",
+        observation
+      );
+      loadPano(taskIndex);
+    });
+  }
+
+  // ---- map --------------------------------------------------------------
+  const WORLD = [[-179, -58], [179, 76]];
+  map = new maplibregl.Map({
+    container: "map", style: "__OPENFREEMAP_STYLE__",
+    center: [0, 12], zoom: 0, minZoom: -2,
+    attributionControl: { compact: true }, dragRotate: false,
+    // Without this the world repeats horizontally, which reads as a rendering
+    // bug at the zoom levels a small guess map uses.
+    renderWorldCopies: false,
+  });
+  map.on("load", () => map.fitBounds(WORLD, { padding: 6, duration: 0 }));
+  // Exposed so the page can be driven from a test harness or the console.
+  window.__ggMap = map;
+  window.__ggState = function () {
+    return {
+      busy: busy,
+      ready: ready,
+      pendingHandler: !!pending,
+      socket: socket ? socket.readyState : null,
+      steps: document.querySelectorAll('#steps .step').length,
+    };
+  };
+
+  /**
+   * Half-width of the visible map, in degrees.
+   *
+   * The environment renders its own map from this, so a pin dropped while
+   * zoomed into a city comes back as a street-level map rather than a
+   * continental one. Without it the agent's view and the player's would
+   * disagree about how precisely the pin could be aimed.
+   */
+  function currentSpanDeg() {
+    const bounds = map.getBounds();
+    const span = Math.abs(bounds.getEast() - bounds.getWest()) / 2;
+    return Math.min(180, Math.max(0.03, span));
+  }
+
+  function updateMapSpan() {
+    const span = currentSpanDeg();
+    $("mapspan").textContent =
+      span >= 1 ? span.toFixed(0) + "\u00b0" : (span * 111).toFixed(0) + " km";
+  }
+  map.on("zoomend", updateMapSpan);
+  map.on("moveend", updateMapSpan);
+  map.on("load", updateMapSpan);
+
+  map.on("click", function (event) {
+    if (busy || $("result").classList.contains("show")) return;
+    // Once you have committed to a pin the map stays open; letting it collapse
+    // on mouse-out makes it easy to lose the guess you were adjusting.
+    $("mapwrap").classList.add("big");
+    map.resize();
+    guess = event.lngLat;
+    if (guessMarker) guessMarker.remove();
+    guessMarker = new maplibregl.Marker({ color: "#c4332a" })
+      .setLngLat(guess).addTo(map);
+    $("submit").className = "ready";
+    $("submit").textContent = "submit guess";
+    // A pin is a real, charged environment step, so the map the agent would see
+    // comes back in the trace panel — framed at the zoom you are looking at, so
+    // the two views agree about how precisely the pin was aimed.
+    const span = currentSpanDeg();
+    step("pin", { lat: guess.lat, lon: guess.lng, span_deg: span },
+         "place_pin(" + guess.lat.toFixed(2) + ", " + guess.lng.toFixed(2) +
+         ", span=" + span.toFixed(2) + ")");
+  });
+
+  $("submit").onclick = function () {
+    if (!guess) return;
+    step("guess", { lat: guess.lat, lon: guess.lng },
+         "submit_guess(" + guess.lat.toFixed(2) + ", " + guess.lng.toFixed(2) + ")");
+  };
+
+  function reveal(observation) {
+    if (observation.distance_km === null || observation.distance_km === undefined) {
+      addStep("guess rejected",
+              observation.feedback || "the environment returned no distance",
+              observation);
+      return;
+    }
+    const km = observation.distance_km;
+    const reward = observation.reward === null ? 0 : observation.reward;
+    const score = observation.score === null ? 0 : observation.score;
+    const points = Math.round(score * MAX_POINTS);
+    const truthLat = observation.true_lat, truthLon = observation.true_lon;
+    total += points;
+    played += 1;
+    $("played").textContent = played + (played === 1 ? " episode" : " episodes");
+
+    $("verdict").textContent =
+      km < 0.025 ? "Perfect." : km < 25 ? "Pinpoint." : km < 200 ? "Close." :
+      km < 1500 ? "Right region." : "Wrong continent.";
+    $("dist").textContent = km < 10 ? (km * 1000).toFixed(0) + " m" : km.toFixed(0) + " km";
+    $("points").textContent = points + " / " + MAX_POINTS;
+    $("reward").textContent = reward.toFixed(3);
+    $("breakdown2").textContent =
+      score.toFixed(3) + " - " + (observation.action_cost || 0).toFixed(2);
+    $("truth").textContent = fmt(truthLat, truthLon);
+    $("bar").firstElementChild.style.width = (reward * 100).toFixed(1) + "%";
+    $("total").textContent = total;
+    $("result").classList.add("show");
+    document.body.classList.add("revealing");
+    $("actions").style.opacity = "0";
+
+    truthMarker = new maplibregl.Marker({ color: "#5aa06e" })
+      .setLngLat([truthLon, truthLat]).addTo(map);
+    const line = {
+      type: "Feature",
+      geometry: {
+        type: "LineString",
+        coordinates: [[guess.lng, guess.lat], [truthLon, truthLat]],
+      },
+    };
+    if (lineAdded) {
+      map.getSource("shot").setData(line);
+    } else {
+      map.addSource("shot", { type: "geojson", data: line });
+      map.addLayer({
+        id: "shot", type: "line", source: "shot",
+        paint: { "line-color": "#c4332a", "line-width": 2.5, "line-dasharray": [2, 1.6] },
+      });
+      lineAdded = true;
+    }
+    $("mapwrap").classList.add("reveal");
+    map.resize();
+    setTimeout(function () {
+      map.fitBounds(
+        [[Math.min(guess.lng, truthLon), Math.min(guess.lat, truthLat)],
+         [Math.max(guess.lng, truthLon), Math.max(guess.lat, truthLat)]],
+        { padding: 80, maxZoom: 7, duration: 900 }
+      );
+    }, 260);
+  }
+
+  function clearRound() {
+    guess = null;
+    setBusy(false);
+    if (guessMarker) { guessMarker.remove(); guessMarker = null; }
+    if (truthMarker) { truthMarker.remove(); truthMarker = null; }
+    if (lineAdded) {
+      map.getSource("shot").setData({
+        type: "Feature", geometry: { type: "LineString", coordinates: [] },
+      });
+    }
+    $("mapwrap").classList.remove("reveal", "big");
+    map.resize();
+    map.fitBounds(WORLD, { padding: 6, duration: 700 });
+    $("submit").className = "";
+    $("submit").textContent = "click the map to place a pin";
+    $("result").classList.remove("show");
+    document.body.classList.remove("revealing");
+    $("actions").style.opacity = "1";
+  }
+
+  // An episode is one guess, so there is no round to advance: the terminal
+  // control simply starts another episode.
+  $("advance").onclick = function () {
+    clearRound();
+    startRound();
+  };
+
+  document.addEventListener("keydown", function (event) {
+    if (event.key === "m" || event.key === "M") {
+      $("mapwrap").classList.toggle("big");
+      map.resize();
+      if (!guess && !busy) map.fitBounds(WORLD, { padding: 6, duration: 250 });
+    } else if (event.key === "t" || event.key === "T") {
+      setTrace($("trace").classList.contains("hidden"));
+    } else if (event.key === "ArrowUp" || event.key === "w") {
+      if (!$("move-fwd").classList.contains("gone")) $("move-fwd").click();
+    } else if (event.key === "ArrowDown" || event.key === "s") {
+      if (!$("move-back").classList.contains("gone")) $("move-back").click();
+    } else if (event.key === "l" || event.key === "L") {
+      if (!$("padTurn").classList.contains("gone")) $("look-now").click();
+    } else if (event.key === "ArrowLeft" || event.key === "a") {
+      if (!$("padTurn").classList.contains("gone")) $("turn-left").click();
+    } else if (event.key === "ArrowRight" || event.key === "d") {
+      if (!$("padTurn").classList.contains("gone")) $("turn-right").click();
+    } else if (event.key === "Enter") {
+      if ($("result").classList.contains("show")) { $("advance").click(); }
+      else { $("submit").click(); }
+    }
+  });
+
+  connect();
+})();
+</script>
+</body>
+</html>
+"""
+
+
+def play_page_html(splits: list[dict] | int, split: str | None = None) -> str:
+    """
+    Return the standalone play page.
+
+    Served at `/geoguesser/play` and embedded in the Gradio tab through an
+    iframe. It is a full document rather than a fragment because `gr.HTML`
+    inserts markup without running `<script>` tags.
+
+    Args:
+        splits (`list[dict]` or `int`):
+            Split descriptors from [`~GeoGuesserEnvironment.list_splits`]. A
+            bare integer is accepted as a task count for callers predating
+            splits.
+        split (`str`, *optional*):
+            Which split the page should play. Defaults to the split marked
+            `default`, else the first one.
+
+    Returns:
+        `str`: A complete HTML document.
+    """
+    if isinstance(splits, int):
+        descriptors = [
+            {"name": "train", "num_tasks": splits, "default": True, "type": "train"}
+        ]
+    else:
+        descriptors = list(splits) or [
+            {"name": "train", "num_tasks": 1, "default": True, "type": "train"}
+        ]
+    chosen = next(
+        (d for d in descriptors if d["name"] == split),
+        next((d for d in descriptors if d.get("default")), descriptors[0]),
+    )
+    replacements = {
+        "__SPLIT__": json.dumps(chosen["name"]),
+        "__N_TASKS__": str(max(1, int(chosen.get("num_tasks", 1)))),
+        "__MAX_POINTS__": str(MAX_POINTS_PER_ROUND),
+        "__MAPLIBRE_JS__": MAPLIBRE_JS,
+        "__MAPLIBRE_CSS__": MAPLIBRE_CSS,
+        "__PANNELLUM_JS__": PANNELLUM_JS,
+        "__PANNELLUM_CSS__": PANNELLUM_CSS,
+        "__OPENFREEMAP_STYLE__": OPENFREEMAP_STYLE,
+    }
+    page = _TEMPLATE
+    for token, value in replacements.items():
+        page = page.replace(token, value)
+    return page
+
+
+def _iframe(task: str | int = "random", split: str = "") -> str:
+    """Markup for the play iframe, pointed at one task of one split.
+
+    Args:
+        task (`str` or `int`, *optional*, defaults to `"random"`):
+            Task index to open, or `"random"`.
+        split (`str`, *optional*):
+            Split to play. Empty means the server's default split.
+
+    Returns:
+        `str`: An iframe element. Re-rendering it with a different task is what
+        makes the Gradio controls reload the round, since the page reads its
+        task from the URL.
+    """
+    query = f"?task={task}"
+    if split:
+        query += f"&split={urllib.parse.quote(split)}"
+    return (
+        f'<iframe src="/geoguesser/play{query}" '
+        'style="width:100%;height:720px;border:1px solid #2c353d;'
+        'border-radius:6px" allow="fullscreen"></iframe>'
+    )
+
+
+def build_geoguesser_gradio_app(
+    web_manager: Any,
+    action_fields: List[Dict[str, Any]],
+    metadata: Optional[Any],
+    is_chat_env: bool,
+    title: str,
+    quick_start_md: str,
+) -> gr.Blocks:
+    """
+    Build the human-play tab.
+
+    The episode controls live here, on the Gradio side, rather than inside the
+    page: picking a task is orchestration, the same `reset(task_index=k)` an
+    eval harness calls, so it belongs with the host controls and not among the
+    in-game HUD.
+
+    Args:
+        web_manager (`Any`):
+            The playground's environment manager, unused here.
+        action_fields (`list[dict]`):
+            Action schema fields, unused here.
+        metadata (`Any`, *optional*):
+            Environment metadata, unused here.
+        is_chat_env (`bool`):
+            Whether the env is chat-shaped, unused here.
+        title (`str`):
+            Playground title.
+        quick_start_md (`str`):
+            Quick-start markdown, unused here.
+
+    Returns:
+        `gradio.Blocks`: The play tab, hosting `/geoguesser/play` in an iframe.
+    """
+    # Ask the server which splits it actually serves, rather than re-deriving
+    # them here from environment variables and drifting out of step with it.
+    descriptors: list[dict] = []
+    try:
+        from .app import ACTIVE_DEFAULT_SPLIT, create_geoguesser_environment
+
+        descriptors = create_geoguesser_environment().list_splits()
+        default_split = ACTIVE_DEFAULT_SPLIT
+    except Exception:  # pragma: no cover - the page still works without counts
+        default_split = "train"
+    if not descriptors:
+        descriptors = [
+            {"name": default_split, "num_tasks": 1, "default": True, "type": "train"}
+        ]
+
+    counts = {d["name"]: max(1, int(d.get("num_tasks", 1))) for d in descriptors}
+    names = list(counts)
+    if default_split not in counts:
+        default_split = names[0]
+
+    def _label(split: str) -> str:
+        return f"reset(index=)  ·  0 to {counts[split] - 1}"
+
+    with gr.Blocks(title="Geoguesser Environment") as blocks:
+        with gr.Row():
+            split_box = gr.Dropdown(
+                choices=names,
+                value=default_split,
+                label="reset(split=)",
+                scale=1,
+                interactive=len(names) > 1,
+            )
+            task_box = gr.Number(
+                value=0,
+                minimum=0,
+                maximum=counts[default_split] - 1,
+                step=1,
+                precision=0,
+                label=_label(default_split),
+                scale=2,
+            )
+            load_button = gr.Button("load episode", variant="primary", scale=1)
+            random_button = gr.Button("random episode", scale=1)
+        frame = gr.HTML(value=_iframe("random", default_split), show_label=False)
+
+        def _on_split(split: str):
+            """Re-range the index box so it cannot address a missing task."""
+            split = split or default_split
+            return gr.update(maximum=counts[split] - 1, value=0, label=_label(split))
+
+        split_box.change(fn=_on_split, inputs=split_box, outputs=task_box)
+        load_button.click(
+            fn=lambda index, split: _iframe(int(index or 0), split or default_split),
+            inputs=[task_box, split_box],
+            outputs=frame,
+        )
+        random_button.click(
+            fn=lambda split: _iframe(
+                random.randrange(counts[split or default_split]),
+                split or default_split,
+            ),
+            inputs=split_box,
+            outputs=frame,
+        )
+    return blocks
+
+
+__all__ = ["build_geoguesser_gradio_app", "play_page_html"]

geoguesser_env/server/parser.py

@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Extract coordinates from a model's free-text reply.
+
+Models emit reasoning and coordinates together, in many shapes. The parser
+accepts what they actually produce rather than demanding a schema, and returns
+`None` when nothing usable is present so the failure lands in the reward
+instead of raising.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+# 48.8584, 2.2945   |   -16.49 / -68.12   |   lat: 12.9 lon: 77.5
+_DECIMAL_PAIR = re.compile(
+    r"(-?\d{1,3}(?:\.\d+)?)\s*(?:,|/|;|\s+and\s+|\s+)\s*(-?\d{1,3}(?:\.\d+)?)"
+)
+
+# 48°51'29"N 2°17'40"E
+_DMS = re.compile(
+    r"(\d{1,3})\s*[°d]\s*(\d{1,2})?\s*['′m]?\s*(\d{1,2}(?:\.\d+)?)?"
+    r"\s*[\"″s]?\s*([NSEW])",
+    re.IGNORECASE,
+)
+
+_LABELLED = re.compile(
+    r"lat(?:itude)?\s*[:=]\s*(-?\d{1,3}(?:\.\d+)?)"
+    r".{0,40}?"
+    r"lon(?:g|gitude)?\s*[:=]\s*(-?\d{1,3}(?:\.\d+)?)",
+    re.IGNORECASE | re.DOTALL,
+)
+
+_TAG = re.compile(r"<guess>(.*?)</guess>", re.IGNORECASE | re.DOTALL)
+
+_JSON_ISH = re.compile(
+    r"\"lat(?:itude)?\"\s*:\s*(-?\d{1,3}(?:\.\d+)?)"
+    r".{0,60}?"
+    r"\"lon(?:g|gitude)?\"\s*:\s*(-?\d{1,3}(?:\.\d+)?)",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+@dataclass
+class ParsedGuess:
+    """Outcome of parsing a reply.
+
+    Attributes:
+        lat (`float` or `None`):
+            Latitude, or `None` when nothing could be extracted.
+        lon (`float` or `None`):
+            Longitude, or `None` when nothing could be extracted.
+        source (`str`):
+            Which pattern matched: `"tag"`, `"json"`, `"labelled"`, `"dms"`,
+            `"decimal"` or `"none"`.
+        note (`str`):
+            Short explanation, safe to show the model as feedback.
+    """
+
+    lat: float | None
+    lon: float | None
+    source: str
+    note: str = ""
+
+    @property
+    def ok(self) -> bool:
+        """Whether a usable coordinate pair was extracted."""
+        return self.lat is not None and self.lon is not None
+
+
+def _valid(lat: float, lon: float) -> bool:
+    return -90.0 <= lat <= 90.0 and -180.0 <= lon <= 180.0
+
+
+def _dms_to_decimal(deg: str, minute: str | None, sec: str | None, hemi: str) -> float:
+    value = float(deg) + float(minute or 0) / 60 + float(sec or 0) / 3600
+    return -value if hemi.upper() in ("S", "W") else value
+
+
+def parse_guess(response: str) -> ParsedGuess:
+    """
+    Pull a coordinate pair out of a model reply.
+
+    Patterns are tried most explicit first, so a `<guess>` tag or a labelled
+    `lat:`/`lon:` pair wins over a bare number pair that might be a date or a
+    step count.
+
+    Args:
+        response (`str`):
+            The model's unedited reply.
+
+    Returns:
+        [`ParsedGuess`]: The extracted coordinates, or a result whose `ok` is
+        `False` with a `note` explaining what was wrong.
+
+    Examples:
+
+    ```python
+    parse_guess("I think coastal Portugal. <guess>38.72, -9.14</guess>")
+    ```
+    """
+    if not response or not response.strip():
+        return ParsedGuess(None, None, "none", "Empty response.")
+
+    tagged = _TAG.search(response)
+    haystacks = [(tagged.group(1), "tag")] if tagged else []
+    haystacks.append((response, "body"))
+
+    for text, origin in haystacks:
+        for pattern, name in ((_JSON_ISH, "json"), (_LABELLED, "labelled")):
+            m = pattern.search(text)
+            if m:
+                lat, lon = float(m.group(1)), float(m.group(2))
+                if _valid(lat, lon):
+                    src = name if origin == "body" else "tag"
+                    return ParsedGuess(lat, lon, src)
+                return ParsedGuess(
+                    None, None, "none", f"Coordinates out of range: {lat}, {lon}."
+                )
+
+        dms = _DMS.findall(text)
+        if len(dms) >= 2:
+            lat_m = next((d for d in dms if d[3].upper() in ("N", "S")), None)
+            lon_m = next((d for d in dms if d[3].upper() in ("E", "W")), None)
+            if lat_m and lon_m:
+                lat = _dms_to_decimal(*lat_m)
+                lon = _dms_to_decimal(*lon_m)
+                if _valid(lat, lon):
+                    return ParsedGuess(lat, lon, "dms")
+
+        m = _DECIMAL_PAIR.search(text)
+        if m:
+            lat, lon = float(m.group(1)), float(m.group(2))
+            if _valid(lat, lon):
+                src = "decimal" if origin == "body" else "tag"
+                return ParsedGuess(lat, lon, src)
+            return ParsedGuess(
+                None, None, "none", f"Coordinates out of range: {lat}, {lon}."
+            )
+
+    return ParsedGuess(
+        None,
+        None,
+        "none",
+        "No coordinates found. Reply with a latitude and longitude, for "
+        "example <guess>48.8584, 2.2945</guess>.",
+    )