AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repo. The active surface is app.py + ui/ + wavereader/ + data/ (the v2 rebuild). legacy/ holds the frozen v1 front end (main.py + app/) — don't extend it; it survives only as the fallback layer in ui/_compat.py.

What is live now

• app.py — v2 entrypoint: build() + gr.api tools + demo.launch(css=APP_CSS, mcp_server=True). Run uv run python app.py.
• ui/ — the single-page front end (no tabs): app.py (layout + wiring, ≤3 gr.State; Bells Beach auto-selected on load so there are no empty states), panels/{lens,story,intel,agent}.py (map-lens column | forecast story | intel rail | full-width agent bar), charts/{strip,score,seafloor,climate,map,_style}.py, contracts.py (SELECT_KEYS/FETCH_KEYS/AGENT_KEYS + fill() — handlers return via fill(KEYS, …) so output ordering can't drift), _compat.py (backend access: v2 core → legacy.app.* → stubs; also wetsuit hints, engine chips, surf cams), theme.py (APP_CSS, IBM Plex Mono lo-fi identity — don't restyle without asking).
• wavereader/ — pure core, typed + tested, no Gradio imports: breaks.py (catalogue, memoized load_breaks), openmeteo.py (versioned/atomic disk cache, seaward grid-snap), scoring.py (deterministic 0–10 engine — the LLM never owns numbers), seafloor.py (GEBCO world model), climate.py (ERA5 5-yr profiles + audit; break_climate reads the profile embedded on each break record, per-slug file fallback), tools.py (the typed tool functions shared by agent + MCP), agent.py (smolagents ToolCallingAgent, native tool calls, budget: 6 steps / 2 score_week / 700 tokens), narrate.py + llm.py (one InferenceClient factory: Nemotron 3 Ultra via deepinfra, WR_* env overrides).
• scripts/warm_caches.py — pre-fill forecast + seafloor caches (demo hot start). scripts/build_climate.py — climatology builder (re-embeds built profiles into the catalogue after each run, backup first).
• scripts/check_coords.py + scripts/check_coast.py — break-coordinate maintenance: check_coords validates/fixes state/region/duplicate placement against OSM; check_coast audits GEBCO elevation at every break point and (--fix) snaps non-coastal ones to the nearest 0 m shoreline crossing (both write a timestamped backup first).
• data/ — australia-surf-breaks-enriched.json (238 breaks; each record embeds its ERA5 profile under climate — 236 of 238, the two duplicate Gnaraloo rows have no profile), surf-break-schema.json (contract), climate/*.json (per-slug ERA5 profiles — build_climate.py output and break_climate's fallback; also index.json manifest), surf-cams.json (camera links keyed "name | state | region"), surf-break-example-bells.json (prompt worked example).

Deploying to HF Spaces

• The Space lucashudsn/wavereader (public) is this repo — remote space. Every push to main auto-deploys via .github/workflows/deploy-space.yml (needs the GitHub repo secret HF_TOKEN) — merging to main ships it; no manual step. For any other branch, ship manually with scripts/deploy_space.sh [ref] (builds a throwaway commit that prepends space-config.yaml to README.md and force-pushes it to space:main — Spaces need YAML frontmatter, GitHub doesn't have to see it; the ref defaults to your current branch), then git push origin <branch> to keep GitHub in sync. The Space builds from the pushed commit; watch Logs → Build on the Space page or poll HfApi().get_space_runtime("lucashudsn/wavereader") until RUNNING.
• space-config.yaml is the Space config. Keep sdk_version in lockstep with the gradio pin in requirements.txt (regenerate that file only via uv export --no-hashes --format requirements-txt --no-dev -o requirements.txt — other invocations can leave stray progress lines that break pip), and python_version in lockstep with pyproject.toml's requires-python. If you change Space settings via the web UI, HF rewrites the Space's README.md — mirror anything you care about back into the yaml.
• HF_TOKEN is a Space secret (set once via Settings → Variables and secrets or HfApi().add_space_secret); WR_* overrides can be added the same way. .cache/ is ephemeral on the Space and rebuilds lazily — no persistent storage, no warm step.

Conventions that matter

• One spot drives everything: selected (gr.State) is the single source of truth — picking a spot re-aims the map, badges, forecast strip, world model and climatology together. Keep it that way.
• Staged spin-ups: ui/panels/story.py::fetch_forecast is a generator that yields stage 1 (charts, ~ms) then stage 2 (seafloor world model from a parallel thread). Status lines name the engine + latency. Keep that pattern for anything slow.
• Charts: theme through ui/charts/_style.py::style_fig; weekend shading via add_weekend_shading. The week strip lives in charts/strip.py (score/swell/wind rows); window slicing (weekend/mornings/arvos) re-charts from state via filter_hours — no refetch. Seafloor display is bicubically smoothed (scipy) and its wave animation is period-driven — smoothing and animation are display-only; stats stay on the raw grid.
• MCP surface = exactly score_week / rank_region_week / explain_score (gr.api in app.py). All event listeners are registered with api_name=False — keep it that way.
• The LLM never owns numbers. Scores/forecasts/analysis stay deterministic; the model narrates and cites tools.

Data contracts

• Required break fields: name, state, region, location, skillLevel, breakType, peakType, idealSwell, idealWind, idealTide. Optional: description, id, bestSeason, hazards, crowdFactor. Never invent enum values — check data/surf-break-schema.json first.
• Canonical state/region always come from the input list, never the model. location.country is "Australia".
• New prompts must load schema + example from data/ (don't paste copies).

Rules for edits

1. Everything is tracked in this repo (no nested git — don't re-init one).
2. Never commit .env, .venv/, __pycache__/, .DS_Store, .cache/ (all ignored).
3. Never read .env or print secrets/tokens. Use .env.example for var names; check presence with printenv HF_TOKEN | wc -c or [ -n "$HF_TOKEN" ] style checks that never echo the value.
4. Keep prompt files in data/; keep app.py free of embedded schema text.
5. Test cheaply: uv run pytest -q (offline fixtures) + uv run python -c "import app" for import health. Live LLM calls cost inference — dry-run the agent via the injected fake model (tests/test_agent_dryrun.py) before any live turn.