documents/FORECAST.md

Surf forecast tab

The surf forecast tab in app/ui.py:build_demo() scores the break selected on the encyclopedia tab. Two stages:

• Stage 1 — deterministic charts (fetch_forecast): Open-Meteo numbers in, scoring.py numbers out. No agent/LLM in this path.
• Stage 2 — narrated report (generate_reports, opt-in): the LLM narrates the Stage-1 scores only — it never invents swell/wind/score values.

Pipeline

pick break (tab 1, break_dd -> selected_break gr.State)
  -> press "Get forecast (charts)" (tab 2, fetch_btn)
   -> fetch_forecast() [app/forecast_handlers.py]
   -> lazy `from app import surf_forecast` (direct package import)
  -> get_scored_week(break, skill, days=7)
       -> adapters.enriched_to_scoring_spot(break)   # schema -> scoring shape
       -> forecasts.get_forecast(lat, lng, days)     # marine + wind, cached
       -> scoring.score_week(forecast, spot, skill)  # 0-10 per hour
  -> best_window / daily_best / build_score_fig / build_waves_fig / build_wind_fig
  -> scored_payload gr.State {break, skill, spot, scored, daily, best, days}
  -> press "Generate surf report" (tab 2, report_btn) [optional]
   -> generate_reports() [app/forecast_handlers.py]
   -> lazy `from app import generate_surf_report` (direct package import)
  -> generate_surf_report_stream(break, skill, daily, best, days)

fetch_forecast fixes days = 7 (no days slider in the UI; get_scored_week still clamps any days arg to 1–7). It shows gr.Progress steps and writes human-readable status into status_box plus a tool-call trace into report_telemetry_box; any exception surfaces there with empty figs (no traceback in UI). An empty scored list disables the report path (scored_payload = None).

Adapter (app/adapters.py)

scoring.py expects the old spot shape; the enriched schema differs, so the adapter bridges it:

scoring expects	enriched has	mapping
ideal_swell.direction: "SE"	idealSwell.direction: ["E","ESE","SE"]	/-join list (_dir_to_deg parses / as cyclic mean); empty → "E"
ideal_swell.size_ft_min/max	idealSwell.sizeRangeFt.{min,max}	float cast (missing → 0.0)
ideal_wind.direction	idealWind.direction: [...]	same /-join; empty → "E"
ideal_wind.strength_kt_max	only idealWind.type (offshore/…)	flat 15.0 (DEFAULT_WIND_MAX_KT) — schema has no knots value; final limit is min(15, skill_profile_max) in _score_wind
skill beginner/intermediate/advanced/expert	+ pro-only	pro-only/pro only/pro → expert; unknown/None → intermediate

Helpers: normalize_skill(), break_skill() (break's own tier), get_coords() (mirrors app/maps.py _lat/_lng, None on missing).

Forecast client (app/forecasts.py)

• Two Open-Meteo endpoints merged on time by _build_normalized: marine-api.open-meteo.com (hourly wave_height, wave_period, wave_direction, wind_wave_height, swell_wave_height) + api.open-meteo.com (hourly wind_speed_10m in km/h, converted to knots in score_week, + wind_direction_10m). Marine serves no wind.
• Grid snap: coords shift ~0.13° seaward (_seaward_offset, rounded to 2 dp by _round_coords) so lookups land on a marine grid point — TAS (lat <= -39.5) shifts south, east coast (lon >= 147) shifts east, west coast (lon <= 125) shifts west, otherwise (SA/VIC south coast) shifts south.
• Cache: .cache/forecasts/<lat>_<lon>_<days>.json envelope {fetched_at, data} (key from the raw spot coords; the seaward offset is a fetch detail only). TTL 6h (CACHE_TTL_SECONDS). Fresh cache served without network (written atomically via tmp + rename); on API failure the stale entry is served as fallback (legacy pre-envelope files return with fetched_at = 0 so they still work as stale fallback); raises only with no usable data at all.

Scoring (app/scoring.py)

Per hour (score_hour), weights swell_size 0.30 / swell_direction 0.20 / wind 0.30 / period 0.20 (redistributed when direction missing):

• size — 10 inside spot's [min,max], Gaussian falloff outside (σ = max(1.0, min*0.4) below, σ = max(1.5, max*0.5) above), multiplied by skill comfort multiplier → 0 above max_safe_size_ft.
• direction — Gaussian on angular diff to ideal (σ = 45/1.5 = 30°, so 45° off ≈ 3.2/10).
• wind — mean of speed (10 if ≤ limit else 0; glassy ≤5kt always 10) and direction (10 * max(0, cos(diff/2)), i.e. perfect offshore → 10, 180° off (onshore) → 0). Limit = min(spot 15kt, skill max).
• period — 0 at ≤4s, linear to 10 at ≥14s, never penalised above.

score_week skips hours with nulls and converts wind_speed_10m km/h → kt (× 0.539957). Skill profiles (ft / kt / s):

skill	comfort ft	max safe ft	max wind kt
beginner	1.0–3.5	4.5	12
intermediate	2.0–6.5	8.5	18
advanced	3.0–12.0	18.0	25
expert (+pro-only)	4.0–30.0	50.0	35

UI outputs (app/surf_forecast.py builders)

get_scored_week returns {forecast, scored, spot, skill, lat, lng}. daily_best groups by date (first 10 chars of time) and returns {date, time, score, wave_height_m, wave_period_s, wind_speed_kt, wind_direction_deg} per day. best_window is the single highest-scoring hour.

• best_md hero: **score/10 @ time** — H m @ P s, wind Wkt (deg°).
• build_score_fig — score bars coloured red → green by quality (≥8 dark green, ≥6 light green, ≥4 yellow, ≥2 orange, else red) + gold ★ marker on the best hour.
• build_waves_fig — wave_height_m filled area (blue, left axis) + wave_period_s line (orange, right axis).
• build_wind_fig — arrows only, no y-axis: colour = direction quality vs the spot's ideal offshore (green ≤45°, yellow cross ≤135°, red onshore above that; dark blue when the spot has no parseable direction), size = strength (22 → 33pt over 0–30kt), subsampled to ~28 arrows. Arrows point where the wind blows TO; exact kt + compass on hover.
• All three share _strip_layout styling (compact heights, unified hover, white plot bg). build_components_fig is retired (returns No forecast data) — use build_score_fig.
• Empty scored → figs annotated No forecast data, report disabled.

Stage-2 report (app/generate_surf_report.py)

Same framework as break generation (single-shot InferenceClient call, nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-BF16 via provider="fireworks-ai", deliberately NOT a smolagents CodeAgent). Speed-first: the prompt carries ONLY the daily bests (≤7 lines) + the single best window + a one-line break summary (ideals + up to 3 hazards) — never the full hourly table or full break record.

• Output is plain markdown, NOT JSON: one - bullet per day in date order (date, score, height/period, wind, short outlook phrase) plus a final **Recommendation: <date + time> -- <reason>.** line. max_tokens=500, temperature=0.3.
• Reasoning disabled at the API level (EXTRA_BODY = {"reasoning_effort": "none"} + /no_think system prompt). Markers @@REPORT@@ … @@END@@ fence the answer; _clean_output strips <think> blocks, fences, and plain-text planning sentences ("we need to…") live during streaming.
• generate_surf_report_stream yields the accumulated cleaned report per delta; stats reports reasoning_chars (hidden channel, never displayed) vs content_chars so callers can prove the visible text is the final report. app/forecast_handlers.py generate_reports yields an instant "Contacting report model…" placeholder first so the button never looks dead, then streams. LLM failure keeps the deterministic charts — only the report box shows the error.

Behaviour + limits

• Explicit Get forecast button — no auto-fetch on pick (saves API calls). Skill dropdown defaults to the selected break's tier (pro-only → expert); window fixed at 7 days. Report is a second explicit opt-in after inspecting the charts.
• Missing coords → ValueError → status error. No-break → warning state, no fetch. No scored hours → warning, report disabled.
• Custom ⭐ break works identically (same schema + coords).
• Known limits: no tide curves (Open-Meteo has none — idealTide is qualitative only); flat 15kt wind tolerance for all spots; swell direction is a cyclic mean of the ideal list, not a per-peak model.