polish: scoring null-hardening, spot adapter fix, UI loading states + MCP badge copy

requirements.txt

@@ -0,0 +1,258 @@
+Resolved 83 packages in 3ms
+# This file was autogenerated by uv via the following command:
+#    uv export --no-hashes --format requirements-txt --no-dev
+annotated-doc==0.0.5
+    # via
+    #   fastapi
+    #   typer
+annotated-types==0.8.0
+    # via pydantic
+anyio==4.15.1
+    # via
+    #   gradio
+    #   httpx
+    #   httpx2
+    #   mcp
+    #   openai
+    #   sse-starlette
+    #   starlette
+attrs==26.1.0
+    # via
+    #   jsonschema
+    #   referencing
+audioop-lts==0.2.2
+    # via gradio
+brotli==1.2.0
+    # via gradio
+certifi==2026.7.22
+    # via
+    #   httpcore
+    #   httpx
+    #   requests
+cffi==2.1.1 ; platform_python_implementation != 'PyPy'
+    # via cryptography
+charset-normalizer==3.5.1
+    # via requests
+click==8.5.0
+    # via
+    #   huggingface-hub
+    #   uvicorn
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via
+    #   tqdm
+    #   typer
+cryptography==50.0.1
+    # via pyjwt
+fastapi==0.141.1
+    # via gradio
+filelock==3.32.5
+    # via huggingface-hub
+fsspec==2026.7.0
+    # via
+    #   gradio-client
+    #   huggingface-hub
+gradio==6.26.0
+    # via wavereader
+gradio-client==2.6.1
+    # via
+    #   gradio
+    #   hf-gradio
+groovy==0.1.2
+    # via gradio
+h11==0.16.0
+    # via
+    #   httpcore
+    #   httpcore2
+    #   uvicorn
+hf-gradio==0.4.1
+    # via gradio
+hf-xet==1.6.0 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httpcore2==2.12.0 ; sys_platform != 'emscripten'
+    # via httpx2
+httpx==0.28.1
+    # via
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   mcp
+    #   safehttpx
+    #   wavereader
+httpx-sse==0.4.3
+    # via mcp
+httpx2==2.12.0
+    # via openai
+httpx2-jsfetch==1.0 ; sys_platform == 'emscripten'
+    # via httpx2
+huggingface-hub==1.30.0
+    # via
+    #   gradio
+    #   gradio-client
+    #   smolagents
+    #   wavereader
+idna==3.19
+    # via
+    #   anyio
+    #   httpx
+    #   httpx2
+    #   requests
+jinja2==3.1.6
+    # via
+    #   gradio
+    #   smolagents
+jiter==0.16.0
+    # via openai
+jsonschema==4.26.0
+    # via
+    #   mcp
+    #   wavereader
+jsonschema-specifications==2025.9.1
+    # via jsonschema
+markdown-it-py==4.2.0
+    # via rich
+markupsafe==3.0.3
+    # via
+    #   gradio
+    #   jinja2
+mcp==1.30.0
+    # via gradio
+mdurl==0.1.2
+    # via markdown-it-py
+narwhals==2.25.0
+    # via plotly
+numpy==2.5.3
+    # via
+    #   gradio
+    #   pandas
+openai==3.8.0
+    # via smolagents
+orjson==3.12.0
+    # via gradio
+packaging==26.3
+    # via
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   plotly
+pandas==3.0.5
+    # via
+    #   gradio
+    #   wavereader
+pillow==12.3.0
+    # via
+    #   gradio
+    #   smolagents
+plotly==7.0.0
+    # via wavereader
+pycparser==3.0 ; implementation_name != 'PyPy' and platform_python_implementation != 'PyPy'
+    # via cffi
+pydantic==2.12.5
+    # via
+    #   fastapi
+    #   gradio
+    #   mcp
+    #   openai
+    #   pydantic-settings
+    #   wavereader
+pydantic-core==2.41.5
+    # via pydantic
+pydantic-settings==2.15.0
+    # via mcp
+pydub==0.25.1
+    # via gradio
+pygments==2.21.0
+    # via rich
+pyjwt==2.13.0
+    # via mcp
+python-dateutil==2.9.0.post0
+    # via pandas
+python-dotenv==1.2.3
+    # via
+    #   pydantic-settings
+    #   smolagents
+python-multipart==0.0.32
+    # via
+    #   gradio
+    #   mcp
+pytz==2026.3.post1
+    # via gradio
+pywin32==312 ; sys_platform == 'win32'
+    # via mcp
+pyyaml==6.0.3
+    # via
+    #   gradio
+    #   huggingface-hub
+referencing==0.37.0
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+requests==2.34.2
+    # via smolagents
+rich==15.0.0
+    # via
+    #   smolagents
+    #   typer
+rpds-py==2026.6.3
+    # via
+    #   jsonschema
+    #   referencing
+safehttpx==0.1.7
+    # via gradio
+semantic-version==2.10.0
+    # via gradio
+shellingham==1.5.4
+    # via typer
+six==1.17.0
+    # via python-dateutil
+smolagents==1.26.0
+    # via wavereader
+sniffio==1.3.1
+    # via openai
+sse-starlette==3.4.11
+    # via mcp
+starlette==1.6.0
+    # via
+    #   fastapi
+    #   gradio
+    #   mcp
+    #   sse-starlette
+tomlkit==0.14.0
+    # via gradio
+tqdm==4.70.0
+    # via huggingface-hub
+truststore==0.10.4 ; sys_platform != 'emscripten'
+    # via
+    #   httpcore2
+    #   httpx2
+typer==0.27.2
+    # via
+    #   gradio
+    #   hf-gradio
+typing-extensions==4.16.0
+    # via
+    #   anyio
+    #   fastapi
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   mcp
+    #   openai
+    #   pydantic
+    #   pydantic-core
+    #   typing-inspection
+typing-inspection==0.4.4
+    # via
+    #   fastapi
+    #   mcp
+    #   pydantic
+    #   pydantic-settings
+tzdata==2026.3 ; sys_platform == 'emscripten' or sys_platform == 'win32'
+    # via pandas
+urllib3==2.7.0
+    # via requests
+uvicorn==0.52.4
+    # via
+    #   gradio
+    #   mcp

ui/app.py

@@ -23,6 +23,8 @@ def build() -> gr.Blocks:
         gr.Markdown("# wave~reader", elem_classes=["hero-title"])
         gr.Markdown("a guide to australian surf breaks — browse, score the week, or ask the agent.",
                     elem_classes=["hero-sub"])
+        gr.Markdown("_MCP ready — `/gradio_api/mcp/schema` · `score_week` / `rank_region_week` / `explain_score`_",
+                    elem_classes=["hero-sub"])
 
         selected = gr.State(None)
         scored = gr.State(None)
@@ -41,20 +43,22 @@ def build() -> gr.Blocks:
                          a["status_box"], a["agent_score"], a["agent_swell"],
                          a["agent_wind"], a["spot_dd"], a["rank_df"], agent_store]
 
-        # -- book: one-way filters --
+        # -- book: one-way filters (also reset details on empty result) --
+        _filter_outputs = [b["map_plot"], b["break_radio"], b["details_df"],
+                           b["rose_plot"], b["audit_md"], b["pick_header"]]
         b["state_dd"].change(
             b["state_regions"], inputs=b["state_dd"], outputs=b["region_dd"],
         ).then(
             b["filter_changed"], inputs=[b["state_dd"], b["region_dd"], b["skill_dd"]],
-            outputs=[b["map_plot"], b["break_radio"]],
+            outputs=_filter_outputs,
         )
         b["region_dd"].change(
             b["filter_changed"], inputs=[b["state_dd"], b["region_dd"], b["skill_dd"]],
-            outputs=[b["map_plot"], b["break_radio"]],
+            outputs=_filter_outputs,
         )
         b["skill_dd"].change(
             b["filter_changed"], inputs=[b["state_dd"], b["region_dd"], b["skill_dd"]],
-            outputs=[b["map_plot"], b["break_radio"]],
+            outputs=_filter_outputs,
         )
         # -- book pick → details + climate + shared pick → swell fetch --
         b["break_radio"].change(
@@ -63,20 +67,25 @@ def build() -> gr.Blocks:
                      b["pick_header"], selected],
         ).then(
             s["fetch_forecast"], inputs=[selected, s["skill_dd"]], outputs=swell_outputs,
+            show_progress="full",
         )
         # -- swell: skill change refetches; narrate streams markdown --
         s["skill_dd"].change(
             s["fetch_forecast"], inputs=[selected, s["skill_dd"]], outputs=swell_outputs,
+            show_progress="full",
         )
-        s["narrate_btn"].click(s["narrate"], inputs=scored, outputs=s["report_md"])
+        s["narrate_btn"].click(s["narrate"], inputs=scored, outputs=s["report_md"],
+                               show_progress="minimal")
         # -- agent: chat streams tool cards + meter + charts --
         a["send_btn"].click(
             a["chat"], inputs=[a["msg"], a["chatbot"], a["skill_dd"], a["token_box"],
                                selected, agent_store], outputs=agent_outputs,
+            show_progress="minimal",
         )
         a["msg"].submit(
             a["chat"], inputs=[a["msg"], a["chatbot"], a["skill_dd"], a["token_box"],
                                selected, agent_store], outputs=agent_outputs,
+            show_progress="minimal",
         )
         a["spot_dd"].change(
             a["show_spot"], inputs=[a["spot_dd"], agent_store],

ui/charts/climate.py

@@ -53,12 +53,22 @@ def build_rose_fig(profile: dict | None, name: str = ""):
 
 
 def format_findings(findings: list[dict] | None) -> str:
-    """Format audit findings as lo-fi chips (one line each, emoji severity)."""
+    """Format audit findings as lo-fi chips (HTML pills + emoji severity)."""
     if not findings:
         return "_No climate audit yet — pick a break._"
     icon = {"ok": "✅", "info": "ℹ️", "warn": "⚠️", "error": "❌"}
-    lines = []
-    for f in findings:
-        level = str((f or {}).get("level", "info")).lower()
-        lines.append(f"{icon.get(level, 'ℹ️')} {(f or {}).get('message', '')}")
-    return "\n\n".join(lines)
+    chips = []
+    for f in findings or []:
+        if not isinstance(f, dict):
+            continue
+        level = str(f.get("level", "info")).lower()
+        if level not in ("ok", "info", "warn", "error"):
+            level = "info"
+        msg = str(f.get("message", "")).replace("<", "&lt;").replace(">", "&gt;")
+        chips.append(
+            f"<span class=\"audit-chip audit-{level}\">"
+            f"{icon.get(level, 'ℹ️')} {msg}</span>"
+        )
+    if not chips:
+        return "_No climate audit yet — pick a break._"
+    return "<div class=\"audit-chips\">" + " ".join(chips) + "</div>"

ui/panels/book.py

@@ -73,7 +73,12 @@ def build_book(records: list[dict], vocab: dict, selected) -> dict:
         fnames = [r.get("name", "?") for r in filtered]
         picker = gr.update(choices=fnames, value=None,
                            label=f"Breaks (pick one for details) — {len(fnames)} spot(s)")
-        return fig, picker
+        if not fnames:
+            # Empty result: reset stale details panel (pick_changed can't fire).
+            return (fig, picker, _EMPTY_DETAILS, climate_chart.build_rose_fig(None),
+                    "_No spots match these filters — loosen a filter._",
+                    "### no break selected")
+        return (fig, picker, gr.skip(), gr.skip(), gr.skip(), gr.skip())
 
     def pick_changed(label: str | None):
         """Details + climate rose + audit chips for the picked break."""

ui/theme.py

@@ -55,6 +55,19 @@ button.primary:hover, button.lg.primary:hover {
     color: #ffffff !important;
 }
 .break-list { max-height: 210px; overflow-y: auto; border: 1px solid #0b2c5c; border-radius: 8px; padding: 4px; background: #eef6fd !important; }
+/* climate audit chips: lo-fi pills per severity */
+.audit-chips { display: flex; flex-wrap: wrap; gap: 6px; margin: 4px 0; }
+.audit-chip { display: inline-block; border: 2px solid #0b2c5c; border-radius: 999px; padding: 3px 10px; font-size: 0.8em; background: #ffffff; color: #0b2c5c; }
+.audit-ok { background: #e6f4ea !important; }
+.audit-info { background: #eef6fd !important; }
+.audit-warn { background: #fef7e0 !important; }
+.audit-error { background: #fce8e6 !important; }
+/* mobile: stack columns, shrink map */
+@media (max-width: 700px) {
+  .gradio-container .gr-row { flex-wrap: wrap !important; }
+  .gradio-container .gr-column { min-width: 100% !important; }
+  .hero-title { font-size: 1.6em !important; }
+}
 /* selected break dot -> dark blue (radio circle fill + border) */
 .break-list input[type="radio"]:checked,
 .break-list input[type="checkbox"]:checked {

wavereader/openmeteo.py

@@ -222,7 +222,7 @@ def get_forecast(lat: float, lon: float, days: int = 7) -> dict:
 
     try:
         merged = _fetch_open_meteo(rlat, rlon, days)
-    except (httpx.HTTPError, KeyError, ValueError):
+    except (httpx.HTTPError, KeyError, ValueError, TypeError, AttributeError):
         if cached is not None:
             return cached[0]
         raise

wavereader/scoring.py

@@ -149,6 +149,15 @@ def _normalize_wind_type(wind_type: str | None) -> str:
     return "light/variable"
 
 
+def _safe_float(value) -> float | None:
+    """Coerce to finite float, else None (rejects None/NaN/garbage)."""
+    try:
+        f = float(value)
+    except (TypeError, ValueError):
+        return None
+    return f if math.isfinite(f) else None
+
+
 def enriched_to_scoring_spot(break_: dict) -> dict:
     """Convert one enriched break record to the scoring spot shape.
 
@@ -158,14 +167,16 @@ def enriched_to_scoring_spot(break_: dict) -> dict:
     swell = break_.get("idealSwell", {}) or {}
     size = swell.get("sizeRangeFt", {}) or {}
     wind = break_.get("idealWind", {}) or {}
+    size_min = _safe_float(size.get("min", 0.0))
+    size_max = _safe_float(size.get("max", 0.0))
     return {
         "name": break_.get("name", ""),
         "region": break_.get("region", ""),
         "break_type": break_.get("breakType", ""),
         "ideal_swell": {
             "direction": _join_direction(swell.get("direction")),
-            "size_ft_min": float(size.get("min", 0.0)),
-            "size_ft_max": float(size.get("max", 0.0)),
+            "size_ft_min": size_min if size_min is not None else 0.0,
+            "size_ft_max": size_max if size_max is not None else 0.0,
         },
         "ideal_wind": {
             "direction": _join_direction(wind.get("direction")),
@@ -404,6 +415,10 @@ def _daylight_windows(daily: dict | None) -> dict[str, tuple[str, str]]:
             continue
         if not (isinstance(rise, str) and isinstance(set_, str)):
             continue
+        # ISO local "YYYY-MM-DDTHH:MM" — require full length, else skip
+        # (a truncated sun string must not nuke the whole date).
+        if len(rise) < 16 or len(set_) < 16:
+            continue
         # ISO local "YYYY-MM-DDTHH:MM" — compare the HH:MM slice.
         out[str(day)[:10]] = (rise[11:16], set_[11:16])
     return out
@@ -478,8 +493,9 @@ def _pick_height(row: dict) -> float | None:
     """Prefer the swell component; fall back to the generic aggregate."""
     for key in ("swell_wave_height", "wave_height"):
         v = row.get(key)
-        if v is not None:
-            return v
+        f = _safe_float(v) if v is not None else None
+        if f is not None:
+            return f
     return None
 
 
@@ -487,8 +503,9 @@ def _pick_direction(row: dict) -> float | None:
     """Prefer the swell direction; fall back to the generic aggregate."""
     for key in ("swell_wave_direction", "wave_direction"):
         v = row.get(key)
-        if v is not None:
-            return v
+        f = _safe_float(v) if v is not None else None
+        if f is not None:
+            return f
     return None
 
 
@@ -496,8 +513,9 @@ def _pick_period(row: dict) -> float | None:
     """Prefer the swell period; fall back to the generic aggregate."""
     for key in ("swell_wave_period", "wave_period"):
         v = row.get(key)
-        if v is not None:
-            return v
+        f = _safe_float(v) if v is not None else None
+        if f is not None:
+            return f
     return None
 
 
@@ -512,42 +530,47 @@ def score_week(
     hour. Each returned hour carries its ``"time"``. Hours missing any
     required field are skipped.
     """
-    rows = forecast.get("hourly", [])
+    rows = forecast.get("hourly", []) if isinstance(forecast, dict) else []
+    if not isinstance(rows, list):
+        return []
     windows = _daylight_windows(forecast.get("daily")) if daylight_only else {}
     results = []
 
     for row in rows:
-        if daylight_only and not is_daylight(str(row.get("time", "")), windows):
+        if not isinstance(row, dict):
+            continue
+        t = row.get("time")
+        if not isinstance(t, str) or not t:
+            continue
+        if daylight_only and not is_daylight(t, windows):
             continue
         wave_height = _pick_height(row)
         wave_period = _pick_period(row)
-        wind_speed = row.get("wind_speed_10m")
-        wind_dir = row.get("wind_direction_10m")
+        wind_speed = _safe_float(row.get("wind_speed_10m"))
+        wind_dir = _safe_float(row.get("wind_direction_10m"))
 
         if None in (wave_height, wave_period, wind_speed, wind_dir):
             continue
 
-        gust_raw = row.get("wind_gusts_10m")
+        gust_kt = _safe_float(row.get("wind_gusts_10m"))
+        if gust_kt is not None:
+            gust_kt = gust_kt * 0.539957
+
         try:
-            gust_kt = float(gust_raw) * 0.539957 if gust_raw is not None else None
-        except (TypeError, ValueError):
-            gust_kt = None
-
-        scored = score_hour(
-            wave_height_m=float(wave_height),
-            wave_period_s=float(wave_period),
-            wind_speed_kt=float(wind_speed) * 0.539957,  # km/h to knots conversion
-            wind_direction_deg=float(wind_dir),
-            spot=spot,
-            wave_direction_deg=(
-                float(_pick_direction(row))
-                if _pick_direction(row) is not None
-                else None
-            ),
-            skill_level=skill_level,
-            gust_kt=gust_kt,
-        )
-        scored["time"] = row["time"]
+            scored = score_hour(
+                wave_height_m=float(wave_height),
+                wave_period_s=float(wave_period),
+                wind_speed_kt=float(wind_speed) * 0.539957,  # km/h to knots conversion
+                wind_direction_deg=float(wind_dir),
+                spot=spot,
+                wave_direction_deg=_pick_direction(row),
+                skill_level=skill_level,
+                gust_kt=gust_kt,
+            )
+        except (ValueError, TypeError, KeyError):
+            # One bad spot field or hour must not abort the whole week.
+            continue
+        scored["time"] = t
         results.append(scored)
 
     return results
@@ -575,6 +598,8 @@ def daily_summary(scored_hours: list[dict[str, Any]]) -> list[dict[str, Any]]:
     """
     by_date: dict[str, list[float]] = {}
     for h in scored_hours:
+        if not isinstance(h, dict):
+            continue
         t = h.get("time")
         if not isinstance(t, str):
             continue
@@ -582,6 +607,8 @@ def daily_summary(scored_hours: list[dict[str, Any]]) -> list[dict[str, Any]]:
             score = float(h["score"])
         except (KeyError, TypeError, ValueError):
             continue
+        if not math.isfinite(score):
+            continue
         by_date.setdefault(t[:10], []).append(score)
 
     out = []

wavereader/tools.py

@@ -57,6 +57,11 @@ except ImportError:
     _HAS_BREAKS = False
     _core_resolve_break = None  # type: ignore
 
+try:  # Worker A: wavereader/scoring.py :: enriched_to_scoring_spot
+    from wavereader.scoring import enriched_to_scoring_spot as _core_to_spot  # type: ignore
+except ImportError:
+    _core_to_spot = None  # type: ignore
+
 try:  # Worker A: wavereader/openmeteo.py :: get_forecast(lat, lon, days)
     from wavereader.openmeteo import get_forecast as _core_get_forecast  # type: ignore
     _HAS_FORECAST = True
@@ -200,17 +205,16 @@ def _coords(break_: dict) -> tuple[float | None, float | None]:
 
 
 def _real_scored(break_: dict, skill_level: str) -> list[dict]:
-    """STUB(merge): fetch + score via Worker A; raises on any failure.
-
-    Was the fake-data path before Worker A landed; now the primary path.
-    """
+    """Fetch + score via Worker A; raises on any failure (no fake fallback)."""
     if not (_HAS_SCORING and _HAS_FORECAST and _core_score_week is not None and _core_get_forecast is not None):
         raise RuntimeError("scoring/forecast backends not available")
+    if _core_to_spot is None:
+        raise RuntimeError("scoring spot adapter not available")
     lat, lng = _coords(break_)
     if lat is None or lng is None:
         raise RuntimeError(f"Spot '{break_.get('name')}' has no coordinates")
     forecast = _core_get_forecast(lat, lng, 7)
-    spot = dict(break_)
+    spot = _core_to_spot(break_)
     return _core_score_week(forecast, spot, skill_level)
 
 
@@ -257,13 +261,24 @@ def _slim_hour(row: dict) -> dict:
     )}
 
 
+def _safe_score(value) -> float:
+    try:
+        f = float(value or 0)
+    except (TypeError, ValueError):
+        return 0.0
+    import math as _math
+    return f if _math.isfinite(f) else 0.0
+
+
 def _daily_best(scored: list[dict]) -> list[dict]:
     best_by_date: dict[str, dict] = {}
     for row in scored or []:
+        if not isinstance(row, dict):
+            continue
         date = str(row.get("time", ""))[:10]
         if not date:
             continue
-        if date not in best_by_date or float(row.get("score", 0) or 0) > float(best_by_date[date].get("score", 0) or 0):
+        if date not in best_by_date or _safe_score(row.get("score")) > _safe_score(best_by_date[date].get("score")):
             best_by_date[date] = row
     return [
         {"date": d, **_slim_hour(best_by_date[d])}