Bug fixes, daggr and gradio working

.gitignore

@@ -5,3 +5,6 @@ __pycache__/
 
 # Environment
 .env
+
+# Cache
+.cache/

README.md

@@ -97,10 +97,10 @@ Gradio UI:
 uv run python -m wavereader.app
 ```
 
-Legacy dev server:
+daggr "Morning Surf Report" canvas:
 
 ```sh
-uv run fastapi dev main.py
+uv run python -m wavereader.daggr_pipeline
 ```
 
 ## Built with open everything

ROADMAP.md

@@ -1,134 +1,108 @@
-# ROADMAP — GTC Golden Ticket sprint
+# ROADMAP — wavereader
 
-One-week sprint: **Sun Aug 30 → video published Mon Sep 7, 2026.**
-Contest submissions close **Sep 10** (3-day buffer). Deliverables: public HF
-Space, polished repo, ~2-minute video posted on LinkedIn with #NVIDIAGTC
-tagging Merve Noyan — doubling as an announcement of the Berlin move and
-openness to ML work/research in Berlin.
+**Goal:** Agentic surf forecaster for Australian breaks. Demo video by **Mon Sep 7, 2026** for NVIDIA GTC Golden Ticket contest (#NVIDIAGTC).
 
-Decisions locked: 8-day build to Mon Sep 7 · HF Inference + NVIDIA NIM behind
-one client · surf cams are stretch-only · demo lives on a HF Space ·
-FastAPI + smolagents CodeAgent + Gradio + daggr (no LangChain, no htmx).
+**Stack:** Python 3.12, uv, FastAPI, smolagents CodeAgent, Gradio, daggr, Open-Meteo Marine, HF Inference + NVIDIA NIM.
 
 ---
 
-## Day-by-day
-
-### Sun Aug 30 (tonight, ~2h)
-- Restructure repo to the layout in `AGENTS.md`; pin Python 3.12; add deps
-  (`gradio`, `daggr`, `openai`, `httpx`, `pydantic`, `pytest`); drop
-  `langchain-community`.
-- Grab a free NVIDIA NIM API key (build.nvidia.com); verify HF token works.
-- 30-min spike: hit Open-Meteo Marine API for Snapper Rocks, confirm hourly
-  wave fields look sane.
-
-### Mon Aug 31 — Data layer
-- Validation pass over `data/break_details.json`: coords plausible for region,
-  ranges sane; spot-check ~10 breaks against local knowledge.
-- `spots.py` (search by name/city/region/skill) + `forecasts.py`
-  (Open-Meteo Marine + wind, hourly, 7-day, disk cache).
-- 📹 **Capture:** terminal printing a 7-day forecast table for 3 spots.
-
-### Tue Sep 1 — Scoring engine
-- `scoring.py`: deterministic 0–10 score per hour with per-component
-  breakdown (swell size vs ideal range, swell direction match, wind speed +
-  offshore alignment, wave period). Unit tests.
-- Sanity-check rankings: Bells Beach should score on SW swell + light NW
-  wind; Kirra on long-period E.
-- Outputs: "best hours today" and day-by-week profile per spot.
-- 📹 **Capture:** score table / heatmap clip.
-
-### Wed Sep 2 — Agent core
-- `agent.py`: smolagents CodeAgent, streaming, trace capture; HF⇄NIM switch
-  via env vars. `tools.py`: 5 tools wired (get_forecast, score_week,
-  find_spots, get_spot_knowledge, rank_spots_this_week).
-- System prompt contract: numbers come from tools; the model explains.
-- 📹 **Capture:** the first complete agent answer, raw and candid — great b-roll.
-
-### Thu Sep 3 — Flows + evals
-- End-to-end flows: near-me weekly ranking with skill filter; today-at-X time
-  recommendation; spot Q&A using the knowledge tool.
-- User profile (skill level, home region) carried through conversation.
-- Write + run `evals/golden_questions.json`; fix prompt/tool gaps.
-
-### Fri Sep 4 — API + UI
-- `api.py`: FastAPI endpoints (`/spots` `/forecast` `/score` `/ask`).
-- `app.py`: Gradio UI — **Australia map home page (select your break)**,
-  chat, **interactive seaborn-styled forecast charts** whenever the agent
-  surfaces wind/sea data, agent trace panel, HF/NIM model toggle.
-- 📹 **Capture:** polished Demo Q1 + OpenAPI docs screen.
-
-### Sat Sep 5 — daggr + ship
-- `daggr_pipeline.py`: fixed "Morning Surf Report" DAG (geocode → find_spots
-  → score_week → top-3 rank → InferenceNode narrates). Verify node outputs
-  look good on the canvas.
-- Deploy to HF Space (secrets: `HF_TOKEN`, `NVIDIA_API_KEY`); test the public
-  URL end-to-end.
-- Publish `data/break_details.json` as a HF dataset; README architecture
-  diagram; license.
-- Stretch (only if everything else lands): live surf-cam snapshots → "is it
-  clean/right now" tool for a handful of famous breaks.
-- 📹 **Capture:** daggr canvas walkthrough; Space opened on a phone.
-
-### Sun Sep 6 — Rehearse + record
-- Run evals against the live Space; fix anything that breaks.
-- Full rehearsal, then record the main video (script below).
-- Draft the LinkedIn post.
-
-### Mon Sep 7 — Launch
-- Edit and publish the video; post to LinkedIn (contest entry + Berlin
-  announcement); submit the contest entry.
-- Sep 8–10: buffer for retakes / judge replies.
+## ✅ Done (through Thu Sep 3)
+
+- [x] Repo restructure per `AGENTS.md`; Python 3.12; deps added; `langchain-community` dropped
+- [x] NVIDIA NIM API key + HF token verified
+- [x] Open-Meteo Marine spike: Snapper Rocks hourly fields look sane
+- [x] `data/break_details.json` validation pass (coords, ranges, spot-check 10)
+- [x] `spots.py`: search by name/city/region/skill
+- [x] `forecasts.py`: Open-Meteo Marine + wind, hourly 7-day, disk cache
+- [x] `scoring.py`: deterministic 0–10 score/hour, component breakdown, unit tests
+- [x] Scoring sanity checks: Bells (SW swell + NW wind), Kirra (long-period E)
+- [x] `agent.py`: smolagents CodeAgent, streaming, trace capture, HF⇄NIM switch
+- [x] `tools.py`: 5 tools wired (get_forecast, score_week, find_spots, get_spot_knowledge, rank_spots_this_week)
+- [x] System prompt: numbers from tools, model explains
+- [x] End-to-end flows: near-me weekly ranking with skill filter, best-hours-today, spot Q&A
+- [ ] User profile (skill, home region) carried through conversation (skill filter works via chat; no persistent profile yet)
+- [ ] `evals/golden_questions.json` written; spot-checked manually (ranking+skill, best-hours, spot Q&A) — automated runner still TODO
 
 ---
 
-## Video script (~2 min, landscape screen captures + webcam bubble)
-
-Record each shot's milestone clip during the week as insurance; the final
-video is a re-recorded clean pass through the live Space.
-
-1. **Hook (0:00–0:10).** "I moved to Berlin last week — 16,000 km from the
-   nearest surf break. So I built an agent that finds waves back home."
-   *(B-roll: coastline → app loading.)*
-2. **Problem (0:10–0:25).** "Surf forecasting runs on local knowledge — which
-   winds suit which break, what size it can handle." *(Show
-   `break_details.json` snippet + raw forecast table.)*
-3. **Demo Q1 (0:25–0:55).** In the app: *"Where should I surf near Byron Bay
-   this weekend? Intermediate longboarder."* → ranked spot cards with scores
-   and the why. *(Show the agent trace panel streaming tool calls.)*
-4. **Demo Q2 (0:55–1:15).** *"What time should I surf Snapper Rocks
-   tomorrow?"* → interactive hourly chart, best-window recommendation with
-   wind/swell reasoning.
-5. **Reasoning canvas (1:15–1:35).** daggr Morning Surf Report — click
-   through node outputs live: rank → forecast → narrated report.
-6. **Under the hood (1:35–1:50).** FastAPI OpenAPI docs flash; flip the
-   HF ↔ NIM toggle; show the break knowledge base as a HF dataset.
-7. **CTA (1:50–2:10).** "Everything runs on open models — Qwen via Hugging
-   Face and NVIDIA NIM. Free GTC Berlin ticket, please 🤞 #NVIDIAGTC — and
-   since I just moved to Berlin: if you're working on LLM agents or applied
-   ML, I'd love to talk. DMs open." *(Screen: Space link + repo link.)*
-
-## LinkedIn post skeleton
-
-1. Hook: the move to Berlin.
-2. The problem: surf forecasting's inherent knowledge.
-3. Two sentences: what the app does + the two flagship questions.
-4. Video + Space link.
-5. Open-credentials: Qwen via HF Inference + NVIDIA NIM, open dataset on HF,
-   daggr canvas.
-6. Thanks + tags: judges, #NVIDIAGTC.
-7. Berlin close: "New in Berlin, keen on ML research/engineering — say hi."
-
-*(Nice detail: Hugging Face is headquartered in Berlin — the judge will get it.)*
+### User Data & Personalization
+
+- [ ] **User profile model** — `User` class with:
+  - `skill_level`: beginner / intermediate / advanced / pro → feeds `scoring.py`
+  - `home_region`: state/region for default "near me"
+  - `preferences`:
+    - `wave_direction`: left / right / both
+    - `state`: filter by Australian state
+    - `location`: lat/lon + radius for "near me"
+    - `other_preferences`: tags (reef, beach, point, crowd_tolerance, etc.)
+- [ ] **Skill level → scoring engine**
+  - Adjust ideal swell size per skill (beginner: 0.5–1.5m, pro: 2–4m+)
+  - Weight wind/period components differently per skill
+  - Return skill-adjusted score in `/score`
+- [ ] **Preferences → pre-filter breaks** (before scoring)
+  - Filter by `wave_direction` match
+  - Filter by `state` match
+  - Filter by `location` radius (haversine)
+  - Filter by `other_preferences` tags
+  - Score only filtered subset
+- [ ] **Custom local break (max 1/user)**
+  - Fields: name, lat, lon, region, optimal_swell_direction, optimal_swell_size_range, optimal_wind_direction, skill_level_suitability, notes
+  - Validate coords against Open-Meteo grid
+  - Merge into user's break list for ranking; persist in profile
+  - UI: Gradio form (modal/sidebar) with "Add my local break"
+
+### Infrastructure & Polish
+
+- [ ] Persist user profiles (SQLite or HF dataset) — survive restarts
+- [ ] Auth (email/token or HF OAuth) for multi-user Space
+- [ ] Migrate `data/break_details.json` → proper DB for concurrent writes
+- [ ] Add tide data source (stretch: WillyWeather integration)
+
+### API + UI
+
+- [x] `api.py`: FastAPI endpoints (`/spots`, `/forecast`, `/score`, `/ask`)
+- [x] `app.py`: Gradio UI — Australia map home page, chat, interactive seaborn-styled charts, agent trace panel, HF/NIM toggle
+- [ ] 📹 Capture: polished Demo Q1 + OpenAPI docs screen
+
+### daggr + Deploy
+
+- [x] `daggr_pipeline.py`: "Morning Surf Report" DAG (find_spots → fetch forecasts → score → rank → InferenceNode narrates); embeds in the UI via iframe
+- [ ] Deploy to HF Space (secrets: `HF_TOKEN`, `NVIDIA_API_KEY`); test public URL end-to-end
+- [ ] Publish `data/break_details.json` as HF dataset; README architecture diagram; license
+- [ ] 📹 Capture: daggr canvas walkthrough; Space on phone
+- [ ] Stretch: live surf-cam snapshots tool for famous breaks
+
+### Rehearse + Record
+
+- [ ] Run evals against live Space; fix breaks
+- [ ] Full rehearsal → record main video
+- [ ] Draft LinkedIn post
+
+### Launch
+
+- [ ] Edit + publish video; post to LinkedIn (contest + Berlin announcement); submit entry
+- [ ] Sep 8–10 buffer for retakes / judge replies
 
 ---
 
-## Risks & fallbacks
+## Video Script (~2 min)
 
-| Risk | Mitigation |
-| --- | --- |
-| Daggr beta misbehaves (no conditional branching; pin the version) | The agent trace panel is the reasoning demo; swap video shot 5 for a trace walkthrough. |
-| Open-Meteo coastal grid points sit offshore | Fetch slightly seaward coords; validate Tue against known break behavior. |
-| Demo-day API flakiness / rate limits | Disk-cached forecasts; daily milestone clips mean a retake never rebuilds the week. |
-| Tool-loop unreliability | Small tool set, strict structured outputs, `golden_questions.json` gates recording. |
-| Model availability on either router | Client is provider-agnostic; same model on HF and NIM; fallback model must support tool calling + `json_schema` (see `data/GENERATION.md`). |
+1. **Hook (0:00–0:10)** — "I moved to Berlin — 16,000 km from surf. Built an agent to find waves back home."
+2. **Problem (0:10–0:25)** — Local knowledge: which winds suit which break. Show `break_details.json` + raw forecast.
+3. **Demo Q1 (0:25–0:55)** — "Where should I surf near Byron Bay this weekend? Intermediate longboarder." → ranked cards + trace panel.
+4. **Demo Q2 (0:55–1:15)** — "What time should I surf Snapper Rocks tomorrow?" → interactive hourly chart + best-window reasoning.
+5. **Reasoning canvas (1:15–1:35)** — daggr Morning Surf Report: click through node outputs live.
+6. **Under the hood (1:35–1:50)** — FastAPI OpenAPI docs; HF ↔ NIM toggle; break knowledge base as HF dataset.
+7. **CTA (1:50–2:10)** — Open models (Qwen via HF + NVIDIA NIM). Free GTC Berlin ticket 🤞 #NVIDIAGTC. New in Berlin — DMs open for ML work.
+
+---
+
+## Risks & Fallbacks
+
+| Risk                                             | Mitigation                                                                                           |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| Daggr beta misbehaves (no conditional branching) | Agent trace panel = reasoning demo; swap canvas shot for trace walkthrough                           |
+| Open-Meteo grid points sit offshore              | Fetch slightly seaward coords; validate against known break behavior                                 |
+| Demo-day API flakiness / rate limits             | Disk-cached forecasts; daily milestone clips = no rebuild needed for retakes                         |
+| Tool-loop unreliability                          | Small tool set, strict structured outputs, `golden_questions.json` gates recording                   |
+| Model availability on either router              | Provider-agnostic client; same model on HF + NIM; fallback must support tool calling + `json_schema` |

docs/ARCHITECTURE.md

@@ -0,0 +1,117 @@
+# Architecture
+
+How wavereader turns a natural-language question into a grounded surf
+recommendation. The one-sentence version: **the LLM orchestrates, code owns
+the numbers.**
+
+```
+question ──▶ SurfAgent (smolagents CodeAgent, Qwen3-Next-80B)
+                │  writes python code that calls tools
+                ▼
+             tools.py ──▶ spots.py (knowledge base)
+                │        forecasts.py (Open-Meteo + disk cache)
+                │        scoring.py (deterministic 0–10 score)
+                ▼
+        streaming answer + AgentTrace ──▶ Gradio UI (trace panel + auto-charts)
+```
+
+## Modules
+
+| Module | Role | Key facts |
+|---|---|---|
+| `spots.py` | Loads + validates `data/breaks.json` / `break_details.json`; search | Records keyed by `(name, region)`; coords validated against per-state bounding boxes; 6 regions (NSW, QLD, VIC, WA, SA, TAS) |
+| `forecasts.py` | Open-Meteo Marine + weather client | Hourly, 7-day horizon; merges two endpoints on `time`; disk cache with stale fallback (below) |
+| `scoring.py` | Deterministic surf-quality score | Pure functions, no I/O; per-hour 0–10 score + component breakdown (below) |
+| `agent.py` | smolagents CodeAgent wrapper | `SurfAgent`, provider switching, streaming, `AgentTrace`; `max_steps=10` |
+| `tools.py` | Agent tools + matplotlib plot builders | 5 core tools; plain functions resolve spot by `(name, region)` then delegate |
+| `api.py` | FastAPI backend | `/spots`, `/forecast`, `/score`, `/ask` — see [API.md](API.md) |
+| `app.py` | Gradio UI | Map-first layout, streaming chat, trace panel, auto-charts — see [UI_GUIDE.md](UI_GUIDE.md) |
+| `daggr_pipeline.py` | Fixed Morning Surf Report DAG | Visualises the deterministic pipeline only, **never** the dynamic chat loop (daggr beta has no conditional branching) |
+
+## The model boundary
+
+`SYSTEM_PROMPT` in `agent.py` enforces the product's core rule: the agent
+never computes a number. It writes code that calls tools, reads the results,
+and explains them. Everything numeric comes from:
+
+- **Forecasts** — Open-Meteo responses, normalised to hourly rows
+  (`time`, `wave_height`, `wave_period`, `wave_direction`, `wind_speed_10m`,
+  `wind_direction_10m`).
+- **Scores** — `scoring.score_hour()`, weighted:
+  swell_size 0.30 · swell_direction 0.20 · wind 0.30 · period 0.20.
+
+Component logic (all continuous curves, no cliff edges):
+
+- **Swell size** — 10 inside the spot's ideal `size_ft_min–max` window,
+  Gaussian decay outside, zero above the skill profile's `max_safe_size_ft`.
+- **Swell direction** — Gaussian on angular distance from the spot's ideal
+  direction (45° tolerance); `None` when Open-Meteo has no wave direction,
+  and its weight is redistributed across the remaining components (never
+  silently substituted with wind direction).
+- **Wind** — mean of a speed score and a direction score. Speed: glassy
+  (≤ 5 kt) is always 10, above `min(spot max, skill max)` it is 0.
+  Direction: cosine falloff from perfect offshore to absolute onshore.
+- **Period** — linear ramp, 0 at ≤ 4 s up to 10 at ≥ 14 s; long groundswell
+  is never penalised.
+
+Skill profiles (`beginner / intermediate / advanced / expert`) cap wave size,
+wind tolerance and set the comfort band. Every scored row carries its raw
+inputs back (`wave_height_m`, `wind_speed_kt`, …) so the UI and trace can
+show *why* a score is what it is.
+
+## Forecast fetching and the demo-survivability cache
+
+- Grid points sit offshore: coords are snapped **0.13° seaward** — Tasmania
+  and the south coast shift south, the east coast (lon ≥ 147) shifts east,
+  the west coast (lon ≤ 125) shifts west.
+- Responses are cached to disk at `.cache/forecasts/{lat}_{lon}_{days}.json`
+  as `{"fetched_at": ..., "data": ...}` envelopes, TTL **6 hours**.
+- On a network failure the most recent entry — however stale — is served
+  instead of raising; the app only errors when there is no data at all. This
+  is deliberate: the demo video must survive API flakiness and rate limits.
+- On UI startup a background thread warms the cache for all 100 breaks
+  (disable with `WAVEREADER_WARM_CACHE=0`).
+
+## Agent ↔ UI contract
+
+`SurfAgent.run_stream(question)` yields:
+
+- `("model", delta)` — LLM token chunks (the agent's code-as-reasoning)
+- `("tool", tool_name)` — a tool call is happening
+- `("final", answer)` — the clean final answer
+
+Every run also fills an `AgentTrace` (`trace.to_json()`), with event types
+`tool_call` / `tool_result` / `llm_chunk` / `final_answer`. The UI renders
+this JSON in the trace panel and scrapes the code steps for
+`get_forecast` / `score_week` / `get_spot_knowledge` /
+`rank_spots_this_week(...)` invocations — whichever spots the agent touched
+get interactive plotly charts rendered beneath the chat. Charts are drawn by
+the UI, never by the agent, so the model's context stays small and the
+graphics stay interactive.
+
+Note for tool-call tracing: smolagents CodeAgents emit one
+`python_interpreter` call per step whose "arguments" are the generated code
+blob — the trace panel detects real tool usage inside the blob by regex.
+
+## Provider switching
+
+Both hosts speak the OpenAI chat-completions protocol, so one client class
+(smolagents `OpenAIServerModel`) covers the switch:
+
+| Provider | Base URL | Env var |
+|---|---|---|
+| `hf` (default) | `https://router.huggingface.co/v1` | `HF_TOKEN` |
+| `nim` | `https://integrate.api.nvidia.com/v1` | `NVIDIA_API_KEY` |
+
+When both tokens are set, NIM wins auto-detection; the UI exposes an explicit
+radio switch. `Qwen/Qwen3-Next-80B-A3B-Instruct` is the only model verified
+for both OpenAI-style tool calling and strict `json_schema` on the HF router
+— read `data/GENERATION.md` before swapping models.
+
+## Testing
+
+`uv run pytest` (134 tests) covers scoring curves, cache behaviour/offsets,
+spot validation, tool wiring, the agent (mocked model), the API, the daggr
+pipeline and the UI chart builders. The agent tests mock the LLM, so the
+suite runs offline; the forecast tests mock HTTP but exercise the real cache
+code paths via `tmp_path`.

pyproject.toml

@@ -11,8 +11,12 @@ dependencies = [
     "gradio",
     "httpx",
     "huggingface-hub>=1.29.0",
+    "matplotlib>=3.11.1",
     "openai",
+    "plotly>=7.0.0",
     "pydantic",
+    "pyyaml",
+    "seaborn>=0.13.2",
     "smolagents>=1.26.0",
 ]
 

tests/test_agent.py

@@ -3,10 +3,12 @@
 from __future__ import annotations
 
 import json
-import os
 from unittest.mock import MagicMock, patch
 
 import pytest
+from smolagents.agents import ToolOutput
+from smolagents.memory import FinalAnswerStep, ToolCall as SmolToolCall
+from smolagents.models import ChatMessageStreamDelta
 
 from wavereader.agent import (
     AgentTrace,
@@ -118,9 +120,9 @@ class TestScoreWeekTool:
     def test_forward_spot_not_found(self):
         tool = ScoreWeekTool()
         with patch("wavereader.agent.score_week") as mock_score:
-            mock_score.return_value = []
+            mock_score.return_value = {"error": "Spot 'Bad' (XX) not found"}
             result = tool.forward("Bad", "XX")
-            assert result == []
+            assert "error" in result
 
 
 class TestFindSpotsTool:
@@ -253,93 +255,106 @@ class TestSurfAgentRun:
         assert agent.trace.question == "What's the surf like?"
         assert agent.trace.provider == PROVIDER_HF
 
-    def test_run_stream_yields_chunks(self, mock_build_model):
+    def test_run_stream_yields_deltas_and_final(self, mock_build_model):
+        events = [
+            ChatMessageStreamDelta(content="Hello "),
+            ChatMessageStreamDelta(content="world"),
+            FinalAnswerStep(output="Hello world"),
+        ]
         mock_agent = MagicMock()
-        mock_agent.run.return_value = iter(["chunk1", "chunk2", "chunk3"])
+        mock_agent.run.return_value = iter(events)
 
         with patch("wavereader.agent.CodeAgent", return_value=mock_agent):
             agent = SurfAgent(provider=PROVIDER_HF)
             chunks = list(agent.run_stream("Test question"))
 
-        assert chunks == ["chunk1", "chunk2", "chunk3"]
+        assert chunks == [
+            ("model", "Hello "),
+            ("model", "world"),
+            ("final", "Hello world"),
+        ]
         assert agent.trace is not None
+        final_events = [e for e in agent.trace.events if e.type == "final_answer"]
+        assert len(final_events) == 1
+        assert final_events[0].data["answer"] == "Hello world"
 
     def test_run_stream_captures_tool_calls_in_trace(self, mock_build_model):
-        """Verify trace captures tool calls during streaming."""
-        from smolagents.memory import ActionStep, ToolCall
-        from smolagents.monitoring import Timing
-
-        # Create a proper ActionStep-like object with tool_calls
-        tool_call = ToolCall(name="get_forecast", arguments={"spot_name": "Snapper", "region": "QLD"}, id="call-1")
-        memory_step_with_tool = ActionStep(
-            step_number=1,
-            timing=Timing(start_time=0, end_time=0),
-            tool_calls=[tool_call],
-            observations="forecast data",
-            is_final_answer=False,
+        """Trace captures tool calls/results flowing through _step_stream.
+
+        Mirrors real smolagents: _run_stream yields whatever _step_stream
+        yields, so tool events surface via the wrapped generator.
+        """
+        tool_call = SmolToolCall(
+            name="get_forecast",
+            arguments={"spot_name": "Snapper Rocks", "region": "QLD"},
+            id="call-1",
         )
-        memory_step_without_tool = ActionStep(
-            step_number=2,
-            timing=Timing(start_time=0, end_time=0),
-            tool_calls=[],
-            observations="",
-            is_final_answer=True,
+        tool_output = ToolOutput(
+            id="call-1",
+            output={"hourly": []},
+            is_final_answer=False,
+            observation="forecast data",
+            tool_call=tool_call,
         )
 
-        call_count = {"count": 0}
-        step_results = [memory_step_with_tool, memory_step_without_tool]
-
-        def mock_step(memory_step, *args, **kwargs):
-            result = step_results[call_count["count"]]
-            call_count["count"] += 1
-            return result
-
-        # Use a real object instead of MagicMock so step can be dynamically replaced
-        class MockAgent:
-            def __init__(self):
-                self.step = mock_step
+        class FakeAgent:
+            def _step_stream(self, memory_step):
+                yield tool_call
+                yield tool_output
 
             def run(self, question, stream=False):
-                if stream:
-                    # Call step through self.step (which will be wrapped by traced_step)
-                    self.step(memory_step_with_tool)
-                    yield "chunk 1"
-                    self.step(memory_step_without_tool)
-                    yield "chunk 2"
-                return "final answer"
-
-        mock_agent = MockAgent()
+                for output in self._step_stream(None):
+                    yield output
+                yield FinalAnswerStep(output="done")
 
-        with patch("wavereader.agent.CodeAgent", return_value=mock_agent):
+        with patch("wavereader.agent.CodeAgent", return_value=FakeAgent()):
             agent = SurfAgent(provider=PROVIDER_HF)
-            list(agent.run_stream("Test"))
+            results = list(agent.run_stream("Test"))
 
+        assert ("final", "done") in results
         trace = agent.trace
         tool_call_events = [e for e in trace.events if e.type == "tool_call"]
         tool_result_events = [e for e in trace.events if e.type == "tool_result"]
 
         assert len(tool_call_events) == 1
         assert tool_call_events[0].data["name"] == "get_forecast"
-        # observations is a string, so traced_step iterates character by character
-        # "forecast data" = 12 chars + 1 space = 13 events
-        assert len(tool_result_events) == 13
-        # First and last character events
-        assert tool_result_events[0].data["observation"] == "f"
-        assert tool_result_events[-1].data["observation"] == "a"
-
-    def test_run_stream_captures_llm_chunks(self, mock_build_model):
-        mock_agent = MagicMock()
-        mock_agent.step = MagicMock(return_value=MagicMock(tool_calls=[], observations=[]))
-        mock_agent.run.return_value = iter(["hello", " world"])
+        assert tool_call_events[0].data["arguments"] == {
+            "spot_name": "Snapper Rocks",
+            "region": "QLD",
+        }
+        assert len(tool_result_events) == 1
+        assert tool_result_events[0].data["observation"] == "forecast data"
+        assert tool_result_events[0].data["name"] == "get_forecast"
+
+    def test_run_captures_tool_calls_in_trace(self, mock_build_model):
+        """The non-streaming run() path also captures tool activity."""
+        tool_call = SmolToolCall(name="find_spots", arguments={"region": "QLD"}, id="call-2")
+        tool_output = ToolOutput(
+            id="call-2",
+            output=[],
+            is_final_answer=False,
+            observation="2 spots",
+            tool_call=tool_call,
+        )
 
-        with patch("wavereader.agent.CodeAgent", return_value=mock_agent):
+        class FakeAgent:
+            def _step_stream(self, memory_step):
+                yield tool_call
+                yield tool_output
+
+            def run(self, question, stream=False):
+                list(self._step_stream({"step": 1}))
+                return "answer"
+
+        with patch("wavereader.agent.CodeAgent", return_value=FakeAgent()):
             agent = SurfAgent(provider=PROVIDER_HF)
-            list(agent.run_stream("Test"))
+            result = agent.run("Test")
 
-        llm_events = [e for e in agent.trace.events if e.type == "llm_chunk"]
-        assert len(llm_events) == 2
-        assert llm_events[0].data["chunk"] == "hello"
-        assert llm_events[1].data["chunk"] == " world"
+        assert result == "answer"
+        tool_call_events = [e for e in agent.trace.events if e.type == "tool_call"]
+        tool_result_events = [e for e in agent.trace.events if e.type == "tool_result"]
+        assert tool_call_events[0].data["name"] == "find_spots"
+        assert tool_result_events[0].data["observation"] == "2 spots"
 
 
 # ---------------------------------------------------------------------------
@@ -357,13 +372,17 @@ def test_run_agent_function(mock_build_model):
 
 
 def test_run_agent_stream_function(mock_build_model):
+    events = [
+        ChatMessageStreamDelta(content="stream"),
+        FinalAnswerStep(output="streaming done"),
+    ]
     mock_agent = MagicMock()
-    mock_agent.run.return_value = iter(["stream", "ing"])
+    mock_agent.run.return_value = iter(events)
 
     with patch("wavereader.agent.CodeAgent", return_value=mock_agent):
         result = list(run_agent_stream("Test question", provider=PROVIDER_HF))
 
-    assert result == ["stream", "ing"]
+    assert result == [("model", "stream"), ("final", "streaming done")]
 
 
 # ---------------------------------------------------------------------------

tests/test_api.py

@@ -0,0 +1,109 @@
+"""Unit tests for wavereader.api — FastAPI endpoints."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+from fastapi.testclient import TestClient
+
+from wavereader.api import app
+
+client = TestClient(app)
+
+
+def test_root():
+    resp = client.get("/")
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["name"] == "wavereader"
+    assert data["status"] == "ok"
+
+
+def test_list_spots():
+    resp = client.get("/spots?limit=3")
+    assert resp.status_code == 200
+    spots = resp.json()
+    assert len(spots) <= 3
+    assert all("name" in s for s in spots)
+
+
+def test_list_spots_by_region():
+    resp = client.get("/spots?region=QLD&limit=5")
+    assert resp.status_code == 200
+    spots = resp.json()
+    assert all(s["region"] == "QLD" for s in spots)
+
+
+def test_get_spot():
+    resp = client.get("/spots/Snapper Rocks?region=QLD")
+    assert resp.status_code == 200
+    spot = resp.json()
+    assert spot["name"] == "Snapper Rocks"
+    assert spot["region"] == "QLD"
+
+
+def test_get_spot_not_found():
+    resp = client.get("/spots/Nonexistent?region=XX")
+    assert resp.status_code == 404
+
+
+def _fake_forecast(lat: float, lon: float, days: int = 7) -> dict:
+    """Offline stand-in for Open-Meteo so tests never hit the network."""
+    return {
+        "hourly": [
+            {
+                "time": f"2024-01-01T{h:02d}:00",
+                "wave_height": 1.5,
+                "wave_period": 10,
+                "wave_direction": 135,
+                "wind_speed_10m": 10,
+                "wind_direction_10m": 135,
+            }
+            for h in range(24)
+        ]
+    }
+
+
+def test_forecast():
+    with patch("wavereader.forecasts.get_forecast", side_effect=_fake_forecast):
+        resp = client.get("/forecast?spot=Snapper Rocks&region=QLD&days=2")
+    assert resp.status_code == 200
+    data = resp.json()
+    assert "hourly" in data
+    assert len(data["hourly"]) > 0
+
+
+def test_forecast_spot_not_found():
+    resp = client.get("/forecast?spot=Nonexistent&region=XX")
+    assert resp.status_code == 404
+
+
+def test_score():
+    with patch("wavereader.forecasts.get_forecast", side_effect=_fake_forecast):
+        resp = client.get("/score?spot=Snapper Rocks&region=QLD&days=2")
+    assert resp.status_code == 200
+    data = resp.json()
+    assert isinstance(data, list)
+    assert len(data) > 0
+    assert "score" in data[0]
+    assert "components" in data[0]
+    assert "time" in data[0]
+
+
+def test_score_spot_not_found():
+    resp = client.get("/score?spot=Nonexistent&region=XX")
+    assert resp.status_code == 404
+
+
+def test_ask_missing_config_returns_503():
+    with patch("wavereader.api.SurfAgent", side_effect=ValueError("HF_TOKEN environment variable not set")):
+        resp = client.post("/ask", json={"question": "How's Snapper?"})
+    assert resp.status_code == 503
+    assert "HF_TOKEN" in resp.json()["detail"]
+
+
+def test_ask_agent_failure_returns_502():
+    with patch("wavereader.api.SurfAgent", side_effect=RuntimeError("boom")):
+        resp = client.post("/ask", json={"question": "How's Snapper?"})
+    assert resp.status_code == 502

tests/test_app.py

@@ -0,0 +1,117 @@
+"""Unit tests for wavereader.app — Gradio UI chart functions and helpers."""
+
+from __future__ import annotations
+
+import json
+
+from wavereader.app import (
+    create_australia_map,
+    create_seaborn_template,
+    create_wave_height_chart,
+    create_score_chart,
+    create_ranking_chart,
+    update_trace_panel,
+    build_ui,
+)
+
+
+def test_australia_map_creates_figure():
+    fig = create_australia_map()
+    assert fig is not None
+    assert len(fig.data) >= 1
+
+
+def test_seaborn_template_has_keys():
+    t = create_seaborn_template()
+    assert "layout" in t
+    assert "font" in t["layout"]
+    assert "paper_bgcolor" in t["layout"]
+
+
+def test_wave_height_chart_empty():
+    fig = create_wave_height_chart({}, "Spot")
+    assert fig is not None
+
+
+def test_wave_height_chart_with_data():
+    forecast = {
+        "hourly": [
+            {
+                "time": f"2024-01-01T{i:02d}:00",
+                "wave_height": 1.5,
+                "wave_period": 10,
+                "wind_speed_10m": 15,
+                "wind_direction_10m": 135,
+            }
+            for i in range(24)
+        ]
+    }
+    fig = create_wave_height_chart(forecast, "Snapper Rocks")
+    assert len(fig.data) == 3  # wave height, period, wind
+
+
+def test_score_chart_empty():
+    fig = create_score_chart([], "Spot")
+    assert fig is not None
+
+
+def test_score_chart_with_data():
+    scores = [
+        {
+            "time": f"2024-01-01T{i:02d}:00",
+            "score": 7.5,
+            "components": {
+                "swell_size": 8.0,
+                "swell_direction": 7.0,
+                "wind": 7.5,
+                "period": 7.5,
+            },
+        }
+        for i in range(24)
+    ]
+    fig = create_score_chart(scores, "Snapper Rocks")
+    assert len(fig.data) == 5  # total + 4 components
+
+
+def test_ranking_chart_empty():
+    fig = create_ranking_chart([], "NSW")
+    assert fig is not None
+
+
+def test_ranking_chart_with_data():
+    ranked = [
+        {"name": "A", "region": "NSW", "best_score": 8.5, "best_time": "2024-01-01T12:00"},
+        {"name": "B", "region": "NSW", "best_score": 6.0, "best_time": "2024-01-01T08:00"},
+    ]
+    fig = create_ranking_chart(ranked, "NSW")
+    assert len(fig.data) >= 1
+
+
+def test_update_trace_panel_empty():
+    result = update_trace_panel("")
+    assert "No trace yet" in result
+
+
+def test_update_trace_panel_with_data():
+    trace = {
+        "question": "Best spot?",
+        "model": "Qwen",
+        "provider": "hf",
+        "events": [
+            {"type": "tool_call", "data": {"name": "score_week", "arguments": {"spot_name": "A"}}},
+            {"type": "tool_result", "data": {"observation": "[{score: 8.5}]"}},
+        ],
+    }
+    result = update_trace_panel(json.dumps(trace))
+    assert "Best spot?" in result
+    assert "score_week" in result
+
+
+def test_update_trace_panel_invalid_json():
+    result = update_trace_panel("not json")
+    assert result == "not json"
+
+
+def test_build_ui_creates_blocks():
+    demo = build_ui()
+    assert demo is not None

tests/test_daggr.py

@@ -0,0 +1,145 @@
+"""Unit tests for wavereader.daggr_pipeline — Morning Surf Report DAG."""
+
+from __future__ import annotations
+
+from wavereader.daggr_pipeline import (
+    build_pipeline,
+    find_spots_fn,
+    fetch_forecasts_fn,
+    score_forecasts_fn,
+    rank_spots_fn,
+    format_report_fn,
+    _narration_preprocess,
+    _narration_postprocess,
+)
+
+
+def test_find_spots_fn():
+    result = find_spots_fn("QLD", skill=None)
+    assert "spots" in result
+    assert "region" in result
+    assert result["region"] == "QLD"
+    assert len(result["spots"]) > 0
+
+
+def test_find_spots_fn_all_sentinel_means_no_filter():
+    """The UI's "all" skill sentinel must not be passed to the substring match."""
+    unfiltered = find_spots_fn("QLD", skill=None)
+    all_sentinel = find_spots_fn("QLD", skill="all")
+    assert len(all_sentinel["spots"]) == len(unfiltered["spots"]) > 0
+    assert all_sentinel["skill"] is None
+
+
+def test_find_spots_fn_with_skill():
+    result = find_spots_fn("QLD", skill="beginner")
+    assert "spots" in result
+    for spot in result["spots"]:
+        assert "beginner" in spot["additional_details"]["skill_level"].lower()
+
+
+def test_pipeline_string_keys_end_to_end(tmp_path, monkeypatch):
+    """fetch → score → rank works with "{name}|{region}" string keys."""
+    from wavereader import forecasts as forecasts_mod
+
+    fake = {
+        "hourly": [
+            {
+                "time": "2024-01-01T06:00",
+                "wave_height": 1.5,
+                "wave_period": 12,
+                "wave_direction": 135,
+                "wind_speed_10m": 8,
+                "wind_direction_10m": 180,
+            }
+        ]
+    }
+    monkeypatch.setattr(forecasts_mod, "get_forecast", lambda lat, lng, days=7: fake)
+
+    spots_found = find_spots_fn("QLD")["spots"][:3]
+    fetched = fetch_forecasts_fn(spots_found)
+    assert fetched["forecasts"]
+    for key in fetched["forecasts"]:
+        assert isinstance(key, str) and "|" in key
+
+    scored = score_forecasts_fn(fetched["forecasts"], spots_found)
+    assert set(scored["scored"]) == set(fetched["forecasts"])
+
+    ranked = rank_spots_fn(scored["scored"], spots_found)
+    assert len(ranked["ranked"]) == len(spots_found)
+    assert ranked["ranked"][0]["best_score"] >= 0
+
+
+def test_narration_preprocess_flat_prompt():
+    inputs = {
+        "ranked": [{"name": "A", "region": "QLD", "best_score": 8.0}],
+        "region": "QLD",
+    }
+    result = _narration_preprocess(inputs)
+    # daggr's text-generation path sends the first value as a plain prompt
+    assert list(result.keys())[0] == "prompt"
+    assert isinstance(result["prompt"], str)
+    assert "QLD" in result["prompt"]
+
+
+def test_narration_postprocess_handles_shapes():
+    assert _narration_postprocess("plain text") == {"ai_report": "plain text"}
+    assert _narration_postprocess([{"generated_text": "gen"}]) == {"ai_report": "gen"}
+    assert _narration_postprocess(42) == {"ai_report": "42"}
+
+
+def test_format_report_fn_empty():
+    result = format_report_fn([], "NSW")
+    assert "report" in result
+    assert "No spots" in result["report"]
+
+
+def test_format_report_fn_with_data():
+    ranked = [
+        {
+            "name": "Test Spot",
+            "region": "QLD",
+            "best_score": 8.5,
+            "best_time": "2024-01-01T12:00",
+            "best_hour": {
+                "time": "2024-01-01T12:00",
+                "score": 8.5,
+                "components": {"swell_size": 9.0, "swell_direction": 8.0, "wind": 8.5, "period": 8.5},
+            },
+        }
+    ]
+    result = format_report_fn(ranked, "QLD")
+    assert "report" in result
+    assert "Test Spot" in result["report"]
+    assert "8.5" in result["report"]
+
+
+def test_format_report_fn_missing_direction_shows_na():
+    ranked = [
+        {
+            "name": "Test Spot",
+            "region": "QLD",
+            "best_score": 8.5,
+            "best_time": "2024-01-01T12:00",
+            "best_hour": {
+                "time": "2024-01-01T12:00",
+                "score": 8.5,
+                "components": {"swell_size": 9.0, "swell_direction": None, "wind": 8.5, "period": 8.5},
+            },
+        }
+    ]
+    result = format_report_fn(ranked, "QLD")
+    assert "n/a" in result["report"]
+
+
+def test_build_pipeline():
+    graph = build_pipeline()
+    assert graph is not None
+    entry = graph.get_entry_nodes()
+    assert len(entry) == 1
+    assert entry[0].name == "User Input"
+    outputs = graph.get_output_nodes()
+    assert "Narrate Report" in outputs
+    assert "Format Report" in outputs
+    order = graph.get_execution_order()
+    assert order[0] == "User Input"
+    assert order[-1] in ("Narrate Report", "Format Report")

tests/test_forecasts.py

@@ -0,0 +1,190 @@
+"""Unit tests for wavereader.forecasts — cache, offsets, merge, fallbacks."""
+
+from __future__ import annotations
+
+import json
+import time
+from unittest.mock import patch
+
+import httpx
+import pytest
+
+from wavereader import forecasts
+
+
+# ---------------------------------------------------------------------------
+# Seaward offsets
+# ---------------------------------------------------------------------------
+
+def test_offset_east_coast_moves_east():
+    # Snapper Rocks (QLD): seaward is east, not the old fixed south-east
+    rlat, rlon = forecasts._round_coords(-28.173, 153.556)
+    assert rlon > 153.556
+    assert rlat == pytest.approx(-28.173, abs=0.01)
+
+
+def test_offset_west_coast_moves_west():
+    # Margaret River region (WA): seaward is west
+    rlat, rlon = forecasts._round_coords(-33.95, 115.0)
+    assert rlon < 115.0
+    assert rlat == pytest.approx(-33.95, abs=0.01)
+
+
+def test_offset_south_coast_moves_south():
+    # Bells Beach (VIC): seaward is south
+    rlat, rlon = forecasts._round_coords(-38.37, 144.25)
+    assert rlat < -38.37
+    assert rlon == pytest.approx(144.25, abs=0.01)
+
+
+def test_offset_tasmania_moves_south():
+    rlat, _ = forecasts._round_coords(-41.0, 145.0)
+    assert rlat < -41.0
+
+
+# ---------------------------------------------------------------------------
+# Cache behaviour
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def cache_env(tmp_path, monkeypatch):
+    """Point the cache at a temp dir and freeze time deterministically."""
+    monkeypatch.setattr(forecasts, "CACHE_DIR", tmp_path)
+    return tmp_path
+
+
+def test_cache_roundtrip_and_ttl(cache_env):
+    now = time.time()
+    with patch.object(forecasts, "_fetch_open_meteo", return_value={"hourly": [{"time": "t"}]}) as fetch:
+        first = forecasts.get_forecast(-28.0, 153.0, days=2)
+        assert fetch.call_count == 1
+        assert first["hourly"][0]["time"] == "t"
+
+        # Envelope has a timestamp
+        raw = json.loads(next(cache_env.glob("*.json")).read_text())
+        assert raw["fetched_at"] == pytest.approx(now, abs=30)
+
+        # Fresh cache: served without a second network call
+        forecasts.get_forecast(-28.0, 153.0, days=2)
+        assert fetch.call_count == 1
+
+
+def test_stale_cache_is_refetched(cache_env):
+    with patch.object(forecasts, "_fetch_open_meteo", side_effect=[{"hourly": [{"v": 1}]}, {"hourly": [{"v": 2}]}]):
+        forecasts.get_forecast(-28.0, 153.0, days=2)
+
+    # Age the cache entry beyond the TTL
+    p = next(cache_env.glob("*.json"))
+    raw = json.loads(p.read_text())
+    raw["fetched_at"] = time.time() - forecasts.CACHE_TTL_SECONDS - 1
+    p.write_text(json.dumps(raw))
+
+    with patch.object(forecasts, "_fetch_open_meteo", return_value={"hourly": [{"v": 3}]}) as fetch:
+        refreshed = forecasts.get_forecast(-28.0, 153.0, days=2)
+    assert fetch.call_count == 1
+    assert refreshed["hourly"][0]["v"] == 3
+
+
+def test_http_failure_falls_back_to_stale_cache(cache_env):
+    with patch.object(forecasts, "_fetch_open_meteo", return_value={"hourly": [{"v": 1}]}):
+        forecasts.get_forecast(-28.0, 153.0, days=2)
+
+    # Age it, then make the network fail
+    p = next(cache_env.glob("*.json"))
+    raw = json.loads(p.read_text())
+    raw["fetched_at"] = 0.0
+    p.write_text(json.dumps(raw))
+
+    def boom(*args, **kwargs):
+        raise httpx.ConnectError("network down")
+
+    with patch.object(forecasts, "_fetch_open_meteo", side_effect=boom):
+        served = forecasts.get_forecast(-28.0, 153.0, days=2)
+    assert served["hourly"][0]["v"] == 1
+
+
+def test_http_failure_no_cache_raises(cache_env):
+    def boom(*args, **kwargs):
+        raise httpx.ConnectError("network down")
+
+    with patch.object(forecasts, "_fetch_open_meteo", side_effect=boom):
+        with pytest.raises(httpx.ConnectError):
+            forecasts.get_forecast(-28.0, 153.0, days=2)
+
+
+def test_corrupt_cache_is_ignored(cache_env):
+    cache_env.joinpath("-28.00_153.00_2.json").write_text("{not json")
+    with patch.object(forecasts, "_fetch_open_meteo", return_value={"hourly": []}) as fetch:
+        forecasts.get_forecast(-28.0, 153.0, days=2)
+    assert fetch.call_count == 1
+
+
+def test_legacy_cache_format_still_loads(cache_env):
+    # Pre-envelope files (plain frame) are accepted and treated as stale;
+    # served when the network fails.
+    cache_env.joinpath("-28.00_153.00_2.json").write_text(json.dumps({"hourly": [{"legacy": True}]}))
+
+    def boom(*args, **kwargs):
+        raise httpx.ConnectError("network down")
+
+    with patch.object(forecasts, "_fetch_open_meteo", side_effect=boom):
+        served = forecasts.get_forecast(-28.0, 153.0, days=2)
+    assert served["hourly"][0]["legacy"] is True
+
+
+def test_cache_key_includes_days(cache_env):
+    with patch.object(forecasts, "_fetch_open_meteo", return_value={"hourly": []}):
+        forecasts.get_forecast(-28.0, 153.0, days=2)
+        forecasts.get_forecast(-28.0, 153.0, days=7)
+    keys = {p.name for p in cache_env.glob("*.json")}
+    assert len(keys) == 2
+
+
+# ---------------------------------------------------------------------------
+# _build_normalized
+# ---------------------------------------------------------------------------
+
+def _marine_payload(times, heights):
+    return {"hourly": {
+        "time": times,
+        "wave_height": heights,
+        "wave_period": [10.0] * len(times),
+        "wave_direction": [135.0] * len(times),
+        "wind_wave_height": [0.5] * len(times),
+        "swell_wave_height": [1.0] * len(times),
+    }}
+
+
+def _weather_payload(times):
+    return {"hourly": {
+        "time": times,
+        "wind_speed_10m": [18.5] * len(times),
+        "wind_direction_10m": [180.0] * len(times),
+    }}
+
+
+def test_build_normalized_merges_on_time():
+    times = ["2024-01-01T00:00", "2024-01-01T01:00"]
+    merged = forecasts._build_normalized(_marine_payload(times, [1.2, 1.4]), _weather_payload(times))
+    rows = merged["hourly"]
+    assert len(rows) == 2
+    assert rows[0]["wave_height"] == 1.2
+    assert rows[0]["wind_speed_10m"] == 18.5
+    assert rows[1]["wave_period"] == 10.0
+
+
+def test_build_normalized_missing_weather_hour():
+    marine_times = ["2024-01-01T00:00", "2024-01-01T01:00"]
+    weather_times = ["2024-01-01T00:00"]  # weather ends an hour early
+    merged = forecasts._build_normalized(
+        _marine_payload(marine_times, [1.2, 1.4]), _weather_payload(weather_times)
+    )
+    rows = merged["hourly"]
+    assert "wind_speed_10m" in rows[0]
+    assert "wind_speed_10m" not in rows[1]
+
+
+def test_build_normalized_keeps_nulls():
+    times = ["2024-01-01T00:00", "2024-01-01T01:00"]
+    merged = forecasts._build_normalized(_marine_payload(times, [1.2, None]), _weather_payload(times))
+    assert merged["hourly"][1]["wave_height"] is None

tests/test_scoring.py

@@ -83,8 +83,8 @@ def test_swell_size_outside_low():
         "ideal_swell": {"size_ft_min": 4, "size_ft_max": 5, "direction": "SE"},
         "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
     }
-    # just below the extended cutoff (~0.92 m)
-    s = score_hour(0.8, 10, 5, 135, spot)["components"]["swell_size"]
+    # inside the decay band below the ideal range (~0.91-1.22 m)
+    s = score_hour(1.0, 10, 5, 135, spot)["components"]["swell_size"]
     assert s < 10.0 and s > 0.0
 
 
@@ -93,16 +93,24 @@ def test_swell_size_outside_high():
         "ideal_swell": {"size_ft_min": 4, "size_ft_max": 5, "direction": "SE"},
         "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
     }
-    # just above the extended cutoff (~1.82 m)
-    s = score_hour(1.8, 10, 5, 135, spot)["components"]["swell_size"]
+    # inside the decay band above the ideal range (~1.52-1.83 m)
+    s = score_hour(1.7, 10, 5, 135, spot)["components"]["swell_size"]
     assert s < 10.0 and s > 0.0
 
 
-def test_swell_size_far_outside_zero():
+def test_swell_size_decay_is_continuous():
+    """Score falls smoothly through the lower edge of the ideal range."""
     spot = {
         "ideal_swell": {"size_ft_min": 4, "size_ft_max": 5, "direction": "SE"},
         "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
     }
+    inside = score_hour(1.3, 10, 5, 135, spot)["components"]["swell_size"]
+    edge = score_hour(1.21, 10, 5, 135, spot)["components"]["swell_size"]
+    below = score_hour(1.1, 10, 5, 135, spot)["components"]["swell_size"]
+    assert inside == 10.0
+    assert edge <= 10.0
+    assert 0.0 < below < edge
+    # far outside the decay band → 0
     assert score_hour(3.0, 10, 5, 135, spot)["components"]["swell_size"] == 0.0
 
 
@@ -116,7 +124,8 @@ def test_swell_direction_perfect_match():
         "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
     }
     # SE = 135°
-    assert score_hour(1.5, 10, 5, 135, spot)["components"]["swell_direction"] == 10.0
+    result = score_hour(1.5, 10, 5, 135, spot, wave_direction_deg=135)
+    assert result["components"]["swell_direction"] == 10.0
 
 
 def test_swell_direction_opposite():
@@ -125,7 +134,8 @@ def test_swell_direction_opposite():
         "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
     }
     # SE (135) vs NW (315) → 180° diff → 0
-    assert score_hour(1.5, 10, 5, 315, spot)["components"]["swell_direction"] == 0.0
+    result = score_hour(1.5, 10, 5, 315, spot, wave_direction_deg=315)
+    assert result["components"]["swell_direction"] == 0.0
 
 
 # ---------------------------------------------------------------------------
@@ -175,8 +185,9 @@ def test_period_great():
 
 
 def test_period_too_long():
-    # Very long periods (storm swells) still score high but not perfect
+    # 14 s+ is a perfect 10 (no falloff for very long periods)
     assert _score_period(14.0) == 10.0
+    assert _score_period(20.0) == 10.0
     assert _score_period(8.0) > _score_period(5.0)
 
 
@@ -193,7 +204,26 @@ def test_score_hour_shape():
     }
     assert 0 <= result["score"] <= 10
     for v in result["components"].values():
-        assert 0 <= v <= 10
+        assert v is None or 0 <= v <= 10
+
+
+def test_score_hour_missing_wave_direction():
+    """Unknown swell direction → component None, weight redistributed, no wind substitution."""
+    result = score_hour(1.5, 10, 5, 135, _SPOT, wave_direction_deg=None)
+    assert result["components"]["swell_direction"] is None
+    assert result["wave_direction_deg"] is None
+    # Direction was NOT silently replaced with wind direction (135 ≠ 0 → not perfect)
+    assert result["components"]["swell_direction"] != 10.0
+    assert 0 <= result["score"] <= 10
+    # With redistributed weights the remaining components still dominate
+    assert result["score"] > 0
+
+
+def test_score_hour_missing_direction_differs_from_wind_substitution():
+    """Score without swell direction must differ from one scoring wind as swell."""
+    with_dir = score_hour(1.5, 10, 5, 135, _SPOT, wave_direction_deg=0)
+    without_dir = score_hour(1.5, 10, 5, 135, _SPOT, wave_direction_deg=None)
+    assert without_dir["score"] != with_dir["score"]
 
 
 def test_score_hour_contains_raw_inputs():
@@ -276,6 +306,43 @@ def test_score_week_has_time_and_score():
     assert "score" in results[0]
 
 
+def test_score_week_skips_null_hours():
+    """Open-Meteo returns null marine hours beyond the horizon — skip, don't crash."""
+    forecast = {
+        "hourly": [
+            {
+                "time": "2024-01-01T00:00",
+                "wave_height": 1.5,
+                "wave_period": 10,
+                "wind_speed_10m": 10,
+                "wind_direction_10m": 135,
+                "wave_direction": 130,
+            },
+            {
+                "time": "2024-01-01T01:00",
+                "wave_height": None,
+                "wave_period": None,
+                "wind_speed_10m": 10,
+                "wind_direction_10m": 135,
+                "wave_direction": None,
+            },
+        ]
+    }
+    results = score_week(forecast, _SPOT)
+    assert len(results) == 1
+    assert results[0]["time"] == "2024-01-01T00:00"
+
+
+def test_score_week_all_null_returns_empty():
+    forecast = {
+        "hourly": [
+            {"time": "2024-01-01T00:00", "wave_height": None, "wave_period": None,
+             "wind_speed_10m": None, "wind_direction_10m": None}
+        ]
+    }
+    assert score_week(forecast, _SPOT) == []
+
+
 # ---------------------------------------------------------------------------
 # rank_spots_this_week
 # ---------------------------------------------------------------------------

tests/test_tools.py

@@ -0,0 +1,82 @@
+"""Direct wiring tests for wavereader.tools — with forecasts mocked, spots real."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from wavereader import tools
+
+
+def _fake_forecast(lat, lng, days=7):
+    return {
+        "hourly": [
+            {
+                "time": f"2024-01-01T{h:02d}:00",
+                "wave_height": 1.5,
+                "wave_period": 11,
+                "wave_direction": 135,
+                "wind_speed_10m": 9,
+                "wind_direction_10m": 180,
+            }
+            for h in range(6)
+        ]
+    }
+
+
+def test_get_forecast_known_spot():
+    with patch("wavereader.forecasts.get_forecast", side_effect=_fake_forecast) as mock_fc:
+        result = tools.get_forecast("Snapper Rocks", "QLD")
+    assert "hourly" in result
+    mock_fc.assert_called_once()
+
+
+def test_get_forecast_unknown_spot():
+    result = tools.get_forecast("Nowhere", "XX")
+    assert "error" in result
+
+
+def test_score_week_known_spot():
+    with patch("wavereader.forecasts.get_forecast", side_effect=_fake_forecast):
+        result = tools.score_week("Snapper Rocks", "QLD")
+    assert isinstance(result, list)
+    assert len(result) == 6
+    assert "score" in result[0]
+
+
+def test_score_week_unknown_spot_returns_error_dict():
+    """Bad spot name must be distinguishable from no scoreable hours."""
+    result = tools.score_week("Nowhere", "XX")
+    assert isinstance(result, dict)
+    assert "error" in result
+
+
+def test_find_spots_by_query():
+    results = tools.find_spots(query="Snapper")
+    assert any(r["name"] == "Snapper Rocks" for r in results)
+
+
+def test_find_spots_by_skill():
+    results = tools.find_spots(query="Bells", skill="advanced")
+    for r in results:
+        assert "advanced" in r["additional_details"]["skill_level"].lower()
+
+
+def test_get_spot_knowledge():
+    result = tools.get_spot_knowledge("Bells Beach", "VIC")
+    assert result["name"] == "Bells Beach"
+    assert "ideal_swell" in result
+
+
+def test_get_spot_knowledge_unknown():
+    assert "error" in tools.get_spot_knowledge("Nowhere", "XX")
+
+
+def test_rank_spots_this_week_ranks_descending():
+    with patch("wavereader.forecasts.get_forecast", side_effect=_fake_forecast):
+        ranked = tools.rank_spots_this_week("TAS", skill=None)
+    assert ranked, "expected at least one TAS break"
+    scores = [r["best_score"] for r in ranked]
+    assert scores == sorted(scores, reverse=True)
+    for r in ranked:
+        assert r["region"] == "TAS"
+        assert r["best_time"]

wavereader/agent.py

@@ -8,23 +8,26 @@ OpenAI-style tool calling and strict ``json_schema`` on the HF router — see
 ``data/GENERATION.md`` before swapping models).
 
 The agent interprets and explains only; all numbers come from scoring.py /
-forecasts.py via the tools in tools.py. Streaming + trace capture for the UI
-trace panel.
+forecasts.py via the tools in tools.py. Streaming + trace capture feed the UI
+trace panel; the UI renders charts itself from the trace (the agent never
+needs to plot).
 """
 
 from __future__ import annotations
 
+import importlib.resources
 import json
 import os
-from contextlib import contextmanager
+import time
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Generator
 
-from smolagents import CodeAgent, InferenceClientModel, PromptTemplates, Tool, tool
 import yaml
-import importlib.resources
+from smolagents import CodeAgent, InferenceClientModel, OpenAIServerModel, PromptTemplates, Tool
+from smolagents.agents import ToolOutput
+from smolagents.memory import FinalAnswerStep, ToolCall as SmolToolCall
+from smolagents.models import ChatMessageStreamDelta
 
-from wavereader import forecasts, scoring, spots
 from wavereader.tools import (
     find_spots,
     get_forecast,
@@ -40,10 +43,20 @@ IMPORTANT RULES:
 2. You interpret and explain the data returned by tools. You do not invent wave heights, wind speeds, or surf scores.
 3. Tide information is qualitative only (from the knowledge base). Open-Meteo does not provide tides — never promise tide curves.
 4. When the user asks about a specific spot, use get_spot_knowledge first to understand its ideal conditions.
-5. For forecasts and scores, use get_forecast and score_week. For rankings, use rank_spots_this_week.
-6. For finding spots by region/skill, use find_spots.
-7. Always cite the data source (tool name) when giving numbers.
-8. Be concise and practical — surfers want actionable recommendations.
+5. Always cite the data source (tool name) when giving numbers.
+6. Be concise and practical — surfers want actionable recommendations.
+7. The UI renders charts automatically whenever you surface forecast or score data — never describe plots or say you cannot show them.
+
+CALL TOOLS EXACTLY LIKE THIS (keyword spellings matter):
+- find_spots(query="QLD", skill="beginner")  # query = spot name OR state code: NSW, QLD, VIC, WA, SA, TAS
+- get_spot_knowledge(spot_name="Snapper Rocks", region="QLD")
+- get_forecast(spot_name="Snapper Rocks", region="QLD")
+- score_week(spot_name="Snapper Rocks", region="QLD")  # ONE spot per call
+- rank_spots_this_week(region="QLD", skill="beginner")  # use this to COMPARE many spots in a state
+
+Workflow: to answer "where should I surf in <state>", call rank_spots_this_week first,
+then get_spot_knowledge + score_week for the top 1-2 spots. Never invent keyword
+names — use exactly the ones above.
 """
 
 PROVIDER_HF = "hf"
@@ -57,7 +70,8 @@ NIM_BASE_URL = "https://integrate.api.nvidia.com/v1"
 @dataclass
 class TraceEvent:
     """A single event in the agent trace."""
-    type: str  # "tool_call", "tool_result", "llm_chunk", "error"
+
+    type: str  # "tool_call", "tool_result", "llm_chunk", "final_answer", "error"
     timestamp: float
     data: dict[str, Any]
 
@@ -65,25 +79,29 @@ class TraceEvent:
 @dataclass
 class AgentTrace:
     """Captured trace of an agent run."""
+
     events: list[TraceEvent] = field(default_factory=list)
     question: str = ""
     model: str = ""
     provider: str = ""
 
     def add_event(self, event_type: str, data: dict[str, Any]) -> None:
-        import time
-        self.events.append(TraceEvent(type=event_type, timestamp=time.time(), data=data))
+        self.events.append(
+            TraceEvent(type=event_type, timestamp=time.time(), data=data)
+        )
 
     def to_json(self) -> str:
-        return json.dumps({
-            "question": self.question,
-            "model": self.model,
-            "provider": self.provider,
-            "events": [
-                {"type": e.type, "timestamp": e.timestamp, "data": e.data}
-                for e in self.events
-            ]
-        })
+        return json.dumps(
+            {
+                "question": self.question,
+                "model": self.model,
+                "provider": self.provider,
+                "events": [
+                    {"type": e.type, "timestamp": e.timestamp, "data": e.data}
+                    for e in self.events
+                ],
+            }
+        )
 
 
 class GetForecastTool(Tool):
@@ -101,7 +119,11 @@ class GetForecastTool(Tool):
 
 class ScoreWeekTool(Tool):
     name = "score_week"
-    description = "Get hour-by-hour surf scores for the next 7 days at a spot."
+    description = (
+        "Get hour-by-hour surf scores for the next 7 days at ONE spot. "
+        "Example: score_week(spot_name=\"Snapper Rocks\", region=\"QLD\"). "
+        "To compare many spots, use rank_spots_this_week instead."
+    )
     inputs = {
         "spot_name": {"type": "string", "description": "Name of the surf spot"},
         "region": {"type": "string", "description": "Australian state/region"},
@@ -114,16 +136,26 @@ class ScoreWeekTool(Tool):
 
 class FindSpotsTool(Tool):
     name = "find_spots"
-    description = "Search breaks by name/region with optional skill filter."
+    description = (
+        "Search breaks by name or state code with optional skill filter. "
+        "Example: find_spots(query=\"QLD\", skill=\"beginner\")"
+    )
     inputs = {
-        "query": {"type": "string", "description": "Search query for spot name or region", "nullable": True},
+        "query": {"type": "string", "description": "Spot name OR Australian state code (NSW, QLD, VIC, WA, SA, TAS)", "nullable": True},
+        "region": {"type": "string", "description": "Alias for query when searching a state code", "nullable": True},
         "skill": {"type": "string", "description": "Skill level filter (beginner, intermediate, advanced, expert)", "nullable": True},
         "limit": {"type": "integer", "description": "Maximum number of results to return", "nullable": True},
     }
     output_type = "object"
 
-    def forward(self, query: str = "", skill: str | None = None, limit: int = 10) -> list[dict]:
-        return find_spots(query=query, skill=skill, limit=limit)
+    def forward(
+        self,
+        query: str = "",
+        region: str | None = None,
+        skill: str | None = None,
+        limit: int = 10,
+    ) -> list[dict]:
+        return find_spots(query=query or region or "", skill=skill, limit=limit)
 
 
 class GetSpotKnowledgeTool(Tool):
@@ -141,7 +173,11 @@ class GetSpotKnowledgeTool(Tool):
 
 class RankSpotsThisWeekTool(Tool):
     name = "rank_spots_this_week"
-    description = "Rank spots in a region by their best score this week, with optional skill filter."
+    description = (
+        "Rank ALL spots in a state by their best score this week. "
+        "Example: rank_spots_this_week(region=\"QLD\", skill=\"beginner\"). "
+        "Use this first for 'where should I surf' questions."
+    )
     inputs = {
         "region": {"type": "string", "description": "Australian state/region"},
         "skill": {"type": "string", "description": "Skill level filter", "nullable": True},
@@ -161,38 +197,44 @@ TOOLS = [
 ]
 
 
-def _build_model(provider: str, model: str | None = None) -> InferenceClientModel:
-    """Build the InferenceClientModel for the given provider."""
+def _build_model(provider: str, model: str | None = None) -> OpenAIServerModel:
+    """Build the OpenAI-compatible model client for the given provider.
+
+    Both the HF router and NVIDIA NIM speak the OpenAI chat-completions
+    protocol, so one client class covers the HF⇄NIM switch.
+    """
     model_id = model or DEFAULT_MODEL
 
     if provider == PROVIDER_HF:
         token = os.getenv("HF_TOKEN")
         if not token:
-            raise ValueError("HF_TOKEN environment variable not set for Hugging Face provider")
-        return InferenceClientModel(
+            raise ValueError(
+                "HF_TOKEN environment variable not set for Hugging Face provider"
+            )
+        return OpenAIServerModel(
             model_id=model_id,
             api_base=HF_BASE_URL,
-            token=token,
+            api_key=token,
         )
     elif provider == PROVIDER_NIM:
         api_key = os.getenv("NVIDIA_API_KEY")
         if not api_key:
-            raise ValueError("NVIDIA_API_KEY environment variable not set for NVIDIA NIM provider")
-        return InferenceClientModel(
+            raise ValueError(
+                "NVIDIA_API_KEY environment variable not set for NVIDIA NIM provider"
+            )
+        return OpenAIServerModel(
             model_id=model_id,
             api_base=NIM_BASE_URL,
-            token=api_key,
+            api_key=api_key,
         )
     else:
         raise ValueError(f"Unknown provider: {provider}. Use 'hf' or 'nim'")
 
 
 def _detect_provider() -> str:
-    """Auto-detect provider from available env vars."""
+    """Auto-detect provider from available env vars (NIM preferred)."""
     if os.getenv("NVIDIA_API_KEY"):
         return PROVIDER_NIM
-    if os.getenv("HF_TOKEN"):
-        return PROVIDER_HF
     return PROVIDER_HF
 
 
@@ -207,8 +249,12 @@ class SurfAgent:
         self.provider = provider or _detect_provider()
         self.model = model or DEFAULT_MODEL
         self._model = _build_model(self.provider, self.model)
-        # Load default prompt templates from smolagents package
-        default_templates_yaml = importlib.resources.files("smolagents.prompts").joinpath("code_agent.yaml").read_text()
+        # Load smolagents' default prompt templates, then override system prompt
+        default_templates_yaml = (
+            importlib.resources.files("smolagents.prompts")
+            .joinpath("code_agent.yaml")
+            .read_text()
+        )
         default_templates = yaml.safe_load(default_templates_yaml)
         default_templates["system_prompt"] = SYSTEM_PROMPT
         prompt_templates = PromptTemplates(**default_templates)
@@ -224,54 +270,88 @@ class SurfAgent:
     def trace(self) -> AgentTrace | None:
         return self._trace
 
+    def _capture_item(self, item: Any) -> bool:
+        """Record a tool_call/tool_result from a smolagents stream item.
+
+        Returns True if the item was consumed as a tool event.
+        """
+        if self._trace is None:
+            return False
+        if isinstance(item, SmolToolCall):
+            self._trace.add_event(
+                "tool_call",
+                {"name": item.name, "arguments": item.arguments, "id": item.id},
+            )
+            return True
+        if isinstance(item, ToolOutput):
+            name = item.tool_call.name if item.tool_call is not None else None
+            self._trace.add_event(
+                "tool_result",
+                {"name": name, "observation": str(item.observation)},
+            )
+            return True
+        return False
+
+    def _traced_step_stream(self, original_step_stream):
+        """Wrap a _step_stream generator so run() also captures tool events."""
+
+        def traced(memory_step, *args, **kwargs):
+            for item in original_step_stream(memory_step, *args, **kwargs):
+                self._capture_item(item)
+                yield item
+
+        return traced
+
     def run(self, question: str) -> str:
         """Run the agent synchronously and return the final answer."""
-        self._trace = AgentTrace(question=question, model=self.model, provider=self.provider)
-        return self._agent.run(question)
-
-    def run_stream(self, question: str):
-        """Run the agent with streaming, yielding (chunk, trace_event) pairs."""
-        self._trace = AgentTrace(question=question, model=self.model, provider=self.provider)
-
-        # Wrap the agent's run to capture trace events
-        from smolagents.agents import MultiStepAgent
-        from smolagents.memory import ActionStep
-
-        original_step = self._agent.step
-
-        def traced_step(memory_step: ActionStep, *args, **kwargs):
-            # Capture tool calls
-            if memory_step.tool_calls:
-                for tc in memory_step.tool_calls:
-                    self._trace.add_event("tool_call", {
-                        "name": tc.name,
-                        "arguments": tc.arguments,
-                        "id": tc.id,
-                    })
-            # Capture tool results
-            if memory_step.observations:
-                for obs in memory_step.observations:
-                    self._trace.add_event("tool_result", {"observation": str(obs)})
-            return original_step(memory_step, *args, **kwargs)
-
-        self._agent.step = traced_step
-
+        self._trace = AgentTrace(
+            question=question, model=self.model, provider=self.provider
+        )
+        original_step_stream = self._agent._step_stream
+        self._agent._step_stream = self._traced_step_stream(original_step_stream)
         try:
-            for chunk in self._agent.run(question, stream=True):
-                if self._trace:
-                    self._trace.add_event("llm_chunk", {"chunk": str(chunk)})
-                yield chunk
+            return self._agent.run(question)
         finally:
-            self._agent.step = original_step
-
-
-def run_agent(question: str, provider: str | None = None, model: str | None = None) -> str:
+            self._agent._step_stream = original_step_stream
+
+    def run_stream(
+        self, question: str
+    ) -> Generator[tuple[str, Any], None, None]:
+        """Run the agent with streaming.
+
+        Yields ("model", delta) for LLM tokens, ("tool", tool_name) when a
+        tool call fires, and ("final", answer) at the end. Tool activity is
+        captured into the trace from the stream itself.
+        """
+        self._trace = AgentTrace(
+            question=question, model=self.model, provider=self.provider
+        )
+        for item in self._agent.run(question, stream=True):
+            if isinstance(item, ChatMessageStreamDelta):
+                if item.content:
+                    self._trace.add_event("llm_chunk", {"chunk": item.content})
+                    yield ("model", item.content)
+                continue
+            if isinstance(item, FinalAnswerStep):
+                self._trace.add_event("final_answer", {"answer": item.output})
+                yield ("final", item.output)
+                continue
+            if self._capture_item(item) and isinstance(item, SmolToolCall):
+                name = item.name if isinstance(item.name, str) else "code action"
+                yield ("tool", name)
+
+
+def run_agent(
+    question: str, provider: str | None = None, model: str | None = None
+) -> str:
     """Run the surf agent and return the answer."""
     agent = SurfAgent(provider=provider, model=model)
     return agent.run(question)
 
 
-def run_agent_stream(question: str, provider: str | None = None, model: str | None = None):
+def run_agent_stream(
+    question: str, provider: str | None = None, model: str | None = None
+):
     """Run the surf agent with streaming."""
     agent = SurfAgent(provider=provider, model=model)
     yield from agent.run_stream(question)
@@ -279,9 +359,17 @@ def run_agent_stream(question: str, provider: str | None = None, model: str | No
 
 if __name__ == "__main__":
     import sys
-    question = " ".join(sys.argv[1:]) if len(sys.argv) > 1 else "What time should I surf Snapper Rocks today?"
+
+    question = (
+        " ".join(sys.argv[1:])
+        if len(sys.argv) > 1
+        else "What time should I surf Snapper Rocks today?"
+    )
     print(f"Question: {question}\n")
     print("Answer:")
-    for chunk in run_agent_stream(question):
-        print(chunk, end="", flush=True)
-    print()
+    for kind, chunk in run_agent_stream(question):
+        if kind == "model":
+            print(chunk, end="", flush=True)
+        elif kind == "tool":
+            print(f"\n[tool: {chunk}]", flush=True)
+    print()

wavereader/api.py

@@ -6,35 +6,85 @@ and any non-Gradio consumer. Endpoints: /spots, /forecast, /score, /ask.
 
 from __future__ import annotations
 
-from fastapi import FastAPI
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+from wavereader import forecasts, scoring, spots
+from wavereader.agent import run_agent, SurfAgent
 
 app = FastAPI(title="wavereader", version="0.1.0")
 
 
+class AskRequest(BaseModel):
+    question: str
+    provider: str | None = None
+    model: str | None = None
+
+
+class AskResponse(BaseModel):
+    answer: str
+    trace: str | None = None
+
+
 @app.get("/")
 async def read_root():
-    return {"Hello": "World"}
+    """Health check."""
+    return {"name": "wavereader", "version": "0.1.0", "status": "ok"}
 
 
 @app.get("/spots")
-async def list_spots(query: str = "", region: str | None = None, skill: str | None = None):
-    """Search/validate breaks via spots.py. TODO: wire up."""
-    raise NotImplementedError
+async def list_spots(query: str = "", region: str | None = None, skill: str | None = None, limit: int = 10):
+    """Search/validate breaks via spots.py."""
+    results = spots.find_spots(query=query, region=region, skill=skill, limit=limit)
+    return [b.model_dump() for b in results]
+
+
+@app.get("/spots/{spot_name}")
+async def get_spot(spot_name: str, region: str):
+    """Get full knowledge-base record for a spot keyed by (name, region).
+
+    ``region`` is a required query param: ``/spots/Snapper Rocks?region=QLD``.
+    """
+    spot = spots.get_spot(spot_name, region)
+    if spot is None:
+        raise HTTPException(status_code=404, detail=f"Spot '{spot_name}' ({region}) not found")
+    return spot.model_dump()
 
 
 @app.get("/forecast")
-async def forecast(spot: str, days: int = 7):
-    """Hourly marine + wind forecast via forecasts.py. TODO: wire up."""
-    raise NotImplementedError
+async def forecast(spot: str, region: str, days: int = 7):
+    """Hourly marine + wind forecast via forecasts.py."""
+    s = spots.get_spot(spot, region)
+    if s is None:
+        raise HTTPException(status_code=404, detail=f"Spot '{spot}' ({region}) not found")
+    return forecasts.get_forecast(s.coordinates.lat, s.coordinates.lng, days=days)
 
 
 @app.get("/score")
-async def score(spot: str, days: int = 7):
-    """Deterministic hourly surf scores via scoring.py. TODO: wire up."""
-    raise NotImplementedError
+async def score(spot: str, region: str, days: int = 7):
+    """Deterministic hourly surf scores via scoring.py."""
+    s = spots.get_spot(spot, region)
+    if s is None:
+        raise HTTPException(status_code=404, detail=f"Spot '{spot}' ({region}) not found")
+    fc = forecasts.get_forecast(s.coordinates.lat, s.coordinates.lng, days=days)
+    return scoring.score_week(fc, s.model_dump())
+
+
+@app.post("/ask", response_model=AskResponse)
+async def ask(request: AskRequest):
+    """Agent answer via agent.py tool loop."""
+    try:
+        agent = SurfAgent(provider=request.provider, model=request.model)
+        answer = agent.run(request.question)
+    except ValueError as exc:
+        # Missing/unknown provider config (e.g. unset HF_TOKEN/NVIDIA_API_KEY)
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except Exception as exc:
+        raise HTTPException(status_code=502, detail=f"Agent run failed: {exc}") from exc
+    trace_json = agent.trace.to_json() if agent.trace else None
+    return AskResponse(answer=answer, trace=trace_json)
 
 
-@app.post("/ask")
-async def ask(question: str):
-    """Agent answer via agent.py tool loop. TODO: wire up."""
-    raise NotImplementedError
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

wavereader/app.py

@@ -1,24 +1,867 @@
-"""Gradio demo UI.
+"""Gradio UI for wavereader: Australia map home, agent chat with trace panel,
+interactive seaborn-styled plotly charts, weekly rankings, and the daggr
+Morning Surf Report canvas.
 
-Home page is a map of Australia (select your break), plus chat with the
-agent, interactive seaborn-styled charts (plotly/altair aesthetics) rendered
-whenever the agent surfaces forecast/wind data, and the agent trace panel.
-Calls the core modules (and FastAPI endpoints) — no custom frontend this
-week.
+Run with: uv run python -m wavereader.app
 """
 
 from __future__ import annotations
 
+import json
+import os
+import re
+import subprocess
+import sys
+import threading
 
-def build_ui() -> object:
-    """Assemble the Blocks demo (map home, chat, charts, trace panel).
+import gradio as gr
+import plotly.graph_objects as go
 
-    TODO: Australia map home page, chat pipeline against agent.run_agent,
-    chart rendering, trace panel.
+from wavereader import spots, tools
+from wavereader.agent import PROVIDER_HF, PROVIDER_NIM, SurfAgent
+
+# ---------------------------------------------------------------------------
+# Styling: seaborn "muted" palette applied to plotly
+# ---------------------------------------------------------------------------
+
+MUTED = {
+    "blue": "#4878D0",
+    "orange": "#EE854A",
+    "green": "#6ACC64",
+    "red": "#D65F5F",
+    "purple": "#B47CC7",
+    "brown": "#8C613C",
+    "pink": "#DC7EC0",
+    "gray": "#797979",
+    "gold": "#D5BB67",
+    "cyan": "#82C6E2",
+}
+
+SKILL_COLORS = {
+    "beginner": MUTED["green"],
+    "intermediate": MUTED["cyan"],
+    "advanced": MUTED["orange"],
+    "expert": MUTED["red"],
+}
+
+REGIONS = ["NSW", "QLD", "VIC", "WA", "SA", "TAS"]
+SKILL_FILTERS = ["all", "beginner", "intermediate", "advanced", "expert"]
+
+_DEG_TO_COMPASS = [
+    "N", "NNE", "NE", "ENE", "E", "ESE", "SE", "SSE",
+    "S", "SSW", "SW", "WSW", "W", "WNW", "NW", "NNW",
+]
+
+
+def _compass(deg) -> str:
+    if deg is None:
+        return "–"
+    try:
+        deg = float(deg)
+    except (TypeError, ValueError):
+        return "–"
+    return _DEG_TO_COMPASS[int((deg % 360) / 22.5) % 16]
+
+
+def _primary_skill(skill_level: str) -> str:
+    """Collapse compound skill strings ('beginner to intermediate') to a bucket."""
+    s = (skill_level or "").lower()
+    if "elite" in s or "professional" in s:
+        return "expert"
+    for level in ("beginner", "intermediate", "advanced", "expert"):
+        if level in s:
+            return level
+    return "intermediate"
+
+
+def _matches_skill(skill_level: str, wanted: str) -> bool:
+    if wanted in (None, "", "all"):
+        return True
+    s = (skill_level or "").lower()
+    if wanted == "expert":
+        return "expert" in s or "elite" in s or "professional" in s
+    return wanted in s
+
+
+def create_seaborn_template() -> dict:
+    """Plotly layout template with seaborn aesthetics (whitegrid + muted)."""
+    return {
+        "layout": {
+            "font": {"family": "DejaVu Sans, Helvetica, Arial, sans-serif", "size": 13, "color": "#3b3b3b"},
+            "paper_bgcolor": "white",
+            "plot_bgcolor": "white",
+            "colorway": list(MUTED.values()),
+            "title": {"font": {"size": 17, "color": "#1f2d3d"}, "x": 0.01, "xanchor": "left"},
+            "legend": {"bgcolor": "rgba(0,0,0,0)", "orientation": "h", "y": 1.08},
+            "xaxis": {"gridcolor": "#e6e6e6", "zerolinecolor": "#e6e6e6", "linecolor": "#cccccc"},
+            "yaxis": {"gridcolor": "#e6e6e6", "zerolinecolor": "#e6e6e6", "linecolor": "#cccccc"},
+            "margin": {"l": 60, "r": 70, "t": 70, "b": 55},
+        }
+    }
+
+
+def _style(fig: go.Figure) -> go.Figure:
+    fig.update_layout(**create_seaborn_template()["layout"])
+    return fig
+
+
+def _empty_fig(message: str) -> go.Figure:
+    fig = go.Figure()
+    fig.add_annotation(text=message, showarrow=False, font=dict(size=15, color="#888888"))
+    fig.update_xaxes(visible=False)
+    fig.update_yaxes(visible=False)
+    return _style(fig)
+
+
+# ---------------------------------------------------------------------------
+# Charts (plotly, seaborn-styled)
+# ---------------------------------------------------------------------------
+
+def create_australia_map(skill_filter: str = "all") -> go.Figure:
+    """Scattergeo of all knowledge-base breaks, coloured by skill bucket."""
+    lats, lngs, names, texts, colors = [], [], [], [], []
+    for b in spots.load_breaks():
+        if not _matches_skill(b.additional_details.skill_level, skill_filter):
+            continue
+        swell = b.ideal_swell
+        wind = b.ideal_wind
+        lats.append(b.coordinates.lat)
+        lngs.append(b.coordinates.lng)
+        names.append(b.name)
+        colors.append(SKILL_COLORS.get(_primary_skill(b.additional_details.skill_level), MUTED["gray"]))
+        texts.append(
+            f"<b>{b.name}</b> ({b.region})<br>"
+            f"Skill: {b.additional_details.skill_level}<br>"
+            f"Ideal swell: {swell.size_ft_min}–{swell.size_ft_max} ft {swell.direction}<br>"
+            f"Ideal wind: ≤{wind.strength_kt_max} kt {wind.direction}"
+        )
+
+    fig = go.Figure(
+        go.Scattergeo(
+            lat=lats,
+            lon=lngs,
+            text=names,
+            hovertext=texts,
+            hoverinfo="text",
+            mode="markers",
+            marker=dict(size=9, color=colors, opacity=0.85, line=dict(width=1, color="white")),
+            showlegend=False,
+        )
+    )
+    fig.update_layout(
+        title=dict(text="Australian Surf Breaks", font=dict(size=17, color="#1f2d3d")),
+        geo=dict(
+            scope="world",
+            projection=dict(type="mercator"),
+            center=dict(lat=-25.5, lon=134.5),
+            lonaxis_range=[111, 156],
+            lataxis_range=[-44, -9.5],
+            showland=True,
+            landcolor="#f3efe4",
+            showocean=True,
+            oceancolor="#d7e9f5",
+            showcountries=False,
+            showcoastlines=True,
+            coastlinecolor="#9bb8cc",
+            showlakes=False,
+            bgcolor="#d7e9f5",
+        ),
+        height=560,
+        margin={"l": 10, "r": 10, "t": 50, "b": 10},
+        font={"family": "DejaVu Sans, Helvetica, Arial, sans-serif", "size": 13, "color": "#3b3b3b"},
+    )
+    return fig
+
+
+def create_wave_height_chart(forecast: dict, spot_name: str) -> go.Figure:
+    """Hourly wave height (left axis) + period and wind speed (right axis)."""
+    hourly = (forecast or {}).get("hourly") or []
+    if not hourly:
+        return _empty_fig(f"No forecast data available for {spot_name}")
+
+    times = [h.get("time", "") for h in hourly]
+    wave = [h.get("wave_height") for h in hourly]
+    period = [h.get("wave_period") for h in hourly]
+    wind = [h.get("wind_speed_10m") for h in hourly]
+    wind_dir = [h.get("wind_direction_10m") for h in hourly]
+    wave_dir = [h.get("wave_direction") or h.get("swell_wave_direction") for h in hourly]
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Scatter(
+            x=times, y=wave, name="Wave height (m)", mode="lines",
+            line=dict(color=MUTED["blue"], width=3), fill="tozeroy",
+            fillcolor="rgba(72,120,208,0.12)",
+            customdata=list(zip([_compass(d) for d in wave_dir], [d for d in wave_dir])),
+            hovertemplate="%{x}<br>Wave height: %{y:.2f} m<br>Swell dir: %{customdata[0]} (%{customdata[1]}°)<extra></extra>",
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=times, y=period, name="Period (s)", mode="lines",
+            line=dict(color=MUTED["purple"], width=2, dash="dot"),
+            yaxis="y2",
+            hovertemplate="%{x}<br>Period: %{y:.1f} s<extra></extra>",
+        )
+    )
+    fig.add_trace(
+        go.Scatter(
+            x=times, y=wind, name="Wind (km/h)", mode="lines",
+            line=dict(color=MUTED["red"], width=2),
+            yaxis="y2",
+            customdata=[_compass(d) for d in wind_dir],
+            hovertemplate="%{x}<br>Wind: %{y:.1f} km/h %{customdata}<extra></extra>",
+        )
+    )
+    fig.update_layout(
+        title=f"Wave & Wind Forecast — {spot_name}",
+        xaxis=dict(title="Time (local)"),
+        yaxis=dict(title="Wave height (m)", rangemode="tozero"),
+        yaxis2=dict(title="Period (s) / Wind (km/h)", overlaying="y", side="right", showgrid=False),
+        hovermode="x unified",
+    )
+    return _style(fig)
+
+
+def create_score_chart(scores: list, spot_name: str) -> go.Figure:
+    """Hourly surf score (bold) with the four deterministic components."""
+    if not scores:
+        return _empty_fig(f"No score data available for {spot_name}")
+
+    times = [s.get("time", "") for s in scores]
+    total = [s.get("score") for s in scores]
+    comps = scores[0].get("components") or {}
+
+    fig = go.Figure()
+    component_colors = {
+        "swell_size": MUTED["blue"],
+        "swell_direction": MUTED["cyan"],
+        "wind": MUTED["red"],
+        "period": MUTED["purple"],
+    }
+    for comp in ("swell_size", "swell_direction", "wind", "period"):
+        if comp in comps:
+            fig.add_trace(
+                go.Scatter(
+                    x=times,
+                    y=[(s.get("components") or {}).get(comp) for s in scores],
+                    name=comp.replace("_", " ").title(),
+                    mode="lines",
+                    line=dict(color=component_colors[comp], width=1.5, dash="dot"),
+                    opacity=0.75,
+                    hovertemplate="%{x}<br>" + comp.replace("_", " ") + ": %{y:.1f}<extra></extra>",
+                )
+            )
+    fig.add_trace(
+        go.Scatter(
+            x=times, y=total, name="Surf score", mode="lines",
+            line=dict(color="#1f2d3d", width=3.5),
+            hovertemplate="%{x}<br>Score: %{y:.1f}/10<extra></extra>",
+        )
+    )
+    fig.update_layout(
+        title=f"Hourly Surf Score — {spot_name}",
+        xaxis=dict(title="Time (local)"),
+        yaxis=dict(title="Score (0–10)", range=[0, 10]),
+        hovermode="x unified",
+    )
+    return _style(fig)
+
+
+def create_ranking_chart(ranked: list, region: str) -> go.Figure:
+    """Horizontal bars of each spot's best score this week."""
+    if not ranked:
+        return _empty_fig(f"No ranking data for {region}")
+    spots_sorted = sorted(ranked, key=lambda r: r.get("best_score") or 0)
+    names = [f"{r.get('name', '?')} ({r.get('region', '')})" for r in spots_sorted]
+    values = [r.get("best_score") or 0 for r in spots_sorted]
+    best_times = [r.get("best_time", "–") for r in spots_sorted]
+
+    fig = go.Figure(
+        go.Bar(
+            x=values,
+            y=names,
+            orientation="h",
+            marker=dict(
+                color=values,
+                colorscale=[[0, MUTED["cyan"]], [0.6, MUTED["blue"]], [1, MUTED["green"]]],
+                line=dict(width=0),
+            ),
+            customdata=best_times,
+            hovertemplate="%{y}<br>Best score: %{x:.1f}/10<br>Best time: %{customdata}<extra></extra>",
+        )
+    )
+    fig.update_layout(
+        title=f"Best Scores This Week — {region}",
+        xaxis=dict(title="Best hourly score (0–10)", range=[0, 10]),
+        yaxis=dict(title=""),
+        height=max(360, 28 * len(names) + 120),
+    )
+    return _style(fig)
+
+
+# ---------------------------------------------------------------------------
+# Trace panel
+# ---------------------------------------------------------------------------
+
+_TOOL_EMOJI = {
+    "get_forecast": "🌊",
+    "score_week": "🧮",
+    "find_spots": "🔎",
+    "get_spot_knowledge": "📚",
+    "rank_spots_this_week": "🏆",
+}
+
+# Tool invocations inside CodeAgent python_interpreter code blobs
+_TOOL_CALL_RE = re.compile(
+    r"\b(get_forecast|score_week|find_spots|get_spot_knowledge|rank_spots_this_week)\(([^)]*)"
+)
+
+
+def _code_step_summary(args) -> tuple[str, list[tuple[str, str]]]:
+    """Summarise a python_interpreter code blob: (display_code, tool calls)."""
+    code = args if isinstance(args, str) else str(args)
+    calls = [
+        (tool, re.findall(r"[\"']([^\"']+)[\"']", argstr))
+        for tool, argstr in _TOOL_CALL_RE.findall(code)
+    ]
+    snippet = code.strip().replace("```", "")
+    if len(snippet) > 400:
+        snippet = snippet[:400] + " …"
+    return snippet, calls
+
+
+def update_trace_panel(trace_json: str) -> str:
+    """Render an AgentTrace JSON blob as readable markdown for the UI."""
+    if not trace_json or not trace_json.strip():
+        return (
+            "### 🔍 Agent Trace\n\nNo trace yet — ask the agent a question and "
+            "watch it work: every tool call, the data it saw, and its reasoning "
+            "appear here."
+        )
+    try:
+        trace = json.loads(trace_json)
+    except (json.JSONDecodeError, TypeError):
+        return trace_json
+
+    lines = ["### 🔍 Agent Trace"]
+    question = trace.get("question", "")
+    if question:
+        lines.append(f"**Question:** {question}")
+    model = trace.get("model", "")
+    provider = trace.get("provider", "")
+    if model or provider:
+        lines.append(f"**Model:** `{model}` via `{provider}`")
+    lines.append("")
+
+    n_chunks = 0
+    for evt in trace.get("events", []):
+        etype = evt.get("type", "")
+        data = evt.get("data", {})
+        if etype == "tool_call":
+            name = data.get("name", "?")
+            args = data.get("arguments", {})
+            if name == "python_interpreter":
+                snippet, calls = _code_step_summary(args)
+                called = ", ".join(f"`{tool}`" for tool, _ in calls) if calls else ""
+                lines.append(f"- 🧠 **code step** {f'→ calls {called}' if called else ''}")
+                lines.append(f"\n```python\n{snippet}\n```\n")
+            else:
+                emoji = _TOOL_EMOJI.get(name, "🔧")
+                if isinstance(args, str):
+                    args_display = args
+                else:
+                    args_display = ", ".join(
+                        f"{k}=`{v}`" for k, v in args.items() if v is not None
+                    )
+                lines.append(f"- {emoji} **`{name}`**({args_display})")
+        elif etype == "tool_result":
+            obs = str(data.get("observation", ""))
+            if len(obs) > 220:
+                obs = obs[:220] + "…"
+            lines.append(f"  - ↳ *{obs}*")
+        elif etype == "llm_chunk":
+            n_chunks += 1
+        elif etype == "final_answer":
+            lines.append("- ✅ **Final answer** composed")
+    if n_chunks:
+        lines.append(f"- 💬 Streamed {n_chunks} token chunks")
+
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Data helpers for the UI
+# ---------------------------------------------------------------------------
+
+def _spot_label(b) -> str:
+    return f"{b.name} ({b.region})"
+
+
+def _all_spot_choices() -> list[str]:
+    return sorted(_spot_label(b) for b in spots.load_breaks())
+
+
+def _parse_spot_label(label: str):
+    m = re.match(r"^(.*) \(([A-Z]{2,3})\)$", label or "")
+    if not m:
+        return None
+    return spots.get_spot(m.group(1), m.group(2))
+
+
+def _spot_card(spot) -> str:
+    if spot is None:
+        return "_Select a break to see its profile._"
+
+    def badge(text: str, color: str) -> str:
+        return (
+            f"<span class='skill-badge' style='background:{color}22; color:{color}; "
+            f"border:1px solid {color}66'>{text}</span>"
+        )
+
+    d = spot.additional_details
+    swell = spot.ideal_swell
+    wind = spot.ideal_wind
+    badges = " ".join(
+        badge(t, SKILL_COLORS.get(_primary_skill(t), MUTED["gray"]))
+        for t in (d.skill_level, d.break_type, d.break_direction)
+    )
+    hazards = d.hazards or "—"
+    return f"""
+### 🏄 {spot.name} · {spot.region}
+
+{badges}
+
+{spot.short_description}
+
+| Ideal conditions | |
+|---|---|
+| **Swell** | {swell.size_ft_min}–{swell.size_ft_max} ft from {swell.direction} |
+| **Wind** | offshore/low up to {wind.strength_kt_max} kt ({wind.direction}) |
+| **Tide** | {spot.ideal_tide} *(qualitative)* |
+| **Bottom** | {d.bottom_type} · {d.break_surface} |
+| **Best season** | {d.best_season} |
+
+⚠️ **Hazards:** {hazards}
+
+{d.other_notes or ""}
+"""
+
+
+def _get_spot_data(spot):
+    """Forecast + scores for a spot, with a small in-process cache."""
+    if spot is None:
+        return None, None
+    cache = getattr(_get_spot_data, "_cache", None)
+    if cache is None:
+        cache = _get_spot_data._cache = {}
+    key = (spot.name, spot.region)
+    if key not in cache:
+        forecast = tools.get_forecast(spot.name, spot.region)
+        if "error" in forecast:
+            return None, None
+        scores = tools.score_week(spot.name, spot.region)
+        if isinstance(scores, dict) and "error" in scores:
+            scores = []
+        cache[key] = (forecast, scores)
+    return cache[key]
+
+
+def _guess_region(name: str) -> str | None:
+    """Resolve a spot's region from the knowledge base by exact name."""
+    for b in spots.load_breaks():
+        if b.name.lower() == name.lower():
+            return b.region
+    return None
+
+
+def _extract_trace_targets(trace_json: str) -> tuple[list[tuple[str, str | None]], list[str]]:
+    """What the agent looked at, from python_interpreter code blobs.
+
+    Returns (spot_pairs, rank_regions): spot (name, region-or-None) pairs for
+    forecast/score/knowledge calls, and regions passed to ranking calls.
     """
-    raise NotImplementedError
+    spot_pairs: list[tuple[str, str | None]] = []
+    rank_regions: list[str] = []
+    try:
+        trace = json.loads(trace_json)
+    except (json.JSONDecodeError, TypeError):
+        return spot_pairs, rank_regions
+    for evt in trace.get("events", []):
+        if evt.get("type") != "tool_call":
+            continue
+        args = evt.get("data", {}).get("arguments")
+        code = args if isinstance(args, str) else json.dumps(args or {})
+        for tool, vals in (
+            (t, re.findall(r"[\"']([^\"']+)[\"']", a))
+            for t, a in _TOOL_CALL_RE.findall(code)
+        ):
+            if tool in ("get_forecast", "score_week") and len(vals) >= 2:
+                pair = (vals[0], vals[1])
+            elif tool == "get_spot_knowledge" and vals:
+                pair = (vals[0], vals[1] if len(vals) >= 2 else None)
+            elif tool == "rank_spots_this_week" and vals:
+                if vals[0] not in rank_regions:
+                    rank_regions.append(vals[0])
+                continue
+            else:
+                continue
+            if pair not in spot_pairs:
+                spot_pairs.append(pair)
+    return spot_pairs, rank_regions
 
 
-if __name__ == "__main__":
+# ---------------------------------------------------------------------------
+# Agent chat
+# ---------------------------------------------------------------------------
+
+_agents: dict[str, SurfAgent] = {}
+
+
+def _get_agent(provider: str) -> SurfAgent:
+    if provider not in _agents:
+        _agents[provider] = SurfAgent(provider=provider)
+    return _agents[provider]
+
+
+def _provider_available(provider: str) -> bool:
+    if provider == PROVIDER_NIM:
+        return bool(os.getenv("NVIDIA_API_KEY"))
+    return bool(os.getenv("HF_TOKEN"))
+
+
+def chat_submit(message: str, history: list, provider: str):
+    """Streaming chat handler: yields (chatbot, trace_md, score_chart, wave_chart)."""
+    history = list(history or [])
+    if not message or not message.strip():
+        yield history, gr.update(), gr.update(), gr.update()
+        return
+
+    history.append({"role": "user", "content": message})
+    history.append({"role": "assistant", "content": "…"})
+
+    try:
+        agent = _get_agent(provider)
+    except ValueError as exc:
+        history[-1]["content"] = (
+            f"⚠️ **Model provider not configured.**\n\n{exc}\n\n"
+            "Set `HF_TOKEN` or `NVIDIA_API_KEY` in your environment and restart. "
+            "Everything else (map, charts, rankings, scores) works without tokens."
+        )
+        yield history, gr.update(), gr.update(), gr.update()
+        return
+
+    thinking: list[str] = []
+    final_answer = ""
+    trace_json = ""
+    for kind, chunk in agent.run_stream(message):
+        if kind == "model":
+            thinking.append(chunk)
+            tail = "".join(thinking)[-600:]
+            history[-1]["content"] = f"*🧠 thinking…*\n\n```python\n{tail}\n```"
+            yield history, gr.update(), gr.update(), gr.update()
+        elif kind == "tool":
+            history[-1]["content"] = f"*🔧 calling `{chunk}`…*"
+            yield history, gr.update(), gr.update(), gr.update()
+        elif kind == "final":
+            final_answer = chunk if isinstance(chunk, str) else str(chunk)
+            trace_json = agent.trace.to_json() if agent.trace else ""
+
+    history[-1]["content"] = final_answer or "*(empty answer)*"
+    trace_md = update_trace_panel(trace_json)
+
+    # Auto-render interactive charts for what the agent looked at
+    score_fig: object = gr.update()
+    wave_fig: object = gr.update()
+    spot_pairs, rank_regions = _extract_trace_targets(trace_json)
+    if spot_pairs:
+        name, region = spot_pairs[0]
+        region = region or _guess_region(name)
+        spot = spots.get_spot(name, region) if region else None
+        if spot is not None:
+            forecast, scores = _get_spot_data(spot)
+            if scores:
+                score_fig = create_score_chart(scores[-48:], spot.name)
+            if forecast:
+                wave_fig = create_wave_height_chart(
+                    {"hourly": forecast["hourly"][-48:]}, spot.name
+                )
+    elif rank_regions:
+        ranked = tools.rank_spots_this_week(rank_regions[0], None)
+        score_fig = create_ranking_chart(ranked, rank_regions[0])
+
+    yield history, trace_md, score_fig, wave_fig
+
+
+# ---------------------------------------------------------------------------
+# daggr Morning Surf Report + cache warming (started only by main())
+# ---------------------------------------------------------------------------
+
+def _start_daggr_server(host: str = "127.0.0.1", port: int = 7861) -> None:
+    """Launch the Morning Surf Report canvas as its own process.
+
+    A second Gradio instance inside this process is unreliable, so the daggr
+    app runs standalone; the tab's iframe just points at it.
+    """
+    try:
+        subprocess.Popen(
+            [sys.executable, "-m", "wavereader.daggr_pipeline"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except Exception:
+        pass  # canvas tab falls back to a "how to start" note
+
+
+def _warm_forecast_cache() -> None:
+    """Prefetch all break forecasts into the disk cache (demo survivability)."""
+    for b in spots.load_breaks():
+        try:
+            tools.get_forecast(b.name, b.region)
+        except Exception:
+            continue
+
+
+def _start_background_services() -> None:
+    if os.getenv("WAVEREADER_EMBED_DAGGR", "1") == "1":
+        threading.Thread(target=_start_daggr_server, daemon=True).start()
+    if os.getenv("WAVEREADER_WARM_CACHE", "1") == "1":
+        threading.Thread(target=_warm_forecast_cache, daemon=True).start()
+
+
+# ---------------------------------------------------------------------------
+# UI assembly
+# ---------------------------------------------------------------------------
+
+_CUSTOM_CSS = """
+.gradio-container {max-width: 1400px !important; margin: 0 auto;}
+#wr-header {
+    background: linear-gradient(120deg, #0b3d5c 0%, #1173a6 55%, #19b3a6 100%);
+    border-radius: 16px; padding: 26px 30px !important; color: white;
+    margin-bottom: 14px;
+}
+#wr-header h1 {color: white; margin: 0 0 6px 0; font-size: 2em; letter-spacing: 0.5px;}
+#wr-header p {color: #d7ecf7; margin: 0; font-size: 1.02em;}
+.skill-badge {
+    display: inline-block; padding: 2px 10px; border-radius: 999px;
+    font-size: 0.8em; font-weight: 600; white-space: nowrap;
+}
+#wr-trace {
+    background: #f7fafc; border: 1px solid #e2e8f0; border-radius: 12px;
+    padding: 10px 14px; font-size: 0.92em; max-height: 640px; overflow-y: auto;
+}
+#wr-trace code {background: #eef2f7; padding: 1px 5px; border-radius: 5px;}
+footer {display: none !important;}
+"""
+
+
+def build_ui() -> gr.Blocks:
+    """Assemble the full wavereader demo UI."""
+    spot_choices = _all_spot_choices()
+    hf_ok, nim_ok = _provider_available(PROVIDER_HF), _provider_available(PROVIDER_NIM)
+
+    with gr.Blocks(
+        title="WaveReader — Agentic Surf Forecaster",
+        theme=gr.themes.Soft(
+            primary_hue="sky",
+            secondary_hue="blue",
+            neutral_hue="slate",
+            font=[gr.themes.GoogleFont("Inter"), "ui-sans-serif", "system-ui"],
+        ),
+        css=_CUSTOM_CSS,
+    ) as demo:
+
+        # ------------------------------------------------ header
+        status = "🟢 agent ready" if (hf_ok or nim_ok) else "🔴 set HF_TOKEN or NVIDIA_API_KEY for the agent"
+        gr.HTML(
+            f"""<div id="wr-header">
+<h1>🏄 WaveReader</h1>
+<p>Agentic surf forecaster for Australian breaks — deterministic scores, visible reasoning.
+&nbsp;·&nbsp; Model: <code>Qwen/Qwen3-Next-80B-A3B-Instruct</code> &nbsp;·&nbsp; {status}</p>
+</div>"""
+        )
+
+        with gr.Tabs():
+
+            # ------------------------------------------------ tab: explore (map home)
+            with gr.Tab("🗺️ Explore"):
+                with gr.Row():
+                    with gr.Column(scale=3):
+                        map_plot = gr.Plot(create_australia_map(), label="Surf breaks across Australia", show_label=False)
+                        map_skill_filter = gr.Dropdown(
+                            choices=SKILL_FILTERS, value="all", label="Filter map by skill"
+                        )
+                    with gr.Column(scale=2):
+                        gr.Markdown("### Pick your break")
+                        spot_dropdown = gr.Dropdown(
+                            choices=spot_choices,
+                            value=None,
+                            label="Search 100 breaks (name or region)",
+                            info="Type to filter — e.g. 'Snapper' or 'QLD'",
+                        )
+                        spot_card_md = gr.Markdown(_spot_card(None))
+                        spot_quick_btn = gr.Button(
+                            "📊 Show forecast charts for this spot", variant="secondary"
+                        )
+
+            # ------------------------------------------------ tab: agent chat
+            with gr.Tab("🤖 Surf Agent"):
+                with gr.Row():
+                    with gr.Column(scale=5):
+                        provider_radio = gr.Radio(
+                            choices=[
+                                ("Hugging Face 🤗", PROVIDER_HF),
+                                ("NVIDIA NIM ⚡", PROVIDER_NIM),
+                            ],
+                            value=PROVIDER_HF if hf_ok else PROVIDER_NIM,
+                            label="Model hosting",
+                        )
+                        chatbot = gr.Chatbot(
+                            height=500,
+                            label="WaveReader agent",
+                            placeholder="Ask: *Where should I surf near Byron Bay this weekend as an intermediate?*",
+                        )
+                        with gr.Row():
+                            chat_input = gr.Textbox(
+                                placeholder="Ask about any break, your skill level, best hours…",
+                                scale=8,
+                                show_label=False,
+                                autofocus=True,
+                            )
+                            chat_send = gr.Button("Send 🚀", variant="primary", scale=1)
+                        gr.Examples(
+                            examples=[
+                                "Which QLD spots suit a beginner this week?",
+                                "What time should I surf Snapper Rocks tomorrow?",
+                                "Rank NSW breaks for an advanced surfer and explain the top pick.",
+                            ],
+                            inputs=[chat_input],
+                        )
+                    with gr.Column(scale=3):
+                        trace_panel = gr.Markdown(update_trace_panel(""), elem_id="wr-trace")
+                gr.Markdown("### Charts the agent surfaced")
+                with gr.Row():
+                    chat_score_chart = gr.Plot(
+                        _empty_fig("Ask about a spot — its score chart appears here"),
+                        label="Hourly surf score",
+                    )
+                    chat_wave_chart = gr.Plot(
+                        _empty_fig("Ask about a spot — its forecast chart appears here"),
+                        label="Wave & wind forecast",
+                    )
+
+            # ------------------------------------------------ tab: charts
+            with gr.Tab("📊 Forecast Charts"):
+                with gr.Row():
+                    chart_spot = gr.Dropdown(choices=spot_choices, value=None, label="Spot")
+                    chart_load_btn = gr.Button("Load charts", variant="primary")
+                with gr.Row():
+                    chart_wave_plot = gr.Plot(label="Wave height · period · wind")
+                with gr.Row():
+                    chart_score_plot = gr.Plot(label="Hourly surf score + components")
+
+            # ------------------------------------------------ tab: rankings
+            with gr.Tab("🏆 Weekly Rankings"):
+                with gr.Row():
+                    rank_region = gr.Dropdown(choices=REGIONS, value="NSW", label="Region")
+                    rank_skill = gr.Dropdown(choices=SKILL_FILTERS, value="all", label="Skill level")
+                    rank_btn = gr.Button("Rank this week", variant="primary")
+                rank_plot = gr.Plot(label="Best scores this week")
+                rank_table = gr.Dataframe(
+                    headers=["Spot", "Region", "Best score", "Best time"],
+                    label="Ranked table",
+                    interactive=False,
+                )
+
+            # ------------------------------------------------ tab: morning report
+            with gr.Tab("📋 Morning Surf Report"):
+                gr.Markdown(
+                    "The fixed **Morning Surf Report** pipeline (daggr): pick a region + "
+                    "skill → find spots → fetch forecasts → score → rank → narrated report "
+                    "with deterministic scores."
+                )
+                gr.HTML(
+                    """<div style="border-radius:12px; border:1px solid #e2e8f0; overflow:hidden;">
+<iframe src="http://127.0.0.1:7861" style="width:100%; height:760px; border:0;"></iframe>
+</div>
+<p><i>If the canvas is empty, start the pipeline app:
+<code>uv run python -m wavereader.daggr_pipeline</code> (it runs alongside this UI on port 7861).</i></p>"""
+                )
+
+        # ------------------------------------------------ events: explore
+        map_skill_filter.change(
+            lambda skill: create_australia_map(skill),
+            inputs=[map_skill_filter],
+            outputs=[map_plot],
+        )
+
+        def show_spot_card(label):
+            return _spot_card(_parse_spot_label(label))
+
+        spot_dropdown.change(show_spot_card, inputs=[spot_dropdown], outputs=[spot_card_md])
+
+        def jump_to_charts(label):
+            spot = _parse_spot_label(label)
+            if spot is None:
+                return gr.update(), gr.update(), gr.update()
+            forecast, scores = _get_spot_data(spot)
+            wave = create_wave_height_chart(forecast, spot.name) if forecast else gr.update()
+            score = create_score_chart(scores, spot.name) if scores else gr.update()
+            return wave, score, gr.update(value=label)
+
+        spot_quick_btn.click(
+            jump_to_charts,
+            inputs=[spot_dropdown],
+            outputs=[chart_wave_plot, chart_score_plot, chart_spot],
+        )
+
+        # ------------------------------------------------ events: chat
+        chat_send.click(
+            chat_submit,
+            inputs=[chat_input, chatbot, provider_radio],
+            outputs=[chatbot, trace_panel, chat_score_chart, chat_wave_chart],
+        )
+        chat_input.submit(
+            chat_submit,
+            inputs=[chat_input, chatbot, provider_radio],
+            outputs=[chatbot, trace_panel, chat_score_chart, chat_wave_chart],
+        )
+
+        # ------------------------------------------------ events: charts tab
+        def load_charts(label):
+            spot = _parse_spot_label(label)
+            if spot is None:
+                return _empty_fig("Pick a spot above"), _empty_fig("Pick a spot above")
+            forecast, scores = _get_spot_data(spot)
+            wave = create_wave_height_chart(forecast, spot.name) if forecast else _empty_fig("No forecast")
+            score = create_score_chart(scores, spot.name) if scores else _empty_fig("No scores")
+            return wave, score
+
+        chart_load_btn.click(load_charts, inputs=[chart_spot], outputs=[chart_wave_plot, chart_score_plot])
+        chart_spot.change(load_charts, inputs=[chart_spot], outputs=[chart_wave_plot, chart_score_plot])
+
+        # ------------------------------------------------ events: rankings
+        def run_ranking(region, skill):
+            skill_arg = None if skill == "all" else skill
+            ranked = tools.rank_spots_this_week(region, skill_arg)
+            fig = create_ranking_chart(ranked, region)
+            table = [
+                [r.get("name"), r.get("region"), round(r.get("best_score") or 0, 1), r.get("best_time")]
+                for r in ranked
+            ]
+            return fig, table
+
+        rank_btn.click(run_ranking, inputs=[rank_region, rank_skill], outputs=[rank_plot, rank_table])
+
+    return demo
+
+
+def main() -> None:
+    _start_background_services()
     demo = build_ui()
-    demo.launch()
+    demo.launch(server_name="0.0.0.0", server_port=7860, show_error=True)
+
+
+if __name__ == "__main__":
+    main()

wavereader/daggr_pipeline.py

@@ -2,15 +2,264 @@
 
 Daggr is beta and has NO conditional branching: this visualises the fixed
 morning pipeline only, never the dynamic chat agent loop.
+
+Pipeline:
+  InputNode(region, skill) → FindSpotsFn → FetchForecastsFn →
+  ScoreForecastsFn → RankSpotsFn → { FormatReportFn (deterministic),
+  InferenceNode (narrates) }
+
+Forecasts/scores flow between nodes keyed by ``"{name}|{region}"`` strings
+(tuple keys don't survive a round-trip through gr.JSON).
 """
 
 from __future__ import annotations
 
+import json
+from typing import Any
+
+import gradio as gr
+from daggr import Graph, FnNode, InputNode, InferenceNode
+
+from wavereader import forecasts, scoring, spots
+
+NARRATION_PROMPT = (
+    "You are a surf forecaster. Given a ranked list of spots with scores, "
+    "write a concise, enthusiastic morning surf report. Keep it under 200 "
+    "words. Include specific times and scores. Be practical and actionable."
+)
+
+
+def _spot_key(spot: dict) -> str:
+    return f"{spot['name']}|{spot['region']}"
+
+
+def _split_key(key: str) -> tuple[str, str]:
+    name, region = key.split("|", 1)
+    return name, region
+
+
+def find_spots_fn(region: str, skill: str | None = None) -> dict[str, Any]:
+    """Find breaks in a region with optional skill filter.
+
+    The UI's "all" sentinel means no filter — ``spots.find_spots`` does a
+    substring skill match, so "all" must become None.
+    """
+    if skill in (None, "", "all"):
+        skill = None
+    breaks = spots.find_spots(region=region, skill=skill, limit=20)
+    return {
+        "spots": [b.model_dump() for b in breaks],
+        "region": region,
+        "skill": skill,
+    }
+
+
+def _find_spots_node_fn(region: str, skill: str | None = None):
+    """daggr adapter: FnNode maps tuple returns to output ports in order.
+
+    ``find_spots_fn`` returns a dict for direct/test use; daggr's executor
+    treats a dict return as a single value for the first port only, so the
+    node unwraps it into ``(spots, region, skill)``.
+    """
+    result = find_spots_fn(region, skill)
+    return result["spots"], result["region"], result["skill"]
+
 
-def build_pipeline() -> object:
-    """Assemble the fixed morning-report DAG.
+def fetch_forecasts_fn(spots_list: list[dict]) -> dict[str, Any]:
+    """Fetch forecasts for all spots."""
+    forecasts_map = {}
+    for spot in spots_list:
+        fc = forecasts.get_forecast(
+            spot["coordinates"]["lat"], spot["coordinates"]["lng"], days=7
+        )
+        forecasts_map[_spot_key(spot)] = fc
+    return {"forecasts": forecasts_map}
 
-    TODO: nodes for pick-region -> fetch forecasts -> score -> summarise,
-    rendered on the daggr canvas.
+
+def score_forecasts_fn(forecasts_map: dict, spots_list: list[dict]) -> dict[str, Any]:
+    """Score forecasts for all spots."""
+    scored = {}
+    for spot in spots_list:
+        key = _spot_key(spot)
+        if key in forecasts_map:
+            scored[key] = scoring.score_week(forecasts_map[key], spot)
+    return {"scored": scored}
+
+
+def rank_spots_fn(scored: dict, spots_list: list[dict]) -> dict[str, Any]:
+    """Rank spots by best score from the already-scored hourly rows.
+
+    Scores were computed in the previous node keyed by ``"{name}|{region}"``
+    strings (tuple keys don't survive a round-trip through gr.JSON), so rank
+    directly here rather than re-entering ``scoring.rank_spots_this_week``.
     """
-    raise NotImplementedError
+    ranked = []
+    for spot in spots_list:
+        key = _spot_key(spot)
+        hours = scored.get(key) or []
+        best_hour = max(hours, key=lambda h: h["score"]) if hours else None
+        ranked.append(
+            {
+                "name": spot["name"],
+                "region": spot["region"],
+                "best_score": best_hour["score"] if best_hour else 0.0,
+                "best_time": best_hour["time"] if best_hour else None,
+                "best_hour": best_hour,
+            }
+        )
+    ranked.sort(key=lambda x: x["best_score"], reverse=True)
+    return {"ranked": ranked}
+
+
+def format_report_fn(ranked: list[dict], region: str) -> dict[str, str]:
+    """Format the deterministic morning surf report (authoritative output)."""
+    if not ranked:
+        return {"report": f"No spots found in {region}."}
+
+    lines = [f"☀️ **Morning Surf Report — {region}**", ""]
+    lines.append("📅 Top picks for this week:")
+    lines.append("")
+
+    for i, spot in enumerate(ranked[:5], 1):
+        best = spot["best_hour"]
+        time_str = best["time"].split("T")[1][:5] if best and best.get("time") else "N/A"
+        score = best["score"] if best else 0
+        comps = best["components"] if best else {}
+
+        emoji = "🟢" if score >= 7 else "🟡" if score >= 5 else "🔴"
+        lines.append(f"{i}. {emoji} **{spot['name']}** — Score: {score:.1f}/10 @ {time_str}")
+        lines.append(
+            f"   Swell: {comps.get('swell_size') or 0:.1f} | "
+            f"Dir: {comps.get('swell_direction') if comps.get('swell_direction') is not None else 'n/a'} | "
+            f"Wind: {comps.get('wind') or 0:.1f} | Period: {comps.get('period') or 0:.1f}"
+        )
+
+    lines.append("")
+    lines.append("💡 *Scores are deterministic (0-10) based on ideal swell/wind/period for each break.*")
+    lines.append("*Tide is qualitative only — check local tide charts.*")
+
+    return {"report": "\n".join(lines)}
+
+
+def _narration_preprocess(inputs: dict) -> dict[str, str]:
+    """Flatten ranked spots into a single text-generation prompt.
+
+    daggr's text-generation path calls ``client.text_generation(prompt)``
+    with the first input value — an OpenAI chat payload would be dumped in
+    as a list of dicts, so keep it a plain string.
+    """
+    prompt = (
+        f"{NARRATION_PROMPT}\n\n"
+        f"Region: {inputs['region']}\n"
+        f"Ranked spots: {json.dumps(inputs['ranked'][:5], default=str)}\n\n"
+        "Write a morning surf report."
+    )
+    return {"prompt": prompt}
+
+
+def _narration_postprocess(result: Any) -> dict[str, str]:
+    """Extract text from a text_generation result (str or list of dicts)."""
+    if isinstance(result, str):
+        text = result
+    elif isinstance(result, list) and result and isinstance(result[0], dict):
+        text = result[0].get("generated_text", str(result))
+    else:
+        text = str(result)
+    return {"ai_report": text}
+
+
+def build_pipeline() -> Graph:
+    """Assemble the fixed morning-report DAG."""
+    input_node = InputNode(
+        name="User Input",
+        ports={
+            "region": gr.Dropdown(
+                choices=["NSW", "QLD", "VIC", "WA", "SA", "TAS"],
+                label="Region",
+                value="NSW",
+            ),
+            "skill": gr.Dropdown(
+                choices=["beginner", "intermediate", "advanced", "expert", "all"],
+                label="Skill Level",
+                value="all",
+            ),
+        },
+    )
+
+    find_spots_node = FnNode(
+        _find_spots_node_fn,
+        name="Find Spots",
+        inputs={
+            "region": input_node.region,
+            "skill": input_node.skill,
+        },
+        outputs={"spots": gr.JSON(), "region": gr.Textbox(), "skill": gr.Textbox()},
+    )
+
+    fetch_forecasts_node = FnNode(
+        fetch_forecasts_fn,
+        name="Fetch Forecasts",
+        inputs={"spots_list": find_spots_node.spots},
+        outputs={"forecasts": gr.JSON()},
+    )
+
+    score_forecasts_node = FnNode(
+        score_forecasts_fn,
+        name="Score Forecasts",
+        inputs={
+            "forecasts_map": fetch_forecasts_node.forecasts,
+            "spots_list": find_spots_node.spots,
+        },
+        outputs={"scored": gr.JSON()},
+    )
+
+    rank_spots_node = FnNode(
+        rank_spots_fn,
+        name="Rank Spots",
+        inputs={
+            "scored": score_forecasts_node.scored,
+            "spots_list": find_spots_node.spots,
+        },
+        outputs={"ranked": gr.JSON()},
+    )
+
+    # Narrate with the LLM — narration only; scores stay deterministic.
+    narrate_node = InferenceNode(
+        model="Qwen/Qwen3-Next-80B-A3B-Instruct",
+        name="Narrate Report",
+        inputs={
+            "ranked": rank_spots_node.ranked,
+            "region": find_spots_node.region,
+        },
+        outputs={"ai_report": gr.Markdown()},
+        preprocess=_narration_preprocess,
+        postprocess=_narration_postprocess,
+    )
+
+    format_report_node = FnNode(
+        format_report_fn,
+        name="Format Report",
+        inputs={
+            "ranked": rank_spots_node.ranked,
+            "region": find_spots_node.region,
+        },
+        outputs={"report": gr.Markdown()},
+    )
+
+    graph = Graph("Morning Surf Report", nodes=[input_node])
+    for node in (
+        find_spots_node,
+        fetch_forecasts_node,
+        score_forecasts_node,
+        rank_spots_node,
+        narrate_node,
+        format_report_node,
+    ):
+        graph.add(node)
+
+    return graph
+
+
+if __name__ == "__main__":
+    graph = build_pipeline()
+    graph.launch(host="0.0.0.0", port=7861)

wavereader/forecasts.py

@@ -11,16 +11,21 @@ Two endpoints, merged on ``time``:
   knots for scoring) and ``wind_direction_10m`` (deg).
 
 Grid points snap ~10 km offshore of a spot's coords (Snapper Rocks
--28.173,153.556 resolved to -28.04,153.63). Fetch slightly seaward and
-keep the offset consistent across all spots.
+-28.173,153.556 resolved to -28.04,153.63). Fetch slightly seaward of the
+spot: east-coast breaks shift east, west-coast breaks shift west,
+south-coast breaks (SA/VIC/TAS) shift south.
 
 Cache every response to disk: the demo must survive API flakiness and
-rate limits. Horizon: hourly, 7 days.
+rate limits. Fresh cache (within ``CACHE_TTL_SECONDS``) is served without
+a network call; when the API fails, a stale cache entry is served as a
+fallback rather than raising. Horizon: hourly, 7 days.
 """
 
 from __future__ import annotations
 
 import json
+import os
+import time
 from pathlib import Path
 
 import httpx
@@ -37,35 +42,70 @@ MARINE_HOURLY_FIELDS = (
 )
 WEATHER_HOURLY_FIELDS = ("wind_speed_10m", "wind_direction_10m")
 
-_SNAP_OFFSET = (-0.133, 0.074)
+# ~0.13° is roughly 14 km — enough to move off the coast onto a marine grid point.
+_SEAWARD_OFFSET_DEG = 0.13
 
 CACHE_DIR = Path(__file__).resolve().parent.parent / ".cache" / "forecasts"
+CACHE_TTL_SECONDS = 6 * 3600
+
+
+def _seaward_offset(lat: float, lon: float) -> tuple[float, float]:
+    """Offset a spot's coords toward open ocean so Open-Meteo resolves a marine grid point.
+
+    Direction is inferred from position: Tasmania and the south coast shift
+    south, the east coast (lon >= 147) shifts east, the west coast
+    (lon <= 125) shifts west.
+    """
+    if lat <= -39.5:  # Tasmania: open ocean to the south
+        dlat, dlon = -_SEAWARD_OFFSET_DEG, 0.0
+    elif lon >= 147:  # east coast (QLD/NSW)
+        dlat, dlon = 0.0, _SEAWARD_OFFSET_DEG
+    elif lon <= 125:  # west coast (WA)
+        dlat, dlon = 0.0, -_SEAWARD_OFFSET_DEG
+    else:  # south coast (SA/VIC)
+        dlat, dlon = -_SEAWARD_OFFSET_DEG, 0.0
+    return dlat, dlon
 
 
 def _round_coords(lat: float, lon: float) -> tuple[float, float]:
-    return round(lat + _SNAP_OFFSET[0], 2), round(lon + _SNAP_OFFSET[1], 2)
+    dlat, dlon = _seaward_offset(lat, lon)
+    return round(lat + dlat, 2), round(lon + dlon, 2)
 
 
 def _cache_key(lat: float, lon: float, days: int) -> str:
-    return f"{lat:.2f}_{lon:.2f}_{days}"
+    """Cache key from the *raw* spot coords (offset is a fetch detail only)."""
+    return f"{round(lat, 2):.2f}_{round(lon, 2):.2f}_{days}"
 
 
 def _cache_path(lat: float, lon: float, days: int) -> Path:
     return CACHE_DIR / f"{_cache_key(lat, lon, days)}.json"
 
 
-def _load_cache(lat: float, lon: float, days: int) -> dict | None:
+def _load_cache(lat: float, lon: float, days: int) -> tuple[dict, float] | None:
+    """Return ``(data, fetched_at)`` from disk, or None if absent/corrupt.
+
+    Legacy cache files written before the envelope format are returned with
+    ``fetched_at = 0`` so they still work as a stale fallback.
+    """
     p = _cache_path(lat, lon, days)
-    if p.exists():
-        return json.loads(p.read_text(encoding="utf-8"))
-    return None
+    if not p.exists():
+        return None
+    try:
+        raw = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    if isinstance(raw, dict) and "fetched_at" in raw and "data" in raw:
+        return raw["data"], float(raw["fetched_at"])
+    return raw, 0.0
 
 
 def _save_cache(lat: float, lon: float, days: int, data: dict) -> None:
+    """Write the cache envelope atomically (crash-safe write + rename)."""
     CACHE_DIR.mkdir(parents=True, exist_ok=True)
-    _cache_path(lat, lon, days).write_text(
-        json.dumps(data, ensure_ascii=False), encoding="utf-8"
-    )
+    envelope = {"fetched_at": time.time(), "data": data}
+    tmp = _cache_path(lat, lon, days).with_suffix(".tmp")
+    tmp.write_text(json.dumps(envelope, ensure_ascii=False), encoding="utf-8")
+    os.replace(tmp, _cache_path(lat, lon, days))
 
 
 def _build_normalized(marine: dict, weather: dict) -> dict:
@@ -98,17 +138,8 @@ def _build_normalized(marine: dict, weather: dict) -> dict:
     return {"hourly": frames}
 
 
-def get_forecast(lat: float, lon: float, days: int = 7) -> dict:
-    """Fetch marine + weather hourly data for a coordinate, merged on time.
-
-    Returns a normalised frame: ``{"hourly": [{"time": ..., "wave_height": ...,
-    "wind_speed_10m": ..., ...}, ...]}``.  Disk-cached by rounded coords + days.
-    """
-    rlat, rlon = _round_coords(lat, lon)
-    cached = _load_cache(rlat, rlon, days)
-    if cached is not None:
-        return cached
-
+def _fetch_open_meteo(rlat: float, rlon: float, days: int) -> dict:
+    """Call both Open-Meteo endpoints and return the merged frame."""
     params: dict[str, str | int | float] = {
         "latitude": rlat,
         "longitude": rlon,
@@ -123,14 +154,29 @@ def get_forecast(lat: float, lon: float, days: int = 7) -> dict:
         resp_w.raise_for_status()
         weather = resp_w.json()
 
-    merged = _build_normalized(marine, weather)
-    _save_cache(rlat, rlon, days, merged)
-    return merged
+    return _build_normalized(marine, weather)
 
 
-if __name__ == "__main__":
-    result = get_forecast(-28.173, 153.556, days=2)
-    print(f"Fetched {len(result['hourly'])} hourly rows")
-    if result["hourly"]:
-        print("First:", result["hourly"][0])
-        print("Last:", result["hourly"][-1])
+def get_forecast(lat: float, lon: float, days: int = 7) -> dict:
+    """Fetch marine + weather hourly data for a coordinate, merged on time.
+
+    Returns a normalised frame: ``{"hourly": [{"time": ..., "wave_height": ...,
+    "wind_speed_10m": ..., ...}, ...]}``.  Disk-cached by rounded coords + days:
+    entries younger than ``CACHE_TTL_SECONDS`` are served directly; on a network
+    failure the most recent cache entry (however old) is served as a fallback.
+    Raises only when there is no usable data at all.
+    """
+    rlat, rlon = _round_coords(lat, lon)
+    cached = _load_cache(lat, lon, days)
+    if cached is not None and time.time() - cached[1] < CACHE_TTL_SECONDS:
+        return cached[0]
+
+    try:
+        merged = _fetch_open_meteo(rlat, rlon, days)
+    except (httpx.HTTPError, KeyError, ValueError):
+        if cached is not None:
+            return cached[0]
+        raise
+
+    _save_cache(lat, lon, days, merged)
+    return merged

wavereader/scoring.py

@@ -1,130 +1,189 @@
-"""Deterministic surf-quality scoring.
+"""Deterministic surf-quality scoring module.
 
-The LLM never owns numbers: every score and ranking comes from here.
-Produces a 0-10 quality score per hour plus a component breakdown
-(swell size vs ideal, swell direction match, wind speed + offshore
-alignment, wave period). Tide is qualitative only — Open-Meteo has no
-tides, so it never feeds the numeric score.
+Provides non-linear, robust surf quality evaluations calibrated by surfer skill level.
+Calculates component scores (0.0 to 10.0) using continuous curves and physics-aware decay.
 """
 
 from __future__ import annotations
 
 import math
+from typing import TypedDict, Any, Dict, List, Tuple, Optional
 
-# ---- 16-point compass → degrees (midpoint) ----
+# ---- 16-Point Compass Reference ----
 
 _COMPASS_DEG: dict[str, float] = {
-    "N": 0, "NNE": 22.5, "NE": 45, "ENE": 67.5,
-    "E": 90, "ESE": 112.5, "SE": 135, "SSE": 157.5,
-    "S": 180, "SSW": 202.5, "SW": 225, "WSW": 247.5,
-    "W": 270, "WNW": 292.5, "NW": 315, "NNW": 337.5,
+    "N": 0.0, "NNE": 22.5, "NE": 45.0, "ENE": 67.5,
+    "E": 90.0, "ESE": 112.5, "SE": 135.0, "SSE": 157.5,
+    "S": 180.0, "SSW": 202.5, "SW": 225.0, "WSW": 247.5,
+    "W": 270.0, "WNW": 292.5, "NW": 315.0, "NNW": 337.5,
 }
 
-# Weights for the four components → sum to 1.0
 _WEIGHTS = {
-    "swell_size": 0.25,
+    "swell_size": 0.30,
     "swell_direction": 0.20,
     "wind": 0.30,
-    "period": 0.25,
+    "period": 0.20,
 }
 
+# Skill Profile Thresholds (values in feet, knots, seconds)
+_SKILL_PROFILES: dict[str, dict[str, Any]] = {
+    "beginner": {
+        "comfort_size_min_ft": 1.0,
+        "comfort_size_max_ft": 3.5,
+        "max_safe_size_ft": 4.5,
+        "max_wind_kt": 12.0,
+        "ideal_period_max_s": 12.0,
+    },
+    "intermediate": {
+        "comfort_size_min_ft": 2.0,
+        "comfort_size_max_ft": 6.5,
+        "max_safe_size_ft": 8.5,
+        "max_wind_kt": 18.0,
+        "ideal_period_max_s": 16.0,
+    },
+    "advanced": {
+        "comfort_size_min_ft": 3.0,
+        "comfort_size_max_ft": 12.0,
+        "max_safe_size_ft": 18.0,
+        "max_wind_kt": 25.0,
+        "ideal_period_max_s": 22.0,
+    },
+    "expert": {
+        "comfort_size_min_ft": 4.0,
+        "comfort_size_max_ft": 30.0,
+        "max_safe_size_ft": 50.0,
+        "max_wind_kt": 35.0,
+        "ideal_period_max_s": 25.0,
+    },
+}
 
-def _dir_to_deg(direction: str) -> float:
-    """Parse a cardinal direction string to degrees.
+SKILL_LEVELS = tuple(_SKILL_PROFILES.keys())
+_DEFAULT_SKILL_LEVEL = "intermediate"
 
-    Handles single compass points ('SW'), compound ranges ('W/SW'),
-    and comma-separated values ('SE, S, E') by averaging the endpoints.
-    """
-    # Normalize separators: replace commas with slashes
-    direction = direction.replace(",", "/")
-    parts = direction.replace(" ", "").split("/")
-    degs = [_COMPASS_DEG[p] for p in parts]
-    return sum(degs) / len(degs)
+# ---- Helpers ----
 
+def _dir_to_deg(direction: str) -> float:
+    """Parses cardinal strings, slash-separated, or 'to' directions to degrees."""
+    normalized = direction.replace(",", "/").replace(" to ", "/").replace(" ", "").upper()
+    parts = normalized.split("/")
+    degs = [_COMPASS_DEG[p] for p in parts if p in _COMPASS_DEG]
+    if not degs:
+        raise ValueError(f"Invalid compass direction input: {direction!r}")
+    
+    # Cyclic mean for angles
+    sin_sum = sum(math.sin(math.radians(d)) for d in degs)
+    cos_sum = sum(math.cos(math.radians(d)) for d in degs)
+    mean_deg = math.degrees(math.atan2(sin_sum, cos_sum)) % 360
+    return round(mean_deg, 1)
 
-def _angular_diff(a: float, b: float) -> float:
-    """Shortest angular distance between two bearings in degrees."""
-    d = abs(a - b) % 360
-    return d if d <= 180 else 360 - d
 
+def _angular_diff(a: float, b: float) -> float:
+    """Calculates shortest arc distance between two bearings in degrees."""
+    d = abs(a - b) % 360.0
+    return d if d <= 180.0 else 360.0 - d
+
+
+def _gaussian_decay(value: float, target: float, sigma: float) -> float:
+    """Smooth Gaussian decay yielding 1.0 at target and trailing to 0.0."""
+    return math.exp(-((value - target) ** 2) / (2 * (sigma ** 2)))
+
+
+# ---- Core Scoring Components ----
+
+def _score_swell_size(wave_height_m: float, spot: dict, skill_level: str) -> float:
+    """Evaluates swell size considering spot ideals and surfer safety constraints."""
+    profile = _SKILL_PROFILES[skill_level]
+    wave_height_ft = wave_height_m * 3.28084
+    
+    spot_ideal = spot["ideal_swell"]
+    spot_min_ft = float(spot_ideal["size_ft_min"])
+    spot_max_ft = float(spot_ideal["size_ft_max"])
+
+    # 1. Spot Suitability (Does the spot work?)
+    if spot_min_ft <= wave_height_ft <= spot_max_ft:
+        spot_score = 10.0
+    elif wave_height_ft < spot_min_ft:
+        sigma = max(1.0, spot_min_ft * 0.4)
+        spot_score = 10.0 * _gaussian_decay(wave_height_ft, spot_min_ft, sigma)
+    else:
+        sigma = max(1.5, spot_max_ft * 0.5)
+        spot_score = 10.0 * _gaussian_decay(wave_height_ft, spot_max_ft, sigma)
+
+    # 2. Safety & Comfort Filter
+    comf_min = profile["comfort_size_min_ft"]
+    comf_max = profile["comfort_size_max_ft"]
+    max_safe = profile["max_safe_size_ft"]
+
+    if wave_height_ft > max_safe:
+        # Zero tolerance for dangerous wave heights relative to skill
+        return 0.0
+    
+    skill_mult = 1.0
+    if wave_height_ft < comf_min:
+        skill_mult = max(0.2, wave_height_ft / comf_min)
+    elif wave_height_ft > comf_max:
+        # Smooth penalty down to zero at max_safe_size
+        overage = wave_height_ft - comf_max
+        allowed_headroom = max_safe - comf_max
+        skill_mult = max(0.0, 1.0 - (overage / allowed_headroom) ** 1.5)
 
-def _score_swell_size(wave_height_m: float, spot: dict) -> float:
-    """Score 0-10 based on how close wave_height_m is to the ideal range.
-
-    Ideal size is stored in feet; convert to metres for comparison.
-    Perfect score (10) inside the range, linear decay to 0 at ±30 % outside.
-    """
-    ideal = spot["ideal_swell"]
-    min_m = ideal["size_ft_min"] * 0.3048
-    max_m = ideal["size_ft_max"] * 0.3048
-
-    margin = max(max_m - min_m, 0.1)
-    low_cutoff = min_m - margin
-    high_cutoff = max_m + margin
-
-    if low_cutoff <= wave_height_m <= high_cutoff:
-        if min_m <= wave_height_m <= max_m:
-            return 10.0
-        # Partial credit inside the extended range
-        if wave_height_m < min_m:
-            return 10.0 - 10.0 * (min_m - wave_height_m) / margin
-        return 10.0 - 10.0 * (wave_height_m - max_m) / margin
-
-    return max(
-        10.0 * (1.0 - (low_cutoff - wave_height_m) / margin)
-        if wave_height_m < low_cutoff
-        else 10.0 * (1.0 - (wave_height_m - high_cutoff) / margin),
-        0.0,
-    )
+    return round(spot_score * skill_mult, 2)
 
 
 def _score_swell_direction(wave_dir_deg: float, spot: dict) -> float:
-    """Score 0-10 based on angular match between wave direction and ideal.
-
-    0° difference → 10; 90° → ~3; 180° → 0.
-    """
+    """Calculates directional match relative to optimal spot window."""
     ideal_deg = _dir_to_deg(spot["ideal_swell"]["direction"])
     diff = _angular_diff(wave_dir_deg, ideal_deg)
-    return max(0.0, 10.0 - (diff / 180.0) * 10.0)
+    
+    # Half-width tolerance angle before severe drop-off (e.g., 45 degrees)
+    tolerance_deg = 45.0
+    score = 10.0 * _gaussian_decay(diff, 0.0, tolerance_deg / 1.5)
+    return max(0.0, min(10.0, score))
 
 
-def _score_wind(wind_speed_kt: float, wind_dir_deg: float, spot: dict) -> float:
-    """Score 0-10 combining wind-speed favour and direction (offshore) alignment.
+def _score_wind(
+    wind_speed_kt: float,
+    wind_dir_deg: float,
+    spot: dict,
+    skill_level: str = _DEFAULT_SKILL_LEVEL,
+) -> float:
+    """Scores wind as the mean of a speed score and a direction score.
 
-    Offshore wind (matching the ideal direction) is best.
-    Speed score peaks at ~50 % of strength_kt_max and falls to 0 at max.
-    Direction score follows the same angular model as swell direction.
+    Speed: glassy (<= 5 kt) is always perfect; above the tolerable limit
+    (the spot's ``strength_kt_max``, capped by the skill profile) it scores 0.
+    Direction: cosine falloff from perfect offshore to absolute onshore.
     """
-    ideal = spot["ideal_wind"]
-    ideal_dir_deg = _dir_to_deg(ideal["direction"])
+    profile_max = _SKILL_PROFILES[skill_level]["max_wind_kt"]
+    spot_max = float(spot["ideal_wind"]["strength_kt_max"])
+    limit = min(spot_max, profile_max)
 
-    # Speed: 10 at ≤ half max, linear to 0 at max
-    speed_score = max(0.0, 10.0 - 10.0 * wind_speed_kt / ideal["strength_kt_max"])
-    speed_score = min(speed_score, 10.0)
+    offshore_dir_deg = _dir_to_deg(spot["ideal_wind"]["direction"])
+    diff = _angular_diff(wind_dir_deg, offshore_dir_deg)
+    dir_score = 10.0 * max(0.0, math.cos(math.radians(diff / 2.0)))
 
-    # Direction: angular difference from ideal offshore direction
-    dir_diff = _angular_diff(wind_dir_deg, ideal_dir_deg)
-    dir_score = max(0.0, 10.0 - (dir_diff / 180.0) * 10.0)
+    if wind_speed_kt <= 5.0:
+        speed_score = 10.0  # glassy regardless of direction
+    elif wind_speed_kt <= limit:
+        speed_score = 10.0
+    else:
+        speed_score = 0.0
 
-    return speed_score * 0.5 + dir_score * 0.5
+    return round((speed_score + dir_score) / 2.0, 2)
 
 
 def _score_period(period_s: float) -> float:
-    """Score 0-10 for wave period.
+    """Evaluates swell period quality: 0 below 4 s, 10 from 14 s up.
 
-    Longer periods = better quality. 8 s → ~6, 10 s → 8, 14 s+ → 10,
-    falling off after ~16 s.
+    Long groundswell is never penalised — there is no falloff above 14 s.
     """
-    if period_s >= 14.0:
-        return 10.0
     if period_s <= 4.0:
         return 0.0
-    if period_s >= 10.0:
-        # smooth ramp 10→14
-        return 8.0 + 2.0 * (period_s - 10.0) / 4.0
-    # ramp 4→10
-    return 6.0 * (period_s - 4.0) / 6.0
+    if period_s >= 14.0:
+        return 10.0
+    return round(10.0 * (period_s - 4.0) / 10.0, 2)
+
 
+# ---- Main Interface Functions ----
 
 def score_hour(
     wave_height_m: float,
@@ -132,81 +191,107 @@ def score_hour(
     wind_speed_kt: float,
     wind_direction_deg: float,
     spot: dict,
-) -> dict:
-    """Score one hour against a spot's ideal profile.
-
-    Returns a dict with the composite 0-10 ``score``, a per-component
-    ``components`` breakdown, and the raw inputs for the UI.
-    """
-    c_size = _score_swell_size(wave_height_m, spot)
-    c_dir = _score_swell_direction(wind_direction_deg, spot)
-    c_wind = _score_wind(wind_speed_kt, wind_direction_deg, spot)
+    wave_direction_deg: Optional[float] = None,
+    skill_level: str = _DEFAULT_SKILL_LEVEL,
+) -> dict[str, Any]:
+    """Computes composite surf score (0-10) for a given hour and skill tier."""
+    if skill_level not in _SKILL_PROFILES:
+        raise ValueError(f"Invalid skill_level {skill_level!r}. Expected one of {SKILL_LEVELS}")
+
+    c_size = _score_swell_size(wave_height_m, spot, skill_level)
+    c_dir = (
+        _score_swell_direction(wave_direction_deg, spot)
+        if wave_direction_deg is not None
+        else None
+    )
+    c_wind = _score_wind(wind_speed_kt, wind_direction_deg, spot, skill_level)
     c_period = _score_period(wave_period_s)
 
-    total = (
-        c_size * _WEIGHTS["swell_size"]
-        + c_dir * _WEIGHTS["swell_direction"]
-        + c_wind * _WEIGHTS["wind"]
-        + c_period * _WEIGHTS["period"]
+    components: dict[str, Optional[float]] = {
+        "swell_size": round(c_size, 2),
+        "swell_direction": round(c_dir, 2) if c_dir is not None else None,
+        "wind": round(c_wind, 2),
+        "period": round(c_period, 2),
+    }
+
+    # Weight redistribution when optional components are missing
+    active_weights = {k: v for k, v in _WEIGHTS.items() if components[k] is not None}
+    weight_sum = sum(active_weights.values())
+
+    composite = sum(
+        components[k] * (weight / weight_sum) # type: ignore
+        for k, weight in active_weights.items()
     )
 
     return {
-        "score": round(total, 2),
-        "components": {
-            "swell_size": round(c_size, 2),
-            "swell_direction": round(c_dir, 2),
-            "wind": round(c_wind, 2),
-            "period": round(c_period, 2),
-        },
+        "score": round(composite, 2),
+        "components": components,
+        "skill_level": skill_level,
         "wave_height_m": wave_height_m,
         "wave_period_s": wave_period_s,
         "wind_speed_kt": wind_speed_kt,
         "wind_direction_deg": wind_direction_deg,
+        "wave_direction_deg": wave_direction_deg,
     }
 
 
-def score_week(forecast: dict, spot: dict) -> list[dict]:
-    """Score every hour of a 7-day forecast for one spot.
+def score_week(
+    forecast: dict, spot: dict, skill_level: str = _DEFAULT_SKILL_LEVEL
+) -> list[dict[str, Any]]:
+    """Evaluates every hour in a forecast payload for a target spot."""
+    rows = forecast.get("hourly", [])
+    results = []
 
-    ``forecast`` is the normalised ``{"hourly": [...]}`` frame from
-    ``forecasts.py``.  Each hour row must carry ``time``,
-    ``wave_height``, ``wave_period``, ``wind_speed_10m`` and
-    ``wind_direction_10m``.
-    """
-    rows = forecast["hourly"]
-    results: list[dict] = []
     for row in rows:
+        wave_height = row.get("wave_height")
+        wave_period = row.get("wave_period")
+        wind_speed = row.get("wind_speed_10m")
+        wind_dir = row.get("wind_direction_10m")
+
+        if None in (wave_height, wave_period, wind_speed, wind_dir):
+            continue
+
         scored = score_hour(
-            wave_height_m=float(row["wave_height"]),
-            wave_period_s=float(row["wave_period"]),
-            wind_speed_kt=float(row["wind_speed_10m"]) * 0.539957,  # km/h → kt
-            wind_direction_deg=float(row["wind_direction_10m"]),
+            wave_height_m=float(wave_height),
+            wave_period_s=float(wave_period),
+            wind_speed_kt=float(wind_speed) * 0.539957,  # km/h to knots conversion
+            wind_direction_deg=float(wind_dir),
             spot=spot,
+            wave_direction_deg=float(row["wave_direction"]) if row.get("wave_direction") is not None else None,
+            skill_level=skill_level,
         )
         scored["time"] = row["time"]
         results.append(scored)
+
     return results
 
 
-def rank_spots_this_week(forecasts: dict, spots_list: list[dict]) -> list[dict]:
-    """Rank spots by their best single-hour score across the week.
+def rank_spots_this_week(
+    forecasts: dict[tuple[str, str], dict],
+    spots_list: list[dict],
+    skill_level: str = _DEFAULT_SKILL_LEVEL,
+) -> list[dict[str, Any]]:
+    """Ranks provided spots by their maximum achievable hourly score."""
+    ranked = []
 
-    ``forecasts`` maps ``(name, region)`` → normalised forecast frame.
-    Returns entries sorted by best score descending.
-    """
-    ranked: list[dict] = []
     for spot in spots_list:
         key = (spot["name"], spot["region"])
         if key not in forecasts:
             continue
-        hours = score_week(forecasts[key], spot)
-        best = max(hours, key=lambda h: h["score"]) if hours else None
-        ranked.append({
-            "name": spot["name"],
-            "region": spot["region"],
-            "best_score": best["score"] if best else 0.0,
-            "best_time": best["time"] if best else None,
-            "best_hour": best,
-        })
+
+        hours = score_week(forecasts[key], spot, skill_level=skill_level)
+        best_hour = max(hours, key=lambda h: h["score"]) if hours else None
+
+        ranked.append(
+            {
+                "name": spot["name"],
+                "region": spot["region"],
+                "skill_level": skill_level,
+                "best_score": best_hour["score"] if best_hour else 0.0,
+                "best_time": best_hour["time"] if best_hour else None,
+                "best_hour": best_hour,
+            }
+        )
+
     ranked.sort(key=lambda x: x["best_score"], reverse=True)
     return ranked

wavereader/spots.py

@@ -52,11 +52,6 @@ class IdealSwell(BaseModel):
     size_ft_max: float
     direction: str
 
-    @field_validator("size_ft_min")
-    @classmethod
-    def size_min_lt_max(cls, v: float) -> float:
-        return v
-
     @model_validator(mode="after")
     def check_swell_sizes(self) -> "IdealSwell":
         if self.size_ft_min >= self.size_ft_max:
@@ -124,10 +119,6 @@ class Break(BaseModel):
         return v
 
 
-def _load_raw() -> list[dict]:
-    return json.loads(DATA_PATH.read_text(encoding="utf-8"))
-
-
 def load_breaks(path: Path | str | None = None) -> list[Break]:
     """Load and validate ``data/break_details.json``.
 

wavereader/tools.py

@@ -1,47 +1,273 @@
-"""Agent tools: the function schemas handed to the LLM.
+"""Agent tools: forecast/score/knowledge lookups plus matplotlib plot builders.
 
-Tools are thin wrappers over spots.py / forecasts.py / scoring.py — the
-model chooses them, the deterministic modules compute the values.
+Plain functions resolve a spot by ``(name, region)`` and delegate to
+``forecasts``/``scoring``/``spots``; the smolagents ``Tool`` subclasses below
+expose them to the CodeAgent. The LLM never computes numbers itself.
 """
 
-from __future__ import annotations
-
+import base64
+import io
+import matplotlib
+matplotlib.use("Agg")  # Use non-interactive backend for server-side rendering
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+from smolagents import Tool
 from wavereader import forecasts, scoring, spots
 
-TOOL_SCHEMAS = (
-    "get_forecast",
-    "score_week",
-    "find_spots",
-    "get_spot_knowledge",
-    "rank_spots_this_week",
-)
+# Configure Seaborn global styling
+sns.set_theme(style="whitegrid", palette="muted")
+
+
+def _encode_fig_to_base64(fig) -> str:
+    """Helper to convert a matplotlib figure to base64 string."""
+    buffer = io.BytesIO()
+    fig.savefig(buffer, format="png", bbox_inches="tight", dpi=150)
+    buffer.seek(0)
+    encoded = base64.b64encode(buffer.getvalue()).decode("utf-8")
+    plt.close(fig)
+    return encoded
+
+
+def draw_directional_arrows(ax, x_coords, y_coords, degrees, color="black"):
+    """Annotate plot points with direction arrows pointing towards the direction vector."""
+    for x, y, deg in zip(x_coords, y_coords, degrees):
+        if pd.isna(deg):
+            continue
+        # Convert degrees to radians (standard meteorology: 0° N, 90° E)
+        rad = np.radians(90 - deg)
+        dx = np.cos(rad) * 0.4
+        dy = np.sin(rad) * 0.4
+        ax.annotate(
+            "",
+            xy=(x + dx, y + dy),
+            xytext=(x - dx, y - dy),
+            arrowprops=dict(
+                arrowstyle="->",
+                color=color,
+                lw=1.5,
+                mutation_scale=12,
+            ),
+        )
+
+
+def plot_daily_surf_overview(spot_name: str, region: str) -> dict:
+    s = spots.get_spot(spot_name, region)
+    if s is None:
+        return {"error": f"Spot '{spot_name}' ({region}) not found"}
+
+    forecast = forecasts.get_forecast(s.coordinates.lat, s.coordinates.lng)
+    scores = scoring.score_week(forecast, s.model_dump())
+
+    df = pd.DataFrame(scores)
+
+    # Dynamic date field resolution to prevent KeyError
+    date_col = next((col for col in ["date", "day", "datetime", "timestamp"] if col in df.columns), None)
+    if date_col:
+        df["date_label"] = pd.to_datetime(df[date_col]).dt.strftime("%a %b %d")
+    else:
+        df["date_label"] = [f"Day {i+1}" for i in range(len(df))]
+
+    fig, axes = plt.subplots(3, 1, figsize=(10, 8), sharex=True)
+    fig.suptitle(
+        f"7-Day Surf Overview: {spot_name.title()} ({region.upper()})",
+        fontsize=16,
+        fontweight="bold",
+    )
+
+    # 1. Overall Daily Score
+    sns.barplot(
+        data=df,
+        x="date_label",
+        y="score",
+        ax=axes[0],
+        palette="Blues_d",
+        hue="date_label",
+        legend=False,
+    )
+    axes[0].set_ylabel("Overall Score (0-10)", fontweight="bold")
+    axes[0].set_ylim(0, 10)
+    for p in axes[0].patches:
+        axes[0].annotate(
+            f"{p.get_height():.1f}",
+            (p.get_x() + p.get_width() / 2.0, p.get_height()),
+            ha="center",
+            va="center",
+            xytext=(0, 5),
+            textcoords="offset points",
+            fontweight="bold",
+        )
+
+    # 2. Daily Swell Size & Direction
+    sns.lineplot(
+        data=df,
+        x="date_label",
+        y="swell_height",
+        ax=axes[1],
+        marker="o",
+        color="teal",
+        linewidth=2.5,
+    )
+    if "swell_direction" in df.columns:
+        draw_directional_arrows(
+            axes[1],
+            range(len(df)),
+            df["swell_height"],
+            df["swell_direction"],
+            color="darkslategrey",
+        )
+    axes[1].set_ylabel("Swell Height (m)", fontweight="bold")
+
+    # 3. Daily Wind Speed & Direction
+    sns.lineplot(
+        data=df,
+        x="date_label",
+        y="wind_speed",
+        ax=axes[2],
+        marker="s",
+        color="crimson",
+        linewidth=2.5,
+    )
+    if "wind_direction" in df.columns:
+        draw_directional_arrows(
+            axes[2],
+            range(len(df)),
+            df["wind_speed"],
+            df["wind_direction"],
+            color="darkred",
+        )
+    axes[2].set_ylabel("Wind Speed (kts)", fontweight="bold")
+    axes[2].set_xlabel("Date", fontweight="bold")
+
+    plt.xticks(rotation=15)
+    plt.tight_layout()
+    return {"image_base64": _encode_fig_to_base64(fig), "format": "png"}
+
+
+def plot_hourly_surf_drilldown(
+    spot_name: str, region: str, date_str: str | None = None
+) -> dict:
+    s = spots.get_spot(spot_name, region)
+    if s is None:
+        return {"error": f"Spot '{spot_name}' ({region}) not found"}
+
+    forecast = forecasts.get_forecast(s.coordinates.lat, s.coordinates.lng)
+
+    # Safely retrieve hourly data structure
+    hourly_raw = forecast.get("hourly") or forecast.get("forecast", [])
+    df = pd.DataFrame(hourly_raw)
+    if df.empty:
+        return {"error": "No hourly forecast data available"}
+
+    # Dynamic timestamp field resolution to prevent KeyError
+    ts_col = next((col for col in ["timestamp", "time", "date", "datetime"] if col in df.columns), None)
+    if ts_col is None:
+        return {"error": "No valid timestamp field found in hourly data"}
+
+    df["parsed_timestamp"] = pd.to_datetime(df[ts_col])
+
+    # Target specific date or default to the first available date
+    if date_str:
+        target_date = pd.to_datetime(date_str).date()
+        df = df[df["parsed_timestamp"].dt.date == target_date]
+    else:
+        df = df[df["parsed_timestamp"].dt.date == df["parsed_timestamp"].dt.date.iloc[0]]
+
+    if df.empty:
+        return {"error": f"No data found for date {date_str}"}
+
+    df["hour_str"] = df["parsed_timestamp"].dt.strftime("%H:%M")
+
+    fig, axes = plt.subplots(3, 1, figsize=(12, 9), sharex=True)
+    display_date = df["parsed_timestamp"].dt.strftime("%Y-%m-%d").iloc[0]
+    fig.suptitle(
+        f"Hourly Drilldown for {spot_name.title()} ({display_date})",
+        fontsize=16,
+        fontweight="bold",
+    )
+
+    # 1. Hourly Scores
+    sns.lineplot(
+        data=df,
+        x="hour_str",
+        y="score",
+        ax=axes[0],
+        color="purple",
+        marker="o",
+        linewidth=2,
+    )
+    axes[0].fill_between(
+        df["hour_str"], df["score"], color="purple", alpha=0.15
+    )
+    axes[0].set_ylabel("Score (0-10)", fontweight="bold")
+    axes[0].set_ylim(0, 10)
+
+    # 2. Hourly Swell Size & Direction
+    sns.lineplot(
+        data=df,
+        x="hour_str",
+        y="swell_height",
+        ax=axes[1],
+        color="dodgerblue",
+        marker="o",
+    )
+    if "swell_direction" in df.columns:
+        draw_directional_arrows(
+            axes[1],
+            range(len(df)),
+            df["swell_height"],
+            df["swell_direction"],
+            color="navy",
+        )
+    axes[1].set_ylabel("Swell (m)", fontweight="bold")
+
+    # 3. Hourly Wind Speed & Direction
+    sns.lineplot(
+        data=df,
+        x="hour_str",
+        y="wind_speed",
+        ax=axes[2],
+        color="orangered",
+        marker="o",
+    )
+    if "wind_direction" in df.columns:
+        draw_directional_arrows(
+            axes[2],
+            range(len(df)),
+            df["wind_speed"],
+            df["wind_direction"],
+            color="darkred",
+        )
+    axes[2].set_ylabel("Wind (kts)", fontweight="bold")
+    axes[2].set_xlabel("Time", fontweight="bold")
+
+    plt.xticks(rotation=45)
+    plt.tight_layout()
+    return {"image_base64": _encode_fig_to_base64(fig), "format": "png"}
 
 
 def get_forecast(spot_name: str, region: str) -> dict:
-    """Hourly marine + wind forecast for a named spot."""
     s = spots.get_spot(spot_name, region)
     if s is None:
         return {"error": f"Spot '{spot_name}' ({region}) not found"}
     return forecasts.get_forecast(s.coordinates.lat, s.coordinates.lng)
 
 
-def score_week(spot_name: str, region: str) -> list[dict]:
-    """Hour-by-hour surf scores for the next 7 days at a spot."""
+def score_week(spot_name: str, region: str) -> dict | list[dict]:
     s = spots.get_spot(spot_name, region)
     if s is None:
-        return []
+        return {"error": f"Spot '{spot_name}' ({region}) not found"}
     forecast = forecasts.get_forecast(s.coordinates.lat, s.coordinates.lng)
     return scoring.score_week(forecast, s.model_dump())
 
 
 def find_spots(query: str = "", skill: str | None = None, limit: int = 10) -> list[dict]:
-    """Search breaks by name/region with optional skill filter."""
     results = spots.find_spots(query=query, skill=skill, limit=limit)
     return [b.model_dump() for b in results]
 
 
 def get_spot_knowledge(spot_name: str, region: str) -> dict:
-    """Knowledge-base profile for a spot (ideal swell/wind/tide)."""
     s = spots.get_spot(spot_name, region)
     if s is None:
         return {"error": f"Spot '{spot_name}' ({region}) not found"}
@@ -49,15 +275,174 @@ def get_spot_knowledge(spot_name: str, region: str) -> dict:
 
 
 def rank_spots_this_week(region: str, skill: str | None = None) -> list[dict]:
-    """Rank spots in a region by their best score this week."""
     spots_list = spots.find_spots(region=region, skill=skill)
     if not spots_list:
         return []
-    forecasts_map: dict[tuple[str, str], dict] = {}
+    forecasts_map = {}
     for b in spots_list:
         d = forecasts.get_forecast(b.coordinates.lat, b.coordinates.lng)
         forecasts_map[(b.name, b.region)] = d
     return scoring.rank_spots_this_week(
         forecasts_map,
         [b.model_dump() for b in spots_list],
-    )
+    )
+
+
+class GetForecastTool(Tool):
+    name = "get_forecast"
+    description = "Retrieve the wave forecast for a specific surf spot."
+    inputs = {
+        "spot_name": {
+            "type": "string",
+            "description": "Name of the surf spot.",
+        },
+        "region": {
+            "type": "string",
+            "description": "Region or state code where the spot is located (e.g., 'QLD').",
+        },
+    }
+    output_type = "object"
+
+    def forward(self, spot_name: str, region: str) -> dict:
+        return get_forecast(spot_name=spot_name, region=region)
+
+
+class ScoreWeekTool(Tool):
+    name = "score_week"
+    description = "Score the conditions of a surf spot for the upcoming week based on its forecast."
+    inputs = {
+        "spot_name": {
+            "type": "string",
+            "description": "Name of the surf spot.",
+        },
+        "region": {
+            "type": "string",
+            "description": "Region or state code where the spot is located.",
+        },
+    }
+    output_type = "object"
+
+    def forward(self, spot_name: str, region: str) -> dict | list[dict]:
+        return score_week(spot_name=spot_name, region=region)
+
+
+class FindSpotsTool(Tool):
+    name = "find_spots"
+    description = "Search for surf spots based on query, skill level, and limit."
+    inputs = {
+        "query": {
+            "type": "string",
+            "description": "Search query or region for surf spots. Use State code (e.g., 'QLD') or specific spot names.",
+            "nullable": True,
+        },
+        "skill": {
+            "type": "string",
+            "description": "Skill level (e.g., beginner, intermediate, advanced).",
+            "nullable": True,
+        },
+        "limit": {
+            "type": "integer",
+            "description": "Maximum number of spots to return.",
+            "nullable": True,
+        },
+    }
+    output_type = "object"
+
+    def forward(
+        self, query: str = "", skill: str | None = None, limit: int = 10
+    ) -> list[dict]:
+        return find_spots(query=query, skill=skill, limit=limit)
+
+
+class GetSpotKnowledgeTool(Tool):
+    name = "get_spot_knowledge"
+    description = "Retrieve metadata and detailed knowledge for a specific surf spot."
+    inputs = {
+        "spot_name": {
+            "type": "string",
+            "description": "Name of the surf spot.",
+        },
+        "region": {
+            "type": "string",
+            "description": "Region or state code where the spot is located.",
+        },
+    }
+    output_type = "object"
+
+    def forward(self, spot_name: str, region: str) -> dict:
+        return get_spot_knowledge(spot_name=spot_name, region=region)
+
+
+class RankSpotsThisWeekTool(Tool):
+    name = "rank_spots_this_week"
+    description = "Rank spots in a region for the upcoming week based on scored surf conditions."
+    inputs = {
+        "region": {
+            "type": "string",
+            "description": "Region or state code to rank spots in (e.g., 'QLD').",
+        },
+        "skill": {
+            "type": "string",
+            "description": "Skill level filter (e.g., beginner, intermediate, advanced).",
+            "nullable": True,
+        },
+    }
+    output_type = "object"
+
+    def forward(
+        self, region: str, skill: str | None = None
+    ) -> list[dict]:
+        return rank_spots_this_week(region=region, skill=skill)
+
+
+class PlotDailySurfOverviewTool(Tool):
+    name = "plot_daily_surf_overview"
+    description = (
+        "Generates a 7-day daily overview graph for a surf spot showing score, "
+        "swell height/direction, and wind speed/direction. Returns a base64 encoded PNG."
+    )
+    inputs = {
+        "spot_name": {
+            "type": "string",
+            "description": "Name of the surf spot.",
+        },
+        "region": {
+            "type": "string",
+            "description": "Region or state code (e.g., 'QLD').",
+        },
+    }
+    output_type = "object"
+
+    def forward(self, spot_name: str, region: str) -> dict:
+        return plot_daily_surf_overview(spot_name=spot_name, region=region)
+
+
+class PlotHourlySurfDrilldownTool(Tool):
+    name = "plot_hourly_surf_drilldown"
+    description = (
+        "Generates an hourly drilldown plot for a specific day at a surf spot showing "
+        "hourly score, swell height/direction, and wind speed/direction. Returns a base64 encoded PNG."
+    )
+    inputs = {
+        "spot_name": {
+            "type": "string",
+            "description": "Name of the surf spot.",
+        },
+        "region": {
+            "type": "string",
+            "description": "Region or state code (e.g., 'QLD').",
+        },
+        "date_str": {
+            "type": "string",
+            "description": "Date to drill down into (YYYY-MM-DD). If omitted, defaults to the first available date.",
+            "nullable": True,
+        },
+    }
+    output_type = "object"
+
+    def forward(
+        self, spot_name: str, region: str, date_str: str | None = None
+    ) -> dict:
+        return plot_hourly_surf_drilldown(
+            spot_name=spot_name, region=region, date_str=date_str
+        )