Spaces:
Running
Running
|
Download README.md from Jofthomas/GeoGuess_Arena: direct link, hf CLI and curl.
- Browser
- Download file 4.74 kB
-
https://huggingface.co/spaces/Jofthomas/GeoGuess_Arena/resolve/main/README.md
- Command line
-
hf download hf://spaces/Jofthomas/GeoGuess_Arena/README.md
-
curl -L -o README.md https://huggingface.co/spaces/Jofthomas/GeoGuess_Arena/resolve/main/README.md
4.74 kB
| title: GeoGuessr Arena | |
| emoji: 🌍 | |
| colorFrom: indigo | |
| colorTo: yellow | |
| sdk: docker | |
| app_port: 7860 | |
| hf_oauth: true | |
| hf_oauth_scopes: | |
| - inference-api | |
| pinned: true | |
| models: | |
| - mistralai/Mistral-Large-4.0-1T05-A52B | |
| # GeoGuessr Arena: you vs the machines | |
| Everyone is dropped at the same random Street View location with the same clock. | |
| You explore with a draggable Street View. The AI agents explore with tools: | |
| | tool | what it does | | |
| |---|---| | |
| | `look` / `pan` / `zoom` | change heading, pitch or field of view and get a new 640×640 view | | |
| | `move` | walk forward or backward along the current heading, snapping to the nearest Google panorama | | |
| | `view_map` | a roadmap of any coordinates the agent picks, so it can check a hypothesis. It never shows where the agent actually is. | | |
| | `place_pin` / `reverse_geocode` | drop a candidate pin, or look up which place a coordinate falls in | | |
| | `submit_guess` | lock in a final answer | | |
| While the round is live you only see a **blind feed** of what each rival is doing | |
| ("walked 23 m", "zoomed in"), never what they see or think. | |
| At the reveal you get the guesses map, every agent's walked path, and a full step-by-step | |
| replay of its views, reasoning and tool calls. | |
| ## Space secrets | |
| | secret | needed for | | |
| |---|---| | |
| | `GOOGLE_MAPS_API_KEY` | server side: Street View Static + metadata, Static Maps, Geocoding | | |
| | `GOOGLE_MAPS_BROWSER_KEY` | Maps JavaScript API in the browser. Restrict it by HTTP referrer. Falls back to the server key. | | |
| | `HF_TOKEN` | trace uploads (needs write access to the traces dataset) | | |
| | `MISTRAL_API_KEY` | Mistral models | | |
| | `HF_TRACES_REPO` | optional. Private dataset for traces (default `Jofthomas/geoguessr-arena-traces`) | | |
| Open-weight models (every `key="hf_login"` entry in `MODELS`) run through the HF router on the | |
| **player's own Hugging Face account**: they click "Sign in with Hugging Face" and the Space's | |
| OAuth token (scope `inference-api`) is used for their games, so usage is billed to them. | |
| Proprietary models (`key="byok"`) run on the player's own key. Those keys are held in memory | |
| for the duration of the game only. They are never logged and never written to traces. | |
| Optional tuning variables: `ROUNDS_PER_GAME`, `ROUND_SECONDS`, `AGENT_MAX_STEPS`, `AGENT_MAX_GEOCODES`, | |
| `AGENT_WRAPUP_SECONDS`, `GAMES_PER_IP_PER_HOUR`. | |
| ## Changing the model list | |
| Every opponent is one entry in the `MODELS` dict in [`arena/config.py`](arena/config.py). The lobby, | |
| the live feed, the reveal and the traces all read from it, so adding, removing or editing an entry | |
| is the only change needed. | |
| | field | meaning | | |
| |---|---| | |
| | `label`, `color` | name and colour shown in the UI | | |
| | `provider` | `"openai_compat"` (any OpenAI-style `/chat/completions` with tools), `"openai_responses"` (OpenAI's Responses API, required for their reasoning models with tools) or `"anthropic"` | | |
| | `base_url` | endpoint for `openai_compat`, e.g. `HF_ROUTER_BASE_URL` | | |
| | `model_id` | model name sent to the provider (HF router: the Hub repo id) | | |
| | `key` | `"hf_login"` (player's HF account), `"byok"` (player pastes a key, set `key_hint`), or the name of an env var holding a server key | | |
| | `avatar` | profile picture, e.g. `/static/avatars/qwen.webp` | | |
| | `default_on` | pre-selected in the lobby | | |
| | `catalog` | BYOK only: `"openai"`, `"anthropic"` or `"gemini"`. Once a key is pasted, the lobby lists that provider's models in a dropdown; `model_id` is the default | | |
| | `reasoning_effort` | `openai_responses` (e.g. `"medium"`) or `openai_compat` providers that accept it, e.g. Mistral Large 4 (`"high"` / `"none"`) | | |
| | `max_images` | optional cap on images per request for providers that limit it (also learned automatically from a 413) | | |
| | `token_param`, `extra_body` | optional provider quirks for `openai_compat` | | |
| Model keys (the dict keys) end up in DOM ids: use letters, digits, `-` and `_` only. | |
| Models must accept images **and** support tool calling. For the HF router, check | |
| `https://router.huggingface.co/v1/models`: `input_modalities` must include `image` and at least one live | |
| provider must have `supports_tools: true`. | |
| ## Traces | |
| Each revealed round is written to `data/{date}/{game_id}/round_NN.jsonl` in the private dataset, | |
| with one row per participant: the guess, distance, score, rank, token usage, walked path, pins and | |
| the full provider-neutral message trace. Street View pixels are **not** uploaded | |
| (Google Maps ToS). Each image is stored as its request parameters instead | |
| (`pano`, `heading`, `pitch`, `fov` / map center + zoom), so you can re-fetch it with your own key. | |
| ## Local dev | |
| ```bash | |
| uv venv -p 3.12 .venv && uv pip install -r requirements.txt | |
| cp .env.example .env # fill in keys | |
| .venv/bin/uvicorn arena.main:app --reload --port 7860 | |
| ``` |