Restructure repo to AGENTS.md layout; pin Python 3.12; refresh deps

- pyproject: requires-python >=3.12, hatchling build system, drop
langchain-community + unused anthropic, add gradio/daggr/openai/httpx/
pydantic (pytest as dev dep)
- create wavereader/ package with documented stubs (spots, forecasts,
scoring, agent, tools, api, app, daggr_pipeline); fold main.py's
hello-world into api.py and delete main.py
- forecasts.py stub records Open-Meteo spike findings (marine endpoint
serves waves only, wind from forecast API, ~10km offshore grid snap)
- add evals/golden_questions.json draft (10 golden questions), smoke tests,
.env.example, Open-Meteo Snapper Rocks sample fixture (7 days verified
sane: 0.58-1.32 m hourly waves)

.env.example

@@ -0,0 +1,5 @@
+# Copy to .env and fill in. Never commit .env.
+# HF token (https://huggingface.co/settings/tokens) — router provider default.
+HF_TOKEN=
+# NVIDIA NIM key (build.nvidia.com) — provider switch alternative.
+NVIDIA_API_KEY=

.python-version

@@ -1 +1 @@
-3.14
+3.12

data/samples/openmeteo_snapper.json

@@ -0,0 +1,1573 @@
+{
+  "meta": {
+    "spot": "Snapper Rocks",
+    "fetched": "2026-08-30",
+    "spot_lat": -28.173,
+    "spot_lon": 153.556
+  },
+  "marine": {
+    "latitude": -28.041668,
+    "longitude": 153.62502,
+    "generationtime_ms": 0.19097328186035156,
+    "utc_offset_seconds": 0,
+    "timezone": "GMT",
+    "timezone_abbreviation": "GMT",
+    "elevation": 0.0,
+    "hourly_units": {
+      "time": "iso8601",
+      "wave_height": "m",
+      "wave_period": "s",
+      "wave_direction": "\u00b0",
+      "wind_wave_height": "m",
+      "swell_wave_height": "m"
+    },
+    "hourly": {
+      "time": [
+        "2026-08-30T00:00",
+        "2026-08-30T01:00",
+        "2026-08-30T02:00",
+        "2026-08-30T03:00",
+        "2026-08-30T04:00",
+        "2026-08-30T05:00",
+        "2026-08-30T06:00",
+        "2026-08-30T07:00",
+        "2026-08-30T08:00",
+        "2026-08-30T09:00",
+        "2026-08-30T10:00",
+        "2026-08-30T11:00",
+        "2026-08-30T12:00",
+        "2026-08-30T13:00",
+        "2026-08-30T14:00",
+        "2026-08-30T15:00",
+        "2026-08-30T16:00",
+        "2026-08-30T17:00",
+        "2026-08-30T18:00",
+        "2026-08-30T19:00",
+        "2026-08-30T20:00",
+        "2026-08-30T21:00",
+        "2026-08-30T22:00",
+        "2026-08-30T23:00",
+        "2026-08-31T00:00",
+        "2026-08-31T01:00",
+        "2026-08-31T02:00",
+        "2026-08-31T03:00",
+        "2026-08-31T04:00",
+        "2026-08-31T05:00",
+        "2026-08-31T06:00",
+        "2026-08-31T07:00",
+        "2026-08-31T08:00",
+        "2026-08-31T09:00",
+        "2026-08-31T10:00",
+        "2026-08-31T11:00",
+        "2026-08-31T12:00",
+        "2026-08-31T13:00",
+        "2026-08-31T14:00",
+        "2026-08-31T15:00",
+        "2026-08-31T16:00",
+        "2026-08-31T17:00",
+        "2026-08-31T18:00",
+        "2026-08-31T19:00",
+        "2026-08-31T20:00",
+        "2026-08-31T21:00",
+        "2026-08-31T22:00",
+        "2026-08-31T23:00",
+        "2026-09-01T00:00",
+        "2026-09-01T01:00",
+        "2026-09-01T02:00",
+        "2026-09-01T03:00",
+        "2026-09-01T04:00",
+        "2026-09-01T05:00",
+        "2026-09-01T06:00",
+        "2026-09-01T07:00",
+        "2026-09-01T08:00",
+        "2026-09-01T09:00",
+        "2026-09-01T10:00",
+        "2026-09-01T11:00",
+        "2026-09-01T12:00",
+        "2026-09-01T13:00",
+        "2026-09-01T14:00",
+        "2026-09-01T15:00",
+        "2026-09-01T16:00",
+        "2026-09-01T17:00",
+        "2026-09-01T18:00",
+        "2026-09-01T19:00",
+        "2026-09-01T20:00",
+        "2026-09-01T21:00",
+        "2026-09-01T22:00",
+        "2026-09-01T23:00",
+        "2026-09-02T00:00",
+        "2026-09-02T01:00",
+        "2026-09-02T02:00",
+        "2026-09-02T03:00",
+        "2026-09-02T04:00",
+        "2026-09-02T05:00",
+        "2026-09-02T06:00",
+        "2026-09-02T07:00",
+        "2026-09-02T08:00",
+        "2026-09-02T09:00",
+        "2026-09-02T10:00",
+        "2026-09-02T11:00",
+        "2026-09-02T12:00",
+        "2026-09-02T13:00",
+        "2026-09-02T14:00",
+        "2026-09-02T15:00",
+        "2026-09-02T16:00",
+        "2026-09-02T17:00",
+        "2026-09-02T18:00",
+        "2026-09-02T19:00",
+        "2026-09-02T20:00",
+        "2026-09-02T21:00",
+        "2026-09-02T22:00",
+        "2026-09-02T23:00",
+        "2026-09-03T00:00",
+        "2026-09-03T01:00",
+        "2026-09-03T02:00",
+        "2026-09-03T03:00",
+        "2026-09-03T04:00",
+        "2026-09-03T05:00",
+        "2026-09-03T06:00",
+        "2026-09-03T07:00",
+        "2026-09-03T08:00",
+        "2026-09-03T09:00",
+        "2026-09-03T10:00",
+        "2026-09-03T11:00",
+        "2026-09-03T12:00",
+        "2026-09-03T13:00",
+        "2026-09-03T14:00",
+        "2026-09-03T15:00",
+        "2026-09-03T16:00",
+        "2026-09-03T17:00",
+        "2026-09-03T18:00",
+        "2026-09-03T19:00",
+        "2026-09-03T20:00",
+        "2026-09-03T21:00",
+        "2026-09-03T22:00",
+        "2026-09-03T23:00",
+        "2026-09-04T00:00",
+        "2026-09-04T01:00",
+        "2026-09-04T02:00",
+        "2026-09-04T03:00",
+        "2026-09-04T04:00",
+        "2026-09-04T05:00",
+        "2026-09-04T06:00",
+        "2026-09-04T07:00",
+        "2026-09-04T08:00",
+        "2026-09-04T09:00",
+        "2026-09-04T10:00",
+        "2026-09-04T11:00",
+        "2026-09-04T12:00",
+        "2026-09-04T13:00",
+        "2026-09-04T14:00",
+        "2026-09-04T15:00",
+        "2026-09-04T16:00",
+        "2026-09-04T17:00",
+        "2026-09-04T18:00",
+        "2026-09-04T19:00",
+        "2026-09-04T20:00",
+        "2026-09-04T21:00",
+        "2026-09-04T22:00",
+        "2026-09-04T23:00",
+        "2026-09-05T00:00",
+        "2026-09-05T01:00",
+        "2026-09-05T02:00",
+        "2026-09-05T03:00",
+        "2026-09-05T04:00",
+        "2026-09-05T05:00",
+        "2026-09-05T06:00",
+        "2026-09-05T07:00",
+        "2026-09-05T08:00",
+        "2026-09-05T09:00",
+        "2026-09-05T10:00",
+        "2026-09-05T11:00",
+        "2026-09-05T12:00",
+        "2026-09-05T13:00",
+        "2026-09-05T14:00",
+        "2026-09-05T15:00",
+        "2026-09-05T16:00",
+        "2026-09-05T17:00",
+        "2026-09-05T18:00",
+        "2026-09-05T19:00",
+        "2026-09-05T20:00",
+        "2026-09-05T21:00",
+        "2026-09-05T22:00",
+        "2026-09-05T23:00"
+      ],
+      "wave_height": [
+        1.26,
+        1.28,
+        1.28,
+        1.3,
+        1.3,
+        1.32,
+        1.32,
+        1.28,
+        1.22,
+        1.18,
+        1.14,
+        1.1,
+        1.06,
+        1.04,
+        1.02,
+        1.0,
+        0.98,
+        0.96,
+        0.94,
+        0.92,
+        0.92,
+        0.9,
+        0.92,
+        0.94,
+        0.96,
+        0.98,
+        1.02,
+        1.04,
+        1.04,
+        1.06,
+        1.06,
+        1.04,
+        1.04,
+        1.02,
+        1.02,
+        1.0,
+        1.0,
+        1.0,
+        0.98,
+        0.98,
+        0.96,
+        0.96,
+        0.94,
+        0.94,
+        0.92,
+        0.92,
+        0.9,
+        0.9,
+        0.88,
+        0.88,
+        0.86,
+        0.86,
+        0.86,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.82,
+        0.82,
+        0.8,
+        0.8,
+        0.78,
+        0.78,
+        0.76,
+        0.74,
+        0.72,
+        0.74,
+        0.74,
+        0.76,
+        0.78,
+        0.82,
+        0.84,
+        0.84,
+        0.86,
+        0.86,
+        0.86,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.84,
+        0.82,
+        0.82,
+        0.8,
+        0.78,
+        0.76,
+        0.8,
+        0.82,
+        0.86,
+        0.88,
+        0.9,
+        0.92,
+        0.92,
+        0.92,
+        0.92,
+        0.92,
+        0.9,
+        0.9,
+        0.88,
+        0.86,
+        0.84,
+        0.82,
+        0.8,
+        0.78,
+        0.76,
+        0.72,
+        0.7,
+        0.66,
+        0.64,
+        0.6,
+        0.6,
+        0.58,
+        0.58,
+        0.6,
+        0.6,
+        0.62,
+        0.64,
+        0.64,
+        0.66,
+        0.64,
+        0.64,
+        0.62,
+        0.62,
+        0.62,
+        0.62,
+        0.64,
+        0.64,
+        0.66,
+        0.68,
+        0.68,
+        0.7,
+        0.72,
+        0.76,
+        0.78,
+        0.84,
+        0.9,
+        0.96,
+        0.96,
+        0.98,
+        0.98,
+        0.96,
+        0.94,
+        0.92,
+        0.92,
+        0.9,
+        0.9,
+        0.88,
+        0.86,
+        0.84,
+        0.82,
+        0.8,
+        0.78,
+        0.76,
+        0.76
+      ],
+      "wave_period": [
+        6.0,
+        5.95,
+        5.85,
+        5.8,
+        5.7,
+        5.65,
+        5.6,
+        5.6,
+        5.7,
+        5.75,
+        5.85,
+        5.95,
+        6.0,
+        6.05,
+        6.05,
+        6.05,
+        6.05,
+        6.1,
+        6.1,
+        6.15,
+        6.25,
+        6.25,
+        6.15,
+        5.95,
+        5.8,
+        5.75,
+        5.7,
+        5.7,
+        5.75,
+        5.8,
+        5.9,
+        6.0,
+        6.1,
+        6.25,
+        6.4,
+        6.6,
+        6.75,
+        6.85,
+        6.95,
+        7.05,
+        7.15,
+        7.3,
+        7.4,
+        7.5,
+        7.55,
+        7.6,
+        7.6,
+        7.65,
+        7.65,
+        7.7,
+        7.8,
+        7.85,
+        7.9,
+        8.0,
+        8.05,
+        8.05,
+        8.05,
+        8.05,
+        8.0,
+        7.95,
+        7.95,
+        7.95,
+        8.0,
+        8.05,
+        8.05,
+        8.1,
+        8.1,
+        8.15,
+        8.15,
+        8.2,
+        8.25,
+        8.3,
+        8.3,
+        8.15,
+        7.95,
+        7.65,
+        7.25,
+        6.85,
+        6.5,
+        6.35,
+        6.35,
+        6.35,
+        6.35,
+        6.45,
+        6.45,
+        6.4,
+        6.35,
+        6.3,
+        6.25,
+        6.15,
+        6.1,
+        6.05,
+        6.05,
+        6.05,
+        6.0,
+        5.95,
+        5.95,
+        6.0,
+        6.05,
+        6.05,
+        5.85,
+        5.6,
+        5.4,
+        5.3,
+        5.2,
+        5.2,
+        5.25,
+        5.3,
+        5.4,
+        5.45,
+        5.5,
+        5.55,
+        5.6,
+        5.7,
+        5.8,
+        5.9,
+        6.0,
+        6.1,
+        6.2,
+        6.35,
+        6.5,
+        6.7,
+        6.95,
+        7.1,
+        7.15,
+        7.15,
+        7.05,
+        6.8,
+        6.5,
+        6.2,
+        6.0,
+        5.85,
+        5.8,
+        5.85,
+        6.0,
+        6.1,
+        6.15,
+        6.2,
+        6.2,
+        6.2,
+        6.15,
+        6.1,
+        5.95,
+        5.8,
+        5.6,
+        5.4,
+        5.2,
+        5.0,
+        4.85,
+        4.7,
+        4.6,
+        4.6,
+        4.7,
+        4.75,
+        4.8,
+        4.8,
+        4.85,
+        4.9,
+        4.9,
+        4.95,
+        4.95,
+        4.95,
+        5.0,
+        5.1,
+        5.25,
+        5.35,
+        5.45,
+        5.55
+      ],
+      "wave_direction": [
+        137,
+        137,
+        138,
+        138,
+        139,
+        139,
+        140,
+        139,
+        138,
+        137,
+        135,
+        134,
+        132,
+        131,
+        131,
+        130,
+        129,
+        129,
+        128,
+        128,
+        127,
+        127,
+        129,
+        131,
+        133,
+        133,
+        133,
+        133,
+        134,
+        134,
+        135,
+        134,
+        134,
+        133,
+        132,
+        131,
+        130,
+        129,
+        128,
+        127,
+        126,
+        126,
+        125,
+        125,
+        124,
+        124,
+        123,
+        123,
+        122,
+        121,
+        121,
+        120,
+        120,
+        119,
+        119,
+        119,
+        118,
+        118,
+        117,
+        116,
+        115,
+        115,
+        115,
+        115,
+        114,
+        114,
+        113,
+        113,
+        113,
+        113,
+        113,
+        112,
+        112,
+        108,
+        104,
+        100,
+        93,
+        85,
+        78,
+        76,
+        73,
+        71,
+        70,
+        70,
+        69,
+        67,
+        66,
+        64,
+        60,
+        57,
+        53,
+        51,
+        50,
+        48,
+        47,
+        45,
+        44,
+        45,
+        47,
+        48,
+        45,
+        42,
+        39,
+        37,
+        36,
+        34,
+        35,
+        37,
+        38,
+        38,
+        39,
+        39,
+        40,
+        40,
+        41,
+        42,
+        44,
+        45,
+        47,
+        50,
+        52,
+        54,
+        56,
+        58,
+        57,
+        57,
+        56,
+        53,
+        49,
+        46,
+        43,
+        40,
+        37,
+        39,
+        42,
+        44,
+        44,
+        45,
+        45,
+        43,
+        42,
+        40,
+        36,
+        33,
+        29,
+        25,
+        21,
+        17,
+        16,
+        16,
+        15,
+        15,
+        15,
+        15,
+        15,
+        15,
+        15,
+        15,
+        15,
+        15,
+        15,
+        15,
+        15,
+        17,
+        18,
+        20,
+        21,
+        21
+      ],
+      "wind_wave_height": [
+        0.72,
+        0.78,
+        0.86,
+        0.92,
+        0.98,
+        1.02,
+        1.08,
+        0.96,
+        0.86,
+        0.74,
+        0.58,
+        0.44,
+        0.28,
+        0.3,
+        0.3,
+        0.32,
+        0.3,
+        0.28,
+        0.26,
+        0.26,
+        0.26,
+        0.26,
+        0.36,
+        0.46,
+        0.56,
+        0.62,
+        0.66,
+        0.72,
+        0.7,
+        0.68,
+        0.66,
+        0.58,
+        0.5,
+        0.42,
+        0.36,
+        0.28,
+        0.22,
+        0.16,
+        0.12,
+        0.06,
+        0.06,
+        0.08,
+        0.08,
+        0.08,
+        0.1,
+        0.1,
+        0.08,
+        0.04,
+        0.02,
+        0.02,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.0,
+        0.06,
+        0.12,
+        0.18,
+        0.2,
+        0.2,
+        0.22,
+        0.2,
+        0.16,
+        0.14,
+        0.16,
+        0.18,
+        0.2,
+        0.2,
+        0.2,
+        0.2,
+        0.2,
+        0.2,
+        0.2,
+        0.24,
+        0.3,
+        0.34,
+        0.4,
+        0.48,
+        0.54,
+        0.5,
+        0.46,
+        0.42,
+        0.38,
+        0.34,
+        0.3,
+        0.3,
+        0.3,
+        0.3,
+        0.32,
+        0.34,
+        0.36,
+        0.36,
+        0.36,
+        0.36,
+        0.38,
+        0.42,
+        0.44,
+        0.44,
+        0.42,
+        0.42,
+        0.5,
+        0.58,
+        0.66,
+        0.64,
+        0.64,
+        0.62,
+        0.48,
+        0.36,
+        0.22,
+        0.22,
+        0.2,
+        0.2,
+        0.18,
+        0.16,
+        0.14,
+        0.1,
+        0.06,
+        0.02,
+        0.02,
+        0.0,
+        0.0,
+        0.02,
+        0.04,
+        0.06,
+        0.08,
+        0.1,
+        0.12,
+        0.14,
+        0.16,
+        0.18,
+        0.2,
+        0.2,
+        0.22,
+        0.18,
+        0.14,
+        0.1,
+        0.1,
+        0.1,
+        0.1,
+        0.12,
+        0.12,
+        0.14,
+        0.2,
+        0.28,
+        0.34,
+        0.42,
+        0.5,
+        0.58,
+        0.68,
+        0.78,
+        0.88,
+        0.82,
+        0.76,
+        0.7,
+        0.62,
+        0.52,
+        0.44,
+        0.44,
+        0.42,
+        0.42,
+        0.4,
+        0.4,
+        0.38,
+        0.28,
+        0.2,
+        0.1,
+        0.06,
+        0.04
+      ],
+      "swell_wave_height": [
+        1.0,
+        0.9,
+        0.82,
+        0.72,
+        0.62,
+        0.54,
+        0.44,
+        0.56,
+        0.68,
+        0.8,
+        0.86,
+        0.94,
+        1.0,
+        0.98,
+        0.94,
+        0.92,
+        0.86,
+        0.78,
+        0.72,
+        0.72,
+        0.72,
+        0.72,
+        0.68,
+        0.66,
+        0.62,
+        0.62,
+        0.62,
+        0.62,
+        0.66,
+        0.72,
+        0.76,
+        0.8,
+        0.84,
+        0.88,
+        0.86,
+        0.82,
+        0.8,
+        0.7,
+        0.6,
+        0.5,
+        0.52,
+        0.54,
+        0.56,
+        0.56,
+        0.56,
+        0.56,
+        0.56,
+        0.54,
+        0.54,
+        0.54,
+        0.56,
+        0.56,
+        0.58,
+        0.62,
+        0.64,
+        0.64,
+        0.62,
+        0.62,
+        0.62,
+        0.6,
+        0.6,
+        0.6,
+        0.6,
+        0.6,
+        0.58,
+        0.58,
+        0.56,
+        0.56,
+        0.54,
+        0.54,
+        0.54,
+        0.52,
+        0.52,
+        0.5,
+        0.5,
+        0.48,
+        0.48,
+        0.48,
+        0.48,
+        0.48,
+        0.46,
+        0.46,
+        0.46,
+        0.46,
+        0.46,
+        0.46,
+        0.46,
+        0.46,
+        0.5,
+        0.54,
+        0.58,
+        0.56,
+        0.54,
+        0.52,
+        0.52,
+        0.5,
+        0.5,
+        0.46,
+        0.4,
+        0.36,
+        0.36,
+        0.34,
+        0.34,
+        0.4,
+        0.44,
+        0.5,
+        0.6,
+        0.7,
+        0.8,
+        0.78,
+        0.78,
+        0.76,
+        0.76,
+        0.74,
+        0.74,
+        0.72,
+        0.68,
+        0.66,
+        0.64,
+        0.6,
+        0.58,
+        0.54,
+        0.5,
+        0.46,
+        0.44,
+        0.4,
+        0.38,
+        0.38,
+        0.36,
+        0.36,
+        0.38,
+        0.42,
+        0.44,
+        0.46,
+        0.5,
+        0.52,
+        0.52,
+        0.52,
+        0.52,
+        0.52,
+        0.52,
+        0.52,
+        0.52,
+        0.52,
+        0.52,
+        0.48,
+        0.44,
+        0.4,
+        0.36,
+        0.3,
+        0.26,
+        0.36,
+        0.48,
+        0.58,
+        0.64,
+        0.7,
+        0.76,
+        0.76,
+        0.76,
+        0.76,
+        0.74,
+        0.74,
+        0.72,
+        0.72,
+        0.74,
+        0.74,
+        0.74,
+        0.72
+      ]
+    }
+  },
+  "weather": {
+    "latitude": -28.224957,
+    "longitude": 153.49944,
+    "generationtime_ms": 0.06592273712158203,
+    "utc_offset_seconds": 0,
+    "timezone": "GMT",
+    "timezone_abbreviation": "GMT",
+    "elevation": 0.0,
+    "hourly_units": {
+      "time": "iso8601",
+      "wind_speed_10m": "km/h",
+      "wind_direction_10m": "\u00b0"
+    },
+    "hourly": {
+      "time": [
+        "2026-08-30T00:00",
+        "2026-08-30T01:00",
+        "2026-08-30T02:00",
+        "2026-08-30T03:00",
+        "2026-08-30T04:00",
+        "2026-08-30T05:00",
+        "2026-08-30T06:00",
+        "2026-08-30T07:00",
+        "2026-08-30T08:00",
+        "2026-08-30T09:00",
+        "2026-08-30T10:00",
+        "2026-08-30T11:00",
+        "2026-08-30T12:00",
+        "2026-08-30T13:00",
+        "2026-08-30T14:00",
+        "2026-08-30T15:00",
+        "2026-08-30T16:00",
+        "2026-08-30T17:00",
+        "2026-08-30T18:00",
+        "2026-08-30T19:00",
+        "2026-08-30T20:00",
+        "2026-08-30T21:00",
+        "2026-08-30T22:00",
+        "2026-08-30T23:00",
+        "2026-08-31T00:00",
+        "2026-08-31T01:00",
+        "2026-08-31T02:00",
+        "2026-08-31T03:00",
+        "2026-08-31T04:00",
+        "2026-08-31T05:00",
+        "2026-08-31T06:00",
+        "2026-08-31T07:00",
+        "2026-08-31T08:00",
+        "2026-08-31T09:00",
+        "2026-08-31T10:00",
+        "2026-08-31T11:00",
+        "2026-08-31T12:00",
+        "2026-08-31T13:00",
+        "2026-08-31T14:00",
+        "2026-08-31T15:00",
+        "2026-08-31T16:00",
+        "2026-08-31T17:00",
+        "2026-08-31T18:00",
+        "2026-08-31T19:00",
+        "2026-08-31T20:00",
+        "2026-08-31T21:00",
+        "2026-08-31T22:00",
+        "2026-08-31T23:00",
+        "2026-09-01T00:00",
+        "2026-09-01T01:00",
+        "2026-09-01T02:00",
+        "2026-09-01T03:00",
+        "2026-09-01T04:00",
+        "2026-09-01T05:00",
+        "2026-09-01T06:00",
+        "2026-09-01T07:00",
+        "2026-09-01T08:00",
+        "2026-09-01T09:00",
+        "2026-09-01T10:00",
+        "2026-09-01T11:00",
+        "2026-09-01T12:00",
+        "2026-09-01T13:00",
+        "2026-09-01T14:00",
+        "2026-09-01T15:00",
+        "2026-09-01T16:00",
+        "2026-09-01T17:00",
+        "2026-09-01T18:00",
+        "2026-09-01T19:00",
+        "2026-09-01T20:00",
+        "2026-09-01T21:00",
+        "2026-09-01T22:00",
+        "2026-09-01T23:00",
+        "2026-09-02T00:00",
+        "2026-09-02T01:00",
+        "2026-09-02T02:00",
+        "2026-09-02T03:00",
+        "2026-09-02T04:00",
+        "2026-09-02T05:00",
+        "2026-09-02T06:00",
+        "2026-09-02T07:00",
+        "2026-09-02T08:00",
+        "2026-09-02T09:00",
+        "2026-09-02T10:00",
+        "2026-09-02T11:00",
+        "2026-09-02T12:00",
+        "2026-09-02T13:00",
+        "2026-09-02T14:00",
+        "2026-09-02T15:00",
+        "2026-09-02T16:00",
+        "2026-09-02T17:00",
+        "2026-09-02T18:00",
+        "2026-09-02T19:00",
+        "2026-09-02T20:00",
+        "2026-09-02T21:00",
+        "2026-09-02T22:00",
+        "2026-09-02T23:00",
+        "2026-09-03T00:00",
+        "2026-09-03T01:00",
+        "2026-09-03T02:00",
+        "2026-09-03T03:00",
+        "2026-09-03T04:00",
+        "2026-09-03T05:00",
+        "2026-09-03T06:00",
+        "2026-09-03T07:00",
+        "2026-09-03T08:00",
+        "2026-09-03T09:00",
+        "2026-09-03T10:00",
+        "2026-09-03T11:00",
+        "2026-09-03T12:00",
+        "2026-09-03T13:00",
+        "2026-09-03T14:00",
+        "2026-09-03T15:00",
+        "2026-09-03T16:00",
+        "2026-09-03T17:00",
+        "2026-09-03T18:00",
+        "2026-09-03T19:00",
+        "2026-09-03T20:00",
+        "2026-09-03T21:00",
+        "2026-09-03T22:00",
+        "2026-09-03T23:00",
+        "2026-09-04T00:00",
+        "2026-09-04T01:00",
+        "2026-09-04T02:00",
+        "2026-09-04T03:00",
+        "2026-09-04T04:00",
+        "2026-09-04T05:00",
+        "2026-09-04T06:00",
+        "2026-09-04T07:00",
+        "2026-09-04T08:00",
+        "2026-09-04T09:00",
+        "2026-09-04T10:00",
+        "2026-09-04T11:00",
+        "2026-09-04T12:00",
+        "2026-09-04T13:00",
+        "2026-09-04T14:00",
+        "2026-09-04T15:00",
+        "2026-09-04T16:00",
+        "2026-09-04T17:00",
+        "2026-09-04T18:00",
+        "2026-09-04T19:00",
+        "2026-09-04T20:00",
+        "2026-09-04T21:00",
+        "2026-09-04T22:00",
+        "2026-09-04T23:00",
+        "2026-09-05T00:00",
+        "2026-09-05T01:00",
+        "2026-09-05T02:00",
+        "2026-09-05T03:00",
+        "2026-09-05T04:00",
+        "2026-09-05T05:00",
+        "2026-09-05T06:00",
+        "2026-09-05T07:00",
+        "2026-09-05T08:00",
+        "2026-09-05T09:00",
+        "2026-09-05T10:00",
+        "2026-09-05T11:00",
+        "2026-09-05T12:00",
+        "2026-09-05T13:00",
+        "2026-09-05T14:00",
+        "2026-09-05T15:00",
+        "2026-09-05T16:00",
+        "2026-09-05T17:00",
+        "2026-09-05T18:00",
+        "2026-09-05T19:00",
+        "2026-09-05T20:00",
+        "2026-09-05T21:00",
+        "2026-09-05T22:00",
+        "2026-09-05T23:00"
+      ],
+      "wind_speed_10m": [
+        18.2,
+        18.8,
+        20.2,
+        21.6,
+        21.0,
+        19.2,
+        20.9,
+        18.2,
+        14.1,
+        12.3,
+        10.3,
+        11.2,
+        12.1,
+        12.2,
+        11.7,
+        12.1,
+        11.3,
+        11.1,
+        11.0,
+        11.4,
+        11.9,
+        11.9,
+        10.6,
+        12.4,
+        16.0,
+        18.2,
+        17.6,
+        16.9,
+        18.3,
+        17.1,
+        16.2,
+        13.8,
+        12.2,
+        9.3,
+        7.2,
+        7.7,
+        7.8,
+        8.4,
+        8.0,
+        8.4,
+        7.4,
+        7.8,
+        7.5,
+        7.8,
+        8.4,
+        7.9,
+        5.2,
+        5.8,
+        5.3,
+        7.0,
+        9.1,
+        9.3,
+        9.7,
+        9.2,
+        8.4,
+        7.4,
+        9.9,
+        11.4,
+        11.5,
+        12.7,
+        12.4,
+        12.7,
+        13.1,
+        13.3,
+        14.2,
+        15.2,
+        14.6,
+        13.5,
+        13.0,
+        12.0,
+        11.8,
+        14.3,
+        15.3,
+        15.0,
+        15.0,
+        15.6,
+        17.5,
+        19.8,
+        19.5,
+        16.3,
+        15.4,
+        14.3,
+        14.0,
+        14.0,
+        14.1,
+        15.6,
+        16.4,
+        16.1,
+        15.4,
+        13.5,
+        13.9,
+        14.0,
+        14.3,
+        13.6,
+        12.5,
+        13.7,
+        16.1,
+        16.0,
+        15.7,
+        15.4,
+        15.0,
+        15.7,
+        16.6,
+        16.0,
+        15.3,
+        15.1,
+        14.7,
+        13.9,
+        12.9,
+        11.5,
+        9.8,
+        8.4,
+        7.7,
+        8.0,
+        8.3,
+        8.6,
+        8.5,
+        7.6,
+        4.7,
+        1.8,
+        3.7,
+        6.3,
+        8.8,
+        9.9,
+        9.3,
+        9.0,
+        9.7,
+        9.9,
+        10.1,
+        10.8,
+        12.2,
+        13.4,
+        13.3,
+        10.7,
+        6.9,
+        4.1,
+        3.1,
+        2.6,
+        2.8,
+        3.9,
+        5.4,
+        7.3,
+        9.8,
+        13.1,
+        15.7,
+        17.1,
+        18.5,
+        18.5,
+        16.2,
+        15.1,
+        16.6,
+        19.3,
+        17.8,
+        16.2,
+        15.1,
+        14.4,
+        14.5,
+        15.4,
+        17.2,
+        19.1,
+        20.5,
+        21.1,
+        20.2,
+        17.4,
+        13.2,
+        8.2,
+        4.4,
+        5.2
+      ],
+      "wind_direction_10m": [
+        177,
+        166,
+        156,
+        155,
+        155,
+        146,
+        151,
+        157,
+        176,
+        192,
+        205,
+        222,
+        226,
+        225,
+        223,
+        220,
+        226,
+        233,
+        235,
+        229,
+        228,
+        222,
+        215,
+        199,
+        166,
+        152,
+        148,
+        142,
+        141,
+        142,
+        146,
+        153,
+        161,
+        172,
+        194,
+        213,
+        222,
+        222,
+        226,
+        227,
+        225,
+        226,
+        222,
+        228,
+        235,
+        235,
+        209,
+        182,
+        118,
+        87,
+        73,
+        62,
+        47,
+        31,
+        11,
+        3,
+        3,
+        7,
+        2,
+        349,
+        338,
+        321,
+        316,
+        318,
+        321,
+        320,
+        320,
+        323,
+        319,
+        320,
+        326,
+        329,
+        332,
+        337,
+        346,
+        7,
+        17,
+        20,
+        12,
+        352,
+        346,
+        341,
+        334,
+        329,
+        329,
+        329,
+        325,
+        329,
+        331,
+        335,
+        335,
+        336,
+        333,
+        334,
+        342,
+        349,
+        340,
+        335,
+        329,
+        328,
+        340,
+        356,
+        4,
+        358,
+        344,
+        333,
+        331,
+        331,
+        332,
+        330,
+        325,
+        318,
+        306,
+        288,
+        276,
+        269,
+        263,
+        258,
+        247,
+        186,
+        113,
+        97,
+        88,
+        80,
+        62,
+        37,
+        15,
+        359,
+        343,
+        332,
+        326,
+        323,
+        320,
+        316,
+        309,
+        293,
+        283,
+        282,
+        288,
+        292,
+        296,
+        301,
+        310,
+        317,
+        317,
+        310,
+        301,
+        299,
+        313,
+        340,
+        359,
+        356,
+        352,
+        345,
+        335,
+        326,
+        319,
+        315,
+        314,
+        313,
+        314,
+        314,
+        315,
+        317,
+        322,
+        334,
+        12,
+        76
+      ]
+    }
+  }
+}

evals/golden_questions.json

@@ -0,0 +1,90 @@
+{
+  "_meta": {
+    "status": "draft",
+    "note": "Pre-recording gate for the Sep 7 demo video. Harden expected_behaviors before evals day; a failing eval blocks the recording.",
+    "gate": "run against the deployed app before recording"
+  },
+  "questions": [
+    {
+      "id": "gq-01",
+      "question": "Which days this week are good for surfing near the Gold Coast?",
+      "expected_behaviors": [
+        "agent calls find_spots / rank_spots_this_week for the Gold Coast region",
+        "answer names specific days, backed by scores from scoring.py (no model-invented numbers)",
+        "forecast charts are rendered for surfaced data"
+      ]
+    },
+    {
+      "id": "gq-02",
+      "question": "I'm a beginner — which breaks near the Gold Coast should I try this week?",
+      "expected_behaviors": [
+        "skill filter (beginner) is applied to the ranking",
+        "returned spots are plausible beginner breaks for the region"
+      ]
+    },
+    {
+      "id": "gq-03",
+      "question": "What time should I surf Snapper Rocks today?",
+      "expected_behaviors": [
+        "agent calls get_forecast + score_week and reasons over hourly scores",
+        "answer gives a time window (best hours today) with wind/swell justification"
+      ]
+    },
+    {
+      "id": "gq-04",
+      "question": "Tell me about Margaret Bay — what swell and wind does it like?",
+      "expected_behaviors": [
+        "agent calls get_spot_knowledge and quotes the knowledge base (ideal_swell, ideal_wind, ideal_tide)",
+        "tide is described qualitatively only (no invented tide curves)"
+      ]
+    },
+    {
+      "id": "gq-05",
+      "question": "Best beach for an intermediate surfer near Byron Bay this weekend?",
+      "expected_behaviors": [
+        "ranking restricted to the Byron Bay region with skill=intermediate",
+        "weekend hours only are considered"
+      ]
+    },
+    {
+      "id": "gq-06",
+      "question": "How windy is it going to be at Bondi tomorrow morning?",
+      "expected_behaviors": [
+        "wind comes from the forecast data (wind_speed_10m/wind_direction_10m), not model guesses",
+        "answer includes wind strength and direction with an on/offshore interpretation for the break"
+      ]
+    },
+    {
+      "id": "gq-07",
+      "question": "Is Bells Beach worth a 2-hour drive on Saturday?",
+      "expected_behaviors": [
+        "score for Saturday hours at Bells is computed deterministically and cited",
+        "a clear go/no-go recommendation with reasoning"
+      ]
+    },
+    {
+      "id": "gq-08",
+      "question": "Show me the wave height forecast for Kirra for the next 3 days.",
+      "expected_behaviors": [
+        "interactive hourly wave-height chart is rendered (not just text)",
+        "numbers match the Open-Meteo Marine fetch (agent never fabricates values)"
+      ]
+    },
+    {
+      "id": "gq-09",
+      "question": "Where can I find a quiet weekday dawn patrol in Victoria?",
+      "expected_behaviors": [
+        "spot search constrained to Victoria region",
+        "answer balances scores with knowledge-base character (crowds, skill suitability)"
+      ]
+    },
+    {
+      "id": "gq-10",
+      "question": "Which is better this week: Noosa or Snapper Rocks?",
+      "expected_behaviors": [
+        "both spots scored over the same week and compared with cited numbers",
+        "one clear winner with the deciding factors explained"
+      ]
+    }
+  ]
+}

main.py

@@ -1,7 +0,0 @@
-from fastapi import FastAPI
-
-app = FastAPI()
-
-@app.get("/")
-async def read_root():
-    return {"Hello": "World"}

pyproject.toml

@@ -1,13 +1,28 @@
 [project]
 name = "wavereader"
 version = "0.1.0"
-description = "Surf break data generator and API"
+description = "Agentic surf forecaster for Australian breaks"
 readme = "README.md"
-requires-python = ">=3.14"
+requires-python = ">=3.12"
 dependencies = [
-    "anthropic>=1.2.0",
+    "daggr",
     "ddgs>=9.16.0",
     "fastapi[standard]>=0.141.1",
+    "gradio",
+    "httpx",
     "huggingface-hub>=1.29.0",
-    "langchain-community>=0.4.2",
+    "openai",
+    "pydantic",
 ]
+
+[dependency-groups]
+dev = [
+    "pytest",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["wavereader"]

tests/test_smoke.py

@@ -0,0 +1,33 @@
+"""Smoke tests: package imports and pyproject sanity (structure milestone)."""
+
+import tomllib
+from pathlib import Path
+
+import wavereader
+from wavereader import agent, api, app, daggr_pipeline, forecasts, scoring, spots, tools
+
+REPO = Path(__file__).resolve().parent.parent
+
+
+def test_version():
+    assert wavereader.__version__ == "0.1.0"
+
+
+def test_all_modules_importable():
+    for mod in (agent, api, app, daggr_pipeline, forecasts, scoring, spots, tools):
+        assert mod.__doc__
+
+
+def test_pyproject_pinned():
+    cfg = tomllib.loads((REPO / "pyproject.toml").read_text())
+    assert cfg["project"]["requires-python"] == ">=3.12"
+    deps = " ".join(cfg["project"]["dependencies"])
+    assert "langchain" not in deps
+    assert "anthropic" not in deps
+    for required in ("gradio", "daggr", "openai", "httpx", "pydantic"):
+        assert required in deps
+
+
+def test_api_app_exists():
+    routes = {r.path for r in api.app.routes}
+    assert {"/", "/spots", "/forecast", "/score"} <= routes

wavereader/__init__.py

@@ -0,0 +1,3 @@
+"""wavereader — agentic surf forecaster for Australian breaks."""
+
+__version__ = "0.1.0"

wavereader/agent.py

@@ -0,0 +1,24 @@
+"""Hand-rolled agent tool loop (~100 lines, no LangChain / no frameworks).
+
+Provider-agnostic: one OpenAI-compatible client class; base URL + key come
+from env (``HF_TOKEN`` -> https://router.huggingface.co/v1,
+``NVIDIA_API_KEY`` -> https://integrate.api.nvidia.com/v1). Default model:
+``Qwen/Qwen3-Next-80B-A3B-Instruct`` (only tested model supporting both
+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.
+"""
+
+from __future__ import annotations
+
+
+def run_agent(question: str, model: str | None = None) -> str:
+    """Run the tool loop to answer a surf question.
+
+    TODO: system prompt, tool dispatch loop (tools.py), streaming output,
+    trace capture, provider switch via env.
+    """
+    raise NotImplementedError

wavereader/api.py

@@ -0,0 +1,40 @@
+"""FastAPI backend: data endpoints owned by the core modules.
+
+Gradio (app.py) is the demo UI; this API exposes the same core for tests
+and any non-Gradio consumer. Endpoints: /spots, /forecast, /score, /ask.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+app = FastAPI(title="wavereader", version="0.1.0")
+
+
+@app.get("/")
+async def read_root():
+    return {"Hello": "World"}
+
+
+@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
+
+
+@app.get("/forecast")
+async def forecast(spot: str, days: int = 7):
+    """Hourly marine + wind forecast via forecasts.py. TODO: wire up."""
+    raise NotImplementedError
+
+
+@app.get("/score")
+async def score(spot: str, days: int = 7):
+    """Deterministic hourly surf scores via scoring.py. TODO: wire up."""
+    raise NotImplementedError
+
+
+@app.post("/ask")
+async def ask(question: str):
+    """Agent answer via agent.py tool loop. TODO: wire up."""
+    raise NotImplementedError

wavereader/app.py

@@ -0,0 +1,24 @@
+"""Gradio demo UI.
+
+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.
+"""
+
+from __future__ import annotations
+
+
+def build_ui() -> object:
+    """Assemble the Blocks demo (map home, chat, charts, trace panel).
+
+    TODO: Australia map home page, chat pipeline against agent.run_agent,
+    chart rendering, trace panel.
+    """
+    raise NotImplementedError
+
+
+if __name__ == "__main__":
+    demo = build_ui()
+    demo.launch()

wavereader/daggr_pipeline.py

@@ -0,0 +1,16 @@
+"""Fixed "Morning Surf Report" DAG visualised with daggr.
+
+Daggr is beta and has NO conditional branching: this visualises the fixed
+morning pipeline only, never the dynamic chat agent loop.
+"""
+
+from __future__ import annotations
+
+
+def build_pipeline() -> object:
+    """Assemble the fixed morning-report DAG.
+
+    TODO: nodes for pick-region -> fetch forecasts -> score -> summarise,
+    rendered on the daggr canvas.
+    """
+    raise NotImplementedError

wavereader/forecasts.py

@@ -0,0 +1,46 @@
+"""Open-Meteo Marine + weather forecast client.
+
+Two endpoints, merged on ``time``:
+
+* ``marine-api.open-meteo.com`` — hourly ``wave_height`` (m), ``wave_period``
+  (s), ``wave_direction`` (deg), ``swell_wave_height`` (m),
+  ``wind_wave_height`` (m). Verified 2026-08-30 at Snapper Rocks: 48 hourly
+  entries, no nulls, ~1.3 m @ ~6 s from ~SE. The marine endpoint does NOT
+  serve wind fields.
+* ``api.open-meteo.com`` — hourly ``wind_speed_10m`` (km/h; convert to 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.
+
+Cache every response to disk: the demo must survive API flakiness and rate
+limits. Horizon: hourly, 7 days.
+"""
+
+from __future__ import annotations
+
+MARINE_URL = "https://marine-api.open-meteo.com/v1/marine"
+WEATHER_URL = "https://api.open-meteo.com/v1/forecast"
+
+# Marine hourly fields verified against the live API 2026-08-30.
+MARINE_HOURLY_FIELDS = (
+    "wave_height",
+    "wave_period",
+    "wave_direction",
+    "wind_wave_height",
+    "swell_wave_height",
+)
+WEATHER_HOURLY_FIELDS = (
+    "wind_speed_10m",
+    "wind_direction_10m",
+)
+
+
+def get_forecast(lat: float, lon: float, days: int = 7) -> dict:
+    """Fetch marine + weather hourly data for a coordinate, merged on time.
+
+    TODO: httpx client, disk cache (keyed by rounded coords + day),
+    merge the two responses, return a normalized hourly frame.
+    """
+    raise NotImplementedError

wavereader/scoring.py

@@ -0,0 +1,34 @@
+"""Deterministic surf-quality scoring.
+
+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, period, wind strength/direction vs offshore, tide is
+qualitative only — Open-Meteo has no tides, so it comes from the knowledge
+base and never feeds the numeric score).
+"""
+
+from __future__ import annotations
+
+
+def score_hour(
+    wave_height_m: float,
+    wave_period_s: float,
+    wind_speed_kt: float,
+    wind_direction_deg: float,
+    spot: dict,
+) -> dict:
+    """Score one hour against a spot's ideal profile.
+
+    TODO: component subscores (swell size, period, wind strength,
+    wind alignment vs ideal direction) weighted into a 0-10 total plus a
+    breakdown dict for the UI.
+    """
+    raise NotImplementedError
+
+
+def score_week(forecast: dict, spot: dict) -> list[dict]:
+    """Score every hour of a 7-day forecast for one spot.
+
+    TODO: map score_hour over the merged hourly frame.
+    """
+    raise NotImplementedError

wavereader/spots.py

@@ -0,0 +1,53 @@
+"""Load, validate and search surf breaks.
+
+Source of truth is ``data/break_details.json`` (records keyed by
+``(name, region)``; identity fields anchored to ``data/breaks.json``).
+
+Validation pass lives here rather than hand-edits: coords plausible for the
+named region, ranges sane, spot-check ~10 records against local knowledge.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# TODO: pydantic models for a break record (identity, coordinates,
+# ideal_swell, ideal_wind, ideal_tide, additional_details).
+
+
+@dataclass(frozen=True)
+class Spot:
+    name: str
+    region: str
+
+
+def load_breaks() -> list[dict]:
+    """Load and validate ``data/break_details.json``.
+
+    TODO: parse into pydantic models, run validation (coords vs region,
+    sane ranges), raise on failure.
+    """
+    raise NotImplementedError
+
+
+def find_spots(
+    query: str = "",
+    region: str | None = None,
+    skill: str | None = None,
+    limit: int = 10,
+) -> list[Spot]:
+    """Search breaks by name/city/region and optional skill filter.
+
+    TODO: case-insensitive substring match over name/region; skill filter
+    from knowledge-base suitability. Used by the find_spots tool and
+    /spots endpoint.
+    """
+    raise NotImplementedError
+
+
+def get_spot(spot: Spot) -> dict:
+    """Return the full knowledge-base record for one break.
+
+    TODO: keyed lookup by (name, region).
+    """
+    raise NotImplementedError

wavereader/tools.py

@@ -0,0 +1,40 @@
+"""Agent tools: the function schemas handed to the LLM.
+
+Tools are thin wrappers over spots.py / forecasts.py / scoring.py — the
+model chooses them, the deterministic modules compute the values.
+"""
+
+from __future__ import annotations
+
+TOOL_SCHEMAS = (
+    "get_forecast",
+    "score_week",
+    "find_spots",
+    "get_spot_knowledge",
+    "rank_spots_this_week",
+)
+
+
+def get_forecast(spot: str) -> dict:
+    """Hourly marine + wind forecast for a named spot. TODO."""
+    raise NotImplementedError
+
+
+def score_week(spot: str) -> dict:
+    """Hour-by-hour surf scores for the next 7 days at a spot. TODO."""
+    raise NotImplementedError
+
+
+def find_spots(query: str, skill: str | None = None) -> list[dict]:
+    """Search breaks by name/region with optional skill filter. TODO."""
+    raise NotImplementedError
+
+
+def get_spot_knowledge(spot: str) -> dict:
+    """Knowledge-base profile for a spot (ideal swell/wind/tide). TODO."""
+    raise NotImplementedError
+
+
+def rank_spots_this_week(region: str, skill: str | None = None) -> list[dict]:
+    """Rank spots in a region by their best score this week. TODO."""
+    raise NotImplementedError