restructured and implemented agent scaffold and tools

.zcode/plans/plan-sess_e88d3e27-48e8-42f3-bcb1-112079be5cdf.md

@@ -1,23 +0,0 @@
-# Write project documentation files for WaveReader
-
-Create three markdown files at the repo root capturing everything agreed in this chat, as the project's source of truth for the week:
-
-## 1. `README.md` — public-facing
-- Project pitch: agentic Australian surf forecaster; the "inherent knowledge" problem; the two flagship questions.
-- Features: agent answers ("Where should I surf near Byron Bay this weekend?", "What time at Snapper tomorrow?"), **interactive forecast graphs** shown whenever the agent surfaces wind/sea data (seaborn-styled), **Australia break-selector map on the home page**, agent trace panel, daggr "Morning Surf Report" canvas, HF ↔ NVIDIA NIM model toggle, 101-break open knowledge base.
-- Architecture diagram + stack: FastAPI, hand-rolled tool loop (no LangChain), Gradio, daggr, Qwen3-Next-80B, Open-Meteo Marine API; note on interactivity for seaborn-style charts.
-- Quickstart (uv, env vars HF_TOKEN / NVIDIA_API_KEY), HF Space link (placeholder), license note.
-
-## 2. `AGENTS.md` — for AI coding agents working in this repo
-- Project context + contest deadline context (video Mon Sep 7).
-- Stack rules: pin Python 3.12; deps to add/remove; no LangChain; provider-agnostic OpenAI-compatible client; deterministic scoring engine owns the numbers, LLM only interprets.
-- Repo layout, data file schemas (breaks.json, break_details.json), conventions, evals/golden_questions.json purpose.
-
-## 3. `ROADMAP.md` — the working plan
-- Day-by-day tasks Sun Aug 30 → Mon Sep 7 (as agreed, updated to include the map home page + interactive graphs on Fri's UI day).
-- Daggr strategy + beta caveat (no conditional loops; fixed Morning Surf Report DAG).
-- Shot-by-shot video script (~2 min) with the Berlin move/open-to-work CTA.
-- LinkedIn post copy skeleton (contest entry + Berlin announcement).
-- Risks & fallbacks section.
-
-No code changes — documentation only.

AGENTS.md

@@ -25,9 +25,10 @@ The product promises (see README.md):
   `>=3.14` — downgrade it; 3.14 has unnecessary lib-compatibility risk for a
   one-week build.
 - **Package manager:** uv (`uv add ...`, `uv sync`).
-- **No LangChain / no agent frameworks.** The tool loop is hand-rolled
-  (~100 lines, in `agent.py`). Remove `langchain-community` from deps when
-  touched. `ddgs` stays (used by `data/generate_data.py`).
+- **Agent framework:** smolagents (CodeAgent). The tool loop uses smolagents'
+  CodeAgent with InferenceClientModel for Hugging Face / NVIDIA NIM. Remove
+  `langchain-community` from deps when touched. `ddgs` stays (used by
+  `data/generate_data.py`).
 - **Provider-agnostic LLM client:** one OpenAI-compatible client class; the
   base URL + key come from env vars (`HF_TOKEN`, `NVIDIA_API_KEY`). Default
   model: `Qwen/Qwen3-Next-80B-A3B-Instruct` — chosen because it is the only
@@ -51,7 +52,7 @@ wavereader/
   spots.py          # load + validate + search breaks (name/city/region/skill)
   forecasts.py      # Open-Meteo Marine + weather client; hourly, 7-day; disk cache
   scoring.py        # deterministic 0–10 surf-quality score/hour + component breakdown
-  agent.py          # hand-rolled tool loop; streaming; trace capture; HF⇄NIM switch
+  agent.py          # smolagents CodeAgent; streaming; trace capture; HF⇄NIM switch
   tools.py          # get_forecast, score_week, find_spots, get_spot_knowledge,
                     # rank_spots_this_week
   api.py            # FastAPI endpoints

README.md

@@ -15,7 +15,7 @@ The agent calls real forecast tools, scores every spot with a deterministic surf
 
 |                                    |                                                                                                                                                                                |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 🤖 **Agentic answers**             | Hand-rolled tool-calling loop (no framework) over Qwen3-Next-80B — the LLM interprets, deterministic tools own the data.                                                       |
+| 🤖 **Agentic answers**             | smolagents CodeAgent over Qwen3-Next-80B — the LLM interprets, deterministic tools own the data.                                                       |
 | 📊 **Interactive forecast graphs** | Whenever the agent surfaces wind, swell or wave data, it renders as interactive charts (seaborn-styled): hourly wave height, period, wind speed and direction.                 |
 | 🗺️ **Australia break map**         | The home page is a map of Australia: pick your break directly, or search by city/suburb and let the agent rank nearby spots for your skill level.                              |
 | 🧠 **Break knowledge base**        | 101 breaks with coordinates, ideal swell/wind/tide, break type, skill level and hazards — generated with an open model, web-grounded, published as an open dataset.            |
@@ -33,7 +33,7 @@ The agent calls real forecast tools, scores every spot with a deterministic surf
 ┌──────────────────────────────▼─────────────  FastAPI  ────────────────┐
 │  /spots  /forecast  /score  /ask                                      │
 ├───────────────────────────────────────────────────────────────────────┤
-│  agent.py — hand-rolled tool loop (streaming + trace)                  │
+│  agent.py — smolagents CodeAgent (streaming + trace)                   │
 │      ↳ tools: get_forecast · score_week · find_spots(near/skill)       │
 │               get_spot_knowledge · rank_spots_this_week                │
 ├───────────────────────────────────────────────────────────────────────┤

ROADMAP.md

@@ -8,7 +8,7 @@ openness to ML work/research in Berlin.
 
 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 + hand-rolled agent loop + Gradio + daggr (no LangChain, no htmx).
+FastAPI + smolagents CodeAgent + Gradio + daggr (no LangChain, no htmx).
 
 ---
 
@@ -39,7 +39,7 @@ FastAPI + hand-rolled agent loop + Gradio + daggr (no LangChain, no htmx).
 - 📹 **Capture:** score table / heatmap clip.
 
 ### Wed Sep 2 — Agent core
-- `agent.py`: hand-rolled tool loop, streaming, trace capture; HF⇄NIM switch
+- `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.

pyproject.toml

@@ -13,6 +13,7 @@ dependencies = [
     "huggingface-hub>=1.29.0",
     "openai",
     "pydantic",
+    "smolagents>=1.26.0",
 ]
 
 [dependency-groups]

tests/test_agent.py

@@ -0,0 +1,379 @@
+"""Unit tests for wavereader.agent — smolagents surf forecasting agent."""
+
+from __future__ import annotations
+
+import json
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from wavereader.agent import (
+    AgentTrace,
+    FindSpotsTool,
+    GetForecastTool,
+    GetSpotKnowledgeTool,
+    RankSpotsThisWeekTool,
+    ScoreWeekTool,
+    SurfAgent,
+    TraceEvent,
+    PROVIDER_HF,
+    PROVIDER_NIM,
+    DEFAULT_MODEL,
+    run_agent,
+    run_agent_stream,
+)
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def clear_env(monkeypatch):
+    """Clear provider env vars for each test."""
+    monkeypatch.delenv("HF_TOKEN", raising=False)
+    monkeypatch.delenv("NVIDIA_API_KEY", raising=False)
+
+
+@pytest.fixture
+def mock_model():
+    """Mock InferenceClientModel to avoid real API calls."""
+    with patch("wavereader.agent.InferenceClientModel") as mock:
+        # Configure the mock to return a MagicMock when instantiated
+        mock_instance = MagicMock()
+        mock.return_value = mock_instance
+        yield mock
+
+
+@pytest.fixture
+def mock_build_model():
+    """Mock _build_model to return a mock model instance."""
+    with patch("wavereader.agent._build_model") as mock:
+        mock_instance = MagicMock()
+        mock.return_value = mock_instance
+        yield mock
+
+
+# ---------------------------------------------------------------------------
+# TraceEvent / AgentTrace
+# ---------------------------------------------------------------------------
+
+def test_trace_event_creation():
+    evt = TraceEvent(type="tool_call", timestamp=123.0, data={"name": "test"})
+    assert evt.type == "tool_call"
+    assert evt.timestamp == 123.0
+    assert evt.data == {"name": "test"}
+
+
+def test_agent_trace_add_event():
+    trace = AgentTrace()
+    trace.add_event("tool_call", {"name": "get_forecast", "args": {}})
+    assert len(trace.events) == 1
+    assert trace.events[0].type == "tool_call"
+    assert trace.events[0].data["name"] == "get_forecast"
+
+
+def test_agent_trace_to_json():
+    trace = AgentTrace(question="test?", model="Qwen", provider="hf")
+    trace.add_event("llm_chunk", {"chunk": "hello"})
+    json_str = trace.to_json()
+    data = json.loads(json_str)
+    assert data["question"] == "test?"
+    assert data["model"] == "Qwen"
+    assert data["provider"] == "hf"
+    assert data["events"][0]["type"] == "llm_chunk"
+
+
+# ---------------------------------------------------------------------------
+# Tools (unit test tool forward methods)
+# ---------------------------------------------------------------------------
+
+class TestGetForecastTool:
+    def test_forward_success(self):
+        tool = GetForecastTool()
+        with patch("wavereader.agent.get_forecast") as mock_get:
+            mock_get.return_value = {"hourly": [{"time": "2024-01-01T00:00", "wave_height": 1.5}]}
+            result = tool.forward("Snapper Rocks", "QLD")
+            assert result["hourly"][0]["wave_height"] == 1.5
+            mock_get.assert_called_once_with("Snapper Rocks", "QLD")
+
+    def test_forward_spot_not_found(self):
+        tool = GetForecastTool()
+        with patch("wavereader.agent.get_forecast") as mock_get:
+            mock_get.return_value = {"error": "Spot 'Bad' (XX) not found"}
+            result = tool.forward("Bad", "XX")
+            assert "error" in result
+
+
+class TestScoreWeekTool:
+    def test_forward_success(self):
+        tool = ScoreWeekTool()
+        with patch("wavereader.agent.score_week") as mock_score:
+            mock_score.return_value = [{"time": "2024-01-01T00:00", "score": 8.5}]
+            result = tool.forward("Snapper Rocks", "QLD")
+            assert result[0]["score"] == 8.5
+            mock_score.assert_called_once_with("Snapper Rocks", "QLD")
+
+    def test_forward_spot_not_found(self):
+        tool = ScoreWeekTool()
+        with patch("wavereader.agent.score_week") as mock_score:
+            mock_score.return_value = []
+            result = tool.forward("Bad", "XX")
+            assert result == []
+
+
+class TestFindSpotsTool:
+    def test_forward_with_query(self):
+        tool = FindSpotsTool()
+        with patch("wavereader.agent.find_spots") as mock_find:
+            mock_find.return_value = [{"name": "Snapper Rocks", "region": "QLD"}]
+            result = tool.forward(query="Snapper")
+            assert len(result) == 1
+            assert result[0]["name"] == "Snapper Rocks"
+            mock_find.assert_called_once_with(query="Snapper", skill=None, limit=10)
+
+    def test_forward_with_skill_and_limit(self):
+        tool = FindSpotsTool()
+        with patch("wavereader.agent.find_spots") as mock_find:
+            mock_find.return_value = []
+            tool.forward(query="", skill="beginner", limit=5)
+            mock_find.assert_called_once_with(query="", skill="beginner", limit=5)
+
+
+class TestGetSpotKnowledgeTool:
+    def test_forward_success(self):
+        tool = GetSpotKnowledgeTool()
+        with patch("wavereader.agent.get_spot_knowledge") as mock_get:
+            mock_get.return_value = {"name": "Bells Beach", "region": "VIC", "ideal_swell": {}}
+            result = tool.forward("Bells Beach", "VIC")
+            assert result["name"] == "Bells Beach"
+            mock_get.assert_called_once_with("Bells Beach", "VIC")
+
+    def test_forward_spot_not_found(self):
+        tool = GetSpotKnowledgeTool()
+        with patch("wavereader.agent.get_spot_knowledge") as mock_get:
+            mock_get.return_value = {"error": "Spot 'Bad' (XX) not found"}
+            result = tool.forward("Bad", "XX")
+            assert "error" in result
+
+
+class TestRankSpotsThisWeekTool:
+    def test_forward_success(self):
+        tool = RankSpotsThisWeekTool()
+        with patch("wavereader.agent.rank_spots_this_week") as mock_rank:
+            mock_rank.return_value = [
+                {"name": "A", "region": "QLD", "best_score": 9.0},
+                {"name": "B", "region": "QLD", "best_score": 7.0},
+            ]
+            result = tool.forward("QLD")
+            assert len(result) == 2
+            assert result[0]["best_score"] == 9.0
+            mock_rank.assert_called_once_with("QLD", None)
+
+    def test_forward_with_skill(self):
+        tool = RankSpotsThisWeekTool()
+        with patch("wavereader.agent.rank_spots_this_week") as mock_rank:
+            mock_rank.return_value = []
+            tool.forward("NSW", "advanced")
+            mock_rank.assert_called_once_with("NSW", "advanced")
+
+
+# ---------------------------------------------------------------------------
+# SurfAgent initialization
+# ---------------------------------------------------------------------------
+
+class TestSurfAgentInit:
+    def test_init_with_explicit_provider_hf(self, mock_build_model):
+        agent = SurfAgent(provider=PROVIDER_HF)
+        assert agent.provider == PROVIDER_HF
+        mock_build_model.assert_called_once_with(PROVIDER_HF, DEFAULT_MODEL)
+
+    def test_init_with_explicit_provider_nim(self, mock_build_model):
+        agent = SurfAgent(provider=PROVIDER_NIM)
+        assert agent.provider == PROVIDER_NIM
+        mock_build_model.assert_called_once_with(PROVIDER_NIM, DEFAULT_MODEL)
+
+    def test_init_auto_detect_hf(self, mock_build_model, monkeypatch):
+        monkeypatch.setenv("HF_TOKEN", "test-token")
+        agent = SurfAgent(provider=None)
+        assert agent.provider == PROVIDER_HF
+        mock_build_model.assert_called_once_with(PROVIDER_HF, DEFAULT_MODEL)
+
+    def test_init_auto_detect_nim(self, mock_build_model, monkeypatch):
+        monkeypatch.setenv("NVIDIA_API_KEY", "test-key")
+        agent = SurfAgent(provider=None)
+        assert agent.provider == PROVIDER_NIM
+        mock_build_model.assert_called_once_with(PROVIDER_NIM, DEFAULT_MODEL)
+
+    def test_init_prefers_nim_over_hf(self, mock_build_model, monkeypatch):
+        monkeypatch.setenv("HF_TOKEN", "test-token")
+        monkeypatch.setenv("NVIDIA_API_KEY", "test-key")
+        agent = SurfAgent(provider=None)
+        assert agent.provider == PROVIDER_NIM
+        mock_build_model.assert_called_once_with(PROVIDER_NIM, DEFAULT_MODEL)
+
+    def test_init_unknown_provider_raises(self):
+        with pytest.raises(ValueError, match="Unknown provider"):
+            SurfAgent(provider="unknown")
+
+    def test_init_no_api_key_raises_hf(self, monkeypatch):
+        monkeypatch.delenv("HF_TOKEN", raising=False)
+        monkeypatch.delenv("NVIDIA_API_KEY", raising=False)
+        with pytest.raises(ValueError, match="HF_TOKEN"):
+            SurfAgent(provider=PROVIDER_HF)
+
+    def test_init_no_api_key_raises_nim(self, monkeypatch):
+        monkeypatch.delenv("HF_TOKEN", raising=False)
+        monkeypatch.delenv("NVIDIA_API_KEY", raising=False)
+        with pytest.raises(ValueError, match="NVIDIA_API_KEY"):
+            SurfAgent(provider=PROVIDER_NIM)
+
+    def test_init_custom_model(self, mock_build_model):
+        agent = SurfAgent(provider=PROVIDER_HF, model="custom/model")
+        assert agent.model == "custom/model"
+        mock_build_model.assert_called_once_with(PROVIDER_HF, "custom/model")
+
+
+# ---------------------------------------------------------------------------
+# SurfAgent run / trace capture
+# ---------------------------------------------------------------------------
+
+class TestSurfAgentRun:
+    def test_run_creates_trace(self, mock_build_model):
+        mock_agent = MagicMock()
+        mock_agent.run.return_value = "Test answer"
+
+        with patch("wavereader.agent.CodeAgent", return_value=mock_agent):
+            agent = SurfAgent(provider=PROVIDER_HF)
+            result = agent.run("What's the surf like?")
+
+        assert result == "Test answer"
+        assert agent.trace is not None
+        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):
+        mock_agent = MagicMock()
+        mock_agent.run.return_value = iter(["chunk1", "chunk2", "chunk3"])
+
+        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 agent.trace is not None
+
+    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,
+        )
+        memory_step_without_tool = ActionStep(
+            step_number=2,
+            timing=Timing(start_time=0, end_time=0),
+            tool_calls=[],
+            observations="",
+            is_final_answer=True,
+        )
+
+        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
+
+            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()
+
+        with patch("wavereader.agent.CodeAgent", return_value=mock_agent):
+            agent = SurfAgent(provider=PROVIDER_HF)
+            list(agent.run_stream("Test"))
+
+        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"])
+
+        with patch("wavereader.agent.CodeAgent", return_value=mock_agent):
+            agent = SurfAgent(provider=PROVIDER_HF)
+            list(agent.run_stream("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"
+
+
+# ---------------------------------------------------------------------------
+# Module-level convenience functions
+# ---------------------------------------------------------------------------
+
+def test_run_agent_function(mock_build_model):
+    mock_agent = MagicMock()
+    mock_agent.run.return_value = "Direct answer"
+
+    with patch("wavereader.agent.CodeAgent", return_value=mock_agent):
+        result = run_agent("Test question", provider=PROVIDER_HF)
+
+    assert result == "Direct answer"
+
+
+def test_run_agent_stream_function(mock_build_model):
+    mock_agent = MagicMock()
+    mock_agent.run.return_value = iter(["stream", "ing"])
+
+    with patch("wavereader.agent.CodeAgent", return_value=mock_agent):
+        result = list(run_agent_stream("Test question", provider=PROVIDER_HF))
+
+    assert result == ["stream", "ing"]
+
+
+# ---------------------------------------------------------------------------
+# Provider constants
+# ---------------------------------------------------------------------------
+
+def test_provider_constants():
+    assert PROVIDER_HF == "hf"
+    assert PROVIDER_NIM == "nim"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

tests/test_scoring.py

@@ -0,0 +1,319 @@
+"""Unit tests for wavereader.scoring — deterministic surf-quality scoring."""
+
+from __future__ import annotations
+
+import pytest
+
+from wavereader.scoring import (
+    _angular_diff,
+    _dir_to_deg,
+    _score_period,
+    _score_swell_direction,
+    _score_swell_size,
+    _score_wind,
+    rank_spots_this_week,
+    score_hour,
+    score_week,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_SPOT = {
+    "name": "Test Spot",
+    "region": "QLD",
+    "ideal_swell": {"size_ft_min": 3, "size_ft_max": 8, "direction": "SE"},
+    "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
+}
+
+
+# ---------------------------------------------------------------------------
+# Direction parsing
+# ---------------------------------------------------------------------------
+
+def test_dir_to_deg_simple():
+    assert _dir_to_deg("N") == 0
+    assert _dir_to_deg("E") == 90
+    assert _dir_to_deg("S") == 180
+    assert _dir_to_deg("W") == 270
+    assert _dir_to_deg("SW") == 225
+
+
+def test_dir_to_deg_compound():
+    # W/SW = midpoint of 270 and 225 = 247.5
+    assert _dir_to_deg("W/SW") == 247.5
+    # E/NE = midpoint of 90 and 45 = 67.5
+    assert _dir_to_deg("E/NE") == 67.5
+
+
+# ---------------------------------------------------------------------------
+# Angular diff
+# ---------------------------------------------------------------------------
+
+def test_angular_diff_zero():
+    assert _angular_diff(0, 0) == 0
+
+
+def test_angular_diff_symmetric():
+    assert _angular_diff(45, 315) == 90
+
+
+def test_angular_diff_wrap():
+    assert _angular_diff(350, 10) == 20
+    assert _angular_diff(10, 350) == 20
+
+
+# ---------------------------------------------------------------------------
+# Swell size scoring
+# ---------------------------------------------------------------------------
+
+def test_swell_size_in_ideal():
+    # 4 ft ideal → ~1.22 m; 5 ft → ~1.52 m
+    spot = {
+        "ideal_swell": {"size_ft_min": 4, "size_ft_max": 5, "direction": "SE"},
+        "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
+    }
+    assert score_hour(1.4, 10, 5, 135, spot)["components"]["swell_size"] == 10.0
+
+
+def test_swell_size_outside_low():
+    spot = {
+        "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"]
+    assert s < 10.0 and s > 0.0
+
+
+def test_swell_size_outside_high():
+    spot = {
+        "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"]
+    assert s < 10.0 and s > 0.0
+
+
+def test_swell_size_far_outside_zero():
+    spot = {
+        "ideal_swell": {"size_ft_min": 4, "size_ft_max": 5, "direction": "SE"},
+        "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
+    }
+    assert score_hour(3.0, 10, 5, 135, spot)["components"]["swell_size"] == 0.0
+
+
+# ---------------------------------------------------------------------------
+# Swell direction scoring
+# ---------------------------------------------------------------------------
+
+def test_swell_direction_perfect_match():
+    spot = {
+        "ideal_swell": {"size_ft_min": 3, "size_ft_max": 8, "direction": "SE"},
+        "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
+    }
+    # SE = 135°
+    assert score_hour(1.5, 10, 5, 135, spot)["components"]["swell_direction"] == 10.0
+
+
+def test_swell_direction_opposite():
+    spot = {
+        "ideal_swell": {"size_ft_min": 3, "size_ft_max": 8, "direction": "SE"},
+        "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
+
+
+# ---------------------------------------------------------------------------
+# Wind scoring
+# ---------------------------------------------------------------------------
+
+def test_wind_perfect_offshore():
+    spot = {
+        "ideal_wind": {"strength_kt_max": 10, "direction": "N"},
+        "ideal_swell": {"size_ft_min": 3, "size_ft_max": 8, "direction": "SE"},
+    }
+    # calm wind from N
+    s = score_hour(1.5, 10, 0, 0, spot)["components"]["wind"]
+    assert s == 10.0
+
+
+def test_wind_opposite_direction():
+    spot = {
+        "ideal_wind": {"strength_kt_max": 10, "direction": "N"},
+        "ideal_swell": {"size_ft_min": 3, "size_ft_max": 8, "direction": "SE"},
+    }
+    # strong wind from S (180° away from N)
+    s = score_hour(1.5, 10, 20, 180, spot)["components"]["wind"]
+    assert s == 0.0
+
+
+def test_wind_speed_capped():
+    spot = {
+        "ideal_wind": {"strength_kt_max": 10, "direction": "N"},
+        "ideal_swell": {"size_ft_min": 3, "size_ft_max": 8, "direction": "SE"},
+    }
+    # wind above max speed, perfect direction → speed=0, dir=10 → weighted 5.0
+    s = score_hour(1.5, 10, 12, 0, spot)["components"]["wind"]
+    assert s == 5.0
+
+
+# ---------------------------------------------------------------------------
+# Period scoring
+# ---------------------------------------------------------------------------
+
+def test_period_short():
+    assert _score_period(4.0) == 0.0
+
+
+def test_period_great():
+    assert _score_period(14.0) == 10.0
+
+
+def test_period_too_long():
+    # Very long periods (storm swells) still score high but not perfect
+    assert _score_period(14.0) == 10.0
+    assert _score_period(8.0) > _score_period(5.0)
+
+
+# ---------------------------------------------------------------------------
+# score_hour – composite & breakdown
+# ---------------------------------------------------------------------------
+
+def test_score_hour_shape():
+    result = score_hour(1.5, 10, 5, 135, _SPOT)
+    assert "score" in result
+    assert "components" in result
+    assert set(result["components"].keys()) == {
+        "swell_size", "swell_direction", "wind", "period"
+    }
+    assert 0 <= result["score"] <= 10
+    for v in result["components"].values():
+        assert 0 <= v <= 10
+
+
+def test_score_hour_contains_raw_inputs():
+    result = score_hour(1.5, 10, 5, 135, _SPOT)
+    assert result["wave_height_m"] == 1.5
+    assert result["wave_period_s"] == 10
+    assert result["wind_speed_kt"] == 5
+    assert result["wind_direction_deg"] == 135
+
+
+# ---------------------------------------------------------------------------
+# Bells Beach sanity check (roadmap)
+# ---------------------------------------------------------------------------
+
+def test_bells_beach_swell_nw_wind_high_score():
+    """Bells Beach should score well on SW swell + light NW wind."""
+    bells = {
+        "name": "Bells Beach",
+        "region": "VIC",
+        "ideal_swell": {"size_ft_min": 4, "size_ft_max": 12, "direction": "SW"},
+        "ideal_wind": {"strength_kt_max": 15, "direction": "NW"},
+    }
+    # SW swell = 225°, light NW wind = 315°, low speed
+    result = score_hour(2.0, 12, 5, 315, bells)
+    assert result["score"] > 6.0
+
+
+# ---------------------------------------------------------------------------
+# Kirra sanity check (roadmap): long-period E
+# ---------------------------------------------------------------------------
+
+def test_kirra_long_period():
+    """Kirra scores well on long-period swells."""
+    kirra = {
+        "name": "Kirra",
+        "region": "QLD",
+        "ideal_swell": {"size_ft_min": 3, "size_ft_max": 8, "direction": "SE"},
+        "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
+    }
+    long_result = score_hour(1.5, 14, 5, 135, kirra)
+    short_result = score_hour(1.5, 6, 5, 135, kirra)
+    assert long_result["components"]["period"] > short_result["components"]["period"]
+
+
+# ---------------------------------------------------------------------------
+# score_week
+# ---------------------------------------------------------------------------
+
+def test_score_week_count():
+    forecast = {
+        "hourly": [
+            {
+                "time": "2024-01-01T00:00",
+                "wave_height": 1.5,
+                "wave_period": 10,
+                "wind_speed_10m": 10,
+                "wind_direction_10m": 135,
+            }
+            for _ in range(24)
+        ]
+    }
+    results = score_week(forecast, _SPOT)
+    assert len(results) == 24
+
+
+def test_score_week_has_time_and_score():
+    forecast = {
+        "hourly": [
+            {
+                "time": "2024-01-01T00:00",
+                "wave_height": 1.5,
+                "wave_period": 10,
+                "wind_speed_10m": 10,
+                "wind_direction_10m": 135,
+            }
+        ]
+    }
+    results = score_week(forecast, _SPOT)
+    assert results[0]["time"] == "2024-01-01T00:00"
+    assert "score" in results[0]
+
+
+# ---------------------------------------------------------------------------
+# rank_spots_this_week
+# ---------------------------------------------------------------------------
+
+def test_rank_spots_descending():
+    spot_a = {
+        "name": "A",
+        "region": "QLD",
+        "ideal_swell": {"size_ft_min": 3, "size_ft_max": 8, "direction": "SE"},
+        "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
+    }
+    spot_b = {
+        "name": "B",
+        "region": "NSW",
+        "ideal_swell": {"size_ft_min": 2, "size_ft_max": 4, "direction": "SE"},
+        "ideal_wind": {"strength_kt_max": 10, "direction": "S"},
+    }
+    base_forecast = {
+        "hourly": [
+            {
+                "time": "2024-01-01T00:00",
+                "wave_height": 1.5,
+                "wave_period": 10,
+                "wind_speed_10m": 10,
+                "wind_direction_10m": 135,
+            }
+        ]
+    }
+    forecasts = {
+        ("A", "QLD"): base_forecast,
+        ("B", "NSW"): base_forecast,
+    }
+    # A gets a higher score because its ideal range includes 1.5m better
+    ranked = rank_spots_this_week(forecasts, [spot_a, spot_b])
+    assert len(ranked) == 2
+    assert ranked[0]["best_score"] >= ranked[1]["best_score"]
+
+
+def test_rank_spots_empty():
+    ranked = rank_spots_this_week({}, [])
+    assert ranked == []

tests/test_spots.py

@@ -0,0 +1,185 @@
+"""Unit tests for wavereader.spots — data layer."""
+
+from pathlib import Path
+
+import pytest
+
+from wavereader.spots import (
+    AdditionalDetails,
+    Break,
+    Coordinates,
+    IdealSwell,
+    IdealWind,
+    find_spots,
+    get_spot,
+    load_breaks,
+)
+
+
+# ---------------------------------------------------------------------------
+# load_breaks
+# ---------------------------------------------------------------------------
+
+def test_load_breaks_count():
+    breaks = load_breaks()
+    assert len(breaks) == 100
+
+
+def test_load_breaks_all_have_fields():
+    breaks = load_breaks()
+    for b in breaks:
+        assert b.name
+        assert b.region
+        assert b.coordinates.lat is not None
+        assert b.coordinates.lng is not None
+        assert b.ideal_swell.size_ft_min < b.ideal_swell.size_ft_max
+        assert b.ideal_wind.strength_kt_max > 0
+        assert b.additional_details.skill_level
+
+
+# ---------------------------------------------------------------------------
+# find_spots
+# ---------------------------------------------------------------------------
+
+def test_find_spots_by_name():
+    results = find_spots(query="Snapper")
+    assert all("Snapper" in r.name for r in results)
+
+
+def test_find_spots_by_region():
+    results = find_spots(region="QLD")
+    assert all(r.region == "QLD" for r in results)
+    assert len(results) > 0
+
+
+def test_find_spots_by_skill():
+    results = find_spots(region="QLD", skill="beginner")
+    assert all("beginner" in r.additional_details.skill_level.lower() for r in results)
+
+
+def test_find_spots_limits():
+    results = find_spots(query="", region="NSW", limit=3)
+    assert len(results) <= 3
+
+
+def test_find_spots_empty_query_returns_all():
+    results = find_spots(query="", limit=100)
+    assert len(results) == 100
+
+
+def test_find_spots_no_match():
+    results = find_spots(query="NonexistentBreakXyz")
+    assert results == []
+
+
+# ---------------------------------------------------------------------------
+# get_spot
+# ---------------------------------------------------------------------------
+
+def test_get_spot_existing():
+    spot = get_spot("Snapper Rocks", "QLD")
+    assert spot is not None
+    assert spot.name == "Snapper Rocks"
+    assert spot.region == "QLD"
+
+
+def test_get_spot_missing():
+    spot = get_spot("Nonexistent", "XX")
+    assert spot is None
+
+
+# ---------------------------------------------------------------------------
+# Pydantic validation
+# ---------------------------------------------------------------------------
+
+def test_break_round_trip():
+    b = load_breaks()[0]
+    data = b.model_dump()
+    restored = Break.model_validate(data)
+    assert restored.name == b.name
+
+
+def test_break_invalid_region():
+    with pytest.raises(Exception):
+        Break.model_validate({
+            "name": "Bad",
+            "region": "XX",
+            "short_description": "x",
+            "coordinates": {"lat": -33.0, "lng": 151.0},
+            "ideal_swell": {"size_ft_min": 2.0, "size_ft_max": 5.0, "direction": "SE"},
+            "ideal_wind": {"strength_kt_max": 15.0, "direction": "SW"},
+            "ideal_tide": "mid",
+            "additional_details": {
+                "break_type": "beach",
+                "break_direction": "left",
+                "break_surface": "sand",
+                "bottom_type": "sand",
+                "skill_level": "beginner",
+                "best_season": "summer",
+                "hazards": "rips",
+                "other_notes": "x",
+            },
+        })
+
+
+def test_break_invalid_coords():
+    with pytest.raises(Exception):
+        Break.model_validate({
+            "name": "Bad",
+            "region": "NSW",
+            "short_description": "x",
+            "coordinates": {"lat": 0.0, "lng": 0.0},
+            "ideal_swell": {"size_ft_min": 2.0, "size_ft_max": 5.0, "direction": "SE"},
+            "ideal_wind": {"strength_kt_max": 15.0, "direction": "SW"},
+            "ideal_tide": "mid",
+            "additional_details": {
+                "break_type": "beach",
+                "break_direction": "left",
+                "break_surface": "sand",
+                "bottom_type": "sand",
+                "skill_level": "beginner",
+                "best_season": "summer",
+                "hazards": "rips",
+                "other_notes": "x",
+            },
+        })
+
+
+def test_break_swell_min_lt_max():
+    with pytest.raises(Exception):
+        Break.model_validate({
+            "name": "Bad",
+            "region": "NSW",
+            "short_description": "x",
+            "coordinates": {"lat": -33.0, "lng": 151.0},
+            "ideal_swell": {"size_ft_min": 5.0, "size_ft_max": 3.0, "direction": "SE"},
+            "ideal_wind": {"strength_kt_max": 15.0, "direction": "SW"},
+            "ideal_tide": "mid",
+            "additional_details": {
+                "break_type": "beach",
+                "break_direction": "left",
+                "break_surface": "sand",
+                "bottom_type": "sand",
+                "skill_level": "beginner",
+                "best_season": "summer",
+                "hazards": "rips",
+                "other_notes": "x",
+            },
+        })
+
+
+# ---------------------------------------------------------------------------
+# Region bounding-box validation
+# ---------------------------------------------------------------------------
+
+def test_bells_beach_vic():
+    """Bells Beach is the VIC validation target from the roadmap."""
+    b = get_spot("Bells Beach", "VIC")
+    assert b is not None
+    assert -39.0 <= b.coordinates.lat <= -36.0
+
+
+def test_snapper_rocks_qld():
+    b = get_spot("Snapper Rocks", "QLD")
+    assert b is not None
+    assert -29.0 <= b.coordinates.lat <= -10.0

uv.lock

@@ -156,6 +156,137 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0b/a7/71ac2cff56fec219ed242bb11b8efb69fcc4bec75db06fb7bfe35de520e6/certifi-2026.7.22-py3-none-any.whl", hash = "sha256:62f22742b58a1a33014a2b6b706588a8d7e2a88ae7bd1a6ebe8c992928483775", size = 136983, upload-time = "2026-07-22T03:35:11.276Z" },
 ]
 
+[[package]]
+name = "charset-normalizer"
+version = "3.5.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e5/3f/143b048436775b0f76ac3eec145c019e8173ccc2885c8f20319b996d5e83/charset_normalizer-3.5.1.tar.gz", hash = "sha256:6117b84ea48435e5356dc737f5121485c30920ba43375fa7b434fd753df0eac3", size = 171764, upload-time = "2026-08-15T08:20:44.807Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/30/27/78873dc8b6a56357517b74b6bb9568b80450e7bb4f6ef7e3fa9d22aa0bd7/charset_normalizer-3.5.1-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:5b6d1386bf0096d26d3a863dc0a487a5b4eb9aa93cf5ba69683d29dde6b9d60f", size = 344456, upload-time = "2026-08-15T08:17:10.072Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/4c/be49ada26b1f0232d57aa89bbebf997a5cc2332a5616b6eca26ff680044d/charset_normalizer-3.5.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4582c27e8c889d64811987b5967fbd3ae0c823fe1fd933b543d55ac20bb475fa", size = 238530, upload-time = "2026-08-15T08:17:11.563Z" },
+    { url = "https://files.pythonhosted.org/packages/76/84/6f1290fa07ae6978d3960caa3eb1b8019bf9284ab7c2297b00c099ef4250/charset_normalizer-3.5.1-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:1d1c7a53a6c2103925cdd6d7229f8c567379f211c869793df679f2e9f738c369", size = 230200, upload-time = "2026-08-15T08:17:12.919Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/a0/47b18adeed31c8f16ba9700f32c1b18594cfa09f47eb672a488c273c22bf/charset_normalizer-3.5.1-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e6621fb2a4988d6e53eedc455e5903e2679f3967b8acb3d639f1b63c14a2e893", size = 262222, upload-time = "2026-08-15T08:17:14.571Z" },
+    { url = "https://files.pythonhosted.org/packages/38/fe/341861ac118dae06f3ec0eb487488af52128f2ef2faf0b11003944d22259/charset_normalizer-3.5.1-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:7c0c10730342b0c9b35dd1d619beb8214e520bd96a1f870f452680b238aab3e0", size = 258951, upload-time = "2026-08-15T08:17:16.158Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/89/bb5108dc6c3651dca963f2b0a3ba19bbcb370c94e1b6d3e0e844a58e6dca/charset_normalizer-3.5.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b9af956078716df40d985fb0dfeb2c2120c5ca92ba4ff4b388acfd01cdc14d08", size = 248801, upload-time = "2026-08-15T08:17:17.683Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/ba/ef83ae3aca816393decfa3530976f38a79812d707b80b580ac33b83f9877/charset_normalizer-3.5.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f9f8405c2c758532c74fed975dbee57be1f31a6e865c031870c79a6ed3212ada", size = 244070, upload-time = "2026-08-15T08:17:19.191Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/0b/c5292a2462d69b7378ea89793bbb5b2b6fcf6f7dd6d1667f9619094ad553/charset_normalizer-3.5.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:96fef3e886d6a9874b14f27fc193fbdc69d5d8035783d86aa4e1cea594e695f9", size = 240110, upload-time = "2026-08-15T08:17:20.547Z" },
+    { url = "https://files.pythonhosted.org/packages/46/22/111e5be3b740d5c2a5bfcedb3d237b6591e5c2e82ae9d6ffcb121fe0909c/charset_normalizer-3.5.1-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:5d8531a6569d025f68e2321e7638fb7978f23db58e5f69f56913837aae03816e", size = 232836, upload-time = "2026-08-15T08:17:21.895Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/d2/d2aad6fe0dbb44b194bf3becb60f5a0ac48446ade999a47fe7bb41eb09a7/charset_normalizer-3.5.1-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:aae2ee51122d3ae968a3837d97dc24a0aeebb0dea23694422cd172bd30017cd6", size = 262712, upload-time = "2026-08-15T08:17:23.727Z" },
+    { url = "https://files.pythonhosted.org/packages/35/5a/337e4663a5eae6de99db940ee8066d4145caafb61327db62deda15313cce/charset_normalizer-3.5.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:7235dc28fc6dd9d832ac7c7bce95367dedb85929f17368a0c2bee1e080b9acbf", size = 242977, upload-time = "2026-08-15T08:17:25.157Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/85/f82f8a92e31c7519410e2e1afdc630f28ec47490ce2c09a11c1a43cbb459/charset_normalizer-3.5.1-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:4abdc5f9ad448c1ecbfae2974b820535d6bc6e7eef63babbab3d81cf46968c71", size = 260207, upload-time = "2026-08-15T08:17:26.602Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/52/643d11ffd60e9ac2fd1fb87e167a19285b9eefeff4a40e63c87cbfbeab36/charset_normalizer-3.5.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:ba501e667c17d8411f98e67a022d9604ef179aff0e459b7e292c796837c13573", size = 250562, upload-time = "2026-08-15T08:17:27.971Z" },
+    { url = "https://files.pythonhosted.org/packages/62/16/46556278c2168d12df9da7fede5dc6fc70e60301b26a82bbeec238c9cfe3/charset_normalizer-3.5.1-cp312-cp312-win32.whl", hash = "sha256:cfa1c0cc3a8f9f53f1243a5a99ac36fd003880199383b37672e86ddda9cb07e2", size = 178507, upload-time = "2026-08-15T08:17:29.277Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/7a/4c6c298171e6b3e745633180ff59350fc0ca0db1ffd28df1e369e0579f71/charset_normalizer-3.5.1-cp312-cp312-win_amd64.whl", hash = "sha256:3617ac3cfd8b9888f145ad89dd6e692285834b0201c6074a5eeaad3fd4d668c2", size = 200551, upload-time = "2026-08-15T08:17:30.668Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/d7/eb95a042f0dd22e304b0b6472b154f3546a1a039a9ee89ccb2a7f61591fc/charset_normalizer-3.5.1-cp312-cp312-win_arm64.whl", hash = "sha256:88e85ab89cb822c1e635f51d6d32e488f94e002e70e2f492bdb8b945543f345a", size = 180700, upload-time = "2026-08-15T08:17:32.028Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/61/2cb6ad133dbbb449fa2d37ccae973232f4827e799af258d15e589a3d1e9e/charset_normalizer-3.5.1-cp313-cp313-android_24_arm64_v8a.whl", hash = "sha256:4f298bdadb8f0b9e5672877f647d1be9373ef5320c9e2f049795e26cad28b6a9", size = 211584, upload-time = "2026-08-15T08:17:33.597Z" },
+    { url = "https://files.pythonhosted.org/packages/18/57/a305c968be1ca13f3dd1b32f445877e97addf55d80b65c7cb35fac82b777/charset_normalizer-3.5.1-cp313-cp313-android_24_x86_64.whl", hash = "sha256:88ca277405c2d3b71c4e1c2ee0e7966e807bcba86a69d11e19ba199d18ae4491", size = 223359, upload-time = "2026-08-15T08:17:35.022Z" },
+    { url = "https://files.pythonhosted.org/packages/09/0a/d3646670292ce8d8f8cc11ac067d44885e697a5591f57a9221128da5e7b3/charset_normalizer-3.5.1-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:9362dd90aa7dab48c0054a21187791ccf05473f7dba5d92b8033ae62164675e7", size = 194464, upload-time = "2026-08-15T08:17:36.452Z" },
+    { url = "https://files.pythonhosted.org/packages/de/93/d51ec556e01042fed6f993ea859311bc7917b466684182fbbceb6ca24762/charset_normalizer-3.5.1-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:977cdbd483a9cff38179bea4fd754289a6f2195c7abd414aba85410b3e66cc5e", size = 197676, upload-time = "2026-08-15T08:17:37.819Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/a0/562247944386f7d4ef94467e84876600cc1e0f1b93239aaa9213d2bc3cbd/charset_normalizer-3.5.1-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e90251c0c7bdd54a100a0dce3c07b7e637278c93af29dbf78ebb89a58c4bac7d", size = 340473, upload-time = "2026-08-15T08:17:39.303Z" },
+    { url = "https://files.pythonhosted.org/packages/31/e7/1d994be1b93d41e9502b8b0460eaa88a1dd8df335df415db87d6c3e91ab2/charset_normalizer-3.5.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:94d78ecec2605a8d0398b0f365d5f12a63248438516f5dac536a5eff7337df4a", size = 240156, upload-time = "2026-08-15T08:17:40.66Z" },
+    { url = "https://files.pythonhosted.org/packages/09/53/27923ce5cc6cbccb832037b27dca98882d9c53e9b69e866bbbef4aae7fc8/charset_normalizer-3.5.1-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:d59b75732e9b6f27388e10c14b0259cc5f2e48c78627d185e6a177b58ad3cffe", size = 228246, upload-time = "2026-08-15T08:17:42.003Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/48/5a97e84d63af1d55c07439cb80e56d99a8efb4295700eb4e18c0d1615d2c/charset_normalizer-3.5.1-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:0d929fc574b4d6fd9e7c0f5c2ede8716a41911923aa7fa5fce38e0818aa4a1ac", size = 263660, upload-time = "2026-08-15T08:17:43.627Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/c2/071575791dcc88316c0a9a65ce38897a82e4cfe4a325f0f7fe1b1ac47bcf/charset_normalizer-3.5.1-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:394fea06235c8543390050ed5f529187074b029fb027213f6c46ac11ab5d950e", size = 260354, upload-time = "2026-08-15T08:17:45.094Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/af/63240b0c0248c075c2535a1f1bd992821d8251b9f173abc13329661d09e4/charset_normalizer-3.5.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:62b55f6722735a6c472f88361cde6640608773d9443cebdbb51abf436a1fcdd3", size = 250638, upload-time = "2026-08-15T08:17:46.496Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/66/70dfad64f15be09c15ccfee81330a7e515895dbe296dd23114e9a231268a/charset_normalizer-3.5.1-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fa48b1b63d639f9483e0633e092f5851e2348c352f1f9bb6c8182f87884ef876", size = 244583, upload-time = "2026-08-15T08:17:47.963Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/24/ef36367d38b9ddd4bccbf72888c342e8de1f5ae506fa0b2dcf970e2732a1/charset_normalizer-3.5.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:c71fb0d56c920c269cd3e2e3fe7c610e3f1fdb21a6ce60efa6430ff63676cea6", size = 242038, upload-time = "2026-08-15T08:17:49.481Z" },
+    { url = "https://files.pythonhosted.org/packages/db/ab/55e683ba0fff2e43adafc10daa3001eac90fdaa419a97227d5a7067eedde/charset_normalizer-3.5.1-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:485a0d363cafefcd2538a73c7c838daa2035f09b2c9f9b5e3133f80c6aeb84c2", size = 233677, upload-time = "2026-08-15T08:17:50.845Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/67/0f40eaf8d1b6e7cf15e82382a2965efaca787fc1c2794b7021d37aaf5036/charset_normalizer-3.5.1-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:5c0ea61a470e070686aa30892fed79e297d2c8d0ab46b8bcdf027d38c51da591", size = 264491, upload-time = "2026-08-15T08:17:52.61Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/64/12b4c2a11ee8df4fcc518c78b0d93e3a92bd3d5253d1617ce74ff0e8c7ef/charset_normalizer-3.5.1-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:90b7481fb62fbe172c558bc6fd1c4c98d82004a54a7551f20e11ac9bf0b8708c", size = 245196, upload-time = "2026-08-15T08:17:54.023Z" },
+    { url = "https://files.pythonhosted.org/packages/37/2e/651d910af6d0fba325eee1cda37ec5443462ed25360e666c144166eb6091/charset_normalizer-3.5.1-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:35fe081843b35aad20ffeccec3eeffbe637b15d14f3fb22cc1b59cd8ec17e93c", size = 261660, upload-time = "2026-08-15T08:17:55.491Z" },
+    { url = "https://files.pythonhosted.org/packages/90/c6/b09e05e6db7f64338e0dc067c79577b1138da86c1e38369096851d96be88/charset_normalizer-3.5.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:fd0350afdc3aabd5576f60ea109228bd5538139713c7b094c5cd27c73a98bc6f", size = 252618, upload-time = "2026-08-15T08:17:57.025Z" },
+    { url = "https://files.pythonhosted.org/packages/76/4e/362d4f9fdcdf5556fb2aa3ce7d4a58ebce03ed1ff03aa1d9aca8d02f13f3/charset_normalizer-3.5.1-cp313-cp313-pyemscripten_2025_0_wasm32.whl", hash = "sha256:9d9a0dc7cbe9bec24c3f767c9122c41fe5a1bc43f47cd099d00d393e09769de4", size = 140362, upload-time = "2026-08-15T08:17:58.425Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/d4/703be739b26acce318bd29eb3b25b7209e1b1f527f9eae3d1f1f01fdde2b/charset_normalizer-3.5.1-cp313-cp313-win32.whl", hash = "sha256:d63600d620ad0064c3a748b950ac5ea38a80190e5498532efefa4b7b3f1da1f3", size = 177755, upload-time = "2026-08-15T08:18:00.037Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/33/56d97ade41c8db611e727168c52ae46c9224c362ec28d4b65d7e9869e8da/charset_normalizer-3.5.1-cp313-cp313-win_amd64.whl", hash = "sha256:aea996a6aba25260827c9ea511d1addfde2da9eb686ac961838509086188b7e6", size = 199295, upload-time = "2026-08-15T08:18:01.506Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/75/5b20dd1e6573a01a08158fe104104fa2c8abf941745596954185726cd46c/charset_normalizer-3.5.1-cp313-cp313-win_arm64.whl", hash = "sha256:fd0a274c0e5f9a21565cd9d3dd749b61f96b7aa1e20a93aa1ba4029518f2e5c0", size = 179856, upload-time = "2026-08-15T08:18:02.929Z" },
+    { url = "https://files.pythonhosted.org/packages/29/cd/2b812ce5e888f1ce69a5350281e58aab07ae64a958ecae8912f30865718e/charset_normalizer-3.5.1-cp314-cp314-android_24_arm64_v8a.whl", hash = "sha256:774d157f112367ff4abd29019f38f023c24e00e56edc7829c20e358a5a913ad8", size = 212318, upload-time = "2026-08-15T08:18:04.403Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/4a/a6ee107430768a5334e6d63f31f148a04a1a491ef161a1ac9415a73f2fa8/charset_normalizer-3.5.1-cp314-cp314-android_24_x86_64.whl", hash = "sha256:26422d45fd13551cf564c58932f7d72b4f58b93b0fcf18c35ba6be12b46bb102", size = 224897, upload-time = "2026-08-15T08:18:05.997Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/d9/35ae3f64f29d0179c35c3baefe575904df2913dde519129c7f75995a2b1d/charset_normalizer-3.5.1-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:09a7bba9f739468c8e78c36a75c33768e53cb1959fc638f510454c14683f00d5", size = 194848, upload-time = "2026-08-15T08:18:07.397Z" },
+    { url = "https://files.pythonhosted.org/packages/74/76/f2fc7380f056cc273a53af37f50d08ad54b2c59f61078f31432edcf1c2bd/charset_normalizer-3.5.1-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:4c9548dc78002099910abaebc0a72ac58b7d30931869e0351c09b507dff4ece3", size = 198163, upload-time = "2026-08-15T08:18:08.989Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/40/095ce62fa078483cccc1fa2b36e6bc9580b85422a20ee9f925341c50e44f/charset_normalizer-3.5.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:c428c6c31eb5f4277d7f8eccaf767fbd548ddd5ce3c8b4f4cbbfab3d96b5904c", size = 341823, upload-time = "2026-08-15T08:18:10.458Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/5a/0e58b1c04a1596e0256f407274a92d5fb2ee21324409d1fab1da48a65b5b/charset_normalizer-3.5.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2f06b7eae9dbe77fe1d644ca244dad508de8d302870a43f3c559b521270938a0", size = 242458, upload-time = "2026-08-15T08:18:11.989Z" },
+    { url = "https://files.pythonhosted.org/packages/22/95/b4618ce912e6db0b1aae89ba788e38e8a7eba0f3025cc66e8c0699f977b2/charset_normalizer-3.5.1-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:6b7430cf5728e68f6c462254009a6ef4086e1bea43cf2f57aa9c55fb4f50ff96", size = 226717, upload-time = "2026-08-15T08:18:13.401Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/76/c681192bbda3d55356db5dadd64381d5202b37c6b598fcda5282e88b5d3d/charset_normalizer-3.5.1-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ab743e9bc90c1f73552ec33e10e3331315acd2c397b36065b591b0181de533cc", size = 266111, upload-time = "2026-08-15T08:18:14.961Z" },
+    { url = "https://files.pythonhosted.org/packages/88/be/55127bfca72c0cff6c022488d140d7c5b04c771e3b72e9bdb4836d54979d/charset_normalizer-3.5.1-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f6f7deae3feb4edfa2efaf7c574fe88cbf055038a6abdb40188e4fff66d5699f", size = 263128, upload-time = "2026-08-15T08:18:16.515Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/91/39c3af510b0aa32bbda03374259200f28430febfd1bf5e511fe765282ce5/charset_normalizer-3.5.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:15f024313246a4ed976c60f440bb8d257815513a681d212ff74fd46f7d715a90", size = 251240, upload-time = "2026-08-15T08:18:18.127Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/a5/cbe418bbc6ecdfc3e05a0116002897c4b403a5e838d697e64c78e9f0190d/charset_normalizer-3.5.1-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:823f82903d189af463d7df250ef1f7f696f3cee08cc8d91deb565e8d425f6506", size = 245282, upload-time = "2026-08-15T08:18:19.625Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/a4/689bb42e8e7cd492f3cb64907c6bc00ad247ec9a3628cd3f8eed126e8ae1/charset_normalizer-3.5.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:01e93745f7f219b703b60ba7afead36cfc4242782be5af484673fc500df12da5", size = 244597, upload-time = "2026-08-15T08:18:21.121Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/ce/9962938e179cf9f699d3f1e7b3114b5d7642dee6a893745229f9dd04f274/charset_normalizer-3.5.1-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:329fc3ccb63ad22d867d84c2adea759a64079a37ba4a343433b02c7a2816871e", size = 231376, upload-time = "2026-08-15T08:18:22.57Z" },
+    { url = "https://files.pythonhosted.org/packages/85/54/46000450ada53bd9eac5429a2c8c54cd2d9b39c0c255f229aea9af0948a5/charset_normalizer-3.5.1-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:bb57753e36e4855b8ca375069482250a6246372331a3e4f3407eaebb007443f5", size = 266715, upload-time = "2026-08-15T08:18:24.235Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/bb/618749d70f792b44252a777bf89bfb86823b9bbc1ea13fe8ce759b07f38a/charset_normalizer-3.5.1-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:fce8cbd4997efeb450bd298b54f755dcdff18d496f7a5ddbb4867c6d7c88fdc3", size = 245848, upload-time = "2026-08-15T08:18:25.726Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/3f/ffb64458527c7668031d5eb095d978de561958dc9f5b53f8e488a533e603/charset_normalizer-3.5.1-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:6c9cdde8becb25a7fde49924511aa2644d6f8081cc8df8e9452724303348d8e3", size = 264521, upload-time = "2026-08-15T08:18:27.193Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/ab/74a55fd803916a35ac461daf002708191aac19b546b80dc8cabfedc63d98/charset_normalizer-3.5.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:9ac4444d8d4fd4c4bd08bf451ed3167aa9e7ec6cdb41b648794f1d1103652e36", size = 253054, upload-time = "2026-08-15T08:18:28.568Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/2a/6a9034b7d3c60b17499afb482df5878bf9fa20b50cc3887d5ef017a833db/charset_normalizer-3.5.1-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:f03ac127268b43ef4fe9e6ab6794a6794b49485a0cc0c1db79876d2f33f75bc7", size = 140580, upload-time = "2026-08-15T08:18:30.214Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/46/1d362e1a00d035d66b9869e1281eee115907f7e390a16a07824ab5737360/charset_normalizer-3.5.1-cp314-cp314-win32.whl", hash = "sha256:1f5883d77fd409a261abb5dc8ccbe335720d798b1de4abb3b1d47ccbbc76b53b", size = 180325, upload-time = "2026-08-15T08:18:31.877Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/7c/4938c329b6a9d446f6a59aa2092ff7118f274209b5ed0e26893d1d30a63c/charset_normalizer-3.5.1-cp314-cp314-win_amd64.whl", hash = "sha256:c658c50ac0c98cd755a2dd50b7977d3bca7df401dcc47fbdfa87db53ef7d4e8b", size = 204175, upload-time = "2026-08-15T08:18:33.466Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/33/eeb384dbd8dec570661354592f4f2e1b2fcc92585624d146a000caf53841/charset_normalizer-3.5.1-cp314-cp314-win_arm64.whl", hash = "sha256:4bea7f8ebe90bbd7f0e4a2de42ca6924ba23e3e76418c408ff82f1d46fabd687", size = 184123, upload-time = "2026-08-15T08:18:34.913Z" },
+    { url = "https://files.pythonhosted.org/packages/1c/6c/c73fa9d5a85f6ab05395de61c5f6984e0a9ff40bb5ff888d46dff02526c6/charset_normalizer-3.5.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:fbc597639158fd7c14d55e808718848319540f51b0e6746e3eefa59723a4a348", size = 381682, upload-time = "2026-08-15T08:18:36.349Z" },
+    { url = "https://files.pythonhosted.org/packages/30/c7/63565f860921457feba93bae6c86fb7746deb4cffeed2f375cb845318146/charset_normalizer-3.5.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e71c909f353863b2b89c83de2ebed71ea6d0df8a6ef65a128193c5e650766bef", size = 240826, upload-time = "2026-08-15T08:18:37.887Z" },
+    { url = "https://files.pythonhosted.org/packages/06/ae/7ae8807410dfa33f8e6f1715740adeaafa8a816cc4cb33508f54b1f7c896/charset_normalizer-3.5.1-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:7ac76cf9afd34929d76eb7fcb63be476a4853d8a96f0dcf2d0db68a0cbdf9885", size = 227861, upload-time = "2026-08-15T08:18:39.315Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/a3/887c1642f0da26000b0e0652d91071113c0e72cea33952e225cf589f49a9/charset_normalizer-3.5.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a3a370082ce34d0612f421e15fe011c53bb1feff21a26d06ad4fb244dab5a375", size = 260758, upload-time = "2026-08-15T08:18:40.88Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/11/e6f5b9a3d0e55b0ef7505cd3765cdd48f22db89994c947b316f52f801fd8/charset_normalizer-3.5.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:256dd4d85d9e4dc595e2bc983c980e73f62ddeb3165c58b4c3dfe78c5c8548c1", size = 259950, upload-time = "2026-08-15T08:18:42.351Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/ee/e4e10a94d51cd1ee638aa7e00b65399e6b2a4e8376ab6d2eac9f95586671/charset_normalizer-3.5.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:58d4aa13a59c969dbfdf9e6a9560e242cbfd9e8a8f50c2747714df1a423adf65", size = 249329, upload-time = "2026-08-15T08:18:43.914Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/25/d5f4198819e6059735a84e8d0bfb72dc33976da67b97adcd3fb5a5e07ec6/charset_normalizer-3.5.1-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0c6dfb5ca6723eeed15aa8e564a014d69fcb8812f94eef11fe3631e0508199f5", size = 243137, upload-time = "2026-08-15T08:18:45.368Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/e9/e925ca7569cf9fb9701fd82503fee73eea5268fdb856bdd64947092d3daa/charset_normalizer-3.5.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c010f5581d9c612804cc59fcf7b524b707fbcb72828551237ab545bb5c7034af", size = 242820, upload-time = "2026-08-15T08:18:46.842Z" },
+    { url = "https://files.pythonhosted.org/packages/34/17/672c251a888ed2aebcdd2fe830ad0104e25ff83c43f5c4f9c15e9fc6853c/charset_normalizer-3.5.1-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:52ec005752a56ae79547a05c0139ca2501a0c866390b6115008456b9f0e7cde1", size = 230504, upload-time = "2026-08-15T08:18:48.353Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/fc/f6a85abebd42ce4da2f1db0aa56cc6a0df1995e318b3875d14401b8381d1/charset_normalizer-3.5.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:2bced4061f000f7187254a02ad3433ae17eaf991747ceea2f478422590a5bba9", size = 263087, upload-time = "2026-08-15T08:18:49.859Z" },
+    { url = "https://files.pythonhosted.org/packages/98/66/7c42677e739ba66746b297e2046918d793078094dc239e1e72768cffccc6/charset_normalizer-3.5.1-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:9eea3ab2597a5e65fe65296e2d6a84570845a6b55532d90333d740d48bbc850a", size = 243269, upload-time = "2026-08-15T08:18:51.601Z" },
+    { url = "https://files.pythonhosted.org/packages/de/d8/a50b79237f417af10f8c2a501ce8d1ca87829a22e69117891ca4ba20a69e/charset_normalizer-3.5.1-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:496846868fea80e479324862fa877f02411f2fd0f83b79ccee2607aa68b2a032", size = 258766, upload-time = "2026-08-15T08:18:53.23Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/1d/0fc91aeaeb3c83b748f532399ce67cf84604b48297405d740000f7a9e786/charset_normalizer-3.5.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:85d5855daafc240cc045c026d7a15fd198a09b0fc8ff6f5ecbb5297b509cb11e", size = 250814, upload-time = "2026-08-15T08:18:54.768Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/10/3d8c777cf9024615295aa1b808324ad5b4a77855869c00824bad74ffaf8a/charset_normalizer-3.5.1-cp314-cp314t-win32.whl", hash = "sha256:58d3e12c88e0950bca850ae1f7c256055c097639c2edb9eb123af9807d8b15e4", size = 191074, upload-time = "2026-08-15T08:18:56.305Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/81/ae557d3c44d1a1d688696d60563413a0866a91b7ebc50f20df838be3d8c8/charset_normalizer-3.5.1-cp314-cp314t-win_amd64.whl", hash = "sha256:acaf604462bf330b0d07e7a07c1d6e4adac79e5fb13e9c5140590542cafacc00", size = 216476, upload-time = "2026-08-15T08:18:57.889Z" },
+    { url = "https://files.pythonhosted.org/packages/27/e9/61c01fb8b804692569c036b3fc50495814502dcf13a60649c6055390b02c/charset_normalizer-3.5.1-cp314-cp314t-win_arm64.whl", hash = "sha256:fdb8a068947befafba9952162645dc2fecaeb400e64584829ed5e9b2fbe21a7f", size = 194115, upload-time = "2026-08-15T08:18:59.418Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/4e/8544831ef59d8f27ce92c80871380fdacc8076a8a56ed62f82e54f991333/charset_normalizer-3.5.1-cp315-cp315-macosx_10_15_universal2.whl", hash = "sha256:9085f87b0e38a2b92b8923059b4e8789fe40d9279712d15dcc670048d77079af", size = 342048, upload-time = "2026-08-15T08:19:01.054Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/a6/e3b46852424246065355644f4fb6dbccc0239a42a2eee27ecfc8957f0bcd/charset_normalizer-3.5.1-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2679de311c7946dde5d3b6f44941844133ff5c7cb86099c0061ab1e8901c20a8", size = 242997, upload-time = "2026-08-15T08:19:02.492Z" },
+    { url = "https://files.pythonhosted.org/packages/03/3b/0cc9a26777334ab2f2e3089b948bbf4e4fe72ea70b897715ef6415043ec8/charset_normalizer-3.5.1-cp315-cp315-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:baf3775a2635e5a11fbd5e4e64ee69c7e86875d224a5c72aca4c141064589a90", size = 237014, upload-time = "2026-08-15T08:19:03.943Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/c2/027335f0aa337a2a2e121bac1ad88c4f02ba6053ea0926802784f3db11af/charset_normalizer-3.5.1-cp315-cp315-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8ac8c94b6539074e0f40899301273ac8402b9b3e01c7b7ba269ff30340aaaf20", size = 266174, upload-time = "2026-08-15T08:19:05.598Z" },
+    { url = "https://files.pythonhosted.org/packages/86/d3/e367787febe4e74769dec0f406f2c3c8d1b955fce5aee1fd0f94e8367a45/charset_normalizer-3.5.1-cp315-cp315-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8fe532b3c966d1fb794e0698e4589d0444017ae77fc0b31edea13c0e35bcc449", size = 263361, upload-time = "2026-08-15T08:19:07.251Z" },
+    { url = "https://files.pythonhosted.org/packages/af/3d/391b193eb9f3e84b02f9314088c386debdc0debee843535aaea2e2c6715d/charset_normalizer-3.5.1-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5c84bec0ab5ae0c64bfe73a7d2adcb5ce73b467523fc27fd6a28ab2aa6cbe35a", size = 252143, upload-time = "2026-08-15T08:19:08.816Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/57/de221f1745a90d418199761967e2776bfe2c275a1194220985e8c1d37833/charset_normalizer-3.5.1-cp315-cp315-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:854066be00447fa8de2ccbbe893e2ffc4b123ef16d897af794c1e18bd4a714b0", size = 252086, upload-time = "2026-08-15T08:19:10.255Z" },
+    { url = "https://files.pythonhosted.org/packages/c8/e3/d119f86a01f9331e8186175f24873b1d74a7ee9e2e4b4d68f9947dae5afd/charset_normalizer-3.5.1-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:21b82d8082f6f5e7f456ef0bd16323d08de1266efbfeb476e64b2a91d1471a4e", size = 245231, upload-time = "2026-08-15T08:19:11.807Z" },
+    { url = "https://files.pythonhosted.org/packages/26/de/d8e48c135ae480879539cdb179c8d3b50c7879497d75dd899b5763b69cee/charset_normalizer-3.5.1-cp315-cp315-musllinux_1_2_armv7l.whl", hash = "sha256:838648accb3a7fd9803fd45c87bce8509648eb0c11bc34e216141300977244f2", size = 241546, upload-time = "2026-08-15T08:19:13.416Z" },
+    { url = "https://files.pythonhosted.org/packages/67/c4/217755fd1abc50d326c252922cd642002758095a81ff45010337b8b3ef65/charset_normalizer-3.5.1-cp315-cp315-musllinux_1_2_ppc64le.whl", hash = "sha256:195ce897c6153c0700078142cf8efe3e6454ca4cf4357499e4078dfd83396626", size = 267033, upload-time = "2026-08-15T08:19:14.981Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/d7/34d8e404e358d2adcc5a228c2134643af00104c8fb0bf525f3688d756f05/charset_normalizer-3.5.1-cp315-cp315-musllinux_1_2_riscv64.whl", hash = "sha256:978eab16f55b4ab2c2a745be9a0a840bf8f09a7f227d9c76eb30214d078865a5", size = 252045, upload-time = "2026-08-15T08:19:16.618Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/fa/40414471acf0aa0692ca77305aa00e434fcd8288f0941c93c30e9a5f8f2f/charset_normalizer-3.5.1-cp315-cp315-musllinux_1_2_s390x.whl", hash = "sha256:cc0329df4caaceb950d2f580b5ac716a377f7059624a0bafaeaf8a218c6ed774", size = 264866, upload-time = "2026-08-15T08:19:18.101Z" },
+    { url = "https://files.pythonhosted.org/packages/32/90/fcc850bae791abd2e0c041847f13e270aa08692a79f3e00de6d2dce1cb50/charset_normalizer-3.5.1-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:687c9ca3035544b113bea2055e180af96fb63c0c476e22a9180f51925186e7b7", size = 253932, upload-time = "2026-08-15T08:19:19.734Z" },
+    { url = "https://files.pythonhosted.org/packages/af/af/53afe99068b3c10b4cbae592a52ef72a7c92c0188440e83ee3a078fd8f75/charset_normalizer-3.5.1-cp315-cp315-win32.whl", hash = "sha256:706bfd38730a5ac7a365793269a00f4e988178cec121391f4248d84ad8c972e9", size = 180320, upload-time = "2026-08-15T08:19:21.37Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/bc/f46a132041b29e4a8779ed712d3df1bf112e94ca8de58b66d7ec2c0cf8b9/charset_normalizer-3.5.1-cp315-cp315-win_amd64.whl", hash = "sha256:92caef967d287a407085d61176fce4012b1dd62daed4eb6d5ceb26d3d2538712", size = 204174, upload-time = "2026-08-15T08:19:23.088Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/5d/9ed554480eda8e447b673648628fdc29574d23dbad01fe11837adedd1cae/charset_normalizer-3.5.1-cp315-cp315-win_arm64.whl", hash = "sha256:5fc45d653ea8c9a20479167e11d4a0f8cb2fa3470737ab6f9c827532313187b7", size = 184126, upload-time = "2026-08-15T08:19:24.471Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/32/9b8929bf384061ee1fe5d9c27c6f9776d3d824039ad4e14c88ec00c7808e/charset_normalizer-3.5.1-cp315-cp315t-macosx_10_15_universal2.whl", hash = "sha256:59171c6e45bf07d0d5cab3b0bf81d945035530f6873398b3b531c31184d46663", size = 381441, upload-time = "2026-08-15T08:19:26.038Z" },
+    { url = "https://files.pythonhosted.org/packages/96/10/e9aa7923d3ddac652c99a1c5f7be494e737e151566a44abe018daf757f2c/charset_normalizer-3.5.1-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9dbdd9205662134957cf0c324f639bdc5031c0ca056e2369e238db75187c0f11", size = 241742, upload-time = "2026-08-15T08:19:27.532Z" },
+    { url = "https://files.pythonhosted.org/packages/28/53/a2d249ebddf47b889a100c0bdcb61a2f9dbb8bc24ef325cc062e4f476877/charset_normalizer-3.5.1-cp315-cp315t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e4b018dc5a0eee4676e38fe84a47a427816c590b93b55d9025274ec4d6ffc2dc", size = 235298, upload-time = "2026-08-15T08:19:29.274Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/07/469f78af590f7d5cd48e20d8dbfa3d66deeff9ba37768c04d886b5afd45c/charset_normalizer-3.5.1-cp315-cp315t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ced3fdd71aaa83ce593746c2edb42b7a59cb4c19c8b5c407781c72e493aae55a", size = 262500, upload-time = "2026-08-15T08:19:30.955Z" },
+    { url = "https://files.pythonhosted.org/packages/55/66/3bb56a47f7dcba014055b1a1d33c6f08bbe9c1e74dba154cfa25f90ae885/charset_normalizer-3.5.1-cp315-cp315t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:19a3dd5aa73cef1c99687c4fc57db016a9c17104ae1185da88ba566a5d3bebe4", size = 258888, upload-time = "2026-08-15T08:19:32.458Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/c1/2adc2800903fb013210349313b710a5376856578d9e33e6b9a1d8b36714a/charset_normalizer-3.5.1-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:cc5d36d96478aa9c60654bd932525bf32964c62a7281eafdf16d85003a8d6004", size = 250243, upload-time = "2026-08-15T08:19:33.94Z" },
+    { url = "https://files.pythonhosted.org/packages/95/b5/a18d0dd1157ab655cc2cb14a545f4a4784bbad70ab3502412e36097502d9/charset_normalizer-3.5.1-cp315-cp315t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:04368edf83514385ffc3e1cfd4546e595f4f1272dd23ba437a93a9cc3741d47b", size = 249871, upload-time = "2026-08-15T08:19:35.413Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/c3/525f508cd1e58d0450ac55ed40ac75bc3a97482c59def5278456a5fbf03c/charset_normalizer-3.5.1-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:9b5db6052055d34d41230fb78d7c439c23dc536a9896f6cb039e8dd92cfc1263", size = 243580, upload-time = "2026-08-15T08:19:36.886Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/c1/49a91fe7e97c8140094ca5c64161ab623a70d9f636bf834eace14048acb5/charset_normalizer-3.5.1-cp315-cp315t-musllinux_1_2_armv7l.whl", hash = "sha256:252d099029bcbea642f2a06c4ed5046bdf8b5a8150b64afa5e027e88b106e5ee", size = 239807, upload-time = "2026-08-15T08:19:38.392Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/58/56a48c296601274c4689b864a8e2dfb209b81dfcb39472753ce95eea662b/charset_normalizer-3.5.1-cp315-cp315t-musllinux_1_2_ppc64le.whl", hash = "sha256:6199d5606e2bbf2b096cf64d03f8b6790c91081d5ac866b8e7bb6422738cc60c", size = 264083, upload-time = "2026-08-15T08:19:39.856Z" },
+    { url = "https://files.pythonhosted.org/packages/10/4c/dc48409274a1817ff349711d26c62aa0c597df865d4d69ef79160c859193/charset_normalizer-3.5.1-cp315-cp315t-musllinux_1_2_riscv64.whl", hash = "sha256:77efcff2b23071c349402ac1066667a3d011f62398d81408c9b88ad991747c9e", size = 250317, upload-time = "2026-08-15T08:19:41.53Z" },
+    { url = "https://files.pythonhosted.org/packages/81/58/d325912115caec62d6bdd77bbab5e0b7da5d234a9f20affdffcbcb530d0b/charset_normalizer-3.5.1-cp315-cp315t-musllinux_1_2_s390x.whl", hash = "sha256:a5cbd90ecf0fc62e64726917ad083b73001f0563657a87ec3c0b504e277dc90d", size = 258173, upload-time = "2026-08-15T08:19:43.07Z" },
+    { url = "https://files.pythonhosted.org/packages/34/f7/b13b1ccae2c8ec63980d13be1890eb73f8aeabbfce02a24aabc0908788f5/charset_normalizer-3.5.1-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:4d26f14f041e83dd8edfd61f4cd4fa7285d31798b5bf1f28e70c367ba6c41d61", size = 251960, upload-time = "2026-08-15T08:19:44.587Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/25/ed3f9919c5aef8cc818be1f972f565f7610d7b2076b8ebb98839516ffc3c/charset_normalizer-3.5.1-cp315-cp315t-win32.whl", hash = "sha256:ac13b004224fb341e1e25a1ed5e19d32f57cdb2a403e01f003b46f051a550f6f", size = 191186, upload-time = "2026-08-15T08:19:46.293Z" },
+    { url = "https://files.pythonhosted.org/packages/69/d5/43c2b3e9d8267092b913eb8b0603f0f71993c395632886bd37a7223f96cf/charset_normalizer-3.5.1-cp315-cp315t-win_amd64.whl", hash = "sha256:35aea775dc2bd5f54cd84a1cd2696cc3207c479cb9cf0bd346f0d343e4300ddb", size = 215947, upload-time = "2026-08-15T08:19:47.853Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/76/9aad3e9c8865e5e0efa9a7f6f81c37a67635a985145ecd44528a81e088ee/charset_normalizer-3.5.1-cp315-cp315t-win_arm64.whl", hash = "sha256:fb78f6e7fcd8ad785d28cd577168bc1aaee827b25bb8755638f694794ea98f0a", size = 193909, upload-time = "2026-08-15T08:19:49.383Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/97/fb4e82231aba271ffd775a1b4993b0defc4e3059f286ae41d9433409fe85/charset_normalizer-3.5.1-cp37-abi3-macosx_10_9_universal2.whl", hash = "sha256:41876ee62a3dddf48ff1121ad8f0798032aa03f2fd35f21f34a4cab14f18d8d2", size = 331467, upload-time = "2026-08-15T08:19:50.959Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/2f/fe3f187327aac18e2d54e9d2b08e15d27bf9b642d9e51c219f130fc34d1a/charset_normalizer-3.5.1-cp37-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:a6dac12ff6b846103483683f60c5f8fee205121adc58ffd87e90a90a3af69e99", size = 253057, upload-time = "2026-08-15T08:19:52.654Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/c7/9e48cee5c161fe24da823b61bf381921d77cb994a0a4de148e95018c1984/charset_normalizer-3.5.1-cp37-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:cee5dd7c6fb5dd52a0fe2a740f9bc6e3593f5f8b1788bde49de02086f30182b2", size = 240930, upload-time = "2026-08-15T08:19:54.163Z" },
+    { url = "https://files.pythonhosted.org/packages/49/e0/716601f3cc69be7b198951150c75ead1ece33c3c8036ff6ffa46029659a0/charset_normalizer-3.5.1-cp37-abi3-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:343fb4f2821043bd87095f7b08a1a181febc8e36ac64212143bbfd0a0e1bc235", size = 230822, upload-time = "2026-08-15T08:19:55.807Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/05/71bfc5caa0abcc45aea1f6a4d50ac68e59605ddc7666fe8494f4cd229665/charset_normalizer-3.5.1-cp37-abi3-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ae4a097991662cd4fff0ddc74e0fe7874f82e00042fa0ea00855645ed0c79598", size = 260037, upload-time = "2026-08-15T08:19:57.312Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/92/de7e32ed05341e7a9c4c877c318418197b7f2d66a3b68d561bf2ac57ca3e/charset_normalizer-3.5.1-cp37-abi3-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:4b599739b93b2cbeded49645ae3c8d1405c29ddfbceac1545c87a3f9580a9e96", size = 255097, upload-time = "2026-08-15T08:19:59.056Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/7b/ade0a122600319dfa0b1000ab0f9731c94a817904cf3c5de408c73a4ede7/charset_normalizer-3.5.1-cp37-abi3-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:b39b69b347e5e47a3b5b8cfc005c68c1ba347474e3960236c4944a8ecd174962", size = 250166, upload-time = "2026-08-15T08:20:00.612Z" },
+    { url = "https://files.pythonhosted.org/packages/75/9c/019fbb9f4834491a160951349b1a3714439376f66e5f7cf18b4f18f0c7aa/charset_normalizer-3.5.1-cp37-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:a2028475ba855475b8b4d3cfeb4994269c967aea8b9892dfba907f4263a863a3", size = 241821, upload-time = "2026-08-15T08:20:02.321Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/b8/11d4840bfc99330cc7fbcc2681ee5a044553a6e77655508d8f9b2bff7b34/charset_normalizer-3.5.1-cp37-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:36047af20e17097c3bb9476c2b7655f2f7aa51322c0ba58c07695bedf755a950", size = 232529, upload-time = "2026-08-15T08:20:04.008Z" },
+    { url = "https://files.pythonhosted.org/packages/18/96/2b3a21492d9f65171ac75d872f5018260013d00bfa0ff70ec9f179148cbd/charset_normalizer-3.5.1-cp37-abi3-musllinux_1_2_ppc64le.whl", hash = "sha256:4c4fb141a727957c93edfe5c32a26ceb6b5f6461d67146e2d39f51e16170bea8", size = 260348, upload-time = "2026-08-15T08:20:05.877Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/aa/a69a2028e8bd052476c245460ab19d7de595de084dd968f2d75cd50c3e25/charset_normalizer-3.5.1-cp37-abi3-musllinux_1_2_riscv64.whl", hash = "sha256:2f293479cce755c75f1697e87c409b7ae4c555c7dfecb6e988ad13abba943031", size = 247234, upload-time = "2026-08-15T08:20:07.487Z" },
+    { url = "https://files.pythonhosted.org/packages/35/8a/3d130aeabcaf3d2466af76b7b141c08d9e89c9016ab4b7cdd0f7dc2d1c62/charset_normalizer-3.5.1-cp37-abi3-musllinux_1_2_s390x.whl", hash = "sha256:3588e376b3ea2eea84976f67273d679f229e24c66dce7b82ae45aef04ff6e072", size = 256917, upload-time = "2026-08-15T08:20:09.142Z" },
+    { url = "https://files.pythonhosted.org/packages/80/c2/a7379b840292d0c1ab9fbd17d1f3967aa81794dc95bc74be8999d7fedcf7/charset_normalizer-3.5.1-cp37-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:e199fb99720074809a7720f1c0b4d919eea8b87e88713e0f8f602f7bef543d9d", size = 254846, upload-time = "2026-08-15T08:20:10.727Z" },
+    { url = "https://files.pythonhosted.org/packages/01/65/d43b714731bb2f40d4053dfa00ecfc1c5a301f8e3316c5db3a09af59fe94/charset_normalizer-3.5.1-cp37-abi3-win32.whl", hash = "sha256:dd732602a7009217f658d5863d12d79d373a4de0eebc111094bcdd3bb8e0a6cc", size = 174216, upload-time = "2026-08-15T08:20:12.334Z" },
+    { url = "https://files.pythonhosted.org/packages/35/4f/b911ed898b26a09789eba9c9200c999aff6c61b4bafaf4838e56d1a1e1a3/charset_normalizer-3.5.1-cp37-abi3-win_amd64.whl", hash = "sha256:70055ff39b97c99e7ae40ea3e393fb62aa2e44dbd9b29f8d14f42fb0025c3959", size = 199764, upload-time = "2026-08-15T08:20:13.908Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/a7/920baf467bfd9bf689f3b318340f37aee4572a71f162bd8db51da55ba4fa/charset_normalizer-3.5.1-cp37-abi3-win_arm64.whl", hash = "sha256:87e4f41d375c0b9be2fb5251aee4b8a689169e134535aed81bf085c3b647451e", size = 287318, upload-time = "2026-08-15T08:20:15.551Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/61/d01fc49b8dea277640b55a9e15960dbca9fdc8c9fde18e572d39c59f4019/charset_normalizer-3.5.1-py3-none-any.whl", hash = "sha256:6df0ec430f9a831772c23ca5a224cba36517a58a84bb32c32bb59a9fa67c47f6", size = 68658, upload-time = "2026-08-15T08:20:43.306Z" },
+]
+
 [[package]]
 name = "click"
 version = "8.5.0"
@@ -1515,6 +1646,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
 ]
 
+[[package]]
+name = "requests"
+version = "2.34.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "charset-normalizer" },
+    { name = "idna" },
+    { name = "urllib3" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ac/c3/e2a2b89f2d3e2179abd6d00ebd70bff6273f37fb3e0cc209f48b39d00cbf/requests-2.34.2.tar.gz", hash = "sha256:f288924cae4e29463698d6d60bc6a4da69c89185ad1e0bcc4104f584e960b9ed", size = 142856, upload-time = "2026-05-14T19:25:27.735Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/f4/c67b0b3f1b9245e8d266f0f112c500d50e5b4e83cb6f3b71b6528104182a/requests-2.34.2-py3-none-any.whl", hash = "sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0", size = 73075, upload-time = "2026-05-14T19:25:26.443Z" },
+]
+
 [[package]]
 name = "rich"
 version = "15.0.0"
@@ -1698,6 +1844,23 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" },
 ]
 
+[[package]]
+name = "smolagents"
+version = "1.26.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "huggingface-hub" },
+    { name = "jinja2" },
+    { name = "pillow" },
+    { name = "python-dotenv" },
+    { name = "requests" },
+    { name = "rich" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/bd/85/3ca67bb57743434ac321821ea54cbdbf0d3dcc8d55f37199709e83141340/smolagents-1.26.0.tar.gz", hash = "sha256:4ec92313265f9cfbcabfc88e192b4bc4505f8475dc5f33dc872062fc567037bd", size = 239034, upload-time = "2026-05-29T05:08:44.732Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/89/8c/72bd5edc13288e3f27d4d9c1ef65adc0a68c950ee1fc6d3be270e1110f6c/smolagents-1.26.0-py3-none-any.whl", hash = "sha256:70e1cfb1576f782da93190ee31d9bb2659e5ca4bd84fda0c412e1f20498f28b6", size = 161466, upload-time = "2026-05-29T05:08:43.28Z" },
+]
+
 [[package]]
 name = "sniffio"
 version = "1.3.1"
@@ -1958,6 +2121,7 @@ dependencies = [
     { name = "huggingface-hub" },
     { name = "openai" },
     { name = "pydantic" },
+    { name = "smolagents" },
 ]
 
 [package.dev-dependencies]
@@ -1975,6 +2139,7 @@ requires-dist = [
     { name = "huggingface-hub", specifier = ">=1.29.0" },
     { name = "openai" },
     { name = "pydantic" },
+    { name = "smolagents", specifier = ">=1.26.0" },
 ]
 
 [package.metadata.requires-dev]

wavereader/agent.py

@@ -1,7 +1,7 @@
-"""Hand-rolled agent tool loop (~100 lines, no LangChain / no frameworks).
+"""smolagents CodeAgent for surf forecasting.
 
-Provider-agnostic: one OpenAI-compatible client class; base URL + key come
-from env (``HF_TOKEN`` -> https://router.huggingface.co/v1,
+Provider-agnostic: uses InferenceClientModel with base URL + key 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
@@ -14,11 +14,274 @@ trace panel.
 
 from __future__ import annotations
 
+import json
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any
 
-def run_agent(question: str, model: str | None = None) -> str:
-    """Run the tool loop to answer a surf question.
+from smolagents import CodeAgent, InferenceClientModel, PromptTemplates, Tool, tool
+import yaml
+import importlib.resources
 
-    TODO: system prompt, tool dispatch loop (tools.py), streaming output,
-    trace capture, provider switch via env.
-    """
-    raise NotImplementedError
+from wavereader import forecasts, scoring, spots
+from wavereader.tools import (
+    find_spots,
+    get_forecast,
+    get_spot_knowledge,
+    rank_spots_this_week,
+    score_week,
+)
+
+SYSTEM_PROMPT = """You are a surf forecasting assistant for Australian breaks.
+
+IMPORTANT RULES:
+1. You NEVER compute scores, forecasts, or rankings yourself. All numbers MUST come from the provided tools.
+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.
+"""
+
+PROVIDER_HF = "hf"
+PROVIDER_NIM = "nim"
+
+DEFAULT_MODEL = "Qwen/Qwen3-Next-80B-A3B-Instruct"
+HF_BASE_URL = "https://router.huggingface.co/v1"
+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"
+    timestamp: float
+    data: dict[str, Any]
+
+
+@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))
+
+    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
+            ]
+        })
+
+
+class GetForecastTool(Tool):
+    name = "get_forecast"
+    description = "Get hourly marine + wind forecast for a named spot."
+    inputs = {
+        "spot_name": {"type": "string", "description": "Name of the surf spot (e.g., 'Snapper Rocks')"},
+        "region": {"type": "string", "description": "Australian state/region (NSW, QLD, VIC, WA, SA, TAS)"},
+    }
+    output_type = "object"
+
+    def forward(self, spot_name: str, region: str) -> dict:
+        return get_forecast(spot_name, region)
+
+
+class ScoreWeekTool(Tool):
+    name = "score_week"
+    description = "Get hour-by-hour surf scores for the next 7 days at a spot."
+    inputs = {
+        "spot_name": {"type": "string", "description": "Name of the surf spot"},
+        "region": {"type": "string", "description": "Australian state/region"},
+    }
+    output_type = "object"
+
+    def forward(self, spot_name: str, region: str) -> list[dict]:
+        return score_week(spot_name, region)
+
+
+class FindSpotsTool(Tool):
+    name = "find_spots"
+    description = "Search breaks by name/region with optional skill filter."
+    inputs = {
+        "query": {"type": "string", "description": "Search query for spot name or region", "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)
+
+
+class GetSpotKnowledgeTool(Tool):
+    name = "get_spot_knowledge"
+    description = "Get knowledge-base profile for a spot (ideal swell/wind/tide, skill level, hazards)."
+    inputs = {
+        "spot_name": {"type": "string", "description": "Name of the surf spot"},
+        "region": {"type": "string", "description": "Australian state/region"},
+    }
+    output_type = "object"
+
+    def forward(self, spot_name: str, region: str) -> dict:
+        return get_spot_knowledge(spot_name, region)
+
+
+class RankSpotsThisWeekTool(Tool):
+    name = "rank_spots_this_week"
+    description = "Rank spots in a region by their best score this week, with optional skill filter."
+    inputs = {
+        "region": {"type": "string", "description": "Australian state/region"},
+        "skill": {"type": "string", "description": "Skill level filter", "nullable": True},
+    }
+    output_type = "object"
+
+    def forward(self, region: str, skill: str | None = None) -> list[dict]:
+        return rank_spots_this_week(region, skill)
+
+
+TOOLS = [
+    GetForecastTool(),
+    ScoreWeekTool(),
+    FindSpotsTool(),
+    GetSpotKnowledgeTool(),
+    RankSpotsThisWeekTool(),
+]
+
+
+def _build_model(provider: str, model: str | None = None) -> InferenceClientModel:
+    """Build the InferenceClientModel for the given provider."""
+    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(
+            model_id=model_id,
+            api_base=HF_BASE_URL,
+            token=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(
+            model_id=model_id,
+            api_base=NIM_BASE_URL,
+            token=api_key,
+        )
+    else:
+        raise ValueError(f"Unknown provider: {provider}. Use 'hf' or 'nim'")
+
+
+def _detect_provider() -> str:
+    """Auto-detect provider from available env vars."""
+    if os.getenv("NVIDIA_API_KEY"):
+        return PROVIDER_NIM
+    if os.getenv("HF_TOKEN"):
+        return PROVIDER_HF
+    return PROVIDER_HF
+
+
+class SurfAgent:
+    """Surf forecasting agent with streaming and trace capture."""
+
+    def __init__(
+        self,
+        provider: str | None = None,
+        model: str | None = None,
+    ):
+        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()
+        default_templates = yaml.safe_load(default_templates_yaml)
+        default_templates["system_prompt"] = SYSTEM_PROMPT
+        prompt_templates = PromptTemplates(**default_templates)
+        self._agent = CodeAgent(
+            tools=TOOLS,
+            model=self._model,
+            prompt_templates=prompt_templates,
+            max_steps=10,
+        )
+        self._trace: AgentTrace | None = None
+
+    @property
+    def trace(self) -> AgentTrace | None:
+        return self._trace
+
+    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
+
+        try:
+            for chunk in self._agent.run(question, stream=True):
+                if self._trace:
+                    self._trace.add_event("llm_chunk", {"chunk": str(chunk)})
+                yield chunk
+        finally:
+            self._agent.step = original_step
+
+
+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):
+    """Run the surf agent with streaming."""
+    agent = SurfAgent(provider=provider, model=model)
+    yield from agent.run_stream(question)
+
+
+if __name__ == "__main__":
+    import sys
+    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()

wavereader/forecasts.py

@@ -2,28 +2,32 @@
 
 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).
+* ``marine-api.open-meteo.com`` — hourly ``wave_height`` (m),
+  ``wave_period`` (s), ``wave_direction`` (deg), ``wind_wave_height`` (m),
+  ``swell_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.
+-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.
+Cache every response to disk: the demo must survive API flakiness and
+rate limits. Horizon: hourly, 7 days.
 """
 
 from __future__ import annotations
 
+import json
+from pathlib import Path
+
+import httpx
+
 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",
@@ -31,16 +35,102 @@ MARINE_HOURLY_FIELDS = (
     "wind_wave_height",
     "swell_wave_height",
 )
-WEATHER_HOURLY_FIELDS = (
-    "wind_speed_10m",
-    "wind_direction_10m",
-)
+WEATHER_HOURLY_FIELDS = ("wind_speed_10m", "wind_direction_10m")
+
+_SNAP_OFFSET = (-0.133, 0.074)
+
+CACHE_DIR = Path(__file__).resolve().parent.parent / ".cache" / "forecasts"
+
+
+def _round_coords(lat: float, lon: float) -> tuple[float, float]:
+    return round(lat + _SNAP_OFFSET[0], 2), round(lon + _SNAP_OFFSET[1], 2)
+
+
+def _cache_key(lat: float, lon: float, days: int) -> str:
+    return f"{lat:.2f}_{lon:.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:
+    p = _cache_path(lat, lon, days)
+    if p.exists():
+        return json.loads(p.read_text(encoding="utf-8"))
+    return None
+
+
+def _save_cache(lat: float, lon: float, days: int, data: dict) -> None:
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    _cache_path(lat, lon, days).write_text(
+        json.dumps(data, ensure_ascii=False), encoding="utf-8"
+    )
+
+
+def _build_normalized(marine: dict, weather: dict) -> dict:
+    """Merge marine + weather hourly on ``time`` into a clean frame."""
+    m = marine["hourly"]
+    w = weather["hourly"]
+    marine_times = m["time"]
+
+    weather_index: dict[str, dict[str, float]] = {}
+    for i, t in enumerate(w["time"]):
+        entry: dict[str, float] = {"time": t}
+        for field in WEATHER_HOURLY_FIELDS:
+            if field in w and i < len(w[field]):
+                entry[field] = w[field][i]
+        weather_index[t] = entry
+
+    frames: list[dict] = []
+    for i, t in enumerate(marine_times):
+        row: dict[str, float | str] = {"time": t}
+        for field in MARINE_HOURLY_FIELDS:
+            if field in m and i < len(m[field]):
+                row[field] = m[field][i]
+        wr = weather_index.get(t)
+        if wr:
+            for field in WEATHER_HOURLY_FIELDS:
+                if field in wr:
+                    row[field] = wr[field]
+        frames.append(row)
+
+    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.
 
-    TODO: httpx client, disk cache (keyed by rounded coords + day),
-    merge the two responses, return a normalized hourly frame.
+    Returns a normalised frame: ``{"hourly": [{"time": ..., "wave_height": ...,
+    "wind_speed_10m": ..., ...}, ...]}``.  Disk-cached by rounded coords + days.
     """
-    raise NotImplementedError
+    rlat, rlon = _round_coords(lat, lon)
+    cached = _load_cache(rlat, rlon, days)
+    if cached is not None:
+        return cached
+
+    params: dict[str, str | int | float] = {
+        "latitude": rlat,
+        "longitude": rlon,
+        "forecast_days": days,
+    }
+
+    with httpx.Client(timeout=30.0, follow_redirects=True) as client:
+        resp_m = client.get(MARINE_URL, params={**params, "hourly": ",".join(MARINE_HOURLY_FIELDS)})
+        resp_m.raise_for_status()
+        marine = resp_m.json()
+        resp_w = client.get(WEATHER_URL, params={**params, "hourly": ",".join(WEATHER_HOURLY_FIELDS)})
+        resp_w.raise_for_status()
+        weather = resp_w.json()
+
+    merged = _build_normalized(marine, weather)
+    _save_cache(rlat, rlon, days, merged)
+    return merged
+
+
+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])

wavereader/scoring.py

@@ -2,13 +2,129 @@
 
 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).
+(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.
 """
 
 from __future__ import annotations
 
+import math
+
+# ---- 16-point compass → degrees (midpoint) ----
+
+_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,
+}
+
+# Weights for the four components → sum to 1.0
+_WEIGHTS = {
+    "swell_size": 0.25,
+    "swell_direction": 0.20,
+    "wind": 0.30,
+    "period": 0.25,
+}
+
+
+def _dir_to_deg(direction: str) -> float:
+    """Parse a cardinal direction string to degrees.
+
+    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)
+
+
+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 _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,
+    )
+
+
+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.
+    """
+    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)
+
+
+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.
+
+    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.
+    """
+    ideal = spot["ideal_wind"]
+    ideal_dir_deg = _dir_to_deg(ideal["direction"])
+
+    # 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)
+
+    # 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)
+
+    return speed_score * 0.5 + dir_score * 0.5
+
+
+def _score_period(period_s: float) -> float:
+    """Score 0-10 for wave period.
+
+    Longer periods = better quality. 8 s → ~6, 10 s → 8, 14 s+ → 10,
+    falling off after ~16 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
+
 
 def score_hour(
     wave_height_m: float,
@@ -19,16 +135,78 @@ def score_hour(
 ) -> 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.
+    Returns a dict with the composite 0-10 ``score``, a per-component
+    ``components`` breakdown, and the raw inputs for the UI.
     """
-    raise NotImplementedError
+    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)
+    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"]
+    )
+
+    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),
+        },
+        "wave_height_m": wave_height_m,
+        "wave_period_s": wave_period_s,
+        "wind_speed_kt": wind_speed_kt,
+        "wind_direction_deg": wind_direction_deg,
+    }
 
 
 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.
+    ``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:
+        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"]),
+            spot=spot,
+        )
+        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.
+
+    ``forecasts`` maps ``(name, region)`` → normalised forecast frame.
+    Returns entries sorted by best score descending.
     """
-    raise NotImplementedError
+    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,
+        })
+    ranked.sort(key=lambda x: x["best_score"], reverse=True)
+    return ranked

wavereader/spots.py

@@ -3,31 +3,148 @@
 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.
+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:
+import json
+from pathlib import Path
+
+from pydantic import BaseModel, field_validator, model_validator
+
+DATA_PATH = Path(__file__).resolve().parent.parent / "data" / "break_details.json"
+VALID_REGIONS = {"NSW", "QLD", "VIC", "WA", "SA", "TAS"}
+VALID_SKILL_LEVELS = {
+    "beginner",
+    "beginner to intermediate",
+    "beginner to advanced",
+    "intermediate",
+    "intermediate to advanced",
+    "intermediate to expert",
+    "advanced",
+    "advanced to expert",
+    "expert",
+    "expert only",
+    "elite/professional only",
+}
+
+# Approximate bounding boxes per Australian state/territory (lat_min, lng_min, lat_max, lng_max).
+_REGION_BOUNDS: dict[str, tuple[float, float, float, float]] = {
+    "NSW": (-37.5, 147.5, -26.0, 154.5),
+    "QLD": (-29.0, 138.0, -10.0, 154.5),
+    "VIC": (-39.5, 140.5, -36.0, 150.5),
+    "WA": (-36.0, 113.0, -15.0, 130.0),
+    "SA": (-38.5, 135.5, -34.0, 142.5),
+    "TAS": (-44.0, 144.0, -39.0, 149.5),
+}
+
+
+class Coordinates(BaseModel):
+    lat: float
+    lng: float
+
+
+class IdealSwell(BaseModel):
+    size_ft_min: float
+    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:
+            raise ValueError("size_ft_min must be strictly less than size_ft_max")
+        return self
+
+
+class IdealWind(BaseModel):
+    strength_kt_max: float
+    direction: str
+
+    @field_validator("strength_kt_max")
+    @classmethod
+    def positive(cls, v: float) -> float:
+        if v <= 0:
+            raise ValueError("strength_kt_max must be positive")
+        return v
+
+
+class AdditionalDetails(BaseModel):
+    break_type: str
+    break_direction: str
+    break_surface: str
+    bottom_type: str
+    skill_level: str
+    best_season: str
+    hazards: str
+    other_notes: str
+
+    @field_validator("skill_level")
+    @classmethod
+    def valid_skill(cls, v: str) -> str:
+        if v not in VALID_SKILL_LEVELS:
+            raise ValueError(f"skill_level '{v}' not in known levels")
+        return v
+
+
+class Break(BaseModel):
     name: str
     region: str
-
-
-def load_breaks() -> list[dict]:
+    short_description: str
+    coordinates: Coordinates
+    ideal_swell: IdealSwell
+    ideal_wind: IdealWind
+    ideal_tide: str
+    additional_details: AdditionalDetails
+
+    @field_validator("region")
+    @classmethod
+    def valid_region(cls, v: str) -> str:
+        if v not in VALID_REGIONS:
+            raise ValueError(f"region '{v}' not in {VALID_REGIONS}")
+        return v
+
+    @field_validator("coordinates")
+    @classmethod
+    def coords_in_bounds(cls, v: Coordinates, info: dict) -> Coordinates:
+        region = info.data.get("region")
+        if region and region in _REGION_BOUNDS:
+            lo_lat, lo_lng, hi_lat, hi_lng = _REGION_BOUNDS[region]
+            if not (lo_lat <= v.lat <= hi_lat and lo_lng <= v.lng <= hi_lng):
+                raise ValueError(
+                    f"coords ({v.lat}, {v.lng}) outside plausible range for {region}"
+                )
+        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``.
 
-    TODO: parse into pydantic models, run validation (coords vs region,
-    sane ranges), raise on failure.
+    Raises on validation failure so broken data is caught early.
     """
-    raise NotImplementedError
+    p = Path(path) if path else DATA_PATH
+    raw = json.loads(p.read_text(encoding="utf-8"))
+    breaks: list[Break] = []
+    for i, record in enumerate(raw):
+        try:
+            breaks.append(Break.model_validate(record))
+        except Exception as exc:
+            raise ValueError(
+                f"Invalid record at index {i}: {record.get('name', '?')} "
+                f"({record.get('region', '?')})"
+            ) from exc
+    return breaks
 
 
 def find_spots(
@@ -35,19 +152,32 @@ def find_spots(
     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.
+) -> list[Break]:
+    """Search breaks by name/region and optional skill filter.
 
-    TODO: keyed lookup by (name, region).
+    Case-insensitive substring match over name and region.
     """
-    raise NotImplementedError
+    all_breaks = load_breaks()
+    q = query.lower().strip()
+    results: list[Break] = []
+    for b in all_breaks:
+        if q and q not in b.name.lower() and q not in b.region.lower():
+            continue
+        if region and b.region != region:
+            continue
+        if skill:
+            skill_lower = skill.lower()
+            if skill_lower not in b.additional_details.skill_level.lower():
+                continue
+        results.append(b)
+        if len(results) >= limit:
+            break
+    return results
+
+
+def get_spot(name: str, region: str) -> Break | None:
+    """Return the full knowledge-base record for one break, keyed by (name, region)."""
+    for b in load_breaks():
+        if b.name == name and b.region == region:
+            return b
+    return None

wavereader/tools.py

@@ -6,6 +6,8 @@ model chooses them, the deterministic modules compute the values.
 
 from __future__ import annotations
 
+from wavereader import forecasts, scoring, spots
+
 TOOL_SCHEMAS = (
     "get_forecast",
     "score_week",
@@ -15,26 +17,47 @@ TOOL_SCHEMAS = (
 )
 
 
-def get_forecast(spot: str) -> dict:
-    """Hourly marine + wind forecast for a named spot. TODO."""
-    raise NotImplementedError
+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: str) -> dict:
-    """Hour-by-hour surf scores for the next 7 days at a spot. TODO."""
-    raise NotImplementedError
+def score_week(spot_name: str, region: str) -> list[dict]:
+    """Hour-by-hour surf scores for the next 7 days at a spot."""
+    s = spots.get_spot(spot_name, region)
+    if s is None:
+        return []
+    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) -> list[dict]:
-    """Search breaks by name/region with optional skill filter. TODO."""
-    raise NotImplementedError
+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: str) -> dict:
-    """Knowledge-base profile for a spot (ideal swell/wind/tide). TODO."""
-    raise NotImplementedError
+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"}
+    return s.model_dump()
 
 
 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
+    """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] = {}
+    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],
+    )