Remove committed setuptools build/ and egg-info; they shadow the real sources when the Space is pip-installed

env/openenv_geoguesser_env.egg-info/PKG-INFO

@@ -1,233 +0,0 @@
-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.

env/openenv_geoguesser_env.egg-info/SOURCES.txt

@@ -1,21 +0,0 @@
-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

env/openenv_geoguesser_env.egg-info/dependency_links.txt

@@ -1 +0,0 @@
-

env/openenv_geoguesser_env.egg-info/entry_points.txt

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

env/openenv_geoguesser_env.egg-info/requires.txt

@@ -1,14 +0,0 @@
-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

env/openenv_geoguesser_env.egg-info/top_level.txt

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

geoguesser_env/build/lib/geoguesser_env/__init__.py

@@ -1,49 +0,0 @@
-# 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/build/lib/geoguesser_env/client.py

@@ -1,143 +0,0 @@
-# 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/build/lib/geoguesser_env/harness.py

@@ -1,440 +0,0 @@
-# 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/build/lib/geoguesser_env/models.py

@@ -1,462 +0,0 @@
-# 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.
-        n_free (`int`):
-            Count of free-tool calls, which cost nothing but are capped so they
-            cannot be issued forever.
-        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
-    n_free: int = 0
-    total_moved_meters: float = 0.0
-    submitted: bool = False
-    pins: list[dict[str, Any]] = Field(default_factory=list)

geoguesser_env/build/lib/geoguesser_env/server/__init__.py

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

geoguesser_env/build/lib/geoguesser_env/server/app.py

@@ -1,349 +0,0 @@
-# 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"}
-# Training defaults differ from play defaults on purpose; see the reward-shape
-# note in the README. A hosted Space serves play traffic, so it keeps the game
-# curve and shows the licence credit unless these are set explicitly.
-REWARD_SHAPE = os.getenv("GEOGUESSER_REWARD_SHAPE", "geoguessr")
-COST_MODE = os.getenv("GEOGUESSER_COST_MODE", "subtract")
-HIDE_IDENTITY = os.getenv("GEOGUESSER_HIDE_IDENTITY", "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,
-        reward_shape=REWARD_SHAPE,
-        cost_mode=COST_MODE,
-        hide_task_identity=HIDE_IDENTITY,
-        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/build/lib/geoguesser_env/server/backends/__init__.py

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

geoguesser_env/build/lib/geoguesser_env/server/backends/base.py

@@ -1,127 +0,0 @@
-# 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/build/lib/geoguesser_env/server/backends/panorama.py

@@ -1,399 +0,0 @@
-# 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/build/lib/geoguesser_env/server/geoguesser_environment.py

@@ -1,998 +0,0 @@
-# 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,
-    street_detail_enabled,
-    street_fetch_failed,
-)
-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.
-        max_free_calls (`int`, *optional*, defaults to `24`):
-            How many free-tool calls (`measure`) an episode may make before they
-            begin consuming the step budget. Free tools return arithmetic on
-            coordinates the agent supplied and so reveal nothing, but without a
-            cap a policy can issue them indefinitely and never terminate.
-        reward_shape (`str`, *optional*, defaults to `"geoguessr"`):
-            Distance curve. `"geoguessr"` is the game's own; `"mixture"` adds a
-            5000 km scale so a wrong-continent guess still has a gradient. Use
-            `"mixture"` for training and `"geoguessr"` for anything you report.
-        cost_mode (`str`, *optional*, defaults to `"subtract"`):
-            `"subtract"` takes the action cost off the score and floors at zero,
-            as the game does. `"multiply"` scales the score by `1 - cost`, which
-            preserves the ordering of bad guesses -- required for training, see
-            [`~scoring.compute_reward`].
-        hide_task_identity (`bool`, *optional*, defaults to `False`):
-            Drop `task_index`, `task_id`, `sequence_id` and `attribution` from
-            the per-turn observation metadata. **Set this for RL training**: the
-            contributor username alone determines the country for 74% of
-            training tasks, so leaving it in lets a policy score without looking
-            at the image. The terminal observation carries them either way.
-        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,
-        max_free_calls: int = 24,
-        reward_mode: str = RewardMode.COORDS.value,
-        hierarchical_reward: bool = False,
-        reward_shape: str = "geoguessr",
-        cost_mode: str = "subtract",
-        hide_task_identity: 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
-        # Free tools reveal nothing, so they stay free -- but not unlimited.
-        self._max_free_calls = max_free_calls
-        self._reward_mode = RewardMode(reward_mode)
-        self._hierarchical = hierarchical_reward
-        self._reward_shape = reward_shape
-        self._cost_mode = cost_mode
-        self._hide_task_identity = hide_task_identity
-        # Validate now rather than at the end of the first episode.
-        compute_reward(1.0, shape=reward_shape, cost_mode=cost_mode)
-        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]:
-        # Identity fields are a reward-hacking channel, not just clutter. The
-        # Mapillary contributor determines the country outright for 74% of
-        # training tasks ("amsterdam" only maps the Netherlands), and
-        # task_index/task_id/sequence_id are a few thousand memorisable keys
-        # straight to a coordinate -- either lets a policy score without ever
-        # reading the image. Kept by default so the play UI can show the licence
-        # credit and recordings keep their provenance; RL training must set
-        # hide_task_identity=True. The terminal observation carries them
-        # regardless, since by then the truth is already revealed.
-        if self._hide_task_identity:
-            return {
-                "split": self._split,
-                "street_detail": (
-                    "unavailable"
-                    if street_fetch_failed()
-                    else ("on" if street_detail_enabled() else "off")
-                ),
-                "backend": "mapillary",
-                "episode_mode": self._mode.value,
-                "frame_index": self._state.frame_index,
-            }
-        return {
-            "split": self._split,
-            # A map quietly missing its streets looks like a styling choice, so
-            # say so. Overpass 504s from datacenter egress, which is how a Space
-            # ends up with poorer maps than a laptop for the same task.
-            "street_detail": (
-                "unavailable"
-                if street_fetch_failed()
-                else ("on" if street_detail_enabled() else "off")
-            ),
-            "task_index": self._state.task_index,
-            "task_id": self._state.task_id,
-            "backend": "mapillary",
-            # Opaque upstream identifier, not ground truth: it makes a recorded
-            # episode traceable back to its source sequence.
-            "sequence_id": self._task.sequence_id if self._task else None,
-            "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):
-            # Free, because it is arithmetic on two coordinates the agent
-            # supplied: it reveals nothing about where the agent is. But free
-            # used to mean unbounded -- it incremented no counter, so it never
-            # advanced the step budget and a policy could issue it forever. Past
-            # the cap it starts costing a map action, so the episode terminates.
-            if s.n_free >= self._max_free_calls:
-                s.n_maps += 1
-            else:
-                s.n_free += 1
-            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."
-            if s.n_free >= self._max_free_calls:
-                observation.feedback += " Free-tool budget spent; this now costs."
-            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,
-                "country": self._task.country,
-                "task_index": self._state.task_index,
-                "task_id": self._state.task_id,
-                "sequence_id": self._task.sequence_id,
-                "attribution": self._task.attribution,
-            }
-            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,
-                shape=self._reward_shape,
-            )
-            reward = compute_reward(
-                distance,
-                cost=cost,
-                country_hit=country_hit,
-                region_hit=region_hit,
-                hierarchical=self._hierarchical,
-                shape=self._reward_shape,
-                cost_mode=self._cost_mode,
-            )
-
-        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} scaled by {1 - min(cost, 0.5):.2f} "
-                f"action cost = {reward:.3f}."
-                if self._cost_mode == "multiply"
-                else f"Score {score:.3f} minus {cost:.2f} action cost = {reward:.3f}."
-            )
-        )
-        observation.metadata = {
-            **self._metadata(),
-            # Revealed here and only here, next to true_lat/true_lon: the
-            # country is the label a per-region breakdown needs, and a task spec
-            # deliberately does not carry it.
-            "country": self._task.country,
-            # Restored here even under hide_task_identity: the episode is over,
-            # so provenance can no longer be used to shortcut it.
-            "task_index": self._state.task_index,
-            "task_id": self._state.task_id,
-            "sequence_id": self._task.sequence_id,
-            "attribution": self._task.attribution,
-            "guess": [lat, lon],
-            "guess_country": guess_place.country,
-            "verdict": verdict(distance),
-            "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/build/lib/geoguesser_env/server/gradio_ui.py

@@ -1,1044 +0,0 @@
-# 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/build/lib/geoguesser_env/server/parser.py

@@ -1,149 +0,0 @@
-# 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>.",
-    )

geoguesser_env/build/lib/geoguesser_env/server/render/__init__.py

@@ -1,3 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-
-"""Image rendering for the GeoGuesser environment."""

geoguesser_env/build/lib/geoguesser_env/server/render/minimap.py

@@ -1,824 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-
-"""The guess map, rendered offline.
-
-Everything here runs against bundled Natural Earth vectors, so a pin costs no
-network call and always renders the same bytes. Map detail is a function of
-zoom alone and never of proximity to the target: prefetching finer data around
-task locations would turn the map into a ground-truth oracle.
-
-The renderer answers only "where did the agent point?". It never draws, names
-or hints at the true location.
-"""
-
-from __future__ import annotations
-
-import functools
-import hashlib
-import io
-import json
-import logging
-import math
-import os
-import pathlib
-import urllib.parse
-import urllib.request
-from dataclasses import dataclass
-
-import matplotlib
-
-matplotlib.use("Agg")
-
-import matplotlib.patheffects as path_effects  # noqa: E402
-import matplotlib.pyplot as plt  # noqa: E402
-from matplotlib.collections import LineCollection  # noqa: E402
-from matplotlib.patches import Polygon as MplPolygon  # noqa: E402
-from matplotlib.path import Path as MplPath  # noqa: E402
-from PIL import Image  # noqa: E402
-
-from ..scoring import haversine_km as _haversine_km  # noqa: E402
-
-logger = logging.getLogger(__name__)
-
-
-GEO_DIR = pathlib.Path(__file__).resolve().parents[2] / "data" / "geo"
-COUNTRIES_FILE = GEO_DIR / "ne_110m_admin_0_countries.geojson"
-CITIES_FILE = GEO_DIR / "ne_50m_populated_places.geojson"
-
-# Optional detail layers, fetched by scripts/fetch_detail_geo.py. Without them
-# the map shows outlines and major cities only, which is enough to place a
-# country but not to aim within a city — while the human's map is street-level.
-# The reward measures precision, so the two views have to agree about how
-# precisely a pin can be aimed.
-DETAIL_DIR = GEO_DIR / "detail"
-
-# Detail appears as a function of zoom alone, never of proximity to the answer.
-# Loading finer data near task locations would turn the cache into an oracle.
-# Below this the map fetches real OSM ways, because Natural Earth 10m tops out
-# at highway level: it will show the motorways around a city but not the street
-# grid inside it, and the player's tiles show both. Responses are cached to
-# disk, so the first render of a neighbourhood is slow and every later one is
-# instant and byte-identical.
-STREET_MAX_SPAN_DEG = 0.35
-STREET_LABEL_MAX_SPAN_DEG = 0.08
-"""Street names only below this span. Wider, and the names collide."""
-MAX_STREET_LABELS = 14
-"""A cap, because a dense grid has hundreds of named ways."""
-OVERPASS_URL = "https://overpass-api.de/api/interpreter"
-OVERPASS_TIMEOUT_S = 40.0
-OSM_CACHE_DIR = pathlib.Path(
-    os.environ.get("GEOGUESSER_OSM_CACHE", str(GEO_DIR / "osm_cache"))
-)
-"""Where fetched street windows are cached.
-
-Configurable so a deployment that cannot reach Overpass -- a Space, whose
-datacenter egress gets 504s from the public instance -- can mount a pre-warmed
-cache instead of silently rendering maps without streets.
-"""
-
-OVERPASS_ATTEMPTS = 2
-"""Overpass 504s under load; one cheap retry recovers a useful fraction."""
-
-_STREET_FETCH_FAILED = [False]
-"""Whether the most recent street fetch failed, for observation metadata.
-
-A map quietly missing its streets looks like a styling choice rather than a
-degraded environment, so the failure is reported rather than inferred.
-"""
-
-
-def street_fetch_failed() -> bool:
-    """Whether the last street fetch in this process failed."""
-    return _STREET_FETCH_FAILED[0]
-
-
-_OSM_SCHEMA = 2
-"""Bumped whenever the per-way record changes, to retire stale caches."""
-
-# Ways worth drawing, heaviest first, with the line width to draw them at.
-STREET_WEIGHTS = {
-    "motorway": 2.2,
-    "trunk": 2.0,
-    "primary": 1.7,
-    "secondary": 1.4,
-    "tertiary": 1.1,
-    "residential": 0.8,
-    "unclassified": 0.8,
-    "living_street": 0.7,
-    "service": 0.5,
-    "pedestrian": 0.5,
-    "motorway_link": 1.2,
-    "trunk_link": 1.1,
-    "primary_link": 1.0,
-    "secondary_link": 0.9,
-    "tertiary_link": 0.8,
-}
-
-URBAN_MAX_SPAN_DEG = 4.0
-ROADS_MAX_SPAN_DEG = 4.0
-RIVERS_MAX_SPAN_DEG = 6.0
-TOWNS_MAX_SPAN_DEG = 4.0
-
-# Version of the bundled geodata. Any change alters reverse-geocode text and
-# therefore the observations, so eval scores must cite it.
-GEODATA_VERSION = "natural-earth-110m+50m/2024.1"
-
-_LAND = "#e9e5dd"
-_ROAD = "#8a6a52"
-_RIVER = "#6f9fba"
-_URBAN = "#e4ded6"
-_TOWN = "#3d3833"
-_WATER = "#cfe0ea"
-_BORDER = "#5f5a54"
-_PIN = "#c4332a"
-_TRUTH = "#3f7a55"
-_INK = "#2b2a28"
-
-_COMPASS = ("N", "NE", "E", "SE", "S", "SW", "W", "NW")
-
-# Mutable so the server can turn street fetching off for a run that must never
-# touch the network, without threading a flag through every render call.
-_STREETS_ENABLED = [True]
-
-
-def set_street_detail(enabled: bool) -> None:
-    """Turn OSM street fetching on or off for this process."""
-    _STREETS_ENABLED[0] = bool(enabled)
-
-
-def street_detail_enabled() -> bool:
-    """Whether OSM street fetching is currently on."""
-    return _STREETS_ENABLED[0]
-
-
-@dataclass(frozen=True)
-class Place:
-    """Where a coordinate falls, in words.
-
-    Attributes:
-        country (`str` or `None`):
-            Country name, or `None` over open water.
-        continent (`str` or `None`):
-            Continent name, or `None` over open water.
-        subregion (`str` or `None`):
-            UN subregion, or `None` over open water.
-        nearest_city (`str`):
-            Name of the closest populated place in the bundled dataset.
-        city_distance_km (`float`):
-            Distance to that city in kilometres.
-        city_bearing (`str`):
-            Compass direction from the city to the coordinate.
-    """
-
-    country: str | None
-    continent: str | None
-    subregion: str | None
-    nearest_city: str
-    city_distance_km: float
-    city_bearing: str
-
-
-@functools.lru_cache(maxsize=1)
-def _countries() -> list[dict]:
-    return json.loads(COUNTRIES_FILE.read_text())["features"]
-
-
-@functools.lru_cache(maxsize=1)
-def _cities() -> list[tuple[str, float, float]]:
-    feats = json.loads(CITIES_FILE.read_text())["features"]
-    out = []
-    for f in feats:
-        lon, lat = f["geometry"]["coordinates"]
-        out.append((f["properties"]["name"], lat, lon))
-    return out
-
-
-@functools.lru_cache(maxsize=8)
-def _detail(layer: str) -> list[dict]:
-    """Load one optional detail layer, or an empty list when absent."""
-    path = DETAIL_DIR / f"{layer}.json"
-    if not path.exists():
-        return []
-    return json.loads(path.read_text())
-
-
-def _osm_cache_path(lat: float, lon: float, span: float) -> pathlib.Path:
-    """Cache file for one street window, keyed by a quantised bounding box.
-
-    The key carries `_OSM_SCHEMA`, so widening what is stored per way retires
-    the old files instead of serving geometry with no labels.
-    """
-    key = f"v{_OSM_SCHEMA}_{round(lat, 3):.3f}_{round(lon, 3):.3f}_{round(span, 4):.4f}"
-    digest = hashlib.sha1(key.encode()).hexdigest()[:16]
-    return OSM_CACHE_DIR / f"{digest}.json"
-
-
-def _fetch_streets(lat: float, lon: float, span: float) -> list[dict]:
-    """Ask Overpass for the ways in one window, or return an empty list.
-
-    Any failure — offline, rate limited, malformed — degrades to no streets
-    rather than failing the step that asked for the map.
-    """
-    box = f"{lat - span},{lon - span},{lat + span},{lon + span}"
-    # Street names and road numbers are what make the agent's map comparable to
-    # the human's, and they cost nothing extra: Overpass returns tags with the
-    # geometry either way.
-    query = f'[out:json][timeout:30];way["highway"]({box});out tags geom;'
-    payload = None
-    for attempt in range(1, OVERPASS_ATTEMPTS + 1):
-        request = urllib.request.Request(
-            OVERPASS_URL,
-            data=urllib.parse.urlencode({"data": query}).encode(),
-            headers={"User-Agent": "openenv-geoguesser-env/0.1 (research environment)"},
-        )
-        try:
-            with urllib.request.urlopen(
-                request, timeout=OVERPASS_TIMEOUT_S
-            ) as response:
-                payload = json.loads(response.read())
-            break
-        except Exception as exc:  # noqa: BLE001 - a missing map must not end a step
-            logger.warning(
-                "street detail unavailable for %.3f,%.3f (attempt %d/%d): %r",
-                lat,
-                lon,
-                attempt,
-                OVERPASS_ATTEMPTS,
-                exc,
-            )
-    if payload is None:
-        _STREET_FETCH_FAILED[0] = True
-        return []
-    _STREET_FETCH_FAILED[0] = False
-    ways = []
-    for element in payload.get("elements", []):
-        geometry = element.get("geometry") or []
-        if len(geometry) < 2:
-            continue
-        tags = element.get("tags") or {}
-        kind = tags.get("highway", "residential")
-        way = {
-            "w": STREET_WEIGHTS.get(kind, 0.6),
-            "c": [[point["lon"], point["lat"]] for point in geometry],
-        }
-        # A road number is often the only label a rural road has, and it is
-        # exactly the clue a player reads off a sign.
-        label = tags.get("name") or tags.get("ref")
-        if label:
-            way["n"] = label[:34]
-        ways.append(way)
-    return ways
-
-
-def street_ways(lat: float, lon: float, span: float) -> list[dict]:
-    """
-    Street geometry for one window, cached on disk.
-
-    Args:
-        lat (`float`):
-            Latitude at the centre of the window.
-        lon (`float`):
-            Longitude at the centre of the window.
-        span (`float`):
-            Half-width of the window in degrees.
-
-    Returns:
-        `list[dict]`: One entry per way, with a line width `w` and a coordinate
-        list `c`. Empty when the window is too wide, streets are disabled, or
-        the fetch failed.
-    """
-    path = _osm_cache_path(lat, lon, span)
-    if path.exists():
-        try:
-            return json.loads(path.read_text())
-        except json.JSONDecodeError:
-            path.unlink(missing_ok=True)
-    ways = _fetch_streets(lat, lon, span)
-    OSM_CACHE_DIR.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(ways, separators=(",", ":")))
-    logger.info(
-        "cached %d street ways for %.3f,%.3f span %.3f", len(ways), lat, lon, span
-    )
-    return ways
-
-
-def has_detail() -> bool:
-    """Whether the optional detail layers are installed."""
-    return any(
-        (DETAIL_DIR / f"{name}.json").exists()
-        for name in ("roads", "urban", "places", "rivers")
-    )
-
-
-def _parts(row: dict) -> list[list]:
-    """Coordinate lists for one compacted feature, whatever its geometry."""
-    kind, coordinates = row["t"], row["c"]
-    if kind in ("LineString", "Point"):
-        return [coordinates] if kind == "LineString" else [[coordinates]]
-    if kind == "MultiLineString":
-        return coordinates
-    if kind == "Polygon":
-        return [coordinates[0]]
-    if kind == "MultiPolygon":
-        return [polygon[0] for polygon in coordinates]
-    return []
-
-
-def _near(points: list, lat: float, lon: float, span: float) -> bool:
-    return any(
-        abs(point[0] - lon) < span and abs(point[1] - lat) < span for point in points
-    )
-
-
-def _rings(geometry: dict) -> list[list]:
-    if geometry["type"] == "Polygon":
-        return [geometry["coordinates"][0]]
-    if geometry["type"] == "MultiPolygon":
-        return [poly[0] for poly in geometry["coordinates"]]
-    return []
-
-
-def _bearing(from_lat: float, from_lon: float, to_lat: float, to_lon: float) -> str:
-    d_lon = math.radians(to_lon - from_lon)
-    lat_a, lat_b = math.radians(from_lat), math.radians(to_lat)
-    y = math.sin(d_lon) * math.cos(lat_b)
-    x = math.cos(lat_a) * math.sin(lat_b) - math.sin(lat_a) * math.cos(
-        lat_b
-    ) * math.cos(d_lon)
-    deg = (math.degrees(math.atan2(y, x)) + 360) % 360
-    return _COMPASS[int(deg / 45 + 0.5) % 8]
-
-
-def locate(lat: float, lon: float) -> Place:
-    """
-    Describe a coordinate using only the bundled vectors.
-
-    Args:
-        lat (`float`):
-            Latitude in degrees.
-        lon (`float`):
-            Longitude in degrees.
-
-    Returns:
-        [`Place`]: Administrative names for the point, plus the nearest
-        populated place with distance and bearing.
-    """
-    country = continent = subregion = None
-    for feature in _countries():
-        for ring in _rings(feature["geometry"]):
-            if MplPath(ring).contains_point((lon, lat)):
-                props = feature["properties"]
-                country = props.get("ADMIN")
-                continent = props.get("CONTINENT")
-                subregion = props.get("SUBREGION")
-                break
-        if country:
-            break
-
-    best_name, best_km, best_bearing = "", float("inf"), "N"
-    for name, city_lat, city_lon in _cities():
-        km = _haversine_km(lat, lon, city_lat, city_lon)
-        if km < best_km:
-            best_name, best_km = name, km
-            best_bearing = _bearing(city_lat, city_lon, lat, lon)
-    return Place(country, continent, subregion, best_name, best_km, best_bearing)
-
-
-def describe_pin(
-    index: int, lat: float, lon: float, previous: tuple[float, float] | None = None
-) -> str:
-    """
-    One line of feedback for a pin, containing nothing about the target.
-
-    Args:
-        index (`int`):
-            1-based pin number.
-        lat (`float`):
-            Latitude of the pin.
-        lon (`float`):
-            Longitude of the pin.
-        previous (`tuple[float, float]`, *optional*):
-            The preceding pin, so the agent can compare its own candidates.
-
-    Returns:
-        `str`: Feedback describing the pinned location.
-    """
-    place = locate(lat, lon)
-    where = (
-        f"{place.country} ({place.subregion})"
-        if place.country
-        else "open water - no landmass at this coordinate"
-    )
-    line = (
-        f"Pin {index} placed at {lat:.4f}, {lon:.4f} - {where}. "
-        f"Nearest major city: {place.nearest_city}, "
-        f"~{place.city_distance_km:.0f} km {place.city_bearing}."
-    )
-    if previous is not None:
-        km = _haversine_km(lat, lon, previous[0], previous[1])
-        line += f" Distance from pin {index - 1}: {km:.0f} km."
-    return line
-
-
-def _draw_land(ax, linewidth: float) -> None:
-    for feature in _countries():
-        for ring in _rings(feature["geometry"]):
-            ax.add_patch(
-                MplPolygon(
-                    ring,
-                    closed=True,
-                    facecolor=_LAND,
-                    edgecolor=_BORDER,
-                    linewidth=linewidth,
-                )
-            )
-
-
-def _label_countries(ax, lat: float, lon: float, span: float) -> None:
-    """Label countries visible in the window, clipped to the viewport."""
-    for feature in _countries():
-        for ring in _rings(feature["geometry"]):
-            visible = [
-                p for p in ring if abs(p[0] - lon) < span and abs(p[1] - lat) < span
-            ]
-            if len(visible) > 3:
-                cx = sum(p[0] for p in visible) / len(visible)
-                cy = sum(p[1] for p in visible) / len(visible)
-                ax.text(
-                    cx,
-                    cy,
-                    feature["properties"]["NAME"],
-                    fontsize=7.4,
-                    ha="center",
-                    color="#55504a",
-                    zorder=7,
-                )
-                break
-
-
-def _draw_detail(ax, lat: float, lon: float, span: float) -> None:
-    """Draw urban areas, rivers, roads and town names, by zoom level.
-
-    Each layer switches on below its own span so a wide view stays legible and a
-    tight view shows enough road structure to aim a pin within a town.
-    """
-    if span <= URBAN_MAX_SPAN_DEG:
-        for row in _detail("urban"):
-            for part in _parts(row):
-                if _near(part, lat, lon, span):
-                    ax.add_patch(
-                        MplPolygon(
-                            part,
-                            closed=True,
-                            facecolor=_URBAN,
-                            edgecolor="none",
-                            zorder=2,
-                        )
-                    )
-    if span <= RIVERS_MAX_SPAN_DEG:
-        segments = [
-            part
-            for row in _detail("rivers")
-            for part in _parts(row)
-            if _near(part, lat, lon, span)
-        ]
-        if segments:
-            ax.add_collection(
-                LineCollection(segments, colors=_RIVER, linewidths=0.9, zorder=3)
-            )
-    if span <= ROADS_MAX_SPAN_DEG:
-        segments = [
-            part
-            for row in _detail("roads")
-            for part in _parts(row)
-            if _near(part, lat, lon, span)
-        ]
-        if segments:
-            ax.add_collection(
-                LineCollection(segments, colors=_ROAD, linewidths=1.4, zorder=4)
-            )
-    if span <= STREET_MAX_SPAN_DEG and _STREETS_ENABLED[0]:
-        ways = street_ways(lat, lon, span)
-        # Generalise by zoom the way a real style does: drawing every service
-        # road and footpath at city scale turns the grid into a smear, so the
-        # minor classes only appear once the window is tight enough to hold
-        # them, and widths grow as the window shrinks.
-        floor = 0.75 if span > 0.15 else (0.55 if span > 0.05 else 0.0)
-        scale = 1.0 if span > 0.15 else (1.4 if span > 0.05 else 1.9)
-        drawn = [way for way in ways if way["w"] >= floor]
-        for weight in sorted({way["w"] for way in drawn}):
-            segments = [way["c"] for way in drawn if way["w"] == weight]
-            width = weight * scale
-            # A casing under a white fill is what makes a dense grid legible; a
-            # single flat colour reads as noise.
-            ax.add_collection(
-                LineCollection(
-                    segments, colors="#c9bfb3", linewidths=width + 0.5, zorder=4
-                )
-            )
-            ax.add_collection(
-                LineCollection(segments, colors="#ffffff", linewidths=width, zorder=5)
-            )
-        _label_streets(ax, drawn, lat, lon, span)
-    if span <= TOWNS_MAX_SPAN_DEG:
-        shown = 0
-        for row in _detail("places"):
-            point = row["c"]
-            if abs(point[0] - lon) < span * 0.95 and abs(point[1] - lat) < span * 0.95:
-                ax.plot(
-                    point[0],
-                    point[1],
-                    "o",
-                    markersize=2.6,
-                    markerfacecolor=_TOWN,
-                    markeredgecolor="none",
-                    zorder=6,
-                )
-                if row.get("n"):
-                    label = ax.text(
-                        point[0],
-                        point[1] + span * 0.03,
-                        row["n"],
-                        fontsize=6.2,
-                        ha="center",
-                        color=_TOWN,
-                        zorder=9,
-                    )
-                    label.set_path_effects(
-                        [
-                            path_effects.Stroke(linewidth=1.8, foreground="#ffffff"),
-                            path_effects.Normal(),
-                        ]
-                    )
-                shown += 1
-                if shown >= (8 if span <= STREET_MAX_SPAN_DEG else 28):
-                    break
-
-
-def _label_streets(ax, ways: list[dict], lat: float, lon: float, span: float) -> None:
-    """
-    Write street names along the ways, the way a real map style does.
-
-    One label per name, on that name's longest visible run, rotated to follow
-    the road and haloed so it stays readable over the casing. Longest-run
-    selection matters: labelling an arbitrary segment puts "Main Street" on a
-    50 m stub while the avenue itself goes unnamed.
-
-    Args:
-        ax:
-            Matplotlib axes to draw on.
-        ways (`list[dict]`):
-            Way records from [`street_ways`], some carrying a name in `n`.
-        lat (`float`):
-            Latitude at the centre of the window.
-        lon (`float`):
-            Longitude at the centre of the window.
-        span (`float`):
-            Half-width of the window in degrees.
-    """
-    if span > STREET_LABEL_MAX_SPAN_DEG:
-        return
-    # Pick, per name, the longest run of points that actually falls inside the
-    # window, so the label lands where the reader can see it.
-    best: dict[str, tuple[float, list]] = {}
-    for way in ways:
-        name = way.get("n")
-        if not name:
-            continue
-        inside = [
-            point
-            for point in way["c"]
-            if abs(point[0] - lon) < span * 0.92 and abs(point[1] - lat) < span * 0.92
-        ]
-        if len(inside) < 2:
-            continue
-        length = sum(
-            math.dist(inside[i], inside[i + 1]) for i in range(len(inside) - 1)
-        )
-        if name not in best or length > best[name][0]:
-            best[name] = (length, inside)
-
-    ordered = sorted(best.items(), key=lambda item: -item[1][0])
-    aspect = max(0.05, math.cos(math.radians(lat)))
-    # Parallel streets in a grid all have their midpoint in the same place, so
-    # placing every label at its midpoint stacks them into an unreadable pile.
-    # Claim one coarse cell per label, walking along each road to find a free
-    # one, and drop the label rather than overprint. Longest roads go first, so
-    # the ones worth naming win the space.
-    occupied: set[tuple[int, int]] = set()
-    # The cell has to be taller than the crowding you want to break up, not
-    # just taller than the glyphs: parallel streets one block apart land in
-    # different fine cells and still read as a stack. A tall cell forces
-    # neighbours to slide along their own road instead, which is what a real
-    # map style does.
-    cell_x = span * 0.22
-    cell_y = span * 0.13
-    placed = 0
-    for name, (_, points) in ordered:
-        if placed >= MAX_STREET_LABELS:
-            break
-        middle = len(points) // 2
-        # Try the midpoint first, then positions either side of it.
-        order = sorted(range(len(points)), key=lambda i: abs(i - middle))
-        chosen = None
-        for i in order:
-            cell = (
-                int((points[i][0] - lon) / cell_x),
-                int((points[i][1] - lat) / cell_y),
-            )
-            if cell not in occupied:
-                occupied.add(cell)
-                chosen = i
-                break
-        if chosen is None:
-            continue
-        placed += 1
-        middle = chosen
-        start = points[max(0, middle - 1)]
-        end = points[min(len(points) - 1, middle + 1)]
-        # Longitude degrees are shorter than latitude ones away from the
-        # equator, so the on-screen angle needs the cos(lat) correction or
-        # labels sit visibly off their road.
-        angle = math.degrees(
-            math.atan2(end[1] - start[1], (end[0] - start[0]) * aspect)
-        )
-        if angle > 90:
-            angle -= 180
-        elif angle < -90:
-            angle += 180
-        text = ax.text(
-            points[middle][0],
-            points[middle][1],
-            name,
-            fontsize=4.6,
-            ha="center",
-            va="center",
-            rotation=angle,
-            rotation_mode="anchor",
-            color="#4a453f",
-            zorder=8,
-        )
-        text.set_path_effects(
-            [
-                path_effects.Stroke(linewidth=1.4, foreground="#ffffff"),
-                path_effects.Normal(),
-            ]
-        )
-
-
-def _scale_bar(ax, lat: float, lon: float, span: float) -> None:
-    km_per_degree = 111.32 * max(0.05, math.cos(math.radians(lat)))
-    # A bar reading "100 km" across a hemisphere is worse than no bar.
-    if span > 20:
-        unit = 2000
-    elif span > 5:
-        unit = 500
-    elif span > 2:
-        unit = 100
-    elif span > 0.5:
-        unit = 20
-    else:
-        unit = 5
-    bar = unit / km_per_degree
-    x0, y0 = lon - span * 0.9, lat - span * 0.9
-    ax.plot([x0, x0 + bar], [y0, y0], color=_INK, linewidth=2.2, zorder=9)
-    ax.text(
-        x0 + bar / 2,
-        y0 + span * 0.04,
-        f"{unit} km",
-        fontsize=6.6,
-        ha="center",
-        color=_INK,
-        zorder=9,
-    )
-
-
-def _plot_pins(ax, pins: list[tuple[float, float]], size: float) -> None:
-    for i, (lat, lon) in enumerate(pins, 1):
-        ax.plot(
-            lon,
-            lat,
-            marker="o",
-            markersize=size,
-            markerfacecolor=_PIN,
-            markeredgecolor="white",
-            markeredgewidth=1.5,
-            zorder=8,
-        )
-        ax.annotate(
-            str(i),
-            (lon, lat),
-            color="white",
-            fontsize=size * 0.62,
-            weight="bold",
-            ha="center",
-            va="center",
-            zorder=9,
-        )
-
-
-def _plot_truth(ax, pins, truth: tuple[float, float], size: float) -> None:
-    """Draw the true location and the line to the guess it is being compared to."""
-    truth_lat, truth_lon = truth
-    if pins:
-        guess_lat, guess_lon = pins[-1]
-        ax.plot(
-            [guess_lon, truth_lon],
-            [guess_lat, truth_lat],
-            linestyle="--",
-            color=_PIN,
-            linewidth=1.6,
-            zorder=7,
-        )
-    ax.plot(
-        truth_lon,
-        truth_lat,
-        marker="o",
-        markersize=size,
-        markerfacecolor=_TRUTH,
-        markeredgecolor="white",
-        markeredgewidth=1.5,
-        zorder=10,
-    )
-
-
-def render_map(
-    pins: list[tuple[float, float]],
-    focus: tuple[float, float] | None = None,
-    span_deg: float = 7.0,
-    dpi: int = 100,
-    truth: tuple[float, float] | None = None,
-) -> Image.Image:
-    """
-    Render the guess map: a world panel plus a zoomed panel.
-
-    Args:
-        pins (`list[tuple[float, float]]`):
-            Pins as `(lat, lon)`, drawn and numbered in order.
-        focus (`tuple[float, float]`, *optional*):
-            Centre of the zoomed panel. Defaults to the last pin.
-        span_deg (`float`, *optional*, defaults to `7.0`):
-            Half-width of the zoomed panel in degrees. Below roughly 4 degrees
-            the panel adds urban areas, roads, rivers and town names, when the
-            optional detail layers are installed.
-        dpi (`int`, *optional*, defaults to `100`):
-            Figure resolution.
-        truth (`tuple[float, float]`, *optional*):
-            Ground truth, drawn in green with a dashed line to the last pin.
-            Only ever passed after a guess has been scored, so it cannot leak
-            into an observation the agent sees before committing.
-
-    Returns:
-        `PIL.Image.Image`: The two-panel map.
-    """
-    fig, (world, zoom) = plt.subplots(
-        1, 2, figsize=(10.2, 3.9), dpi=dpi, gridspec_kw={"width_ratios": [1.55, 1]}
-    )
-
-    _draw_land(world, 0.35)
-    world.set_xlim(-180, 180)
-    world.set_ylim(-90, 90)
-    world.set_facecolor(_WATER)
-    for x in range(-180, 181, 60):
-        world.axvline(x, color="white", linewidth=0.5, alpha=0.7)
-    for y in range(-60, 61, 30):
-        world.axhline(y, color="white", linewidth=0.5, alpha=0.7)
-    _plot_pins(world, pins, 8.0)
-    if truth is not None:
-        _plot_truth(world, pins, truth, 8.0)
-    title = "guess and true location" if truth is not None else "your pins - world"
-    world.set_title(title, fontsize=9, loc="left", color="#333")
-    world.set_xticks([])
-    world.set_yticks([])
-
-    focus_lat, focus_lon = focus if focus else (pins[-1] if pins else (20.0, 0.0))
-    _draw_land(zoom, 0.9)
-    zoom.set_xlim(focus_lon - span_deg, focus_lon + span_deg)
-    zoom.set_ylim(focus_lat - span_deg, focus_lat + span_deg)
-    zoom.set_facecolor(_WATER)
-    _draw_detail(zoom, focus_lat, focus_lon, span_deg)
-    # Above about 20 degrees every country in a hemisphere wants a label and the
-    # panel turns into a stack of overlapping text.
-    if TOWNS_MAX_SPAN_DEG < span_deg <= 20.0:
-        _label_countries(zoom, focus_lat, focus_lon, span_deg)
-    _plot_pins(zoom, pins, 10.0)
-    if truth is not None:
-        _plot_truth(zoom, pins, truth, 10.0)
-    _scale_bar(zoom, focus_lat, focus_lon, span_deg)
-    # Below a degree, degrees round to "0"; kilometres are the useful unit there.
-    width_deg = span_deg * 2
-    label = (
-        f"{width_deg:.0f} deg view"
-        if width_deg >= 1
-        else f"{width_deg * 111:.0f} km view"
-    )
-    zoom.set_title(label, fontsize=9, loc="left", color="#333")
-    zoom.set_xticks([])
-    zoom.set_yticks([])
-
-    fig.tight_layout(pad=0.6)
-    buf = io.BytesIO()
-    fig.savefig(buf, format="png", facecolor="white")
-    plt.close(fig)
-    buf.seek(0)
-    return Image.open(buf).convert("RGB")

geoguesser_env/build/lib/geoguesser_env/server/render/pano.py

@@ -1,108 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-
-"""Perspective views out of an equirectangular panorama.
-
-`look()` is a gnomonic reprojection: build a camera ray for every output
-pixel, rotate it by the requested heading and pitch, convert to spherical
-coordinates and sample the source image. Integer sampling keeps it
-deterministic — the same arguments always produce the same bytes, which is
-what lets a GRPO group share one starting observation.
-"""
-
-from __future__ import annotations
-
-import base64
-import io
-
-import numpy as np
-from PIL import Image
-
-
-DEFAULT_SIZE = (640, 640)
-
-
-def look(
-    pano: Image.Image,
-    heading_deg: float,
-    pitch_deg: float = 0.0,
-    fov_deg: float = 90.0,
-    size: tuple[int, int] = DEFAULT_SIZE,
-) -> Image.Image:
-    """
-    Render one perspective view out of an equirectangular panorama.
-
-    Args:
-        pano (`PIL.Image.Image`):
-            Source panorama, 2:1 equirectangular.
-        heading_deg (`float`):
-            Compass heading in degrees, `0` being the panorama's own 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.
-        size (`tuple[int, int]`, *optional*, defaults to `(640, 640)`):
-            Output width and height in pixels.
-
-    Returns:
-        `PIL.Image.Image`: The rendered view.
-
-    Examples:
-
-    ```python
-    view = look(Image.open("pano.jpg"), heading_deg=90, fov_deg=30)
-    ```
-    """
-    src = np.asarray(pano.convert("RGB"))
-    src_h, src_w = src.shape[:2]
-    width, height = size
-
-    focal = 0.5 * width / np.tan(np.radians(fov_deg) / 2)
-    xs, ys = np.meshgrid(np.arange(width) - width / 2, np.arange(height) - height / 2)
-    rays = np.stack([xs, -ys, np.full_like(xs, focal, dtype=float)], axis=-1)
-    rays /= np.linalg.norm(rays, axis=-1, keepdims=True)
-
-    pitch, heading = np.radians(pitch_deg), np.radians(heading_deg)
-    rot_x = np.array(
-        [
-            [1, 0, 0],
-            [0, np.cos(pitch), -np.sin(pitch)],
-            [0, np.sin(pitch), np.cos(pitch)],
-        ]
-    )
-    rot_y = np.array(
-        [
-            [np.cos(heading), 0, np.sin(heading)],
-            [0, 1, 0],
-            [-np.sin(heading), 0, np.cos(heading)],
-        ]
-    )
-    rays = rays @ rot_x.T @ rot_y.T
-
-    lon = np.arctan2(rays[..., 0], rays[..., 2])
-    lat = np.arcsin(np.clip(rays[..., 1], -1.0, 1.0))
-    u = ((lon / (2 * np.pi) + 0.5) * src_w).astype(np.int32) % src_w
-    v = np.clip(((0.5 - lat / np.pi) * src_h).astype(np.int32), 0, src_h - 1)
-    return Image.fromarray(src[v, u])
-
-
-def to_base64(image: Image.Image, fmt: str = "JPEG", quality: int = 85) -> str:
-    """
-    Encode an image for transport inside an observation.
-
-    Args:
-        image (`PIL.Image.Image`):
-            Image to encode.
-        fmt (`str`, *optional*, defaults to `"JPEG"`):
-            Pillow format name. Views use JPEG; maps use PNG.
-        quality (`int`, *optional*, defaults to `85`):
-            JPEG quality, ignored for PNG.
-
-    Returns:
-        `str`: Base64-encoded image bytes, without a data URI prefix.
-    """
-    buf = io.BytesIO()
-    if fmt.upper() == "JPEG":
-        image.save(buf, format="JPEG", quality=quality, optimize=True)
-    else:
-        image.save(buf, format=fmt)
-    return base64.b64encode(buf.getvalue()).decode("ascii")

geoguesser_env/build/lib/geoguesser_env/server/scoring.py

@@ -1,233 +0,0 @@
-# SPDX-License-Identifier: BSD-3-Clause
-
-"""Distance scoring and action costs.
-
-The distance curve is GeoGuessr's own, `5000 * exp(-d / 1492.7)`, normalised
-to `[0, 1]`. Keeping the real curve means scores are directly interpretable
-against the game most people already know.
-"""
-
-from __future__ import annotations
-
-import math
-
-
-# GeoGuessr's decay constant, in kilometres.
-DECAY_KM = 1492.7
-
-# A second, much slower decay used only by the `"mixture"` reward shape. The
-# game curve is worth 0.018 across the whole 6000-20000 km range, so a policy
-# that lands on the wrong continent -- a third of rollouts for a 4B model --
-# gets no gradient for getting *less* wrong. This scale restores one.
-LONG_DECAY_KM = 5000.0
-
-# Fraction of the mixture carried by the game curve; the rest is the long scale.
-MIXTURE_SHORT_WEIGHT = 0.5
-
-REWARD_SHAPES = ("geoguessr", "mixture")
-
-EARTH_RADIUS_KM = 6371.0088
-
-# Action costs. Information gathering is cheap but not free, so an episode has
-# to trade breadth of search against committing to a guess.
-COST_LOOK = 0.01
-COST_MAP = 0.01
-COST_PIN = 0.02
-COST_MOVE = 0.05
-
-# Partial credit weights, used when the reward is hierarchical.
-WEIGHT_COUNTRY = 0.15
-WEIGHT_REGION = 0.10
-
-
-def haversine_km(lat_a: float, lon_a: float, lat_b: float, lon_b: float) -> float:
-    """
-    Great-circle distance between two points in kilometres.
-
-    Args:
-        lat_a (`float`):
-            Latitude of the first point in degrees.
-        lon_a (`float`):
-            Longitude of the first point in degrees.
-        lat_b (`float`):
-            Latitude of the second point in degrees.
-        lon_b (`float`):
-            Longitude of the second point in degrees.
-
-    Returns:
-        `float`: Distance in kilometres.
-
-    Examples:
-
-    ```python
-    d = haversine_km(-16.4897, -68.1193, -17.7833, -63.1821)
-    ```
-    """
-    phi_a, phi_b = math.radians(lat_a), math.radians(lat_b)
-    d_phi = phi_b - phi_a
-    d_lambda = 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 * EARTH_RADIUS_KM * math.asin(math.sqrt(min(1.0, h)))
-
-
-def distance_score(distance_km: float, shape: str = "geoguessr") -> float:
-    """
-    Map a distance to a score in `[0, 1]`.
-
-    Args:
-        distance_km (`float`):
-            Distance between guess and truth in kilometres.
-        shape (`str`, *optional*, defaults to `"geoguessr"`):
-            `"geoguessr"` for the game's own curve, or `"mixture"` for the
-            two-scale curve used when training. The mixture is deliberately
-            *not* the default: reported scores stay comparable to the game.
-
-    Returns:
-        `float`: For `"geoguessr"`, `exp(-distance_km / 1492.7)` -- 0 km scores
-        `1.0`, 150 km about `0.90`, 5000 km about `0.035`. For `"mixture"`,
-        half that plus half of `exp(-distance_km / 5000)`, which keeps the
-        mid-range sharp while leaving real gradient past 3000 km.
-
-    Examples:
-
-    ```python
-    near = distance_score(200.0)                     # 0.875
-    far = distance_score(8000.0, shape="mixture")    # 0.104, versus 0.005
-    ```
-    """
-    if distance_km < 0:
-        raise ValueError(f"distance_km must be non-negative, got {distance_km}")
-    if shape not in REWARD_SHAPES:
-        raise ValueError(f"shape must be one of {REWARD_SHAPES}, got {shape!r}")
-    short = math.exp(-distance_km / DECAY_KM)
-    if shape == "geoguessr":
-        return short
-    long = math.exp(-distance_km / LONG_DECAY_KM)
-    return MIXTURE_SHORT_WEIGHT * short + (1.0 - MIXTURE_SHORT_WEIGHT) * long
-
-
-def action_cost(
-    n_looks: int = 0, n_maps: int = 0, n_pins: int = 0, n_moves: int = 0
-) -> float:
-    """
-    Total cost of the information gathering done this episode.
-
-    Args:
-        n_looks (`int`, *optional*, defaults to `0`):
-            Number of view renders.
-        n_maps (`int`, *optional*, defaults to `0`):
-            Number of map views that were not pins.
-        n_pins (`int`, *optional*, defaults to `0`):
-            Number of pins placed.
-        n_moves (`int`, *optional*, defaults to `0`):
-            Number of moves taken.
-
-    Returns:
-        `float`: Cost to subtract from the distance score.
-    """
-    return (
-        COST_LOOK * n_looks
-        + COST_MAP * n_maps
-        + COST_PIN * n_pins
-        + COST_MOVE * n_moves
-    )
-
-
-# The multiplicative cost is capped so a very long episode scales the score down
-# rather than erasing it. Without a cap a 20-move episode would reach zero.
-MAX_COST_FRACTION = 0.5
-
-
-def compute_reward(
-    distance_km: float | None,
-    *,
-    cost: float = 0.0,
-    country_hit: bool = False,
-    region_hit: bool = False,
-    hierarchical: bool = False,
-    shape: str = "geoguessr",
-    cost_mode: str = "subtract",
-) -> float:
-    """
-    Combine distance, partial credit and action cost into one reward.
-
-    Args:
-        distance_km (`float` or `None`):
-            Distance from guess to truth. `None` means the guess could not be
-            parsed, which scores zero before costs.
-        cost (`float`, *optional*, defaults to `0.0`):
-            Accumulated action cost.
-        country_hit (`bool`, *optional*, defaults to `False`):
-            Whether the guessed country matched.
-        region_hit (`bool`, *optional*, defaults to `False`):
-            Whether the guessed region matched.
-        hierarchical (`bool`, *optional*, defaults to `False`):
-            Whether to add country and region partial credit.
-        shape (`str`, *optional*, defaults to `"geoguessr"`):
-            Distance curve, passed to [`~scoring.distance_score`].
-        cost_mode (`str`, *optional*, defaults to `"subtract"`):
-            `"subtract"` reproduces the game: the cost comes off the score and
-            the result is floored at zero. `"multiply"` scales the score by
-            `1 - cost` instead, which is what training wants -- see below.
-
-    Returns:
-        `float`: Reward in `[0, 1]`.
-
-    <Tip warning={true}>
-
-    `"subtract"` and a floor at zero destroy the ordering of bad guesses. Mean
-    cost for a 4B model is 0.13, and the game curve falls below that at about
-    3300 km, so a 3324 km miss and an 18723 km miss both score exactly 0.0 --
-    measured across 200 episodes, 77 of them collapsed to a single value with
-    zero variance. A GRPO group drawn from those has no advantage and therefore
-    contributes no gradient. `"multiply"` cannot do this: scaling by a positive
-    factor preserves the ordering whatever the cost.
-
-    </Tip>
-
-    Examples:
-
-    ```python
-    # Training: gradient survives on the wrong continent.
-    reward = compute_reward(8000.0, cost=0.13, shape="mixture", cost_mode="multiply")
-    ```
-    """
-    if distance_km is None:
-        return 0.0
-    score = distance_score(distance_km, shape=shape)
-    if hierarchical:
-        score += WEIGHT_COUNTRY * country_hit + WEIGHT_REGION * region_hit
-    score = min(1.0, score)
-    if cost_mode == "multiply":
-        return score * (1.0 - min(max(cost, 0.0), MAX_COST_FRACTION))
-    if cost_mode != "subtract":
-        raise ValueError(
-            f"cost_mode must be 'subtract' or 'multiply', got {cost_mode!r}"
-        )
-    return max(0.0, score - cost)
-
-
-def verdict(distance_km: float) -> str:
-    """
-    Short human-readable label for a distance, for UIs and logs.
-
-    Args:
-        distance_km (`float`):
-            Distance between guess and truth in kilometres.
-
-    Returns:
-        `str`: One of `"Perfect"`, `"Pinpoint"`, `"Close"`, `"Right region"`
-        or `"Wrong continent"`.
-    """
-    if distance_km < 0.025:
-        return "Perfect"
-    if distance_km < 25:
-        return "Pinpoint"
-    if distance_km < 200:
-        return "Close"
-    if distance_km < 1500:
-        return "Right region"
-    return "Wrong continent"

geoguesser_env/openenv_geoguesser_env.egg-info/PKG-INFO

@@ -1,760 +0,0 @@
-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
-cd envs/geoguesser_env
-
-# The frozen 200-task eval split is committed, so this runs as-is, with the
-# same configuration the Space uses.
-./scripts/serve_local.sh             # http://localhost:8000/web/
-
-# 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.
-
-### Training against it
-
-The defaults above reproduce the game, which makes a score directly comparable
-to GeoGuessr. They are the wrong shape for RL, and three flags change that:
-
-| flag | play / eval | training | why |
-|---|---|---|---|
-| `reward_shape` | `"geoguessr"` | `"mixture"` | The game curve is worth **0.018** across the whole 6000-20000 km range, so a policy gets no gradient for landing on the right continent instead of the wrong one. `"mixture"` adds a 5000 km scale, making that span worth 0.150. |
-| `cost_mode` | `"subtract"` | `"multiply"` | Mean action cost for a 4B model is 0.13 and the curve falls below that at ~3300 km, so `max(0, geo - cost)` floors every worse guess at exactly zero. Measured over 200 episodes: **77 collapsed to 0.0 with zero variance**, so a GRPO group drawn from them has no advantage and yields no gradient. A multiplier cannot do this. |
-| `hide_task_identity` | `False` | **`True`** | `metadata` carries `attribution.creator_username`, and the contributor determines the country outright for **74% of training tasks** (`amsterdam` only maps the Netherlands). `task_index`/`task_id`/`sequence_id` are a few thousand memorisable keys straight to a coordinate. Either lets a policy score without reading the image. |
-
-```bash
-GEOGUESSER_REWARD_SHAPE=mixture \
-GEOGUESSER_COST_MODE=multiply \
-GEOGUESSER_HIDE_IDENTITY=1 \
-    uvicorn geoguesser_env.server.app:app
-```
-
-Replaying all 3,037 recorded eval episodes through both settings: episodes
-scoring exactly zero fall from **10-46% to 0%** for every model, and the
-leaderboard order only changes within the tiers already documented as inside
-noise at n=200.
-
-The terminal observation carries full provenance either way — once the truth is
-revealed it can no longer be used to shortcut the episode — so recorded traces
-stay complete under `hide_task_identity`.
-
-## 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.
-
-## On the Hub
-
-| | |
-|---|---|
-| Space | [`HuggingEnvs/geoguesser-env`](https://huggingface.co/spaces/HuggingEnvs/geoguesser-env) |
-| Space (mirror) | [`AdithyaSK/geoguesser-env`](https://huggingface.co/spaces/AdithyaSK/geoguesser-env) |
-| Task splits | [`HuggingEnvs/geoguesser-tasks`](https://huggingface.co/datasets/HuggingEnvs/geoguesser-tasks) |
-| Imagery | [`HuggingEnvs/geoguesser-panos`](https://huggingface.co/buckets/HuggingEnvs/geoguesser-panos) (Storage Bucket, public, mounted read-only at `/data`) |
-
-The Space and the bucket deliberately live in different namespaces: moving the
-Space should not mean re-uploading 22 GB, so `deploy_hub.py` takes the owner of
-each separately (`GEOGUESSER_HF_ORG` and `GEOGUESSER_HF_BUCKET_OWNER`).
-
-The same client drives either:
-
-```python
-env = GeoGuesserEnv(base_url="http://localhost:8000")                      # local
-env = GeoGuesserEnv(base_url="https://huggingenvs-geoguesser-env.hf.space") # Space
-```
-
-Only the file locations differ — locally the indexes and imagery are in the
-repo, on the Space they arrive through the bucket mount. Splits, step budget,
-street labels and offline enforcement are identical, and verified so: the same
-task returns the same image checksums, reward and distance from both.
-
-Deploy with `scripts/deploy_hub.py --all`. `openenv push` is deliberately not
-used: it cannot attach a bucket volume, and its default excludes would upload
-22 GB of panoramas into git.
-
-### Local and Space parity
-
-Verified across a local server and both Spaces, on both splits, driven by the
-same client. Every field below is identical in all three:
-
-| | eval index 42 | train index 1234 |
-|---|---|---|
-| task id | `eval-00042` | `train-01234` |
-| reset image sha256 | `a1447fd8` | `5494a500` |
-| look image sha256 | `1c95af16` | `0850e712` |
-| move distance | 27.778734090271577 m | 26.196924979479498 m |
-| reward, distance | 0.0, 7463.03 km | 0.0, 12647.18 km |
-
-The guess map is **pixel-identical** too: mean absolute difference 0.000/255
-over 1020x390. Only the PNG encoding differs, not the content.
-
-The one fragile part is the street layer, which comes from Overpass. Overpass
-answers a laptop in ~2 s but intermittently returns **504 Gateway Timeout** to
-datacenter egress, which once left the Space rendering coarse
-Natural-Earth-only maps while a laptop drew the full labelled grid. A single
-retry recovers it, and the environment now *reports* the state rather than
-degrading silently: observation metadata carries `street_detail` as `on`, `off`
-or **`unavailable`**, so a poorer map is visible instead of looking like a
-styling choice. Scoring is unaffected either way -- reward is distance-based.
-`GEOGUESSER_OSM_CACHE` points the street cache at a mounted, pre-warmed
-directory for deployments that cannot reach Overpass at all.
-
-## 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.
-
-## Collecting evals
-
-`scripts/collect_eval.py` runs models against a split and records everything
-about each episode. One JSONL line per episode, ~13 KB.
-
-```bash
-export ANTHROPIC_API_KEY=...
-python scripts/collect_eval.py --provider anthropic --model claude-sonnet-5 \
-    --split eval --max-turns 12
-
-# several endpoints in one run, each at its own concurrency
-cp models.example.json models.json     # anthropic / openai / HF router / vLLM
-python scripts/collect_eval.py --models models.json --split eval
-```
-
-Output lands in `rollouts/<run_id>/`: `episodes.jsonl` plus a `run.json` with
-per-model aggregates (mean reward, median distance, within-1/25/200/750 km,
-parse rate, forced guesses, tokens, latency). Runs are **resumable** — re-run the
-same `--run-id` and it skips episodes already recorded.
-
-Each turn carries the camera state **before and after** the action, which is
-what makes a rollout re-renderable: a pan from 0 to 270 degrees can only be
-animated if both ends are known. It also carries the exact prompt, the raw
-reply, separated reasoning, finish reason, token counts, per-attempt errors and
-latency, and the provider's own response id.
-
-**Pixels are not stored.** The environment is deterministic and the panoramas
-are local, so a renderer replays the state trajectory instead. Storing them
-would cost roughly 14 GB for 200 tasks across six models, all re-derivable. What
-*is* stored is a sha256 per observation, so a replay can be *verified* rather
-than assumed:
-
-```bash
-python scripts/verify_replay.py ../../rollouts/<run_id>/episodes.jsonl
-# 3 episodes · 19 view turns checked · 19 match · 0 mismatch
-# every view turn reproduces byte-for-byte
-```
-
-That check is not decorative: it exits non-zero on drift, because a video built
-from a mismatched trace looks authoritative and shows something the model never
-saw. Guess maps are excluded from it by construction — they depend on the
-Overpass response of the moment. Use `--save-frames` when you want the literal
-bytes anyway.
-
-## Rollout video
-
-Two steps, split where the work naturally divides. Python owns
-pixels-from-panoramas, because the gnomonic reprojection already lives here and
-is verified byte-exact against the trace. React owns layout, typography and
-transitions, because that is where iterating on them is pleasant.
-
-```bash
-# 1. Frames + timeline.json, straight into the Remotion project's public/
-python scripts/render_rollout.py ../../rollouts/<run>/episodes.jsonl --episode 0
-
-# 2. Compose
-cd video && npm install
-npx remotion render Rollout out.mp4 --props=public/rollouts/<slug>/timeline.json
-npx remotion studio          # iterate on the composition live
-```
-
-**The pan is a real pan.** A `look` from 0 to 270 degrees is not a cut between
-two stills: it renders one intermediate gnomonic reprojection per video frame
-along the *shortest angular path*, eased like a camera rather than swept
-linearly — 350 to 10 degrees pans +20, not -340. Zoom interpolates the field of
-view the same way. Verified: a `look` segment produces 29 distinct images, a
-`zoom` 24, with no duplicates.
-
-Layout is a large panorama viewport with a HUD of the state the agent is acting
-on (heading, fov, actions left, cost), and a trace pane that reveals turns as
-they happen — the active turn carries the model's raw reply, past turns recede.
-Then a score card with the guess against the truth.
-
-Fidelity is checked before anything is composed: every view keyframe is
-re-rendered at the size the model saw and compared to the trace's sha256, and a
-mismatch aborts. A video that looks authoritative while showing something the
-model never saw is worse than no video.
-
-## 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 |
-| `GEOGUESSER_OSM_CACHE` | `data/geo/osm_cache` | Street-window cache; point at a pre-warmed mount where Overpass is unreachable |
-| `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/openenv_geoguesser_env.egg-info/SOURCES.txt

@@ -1,29 +0,0 @@
-README.md
-__init__.py
-client.py
-harness.py
-models.py
-pyproject.toml
-./__init__.py
-./client.py
-./harness.py
-./models.py
-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

@@ -1 +0,0 @@
-

geoguesser_env/openenv_geoguesser_env.egg-info/entry_points.txt

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

geoguesser_env/openenv_geoguesser_env.egg-info/requires.txt

@@ -1,14 +0,0 @@
-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

@@ -1 +0,0 @@
-geoguesser_env