documents/ENCYCLOPEDIA.md

Encyclopedia tab

The encyclopedia tab in app/ui.py:build_demo() is the break browser. It reads the generated knowledge base, filters it, plots it, and feeds the selected break to the surf forecast tab via shared gr.State.

Data source

• data/australia-surf-breaks-enriched.json → load_breaks() (app/breaks_data.py) into DF. Legacy {"name | state | region": {...}} dict format is accepted; rows with an error column are dropped.
• Derived at import time: STATES, REGIONS_BY_STATE, ALL_REGIONS, SKILLS (filtered to SKILL_ORDER: beginner → intermediate → advanced → expert → pro-only).
• Enriched id is "<name> | <state> | <region>". Canonical state/region come from the input list, never the model.

Filtering

filter_breaks(df, state, region, skill) — "All" / None means no filter, comparison is case-insensitive on state / region / skillLevel.

• state_dd.change → update_region_choices (narrows region list) → update_map → sync_custom_from_filters (pushes map State/Region into the generation form; All leaves the field untouched via gr.skip()).
• region_dd / skill_dd → update_map.

update_map returns (map fig, break choices, records, count, empty details). Unfiltered view frames the whole of Australia (AUSTRALIA_CENTER, zoom 3.5); otherwise the map auto-centers/zooms via _zoom_for_span().

Map

• build_map(records, default_view) — Plotly Scattermap, open-street-map style, marker colour by SKILL_COLORS. Point order matches records order so the break list lines up.
• build_map_with_custom(base_records, custom) — adds the gold star (#FFD700) marker for the session break.
• _lat() / _lng() return None on missing coords; those points are skipped for centering.

Details + selection

• break_dd (Radio, .break-list) → on_break_pick → break_to_table(record), a 16-row Field/Value dataframe (name/state/region/description/skill/break+peak type/coords/ideal swell+wind+tide/season/hazards/crowd).
• _resolve_pick(label, base_records, custom) maps the label back to its record; the custom break carries a ⭐ (your break) suffix and matches by suffix, base records match by name.
• on_break_pick also sets shared selected_break state and updates the forecast tab header + skill default (break's own skillLevel, validated against SKILL_ORDER, fallback intermediate).

Session-only custom break

• generate_custom_break() (in app/custom_break.py) streams (telemetry, details, map, dropdown, state) tuples via yield. Lazy from app import generate_surf_break (direct package import, no importlib shims).
• Empty custom state/region fields fall back to the main map filters; explicit values win. Exactly one custom break per session (gr.State, never written to disk); regeneration replaces it.
• clear_custom_break(base_records, selected) deletes it; if the deleted break was the forecast selection, the forecast header/skill reset too.
• clear / generate do not auto-select the forecast state — pick the break in the list first, then fetch on tab 2.

Theme

Lo-fi via APP_CSS: light blue bg #d6e9f8, dark blue #0b2c5c, Courier. Don't restyle without asking. Callbacks stay wired in build_demo().