Spaces:
Running
Running
| title: wave~reader | |
| emoji: 🏄 | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: gradio | |
| sdk_version: 6.26.0 | |
| python_version: "3.14" | |
| app_file: app.py | |
| license: mit | |
| pinned: false | |
| short_description: Surf-forecast world model for the Australian coast | |
| # wave~reader | |
| **A surf-forecasting world model for the Australian coast: 238 breaks, 168 | |
| deterministic scores per spot, a 3D seafloor built from real GEBCO | |
| bathymetry — and one open model that narrates the numbers instead of | |
| inventing them.** | |
| wave~reader is a single-page Gradio app, built in September 2026 | |
| as an entry for the **GTC Berlin Golden Ticket Developer Contest**. I have | |
| just moved to Berlin; I wanted to build something to make me enjoy ML and | |
| engineering again. | |
| > [Built for GTC Berlin](#built-for-the-gtc-berlin-golden-ticket-developer-contest-) — | |
| > NVIDIA open weights on Hugging Face rails. #NVIDIAGTC | |
| ## One rule holds the whole app together | |
| **The LLM never owns numbers.** Every wave height, wind reading, and 0–10 | |
| score on screen comes out of plain, deterministic Python — | |
| `wavereader/scoring.py`, `wavereader/openmeteo.py`, `wavereader/tools.py` — | |
| running over Open-Meteo marine data and the enriched break catalogue. The | |
| model's contract, written into its system prompt, is to interpret those | |
| numbers, name the tool that produced them, and never compute a forecast | |
| itself. The agent can _recommend_; it can't _hallucinate a swell_. | |
| That split — a deterministic core with the model bolted on as an | |
| interpreter — is the entire architecture, and it's what makes an | |
| open-weights model safe to plan a surf trip around. | |
| ## One screen, four instruments | |
| There are no tabs. One surface, four synchronized instruments, one source | |
| of truth (`selected`): picking a spot re-aims everything at once. | |
| | Instrument | What it does | | |
| | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | |
| | **Map lens** (left) | All 238 breaks on a Plotly map, filtered by state / region / skill. A pick loads the full field guide and re-aims the forecast, world model, and climatology. | | |
| | **Forecast story** (center) | The engines spin up in visible stages — status lines name the engine and its latency. You get a 0–10 score for every hour of the next 7 days, score / swell / wind strips with weekend shading, then a **smoothed 3D seafloor with an animated swell layer** riding the forecast's dominant period (press ▶ swell). An optional streamed narrator writes it up — from the scores only. | | |
| | **Intel rail** (right) | Field guide (peak type, ideal swell / wind / tide, hazards, crowd factor), a **5-year ERA5 swell climate rose** that audits the dataset's own claims, a wetsuit hint, and nearby surf cams. | | |
| | **Agent bar** (full width) | Chat: _"where's it going to be good in NSW this weekend?"_ A smolagents `ToolCallingAgent` on Nemotron 3 Ultra finds spots, ranks regions, explains score breakdowns, and suggests similar breaks. Every tool card shows its **latency in ms**; charts render mid-answer straight from tool payloads. Hard budget: 6 steps, 700 tokens a turn. | | |
| ## Machinery you can watch | |
| The app wears its internals on its sleeve: a strip across the top shows | |
| every engine (🌍 world model · 📡 feeds · 🌡 climate · ⚙ scorer · 🧠 LLM · | |
| 🔌 MCP) with live timings, and slow work loads in stages so the charts are | |
| never blocked. Measured on a laptop against the disk cache: | |
| | Engine | Cold | Warm | Where | | |
| | -------------------------------------------- | -------- | ---------- | ------------------------- | | |
| | ⚙ scoring engine (168 hourly 0–10 scores) | ~300 ms | **0.8 ms** | `wavereader/scoring.py` | | |
| | 📡 Open-Meteo marine + wind feed | ~300 ms | **~1 ms** | `wavereader/openmeteo.py` | | |
| | 🌍 GEBCO world model (10×10 bathymetry grid) | ~1.3 s | **~1 ms** | `wavereader/seafloor.py` | | |
| | 🧠 agent tool call (`score_week` over MCP) | ~2 ms | **0.7 ms** | `wavereader/tools.py` | | |
| | Chart trio (score / swell / wind) | 12–14 ms | — | `ui/charts/` | | |
| Forecast charts land in ~80 ms while the world model resolves in a | |
| parallel thread. `scripts/warm_caches.py` pre-fills every cache before a | |
| demo, so a cold start never happens on camera. The seafloor view bicubically | |
| upsamples the 10×10 GEBCO grid to 41×41 and animates a translucent swell | |
| surface at the forecast's dominant height and period — a world model you | |
| can watch working. (Smoothing and animation are display-only; statistics | |
| always come from the raw grid.) | |
| ## The stack: NVIDIA open weights on Hugging Face rails | |
| Every model call in the repo goes through one door — **Hugging Face | |
| Inference Providers**, served by DeepInfra — running | |
| [`nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-BF16`](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Ultra-550B-A55B-BF16), | |
| the open-weights Ultra of NVIDIA's Nemotron 3 family. No private APIs, no | |
| proprietary endpoints, one `HF_TOKEN`. Around the model, everything is | |
| open too: Open-Meteo forecasts, ERA5 reanalysis, GEBCO 2020 bathymetry via | |
| OpenTopoData, and a scoring engine you can read in one sitting. | |
| With NVIDIA and Hugging Face now one family, this app got to be an early | |
| wedding photo. 🎉 | |
| ## The app is the tool: MCP built in | |
| `app.py` launches with `mcp_server=True`, so any MCP client (Claude | |
| Desktop, opencode, …) can drive the deterministic engines directly at | |
| `<space-or-local-url>/gradio_api/mcp/`. The public surface is exactly | |
| three typed tools — the same functions the agent calls internally: | |
| - `score_week` — hourly 0–10 scores, daily bests, best window for one break | |
| - `rank_region_week` — every break in a region, ranked best-first | |
| - `explain_score` — the size / direction / wind / period breakdown of one scored hour | |
| Verify with `curl <url>/gradio_api/mcp/schema`. Everything else in the UI | |
| is registered with `api_name=False` on purpose — the MCP surface stays | |
| clean. | |
| ## Quickstart | |
| Needs [uv](https://docs.astral.sh/uv/) and Python ≥ 3.14. | |
| ```sh | |
| uv sync | |
| cp .env.example .env # fill in HF_TOKEN (https://huggingface.co/settings/tokens) | |
| uv run app.py | |
| ``` | |
| Or skip the UI and drive the agent from Python: | |
| ```sh | |
| uv run python -c "from wavereader.agent import run_stream; \ | |
| [print(e.get('text', e.get('name', '')), end='') for e in run_stream('best beginner morning this weekend in VIC?')]" | |
| ``` | |
| `HF_TOKEN` is only needed for the agent and the narrator — the forecast | |
| charts, world model, and MCP tools run token-free with plain network | |
| access to Open-Meteo / OpenTopoData and a disk cache under `.cache/`. | |
| On a HF Space the secret is the fallback; the agent panel's BYO-token box | |
| is session-only and never logged. | |
| ## Deploying to HF Spaces | |
| The app is live at [huggingface.co/spaces/lucashudsn/wavereader](https://huggingface.co/spaces/lucashudsn/wavereader). | |
| The Space _is_ this git repo — the `space` remote points at it. Spaces | |
| read their config from YAML frontmatter at the top of `README.md`, but | |
| GitHub renders that block as an ugly metadata table, so it lives in | |
| `space-config.yaml` instead and the deploy flow prepends it in a | |
| throwaway commit at push time (the repo README stays clean; HF gets its | |
| config). Keep `sdk_version` in lockstep with the gradio pin in | |
| `requirements.txt`. If you change Space settings through the web UI, HF | |
| commits them into the Space's `README.md` — mirror anything you care | |
| about back into `space-config.yaml`. | |
| **Two ways to ship — deploys work from any branch, not just `main`:** | |
| 1. **Automatic, on every push to `main`.** The | |
| `.github/workflows/deploy-space.yml` action deploys `main` to the | |
| Space using the repo's `HF_TOKEN` Actions secret. Merge and walk | |
| away; watch progress under the repo's _Actions_ tab and the Space's | |
| _Logs → Build_. | |
| 2. **Manual, any branch.** From a clean tree with your work committed: | |
| ```sh | |
| scripts/deploy_space.sh # deploy the branch you're on | |
| scripts/deploy_space.sh some-branch # deploy any committed ref | |
| git push origin some-branch # keep GitHub in sync | |
| ``` | |
| The script builds its throwaway commit in a temp worktree, so your | |
| checkout is never touched; it force-pushes that tree to the Space's | |
| `main` (deploys are throwaway commits — only the tip matters to the | |
| build). The push asks for credentials: username `lucashudsn`, | |
| password = an HF token with write access | |
| (https://huggingface.co/settings/tokens). | |
| One-time CI setup: the Action needs `HF_TOKEN` as a **GitHub** repo | |
| secret (_Settings → Secrets and variables → Actions_, or | |
| `gh secret set HF_TOKEN`). The Space's own `HF_TOKEN` is a separate | |
| secret, already set. Builds take a few minutes; watch them under the | |
| Space's _Logs → Build_ tab or poll | |
| `HfApi().get_space_runtime("lucashudsn/wavereader")`. | |
| Secrets live in the Space's _Settings → Variables and secrets_ — | |
| `HF_TOKEN` is already set, which is what lets the agent and narrator work | |
| for visitors. `WR_MODEL` / `WR_PROVIDER` / `WR_BASE_URL` can be added the | |
| same way if you ever want to reroute the LLM. Caches under `.cache/` are | |
| ephemeral on the Space and rebuild lazily after a restart; nothing else | |
| needs doing. | |
| ## How it's laid out | |
| ``` | |
| app.py # HF Space entry: single-page UI + gr.api MCP tools | |
| ui/ # the front end | |
| app.py # layout + wiring (≤3 gr.State; Bells on load) | |
| panels/{lens,story,intel,agent}.py # map lens | forecast story | intel rail | agent bar | |
| charts/{map,strip,score,seafloor,climate,_style}.py # Plotly builders, one theme | |
| contracts.py # SELECT/FETCH/AGENT key contracts — no output-order drift | |
| _compat.py # backend access: v2 core → legacy.app.* → stubs | |
| theme.py # APP_CSS — IBM Plex Mono lo-fi identity | |
| wavereader/ # pure core: typed, tested, zero Gradio imports | |
| breaks.py openmeteo.py scoring.py seafloor.py climate.py | |
| tools.py # the deterministic tool functions (agent + MCP) | |
| agent.py # smolagents ToolCallingAgent, typed event stream | |
| narrate.py llm.py # streamed report writer; one InferenceClient factory | |
| scripts/ | |
| warm_caches.py # demo hot start: forecast + seafloor caches | |
| build_climate.py # ERA5 5-yr climatology builder (re-embeds catalogue) | |
| check_coords.py check_coast.py # coordinate + GEBCO coastline maintenance | |
| eval_agent.py # agent evaluation harness | |
| data/ | |
| australia-surf-breaks-enriched.json # 238 schema-valid breaks, ERA5 embedded | |
| surf-break-schema.json # the conformance contract | |
| surf-break-example-bells.json # prompt worked example | |
| surf-cams.json # camera links keyed name | state | region | |
| documents/ | |
| ENCYCLOPEDIA.md FORECAST.md SURFAGENT.md | |
| legacy/ # frozen v1 front end, kept as the compat fallback | |
| ``` | |
| Cheap checks: `uv run pytest -q` (offline fixtures, including an agent | |
| dry-run through an injected fake model) and `uv run python -c "import app"`. | |
| ## Where the data came from | |
| The break catalogue was generated by running **Nemotron 3.5 Lightning** | |
| once per break through the v1 pipeline (now archived in `legacy/`): one | |
| chat call per spot at temperature 0.4, with the JSON schema and the Bells | |
| Beach worked example loaded from `data/` into the prompt. | |
| `state` / `region` are pinned from the input list, never taken from the | |
| model, and every record validates against | |
| `data/surf-break-schema.json` with strict enums for swell, wind, tide, | |
| skill, and hazards. The batch runner is resumable. | |
| After the build, `scripts/build_climate.py` gave each break a **5-year | |
| ERA5 swell profile** (embedded in the record itself — 236 of 238; two | |
| duplicate Gnaraloo rows miss out) and `scripts/check_coords.py` / | |
| `scripts/check_coast.py` keep coordinates honest against OSM and the GEBCO | |
| shoreline. The climate rose in the intel rail uses those profiles to audit | |
| the dataset: where the model's claimed "ideal swell" disagrees with five | |
| years of observed reanalysis, the data wins. | |
| ## The forecast pipeline, end to end | |
| 1. **Deterministic core.** break → `scoring.py` → | |
| `openmeteo.get_forecast` (Open-Meteo marine + wind, disk-cached, | |
| snapped seaward to the right grid cell) → `score_week` → 168 hourly | |
| scores → Plotly strips + best-window hero. In parallel, the **world | |
| model** pulls the GEBCO 2020 grid around the takeoff zone, classifies | |
| the shelf shape, and renders depth, 3D, and transects with the | |
| animated swell layer. | |
| 2. **Narrator (optional).** The prompt carries only the daily bests | |
| (≤7 lines) plus the best window; Nemotron 3 Ultra streams a dot-point | |
| write-up of exactly those numbers. Nothing more. | |
| Full detail in [`documents/FORECAST.md`](documents/FORECAST.md). | |
| ## Built for the GTC Berlin Golden Ticket Developer Contest 🎟️ | |
| wave~reader is a contest entry: an app that could only exist because | |
| NVIDIA ships frontier-class open weights and Hugging Face turns them into | |
| one-token inference. It leans on both halves deliberately — Nemotron 3 | |
| Ultra for language, deterministic Python for physics — and shows its work | |
| on screen the whole way. | |
| Tagging @Merve Noyan — thanks for the nudge. #NVIDIAGTC | |