docs/RIPRAP-OWNER-BRIEF.md

Riprap — Owner's Brief

---

1. The system in one paragraph

Riprap takes any NYC address, neighborhood, or development-permit query and produces a four-section flood-exposure briefing where every numeric claim is anchored to a [doc_id] citation that traces back to the source dataset, agency report, or model output. A natural-language planner (Granite 4.1 3b) routes each query to one of four intent paths; the chosen path fans out across up to ~25 atomic data specialists; a synthesizer (Granite 4.1 8b) reads only the specialist outputs that fired and writes the briefing; a Mellea rejection sampler checks four grounding invariants and rerolls if any fail. The system is NYC-specific and public-record-only: all data comes from NYC OpenData, USGS, NOAA, NWS, or FloodNet, and all four models run inside the container — no vendor LLM is contacted at runtime. The output is a tier 1–4 exposure score (deterministic, published rubric, not generated by the LLM) plus a cited paragraph in prose. What Riprap does not do: damage probability, insurance rating, flood prediction, or any claim about basement apartments or infrastructure that isn't in a public register.

---

2. Architecture map

HTTP request lifecycle

User browser → GET /api/agent/stream?q=<query>
  web/main.py: api_agent_stream()  (async SSE generator)
    runs runner() in a threadpool executor
      app/planner.plan(q, on_token=...)   → streams plan_token events while Granite generates
        returns Plan(intent, targets, specialists, rationale)
      out_q.put({kind:"plan", ...})       → SSE plan event
      intent dispatch:
        "single_address"     → app/intents/single_address.run(plan, q, progress_q, strict=True)
        "neighborhood"       → app/intents/neighborhood.run(plan, q, progress_q, strict=True)
        "development_check"  → app/intents/development_check.run(plan, q, progress_q, strict=True)
        "live_now"           → app/intents/live_now.run(plan, q, progress_q)
        "not_implemented"    → inline JSON response, no FSM
      each intent calls fsm.iter_steps() or its own specialist loop
        → out_q.put({kind:"step", ...})   per specialist
        → out_q.put({kind:"token", ...})  per Granite reconcile chunk
        → out_q.put({kind:"mellea_attempt", ...})  per Mellea pass/fail
      out_q.put({kind:"final", ...})
  event_stream() async generator reads out_q, wraps steps in
    stone_start / stone_done envelope keyed by _STEP_TO_STONE dict,
    yields SSE frames
  SSE response header: Cache-Control: no-cache, X-Accel-Buffering: no

Planner: app/planner.py

• Entry: plan(query, model, on_token) → Plan
• Model: RIPRAP_PLANNER_MODEL env, default granite4.1:3b
• Uses llm.chat(format="json") with temperature=0 for deterministic JSON output via Ollama's constrained-decode mode
• Pre-filter: _not_implemented_message(query) checks two regex patterns (retrospective, ranking) and returns early with a Plan(intent="not_implemented") so no LLM call is made
• Post-validator: _validate(d, raw_query) sanitizes intent, targets, specialists against the declared INTENTS/SPECIALISTS dicts; adds floor specialists via _required_specialists(intent) if planner omitted them
• Floor specialists (always added regardless of planner output): geocode+sandy+dep_stormwater+microtopo for single_address; nta_resolve+sandy+dep_stormwater+nyc311 for neighborhood; nws_alerts+noaa_tides for live_now
• Returns: Plan(intent, targets: list[dict], specialists: list[str], rationale: str)

FSM: app/fsm.py

• Entry: build_app(query) → Burr Application; run(query) → dict; iter_steps(query) → generator
• Burr 0.x ApplicationBuilder with with_state(query=query, trace=[]), with_entrypoint("geocode")
• Actions registered in dict order, transitions are consecutive pairs (linear, not DAG)
• Each @action writes one state key + appends to trace list
• Out-of-NYC guard: _NYC_S/W/N/E = 40.49, -74.27, 40.92, -73.69 — NYC-specific specialists skip with "out of NYC scope" reason; live/national specialists (NWS/NOAA/TTM) run unconditionally
• Thread-locals for streaming (since Burr runs sync in a background thread):
  • set_strict_mode(bool) / _current_strict_mode()
  • set_token_callback(fn) / _current_token_callback()
  • set_mellea_attempt_callback(fn) / _current_mellea_attempt_callback()
  • set_planned_specialists(set) / _current_planned_specialists()
  • set_user_query(str) / _current_user_query()
  • set_planner_intent(str) / _current_planner_intent()
• iter_steps spawns a daemon thread running app.iterate(halt_after=["reconcile"]); snaps threadlocals from caller thread and re-installs on iterate thread; deduplicates trace records by (step_name, started_at)
• Heavy-specialist gate: _HEAVY_SPECIALISTS_ENABLED = True when RIPRAP_LLM_PRIMARY != ollama OR RIPRAP_ML_BASE_URL is set; otherwise False. Controls whether prithvi_live, terramind, eo_chip, terramind_lulc, terramind_buildings fire
• NYCHA register gate: _NYCHA_REGISTERS_ENABLED = controlled by RIPRAP_NYCHA_REGISTERS=1 (default off); registers load a 91 MB GeoJSON file on first call

Full action sequence (default, single_address)

#	Action name	State key written	Data source
1	geocode	geocode, lat, lon	NYC DCP Geosearch → OSM Nominatim fallback
2	sandy	sandy	data/sandy_inundation.geojson (lru_cache)
3	dep	dep	data/dep/*.gdb (3 scenarios, lru_cache)
4	floodnet	floodnet	api.floodnet.nyc Hasura GraphQL
5	nyc311	nyc311	Socrata erm2-nwe9
6	noaa_tides	noaa_tides	api.tidesandcurrents.noaa.gov
7	nws_alerts	nws_alerts	api.weather.gov/alerts/active
8	nws_obs	nws_obs	api.weather.gov/stations//observations
9	ttm_forecast	ttm_forecast	ibm-granite/granite-timeseries-ttm-r2 (in-process or remote)
10	ttm_311_forecast	ttm_311_forecast	TTM r2 on local 311 weekly series
11	floodnet_forecast	floodnet_forecast	TTM r2 on nearest FloodNet sensor history
12	ttm_battery_surge	ttm_battery_surge	msradam/Granite-TTM-r2-Battery-Surge (remote or local)
13	microtopo	microtopo	data/nyc_dem_30m.tif, twi.tif, hand.tif
14	ida_hwm	ida_hwm	data/ida_2021_hwms_ny.geojson
15	mta_entrances	mta_entrances	data/mta_entrances.geojson
16	prithvi	prithvi_water	data/prithvi_ida_2021.geojson (166 polygons)
17–22	(heavy, if enabled)	prithvi_live, terramind, eo_chip, terramind_lulc, terramind_buildings	STAC/Sentinel-2, msradam/TerraMind-NYC-Adapters
23	rag	rag	Granite Embedding 278M over corpus/*.pdf (5 PDFs)
24	gliner	gliner	GLiNER typed-entity extraction over RAG hits
25	reconcile	paragraph, audit, mellea	Granite 4.1:8b via Mellea strict sampler

Capstone reconciliation: app/reconcile.py + app/mellea_validator.py

• build_documents(state) → list[dict] — emits one {"role": "document <doc_id>", "content": "..."} per specialist that fired, in Stones order; gatted by both specialist fire status and the out-of-NYC guard
• trim_docs_to_plan(doc_msgs, planned_specialists) — drops doc messages not matching planner's specialist set; saves ~30–50% prompt tokens; RIPRAP_TRIM_DOCS=0 disables
• EXTRA_SYSTEM_PROMPT — the 4-section skeleton with the citation-discipline rules
• augment_system_prompt(EXTRA_SYSTEM_PROMPT, query, intent) — calls app/framing.detect() to classify question type (11 types, deterministic regex), then appends a QUESTION-AWARE OPENING: directive to the system prompt for non-generic questions
• Strict path (production): reconcile_strict_streaming(doc_msgs, system_prompt, ...) in app/mellea_validator.py
  • Streams each attempt's tokens via on_token(delta, attempt_idx) callback
  • After each attempt runs four checks, fires on_attempt_end(attempt_idx, passed, failed) callback
  • On failure, appends a feedback user-turn naming failing sentences and rerolls
  • Budget: DEFAULT_LOOP_BUDGET = 2 (Ollama primary) or 3 (vLLM primary), overridable via RIPRAP_MELLEA_MAX_ATTEMPTS
• Legacy path (non-strict): reconcile.reconcile(state) → streams tokens, then calls verify_paragraph() which drops sentences with ungrounded numbers (post-hoc, not rejection-sampling)
• The step_reconcile action detects strict mode via _current_strict_mode() and routes to one or the other

Four Mellea grounding checks (app/mellea_validator.py)

1. numerics_grounded — _check_no_invented_numbers(): every non-trivial number in output appears verbatim in haystack (joined document content). Trivial set: {0–10, 100, 311, 911, 211}. Number regex: \b-?\d[\d,]*(?:\.\d+)?\b (word-boundary — skips QN1206, B12)
2. no_placeholder_tokens — _check_no_placeholder_tokens(): output contains none of [source], <document, </document, [doc_id]
3. citations_dense — _check_every_claim_cited(): each non-trivial number has a [doc_id] citation somewhere in the same sentence (sentence boundary: \.[\s)] or end of string)
4. citations_resolve — _check_referenced_doc_ids_exist(): every [id] cited in output is a member of the input doc_id set

SSE event vocabulary (/api/agent/stream)

event	payload	when
hello	{query}	connection open
plan_token	{delta}	planner JSON tokens
plan	{intent, targets, specialists, rationale}	planner done
stone_start	{name, tagline, description}	first step in a Stone fires
step	{step, ok, elapsed_s, result?, err?}	each FSM action completes
token	{delta, attempt?}	Granite reconcile chunk (attempt idx resets on reroll)
mellea_attempt	{attempt, passed, failed}	end of each Mellea attempt
stone_done	{name, tagline, description, n_steps}	last step in a Stone done
final	full state dict (geocode, sandy, dep, paragraph, mellea, energy, ...)	reconcile done
error	{err}	exception
done	{}	stream closing

---

3. The Five Stones, one section each

Cornerstone — Hazard Reader

Job: Establish the historical and modeled flood record at the address. These are static datasets that do not change between queries.

Specialists (file:function, what it does):

Specialist	File:function	What it returns
step_sandy	fsm.py:step_sandy	Boolean: inside 2012 Sandy Inundation Zone; gpd.sjoin point-in-polygon against data/sandy_inundation.geojson (91 MB)
step_dep	fsm.py:step_dep	Three DEP stormwater scenarios: dep_extreme_2080 (3.66 in/hr rainfall, 2080 SLR), dep_moderate_2050 (2.13 in/hr, 2050 SLR), dep_moderate_current; depth class 1–3 per point
step_microtopo	fsm.py:step_microtopo	Point elevation (m), HAND (height above nearest drainage, m), TWI (topographic wetness index), rel_elev_pct_200m, rel_elev_pct_750m, basin_relief_m from rasters in data/
step_ida_hwm	fsm.py:step_ida_hwm	USGS Hurricane Ida 2021 high-water marks; n_within_800m, max_height_above_gnd_ft, nearest_dist_m
step_prithvi	fsm.py:step_prithvi	Point-in-polygon against 166 pre-computed polygons in data/prithvi_ida_2021.geojson; inside_water_polygon bool, nearest_distance_m

Data sources:

• Sandy: NYC OpenData 5xsi-dfpx — downloaded to data/sandy_inundation.geojson
• DEP: NYC DEP Stormwater Flood Maps (2021), Esri FileGDBs at data/dep/*.gdb
• Microtopo: USGS 3DEP 30 m DEM via py3dep + whitebox-workflows for TWI/HAND computation, baked to data/nyc_dem_30m.tif, data/twi.tif, data/hand.tif by scripts/compute_hydrology_indices.py
• Ida HWMs: USGS STN Event 312 (NY State), baked to data/ida_2021_hwms_ny.geojson by scripts/fetch_ida_hwms.py
• Prithvi polygons: offline Prithvi-EO 2.0 segmentation on Sentinel-2 HLS tile (pre-event 2021-08-25, post-event 2021-09-02), baked to data/prithvi_ida_2021.geojson by scripts/run_prithvi_ida.py

Models invoked: Prithvi-EO 2.0 ran offline (TerraTorch) to produce the 166-polygon GeoJSON; no live model at query time for this Stone

Failure modes: Sandy/DEP/Prithvi fail silently if GeoJSON/GDB load errors; microtopo/ida_hwm fail if raster files absent from data/; all check _in_nyc() and skip with "out of NYC scope" for non-NYC addresses

UI evidence cards: Sandy inundation zone (boolean), DEP scenario depth classes (three cards), microtopo terrain indices, Ida HWM count/height, Prithvi polygon proximity

---

Keystone — Asset Register

Job: Quantify what public assets (transit, housing, schools, hospitals, buildings) are exposed to the hazards the Cornerstone established.

Specialists (file:function):

Specialist	File:function	What it returns
step_mta_entrances	fsm.py:step_mta_entrances	MTA subway entrances within 500 m: n_entrances, n_inside_sandy_2012, n_in_dep_extreme_2080; per-entrance elevation + HAND
step_nycha	fsm.py:step_nycha	NYCHA developments within 1.5 km: n_developments, n_majority_inside_sandy_2012, n_with_dep_2080_overlap; per-development footprint overlap percentages
step_doe_schools	fsm.py:step_doe_schools	DOE schools within 1 km: n_schools, n_inside_sandy_2012, n_in_dep_extreme_2080
step_doh_hospitals	fsm.py:step_doh_hospitals	NYS DOH hospitals within 2 km: n_hospitals, n_inside_sandy_2012, n_in_dep_extreme_2080
step_terramind_buildings	fsm.py:step_terramind_buildings	msradam/TerraMind-NYC-Adapters Buildings LoRA: pct_buildings, n_building_components in per-query Sentinel-2 chip; heavy, needs _HEAVY_SPECIALISTS_ENABLED

Data sources:

• MTA: data/mta_entrances.geojson (pre-computed register with elevation + flood layer joins)
• NYCHA: data/registers/nycha.json (built by scripts/build_nycha_register.py)
• DOE schools: data/registers/schools.json
• DOH hospitals: fetched from NYS DOH Health Facility Certification (vn5v-hh5r) at register-build time
• TerraMind-Buildings: msradam/TerraMind-NYC-Adapters adapter nyc-buildings-v1, via app/context/terramind_nyc.py:buildings()

Models invoked: msradam/TerraMind-NYC-Adapters (TerraMind 1.0 base + Buildings LoRA), ~1.6 GB base + ~325 MB LoRA, loaded lazily and cached; runs on RIPRAP_ML remote if configured

Failure modes: NYCHA/DOE/DOH registers require RIPRAP_NYCHA_REGISTERS=1 and the 91 MB sandy GeoJSON to be loaded — they fire disabled by default on local dev. TerraMind-Buildings skips silently if eo_chip didn't fire, deps unavailable, or heavy disabled

UI evidence cards: MTA entrance exposure summary, NYCHA development exposure, school exposure, hospital exposure, TerraMind building footprint fraction

---

Touchstone — Live Observer

Job: Report current conditions — what sensors, 311 data, and EO imagery show right now.

Specialists (file:function):

Specialist	File:function	What it returns
step_floodnet	fsm.py:step_floodnet	FloodNet sensors within 600 m: n_sensors, n_sensors_with_events, n_flood_events_3y, peak_event (max_depth_mm)
step_311	fsm.py:step_311	NYC 311 flood complaints within 200 m, last 5 years: count, by_descriptor breakdown, by_year
step_nws_obs	fsm.py:step_nws_obs	Nearest ASOS hourly METAR: station_id, precip_last_hour_mm, precip_last_3h_mm, precip_last_6h_mm
step_noaa_tides	fsm.py:step_noaa_tides	Nearest of 3 NOAA gauges (Battery 8518750, Kings Point 8516945, Sandy Hook 8531680): observed_ft_mllw, predicted_ft_mllw, residual_ft
step_prithvi_live	fsm.py:step_prithvi_live	Live Sentinel-2 L2A water segmentation via msradam/Prithvi-EO-2.0-NYC-Pluvial v2; pct_water_within_500m, pct_water_full, scene_date, cloud_cover; heavy
step_terramind_lulc	fsm.py:step_terramind_lulc	msradam/TerraMind-NYC-Adapters LULC LoRA: dominant_class, dominant_pct, per-class fractions; heavy

Data sources:

• FloodNet: https://api.floodnet.nyc/v1/graphql — Hasura GraphQL, no auth; ~350 sensors
• 311: Socrata erm2-nwe9 (live API call, 200 m buffer, last 5 years)
• NWS obs: https://api.weather.gov/stations/<id>/observations/latest; nearest of KNYC, KLGA, KJFK, KEWR, KFRG
• NOAA tides: https://api.tidesandcurrents.noaa.gov/api/prod/datagetter; 6-min cadence
• Prithvi live: Microsoft Planetary Computer STAC API for Sentinel-2 L2A; msradam/Prithvi-EO-2.0-NYC-Pluvial v2 weights
• TerraMind LULC: shared chip from step_eo_chip (also STAC/Planetary Computer)

Models invoked: Prithvi-EO-2.0-NYC-Pluvial v2 (300 M params, TerraTorch, flood IoU 0.5979 vs 0.10 base); TerraMind-NYC-Adapters LULC LoRA (mIoU 0.5866, +6.13 pp over full-FT)

Failure modes: FloodNet GraphQL call sets verify=False (self-signed cert); 311 Socrata times out gracefully; NOAA/NWS calls have 15-20 s timeouts; Prithvi/TerraMind LULC require _HEAVY_SPECIALISTS_ENABLED and app/context/eo_chip_cache.py:fetch() succeeding

---

Lodestone — Projector

Job: Report forward-looking signals — NWS alerts, surge forecasts, and complaint-rate trends.

Specialists (file:function):

Specialist	File:function	What it returns
step_nws_alerts	fsm.py:step_nws_alerts	Active NWS flood-relevant alerts at point (Flash Flood, Coastal Flood, etc.): n_active, list of alerts with event/severity/urgency/expires
step_ttm_forecast	fsm.py:step_ttm_forecast	TTM r2 zero-shot Battery surge residual: context 512 steps (51 h at 6-min), horizon 96 steps (9.6 h); forecast_peak_ft, forecast_peak_minutes_ahead; only emits doc when interesting (peak > 0.3 ft)
step_ttm_311_forecast	fsm.py:step_ttm_311_forecast	TTM r2 zero-shot on 52 weeks of 311 complaint history → 4-week forecast; forecast_mean_per_week, forecast_peak_per_week, accelerating flag
step_floodnet_forecast	fsm.py:step_floodnet_forecast	TTM r2 on nearest FloodNet sensor flood-event recurrence; forecast_28d_expected_events, accelerating; silent if sensor history too sparse
step_ttm_battery_surge	fsm.py:step_ttm_battery_surge	msradam/Granite-TTM-r2-Battery-Surge fine-tune: hourly cadence, 96 h horizon; forecast_peak_m, forecast_peak_hours_ahead; only emits doc when interesting

Data sources:

• NWS alerts: https://api.weather.gov/alerts/active filtered to flood event types at the point's county
• TTM context data: live pull from NOAA CO-OPS 6-min water level (for Battery/Kings Point/Sandy Hook); Socrata 311 history; FloodNet GraphQL event history
• Battery surge fine-tune: NOAA hourly verified water level from Battery gauge (NOAA 8518750), loaded by app/live/ttm_battery_surge.py

Models invoked: ibm-granite/granite-timeseries-ttm-r2 (1.5 M params, ~30 MB, CPU-viable, zero-shot); msradam/Granite-TTM-r2-Battery-Surge fine-tune (same backbone, test MAE 0.1091 m, −41% vs persistence, −25% vs zero-shot)

Failure modes: NWS alerts call gracefully returns n_active=0 on timeout; TTM models loaded lazily via app/live/ttm_forecast.py:_load_model() with _DEPS_OK = False fallback pattern; all Lodestone specialists fire unconditionally (no NYC bbox gate except floodnet/311 which are NYC-specific)

---

Capstone — Synthesizer

Job: Read all documents produced by the four data-Stones and write a citation-grounded four-section prose briefing.

Entry: app/mellea_validator.py:reconcile_strict_streaming(doc_msgs, system_prompt, user_prompt, loop_budget, on_token, on_attempt_end)

Document ordering in prompt: geocode preamble → Cornerstone (sandy, dep_*, ida_hwm, prithvi_water, microtopo) → Keystone (mta_entrance_*, nycha_dev_*, doe_school_*, nyc_hospital_*, tm_buildings) → Touchstone (floodnet, nyc311, nws_obs, noaa_tides, prithvi_live, tm_lulc) → Lodestone (nws_alerts, ttm_forecast, ttm_311_forecast, floodnet_forecast_*, ttm_battery) → Policy (rag_*, gliner_*)

Four-section skeleton (from EXTRA_SYSTEM_PROMPT):

• Status. — dominant exposure signal, strongest doc_id citation
• Empirical evidence. — Sandy, 311, FloodNet, Ida HWMs, Prithvi polygons
• Modeled scenarios. — DEP dep_* scenarios, microtopo terrain (HAND, TWI, percentile)
• Policy context. — one sentence per RAG hit, citing agency name + rag_* doc_id

Four grounding checks (described in §2 above): numerics_grounded, no_placeholder_tokens, citations_dense, citations_resolve

Reroll feedback mechanism: _failing_sentences_for_citations(text) identifies sentences with uncited numbers; on reroll the feedback user-turn names those specific sentences and instructs surgical citation additions

Model: RIPRAP_RECONCILER_MODEL env, default granite4.1:8b; num_ctx=4096, num_predict=400

Return shape from step_reconcile: {paragraph, audit: {raw, dropped}, mellea: {rerolls, n_attempts, requirements_passed, requirements_failed, requirements_total, model, loop_budget}}

---

4. The three NYC fine-tunes

msradam/Prithvi-EO-2.0-NYC-Pluvial

• HF Hub path: msradam/Prithvi-EO-2.0-NYC-Pluvial
• Base model: IBM/NASA Prithvi-EO 2.0 (300 M params, ViT-L foundation model pre-trained on HLS Sentinel-2 multispectral imagery), Apache-2.0
• Training data: NYC HLS Sentinel-2 tiles with pluvial flood labels derived from USGS Ida HWM survey and NYC DEP records; Lovász-Softmax loss with copy-paste augmentation; trained on AMD Instinct MI300X
• Metrics: Test flood IoU 0.5979 vs 0.10 on Sen1Floods11 base (6× improvement)
• Invocation: Two paths:
  • Offline (Cornerstone): produced data/prithvi_ida_2021.geojson via scripts/run_prithvi_ida.py; runtime does point-in-polygon, no model call
  • Live (Touchstone): app/flood_layers/prithvi_live.py:fetch(lat, lon) — fetches latest Sentinel-2 L2A chip from Planetary Computer STAC, runs model forward pass, returns pct_water_within_500m, pct_water_full; slow (~30 s), gated by _HEAVY_SPECIALISTS_ENABLED; input 6-band S2L2A chip, output binary segmentation mask
• Degradation: If Planetary Computer STAC unavailable or cloud cover too high, fetch() returns {ok: False, skipped: "...reason..."} and no doc is emitted

msradam/TerraMind-NYC-Adapters

• HF Hub path: msradam/TerraMind-NYC-Adapters
• Base model: TerraMind 1.0 (IBM/ESA any-to-any generative EO foundation model), Apache-2.0
• Training data: NYC Sentinel-2 + SAR chips matched to ESRI Land Cover 2020–2022 labels (LULC adapter) and NYC building footprints (Buildings adapter); trained on AMD Instinct MI300X in ~18 minutes
• Metrics: LULC test mIoU 0.5866 (+6.13 pp over full-FT baseline); Buildings test mIoU 0.5511; TiM 0.6023
• Two adapters:
  • lulc — 5-class land cover (water, built, vegetation, bare, agriculture); invoked by step_terramind_lulc via app/context/terramind_nyc.py:lulc(s2_tensor, s1rtc, dem)
  • buildings — binary building footprint mask; invoked by step_terramind_buildings via app/context/terramind_nyc.py:buildings(s2_tensor, s1rtc, dem)
• Shared chip: Both consume tensors from step_eo_chip → app/context/eo_chip_cache.py:fetch(lat, lon), which fetches S2L2A + S1RTC + DEM chip once per query
• Degradation: If eo_chip didn't fire successfully, both LoRA specialists silently no-op. Lazy load + cached in-process; first call ~30 s, subsequent calls ~3–7 s

msradam/Granite-TTM-r2-Battery-Surge

• HF Hub path: msradam/Granite-TTM-r2-Battery-Surge
• Base model: ibm-granite/granite-timeseries-ttm-r2 (1.5 M params, Tiny Time Mixer, Ekambaram et al. NeurIPS 2024), Apache-2.0
• Training data: NOAA CO-OPS Battery gauge (station 8518750) hourly verified water level, surge residual computed as verified minus harmonic tide; trained on AMD Instinct MI300X
• Metrics: Test MAE 0.1091 m, −41% vs persistence, −25% vs zero-shot TTM r2
• Invocation: app/live/ttm_battery_surge.py:fetch() — loads model via tsfm_public.get_model(), fetches NOAA hourly context, returns {available, context_hours, horizon_hours: 96, forecast_peak_m, forecast_peak_hours_ahead, interesting}; in-process on CPU
• Input shape: (context_length, 1) float tensor of hourly surge residuals; context = 336 h (~14 days)
• Output shape: (96,) hourly forecast, scanned for peak
• Degradation: _DEPS_OK module-level flag set at import time; on failure returns {available: False, reason: "..."}, no doc emitted

---

5. The deployment topology

Local development

• Python 3.12 venv (.venv), uv for package management
• Ollama serving granite4.1:3b + granite4.1:8b locally
• uvicorn web.main:app --host 127.0.0.1 --port 7860
• _HEAVY_SPECIALISTS_ENABLED = False by default (no RIPRAP_ML_BASE_URL set, no vLLM)
• RIPRAP_NYCHA_REGISTERS = 0 by default (heavy 91 MB GeoJSON loads)
• Granite Embedding 278M and TTM r2 download to HF cache on first query (~280 MB + ~30 MB)
• SvelteKit UI built at web/sveltekit/build/; rebuild only needed when sources change

HF Space (production demo URL)

• URL: https://lablab-ai-amd-developer-hackathon-riprap-nyc.hf.space
• Docker SDK, base nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04, hardware cpu-basic (actual hardware is cpu-basic, not T4 — the ARCHITECTURE.md mentions T4 but the Dockerfile's GPU notes are aspirational)
• Python 3.10 inside container (pinning mellea<0.4, transformers<5, huggingface_hub<1)
• entrypoint.sh flow:
  1. Attempts EO toolchain install at runtime to $HOME/.eo-pkgs (bypasses HF build disk limit); if fails, terramind/prithvi-live silently skip
  2. Starts ollama serve in background, polls until ready (up to 60 s)
  3. Pulls granite4.1:8b at runtime if not cached (~5 GB, ~2 min first cold start); 3b is optional
  4. Pre-warms 8b via curl POST /api/generate with keep_alive=24h
  5. Launches uvicorn web.main:app --host 0.0.0.0 --port 7860
• RIPRAP_OLLAMA_3B_TAG=granite4.1:8b set in Dockerfile so planner routes to 8b (avoids disk cost of two separate model pulls)
• web/main.py:_warm_caches() on startup: loads sandy + DEP layers, optionally NYCHA registers, warms RAG (Granite Embedding 278M + 5 PDFs), pre-imports heavy ML stacks to avoid import races, warms Ollama models via HTTP

AMD MI300X droplet (demo GPU path — currently destroyed)

• Two Docker containers on same host, both with --device=/dev/kfd --device=/dev/dri
• Container 1: vllm/vllm-openai-rocm:v0.17.1 — serves granite-4.1-8b on port 8001
  • --max-model-len 8192, --served-model-name granite-4.1-8b
  • GLOO_SOCKET_IFNAME=eth0 required or gloo fails to bind
• Container 2: riprap-models:latest (built from services/riprap-models/Dockerfile) — FastAPI on port 8002 (or 7860 per scripts)
  • Endpoints: GET /healthz, POST /v1/prithvi-pluvial, POST /v1/terramind, POST /v1/ttm-forecast, POST /v1/granite-embed, POST /v1/gliner-extract
  • Model loading: lazy + per-model threading.Lock to prevent double-load on concurrent requests
  • ROCm device: cuda (ROCm's CUDA shim maps cuda to first /dev/kfd device)

Env vars to connect HF Space to droplet:

RIPRAP_LLM_PRIMARY=vllm
RIPRAP_LLM_BASE_URL=http://<ip>:8001/v1
RIPRAP_LLM_API_KEY=<token>
RIPRAP_ML_BASE_URL=http://<ip>:8002
RIPRAP_ML_API_KEY=<token>

What breaks if droplet IP changes: Set the four env vars above via huggingface-cli space variables and restart the Space. The LiteLLM Router builds at import time from env, so a Space restart is required.

Deterministic redeploy: scripts/deploy_droplet.sh <new-ip> $TOKEN — idempotent, ~10–20 min first run (pulls images, builds riprap-models); re-runs on same droplet ~1 min. Known fragile: safetensors==0.8.0rc0 pin in services/riprap-models/requirements-full.txt is an RC and may fail on future pip resolves.

---

6. One query traced end-to-end: "80 Pioneer Street, Brooklyn"

Query enters: GET /api/agent/stream?q=80+Pioneer+Street%2C+Brooklyn

1. Planner (app/planner.py:plan)

• No not-implemented regex matches
• Calls llm.chat(model="granite4.1:3b", messages=[system, user], format="json", stream=True, temperature=0)
• Streams plan_token SSE events as JSON generates
• Returns Plan(intent="single_address", targets=[{type:"address", text:"80 Pioneer Street, Brooklyn"}], specialists=[...], rationale="...")
• Validator adds floor specialists: geocode, sandy, dep_stormwater, microtopo
• SSE: plan event emitted

2. single_address.run (app/intents/single_address.py:run)

• Sets threadlocals: strict=True, planned_specialists={...}, user_query="80 Pioneer Street, Brooklyn", planner_intent="single_address"
• Registers on_token and on_mellea_attempt callbacks on progress_q
• Calls fsm.iter_steps("80 Pioneer Street, Brooklyn")

3. FSM: step_geocode

• app/geocode.py:geocode_one("80 Pioneer Street, Brooklyn")
• Detects borough hint "Brooklyn", calls DCP Geosearch with size=8, filters for Brooklyn results
• Returns GeocodeHit(address="80 Pioneer Street, Brooklyn, NY 11231", borough="Brooklyn", lat=40.6772, lon=-74.0070, bbl="3-00589-0003", ...)
• State: {geocode: {...}, lat: 40.6772, lon: -74.0070}
• SSE: step event {step: "geocode", ok: true, elapsed_s: 0.4, result: {address:..., lat:..., lon:...}}

4. FSM: step_sandy

• Confirmed inside NYC bbox
• sandy_inundation.join(point) — spatial join against data/sandy_inundation.geojson
• Red Hook is inside the 2012 Sandy inundation zone → sandy=True
• State: {sandy: True}
• SSE: step event → opens stone_start: Cornerstone

5. FSM: step_dep

• dep_stormwater.join(pt, scen) for each of 3 scenarios against data/dep/*.gdb
• Likely returns dep_moderate_2050: depth_class=2 (Deep & Contiguous 1-4 ft), dep_extreme_2080: depth_class=3 (Deep Contiguous >4 ft), dep_moderate_current: depth_class=1

6–8. FSM: step_floodnet, step_311, step_noaa_tides

• FloodNet: GraphQL POST to api.floodnet.nyc — checks sensors within 600 m of (40.6772, -74.0070)
• 311: Socrata API call for flood complaints within 200 m, last 5 years
• NOAA: fetches Battery gauge (closest of 3 stations to Red Hook), returns observed/predicted/residual

9–12. FSM: TTM forecast steps

• ttm_forecast.summary_for_point(40.6772, -74.0070): loads ibm-granite/granite-timeseries-ttm-r2, fetches 512 steps of Battery residual history via NOAA, forecasts 96 steps ahead; emits doc only if peak > 0.3 ft
• ttm_311_forecast.weekly_311_forecast_for_point(...): fetches 52-week complaint history for 200 m buffer from 311, runs TTM zero-shot
• floodnet_forecast.summary_for_point(...): nearest sensor historical events → TTM recurrence forecast
• ttm_battery_surge.fetch(): msradam/Granite-TTM-r2-Battery-Surge, hourly context → 96 h forecast

13–14. FSM: step_microtopo, step_ida_hwm

• microtopo.microtopo_at(40.6772, -74.0070): samples data/nyc_dem_30m.tif, hand.tif, twi.tif at point; returns elevation ~3 m, HAND ~0.8 m (near drainage), TWI ~11
• ida_hwm.summary_for_point(...): checks data/ida_2021_hwms_ny.geojson within 800 m — Ida hit Queens hardest, Red Hook had no USGS HWMs

15. FSM: step_mta_entrances

• app/registers/mta_entrances.py:summary_for_point(...): loads data/mta_entrances.geojson, finds entrances within 500 m (likely Smith-9th and Carroll St A/C/G stations)

16. FSM: step_prithvi

• prithvi_water.summary_for_point(40.6772, -74.0070): point-in-polygon against data/prithvi_ida_2021.geojson 166 polygons; Red Hook is coastal — likely inside_water_polygon=True or close proximity

17. FSM: step_rag

• Builds query: "address 80 Pioneer Street, Brooklyn; inside Hurricane Sandy 2012 inundation zone; in Deep Contiguous pluvial scenario; flood resilience plan..."
• rag.retrieve(q, k=3, min_score=0.45): Granite Embedding 278M cosine similarity over embedded corpus; likely returns rag_npcc4 (NPCC4 coastal) + rag_mta (MTA Resilience Roadmap coastal references) + rag_comptroller
• External reads: none after startup (RAG index built at startup via rag.warm())

18. FSM: step_gliner

• gliner_extract.extract_for_rag_hits(hits): GLiNER NER extraction over RAG paragraphs; extracts agency names, dollar amounts, infrastructure projects, NYC locations, date ranges
• Emits gliner_{source} doc messages

19. FSM: step_reconcile

• _current_strict_mode() = True
• build_documents(snap) → ~15 doc messages
• trim_docs_to_plan(doc_msgs, planned_specialists) → drops specialists planner didn't ask for
• augment_system_prompt(EXTRA_SYSTEM_PROMPT, query="80 Pioneer Street, Brooklyn", intent="single_address") → framing.detect() → generic_exposure → no directive added (Red Hook query has no question-shape keywords)
• reconcile_strict_streaming(doc_msgs, framed_prompt, loop_budget=2, on_token=..., on_attempt_end=...)
  • Attempt 0: streams tokens to frontend; runs 4 checks; likely passes
  • If fails: feedback user-turn names failing sentences, attempt 1
• Emits: paragraph, mellea metadata (rerolls=0, requirements_passed=[4/4])
• SSE: multiple token events → mellea_attempt event → stone_done: Capstone → final event

Scoring (computed in web/main.py from final state, or explicitly via app/score.py:composite()):

• sandy=True → empirical.sandy=1.0 → floor triggered (tier capped at 2)
• dep_moderate_2050 depth_class=2 → regulatory.dep_moderate_2050=0.75
• microtopo HAND=0.8 → hydrological.hand_band=1.0 (HAND < 1 m)
• composite likely ≥ 1.5 → raw tier 1; floor_applied=True → final tier capped at min(1,2) = 1 (floor is a floor, not a ceiling — the actual rule caps tier at no worse than 2; since tier 1 is better than tier 2, the floor is satisfied: tier stays 1)
• Final tier: 1 (High exposure)

---

7. What's robust vs fragile

Robust (load-bearing, tested)

• Silence-over-confabulation in specialists: Every FSM action returns the declared state key as None on failure; build_documents() gates on state.get(key) is not None; Granite never invents content from absent documents. Pattern is consistent across 25 specialists.
• NYC-scope guard: _in_nyc() check in every FSM action + build_documents() scope_note mechanism for out-of-NYC addresses. National specialists (NOAA, NWS) still fire and a live-conditions-only briefing is produced.
• LiteLLM Router failover: app/llm.py auto-fails from vLLM to Ollama on timeout/5xx. num_retries=0 so the Router doesn't burn seconds re-hitting dead endpoints. The Ollama fallback fires from the same call site.
• Planner validator floor: _required_specialists() adds geocode/sandy/dep/microtopo even if planner forgot them; prevents silent missing-Stone briefings.
• Four Mellea grounding checks with reroll feedback: The _failing_sentences_for_citations() targeted feedback mechanism is the reason neighborhood queries went from chronic 3/4 → 4/4. The identifier-aware \b regex in _NUM_RE is specifically why it stopped false-firing on NTA codes.
• End-to-end probe suite: scripts/probe_addresses.py drives /api/agent/stream against 5 addresses (442 E Houston, 80 Pioneer, 100 Gold, Hollis, Coney Island), asserts Stone fire patterns + Mellea 4/4 + four-section structure. Last green run: 5/5, 5.8–13.1 s per address at RIPRAP_MELLEA_MAX_ATTEMPTS=3.
• Startup warmup in web/main.py:_warm_caches(): Sandy, DEP, RAG, Ollama models, and heavy ML module pre-imports all happen before the first request. The startup function catches exceptions individually so one failure doesn't kill the app.
• Threadlocal cleanup in finally: blocks: app/intents/single_address.py always resets all five threadlocals in a finally: clause, preventing state bleeding between requests.

Fragile (single points of failure, missing error handling)

• Burr FSM concurrent queries: iter_steps() mutates module-level Burr state. Two concurrent single_address queries to the same uvicorn worker will interleave threadlocals. No per-request isolation. Production HF Space is single-worker; local dev with --workers 2 would break.
• build_documents() complexity radon F=101: ~750-line function with one if/elif branch per specialist. Order matters for the Granite prompt. Small edits risk subtle doc-ordering regressions that are silent but affect citation density.
• entrypoint.sh EO install: Runtime pip install --target for terratorch/einops/diffusers/timm/torchvision into $HOME/.eo-pkgs is brittle — if pip fails mid-install the marker isn't created and the next container start retries, but if the Space's filesystem cache persists a partial install, it might never clear. The build log won't show this failure clearly.
• Droplet redeploy: Dockerfile unverified end-to-end: The last full E2E Dockerfile build was never confirmed — the bootstrap droplet was destroyed before final verification. safetensors==0.8.0rc0 in services/riprap-models/requirements-full.txt is an RC that may fail on a fresh pip resolve.
• NOAA/NWS live calls without rate-limit handling: app/context/noaa_tides.py and nws_obs.py call live APIs on every request with no caching, no retry-after handling. Under concurrent load or NOAA outage, specialists fail silently (returns error key in result dict) but every request re-hits the failed endpoint.
• FloodNet GraphQL verify=False: Certificate validation disabled in app/context/floodnet.py:_gql(). This is a permanent workaround for FloodNet's self-signed cert, not a temporary workaround.
• Static asset cache: web/sveltekit/build/ assets have no cache-busting. When iterating on Svelte sources, browser hard-reload is required.
• Planner 3b → 8b alias on HF Space: RIPRAP_OLLAMA_3B_TAG=granite4.1:8b in the Dockerfile means both planner and reconciler use the 8b on the Space. If 3b is never pulled, the granite4.1:3b model is absent and an explicit call to that tag would fail. Current routing via the alias system prevents this, but a direct tag reference in new code would break.
• vLLM [doc_id=X] normalization in app/llm.py:_normalize_citations(): Applied per-chunk in streaming and once on non-streaming responses. If vLLM ever batches citation tokens across two stream chunks, the regex would miss them. This hasn't happened in practice but is a known theoretical gap.
• RAG startup failure doesn't prevent startup: rag.warm() is wrapped in a try/except that prints and continues. If sentence-transformers fails to load, all queries return without policy context — the briefing still works but silently loses the RAG section.
• Mellea API shape versioning: reconcile_strict() uses mellea.start_session(backend_name="ollama") from Mellea 0.3/0.4 (HF has 0.3, local has 0.4). The _extract_text() and _extract_attempts() helpers duck-type multiple attribute names. reconcile_strict_streaming() avoids Mellea's session entirely (hand-rolled) and is version-independent — this is the production path. The reconcile_strict() function is only exercised in offline contexts.
• NYC 311 Socrata calls uncached: Each query fetches fresh from Socrata. Under rate-limit or extended 311 maintenance, the specialist returns n=0 and no 311 doc is emitted; the briefing silently lacks that signal.

Known gaps / out-of-scope

• compare intent defined in planner.py INTENTS dict but no routing to a compare.py intent module exists in web/main.py:api_agent_stream. Planner would route to it but the runner would fall through to single_address.
• Retrospective mode (what would Riprap have said on date X): blocked at planner with not-implemented message. No historical data replay exists.
• Cross-register ranking (rank top 5 neighborhoods by flood exposure): blocked at planner. Would require a cross-register join that doesn't exist.
• FEMA NFHL integration: FEMA 1% and 0.2% floodplain indicators are in the scoring rubric (app/score.py:REGULATORY) but the corresponding FSM step and data layer are absent — they're stubbed at 0 in practice. The score still works but the FEMA regulatory sub-index doesn't contribute.
• Sub-surface flooding (Ida basement mode): Optical satellites can't see basement flooding. Prithvi correctly emits no polygons for inland Queens. This is documented as an honest scope limit, not a bug.
• /api/compare endpoint exists at web/main.py:compare_stream and works as a two-parallel-FSM-runs endpoint, but the SvelteKit UI doesn't expose a compare page (legacy compare.html was retired in v0.4.5).

---

8. The non-obvious decisions

Why not a risk score from 0–100

The tier is a deterministic, published rubric (Cutter et al. 2003 construction, Tate 2012 equal-weights argument, Balica 2012 empirical floor). A continuous score would imply calibration against labeled damage outcomes — which don't exist here. Riprap has no closed claim records; producing "flood risk 0.73" without claims-driven calibration would be a fabricated precision. The tier is explicitly a prior (METHODOLOGY.md §1). FEMA Risk Rating 2.0 is the product to use if you want claims-driven numbers.

Why silence over confabulation

Specialists that don't fire emit nothing. build_documents() gates on state.get(key) is not None. Granite's post-training includes grounded-generation discipline ("don't generate from absent documents"). This plus the Mellea citation checks means a calm-weather query produces no NWS-alerts section in the briefing rather than "no alerts were found" — that would be correct but uncitable. The section is absent. This is explicit in the system prompt: "Omit any section whose supporting facts are absent from the documents."

Why public-record-only at runtime

Data governance: a newsroom with FOIL'd documents, or an agency with internal capital plans, can't paste that data into a vendor LLM (ARCHITECTURE.md §11). All specialist data comes from NYC OpenData, USGS, NOAA, NWS, FloodNet NYC (public sensor network). No commercial data; no private address databases. The system is reproducible and auditable.

Why the four epistemic tiers (empirical / modeled / proxy / synthetic)

The distinction matters for how much weight to give each signal, documented in ARCHITECTURE.md §1.2. Empirical (Sandy HWMs, Ida HWMs, FloodNet events) = something flooded a place and was measured. Modeled scenarios (DEP, FEMA NFHL) = hydraulic simulation under assumptions. Proxy (311 complaints, HAND, TWI) = indirect indicators. Synthetic prior (TerraMind synthesis) = generative model output, never "imaged" or "reconstructed." The build_documents() function embeds these interpretive framing sentences directly into the doc bodies so Granite is instructed in the document itself how to characterize each source.

Why the Five Stones names

Functional grouping for a trace UI with 25+ specialists. Stonework vocabulary maps to function: Cornerstone remembers the foundation (static hazard record); Keystone is the load-bearing arch piece (what's exposed); Touchstone is the evaluative reference (current state); Lodestone draws you toward something (forecast pull); Capstone is the crown that holds the vault (synthesis). The names let a non-technical demo audience follow the 25-step trace without reading each step label.

Why citation-grounded prose vs structured output

JSON structured output (tier + per-field arrays) is easy to produce but hard to cite in a grant application or news article. The four-section prose format with [doc_id] tags produces text a planner can quote in a FEMA BRIC sub-application or a journalist can use verbatim with inline sourcing. The citation tags map to clickable source chips in the frontend. Structured JSON of the underlying specialist outputs is also available in the final SSE event for machine consumption.

Why Mellea rejection sampling (vs post-hoc sentence dropping)

The original verify_paragraph() in app/reconcile.py drops sentences after generation. This produces a shorter briefing and a silent quality improvement — but the user sees a briefing that may have had sentences removed. The Mellea rejection sampler rerolls the entire generation when it fails, and streams each attempt's tokens to the user live (visible progress), then shows a green/amber inline banner. The user understands the system is enforcing quality, not silently deleting content. Psychologically this is more defensible in a professional context.

Why planner-then-Capstone two-LLM split

The planner is a structured-output routing task (small JSON, deterministic, temperature=0). It should be fast and cheap. The reconciler is a long-form synthesis task requiring dense citation discipline — it benefits from the larger context window and stronger instruction-following of the 8b model. Using 3b for routing keeps TTFB low (planner JSON appears in ~2 s vs ~8 s for 8b). On the HF Space both aliases map to 8b via RIPRAP_OLLAMA_3B_TAG=granite4.1:8b to avoid disk cost, accepting the TTFB penalty.

Why LiteLLM Router

The alternative was a hand-rolled if primary == "vllm": ... else: ollama.chat(...) dispatch. LiteLLM's Router gives model aliasing, failover, and a common call signature for free. The ~250-line shim in app/llm.py covers: Ollama-vs-vLLM backend selection, document-role message extraction for vLLM's HF chat template, [doc_id=X] → [X] citation normalization, JSON-mode translation, and backend info for the UI badge. Any future backend (mlx-lm, llama.cpp, etc.) is a 10-line entry in _build_router().

Why vLLM emits [doc_id=X] while Ollama emits [X]

Ollama's Granite 4.1 Modelfile template lifts role="document <id>" messages into a <documents> block and the model emits bare [X] citations. The HF tokenizer template used by vLLM emits [doc_id=X]. The rest of Riprap (Mellea regex, frontend citation chip parser, sources footer) was written against [X]. The _CITE_NORMALIZE_RE in app/llm.py normalizes per-chunk in streaming, preventing any vLLM-specific citation format from leaking downstream.

Why Prithvi runs offline (baked GeoJSON) while TTM runs live

Prithvi-EO 2.0 with TerraTorch needs GPU and minutes per HLS tile. Running it per-query on a CPU-basic Space is not viable. The 166-polygon GeoJSON was computed once on AMD MI300X, filtered (>30,000 sqft to drop noise, <1 km² to drop tidal artifacts), and committed. The runtime FSM does point-in-polygon (milliseconds). This is honest about what EO models earn their keep on: a one-time defensible event-level signal, not per-request inference. TTM r2 at 1.5 M params runs in milliseconds on CPU — no such tradeoff exists.

Why citations_dense uses sentence scope, not character window

The original implementation used ~40 chars proximity between a number and its citation tag. This was fragile for normal English sentence structure ("The address has 11 flood-related complaints [nyc311] within 200 m"). The citation might be 60 chars from the number. Switching to sentence scope (.[\s)] split) eliminated the chronic 3/4 neighborhood-query failure mode. "Sentence scope" is also how human readers actually assign attribution — the citation at the end of the sentence covers the claim anywhere in that sentence.

---

9. What's next

From OPEN-ISSUES.md, CLAUDE.md polish targets, and code-level TODO comments, in priority order for the May 13 ASCE presentation:

1. Demo-script dry run against live Space. Space sometimes sleeps after idle; cold start is 30–90 s. Pre-ping the Space before presenting. Verify the backend pill shows correct hardware.
2. compare intent wiring. planner.py declares the compare intent (noted as NOT_IMPLEMENTED comment — actually the planner doesn't short-circuit compare, it just routes to single_address by default). If you want the compare flow to work end-to-end, web/main.py:api_agent_stream needs routing to i_addr.run twice in parallel, or a new compare.py intent module.
3. FEMA NFHL layer. The scoring rubric has fema_1pct and fema_02pct weights but no FSM step or data layer. Adding the FEMA NFHL download and a step_fema_nfhl action would materially improve Regulatory sub-index accuracy for addresses in AE/VE zones that aren't in Sandy extent.
4. NYCHA/DOE/DOH registers on Space. RIPRAP_NYCHA_REGISTERS=0 by default. Enabling on HF Space would add 3 more Keystone specialists to every single_address query but requires the 91 MB sandy GeoJSON pre-load to complete within Space startup time.
5. Droplet redeploy verification. The services/riprap-models/Dockerfile was never tested end-to-end. The safetensors==0.8.0rc0 RC pin is the most likely failure point. Next droplet bring-up should test this first.
6. Experiments OPEN-ISSUES.md items. All four issues are in experiments/ only (F821 numpy annotation in exp17, f-string Py 3.12+ syntax in exp18, B023 closure variable in exp05, F841 unused api in exp18). Won't affect production but clean up the codebase.
7. Reranker integration. app/rag.py has a full _ensure_reranker() and RIPRAP_RERANKER_ENABLE flag for ibm-granite/granite-embedding-reranker-english-r2 cross-encoder. Off by default (no HF Space disk for the CrossEncoder model). Enabling on the AMD droplet path would improve Policy context quality at no latency cost.
8. Historical replay / retrospective mode. Blocked at planner with not-implemented message. Substantial feature: would require snapshotting specialist output at query time or storing NOAA/311/FloodNet historical pull results.

---

10. Quick reference: files that matter

Task	Open first
Add a new specialist	app/fsm.py (add @action + wire into build_app()), app/reconcile.py:build_documents() (add doc emission), app/intents/single_address.py (no change usually needed), web/sveltekit/src/ (add step label + source card)
Change the briefing structure / system prompt	app/reconcile.py:EXTRA_SYSTEM_PROMPT, then app/intents/neighborhood.py:EXTRA_SYSTEM_PROMPT for neighborhood path; rebuild web/sveltekit if adding new section rendering
Tune the Mellea grounding checks	app/mellea_validator.py — _NUM_RE, _TRIVIAL_NUMS, _check_every_claim_cited(), _failing_sentences_for_citations()
Change which backend (vLLM vs Ollama)	app/llm.py env vars; no code change needed
Add a new intent	app/planner.py:INTENTS + SPECIALISTS entries, _required_specialists(), then new app/intents/<intent>.py; wire in web/main.py:api_agent_stream and api_agent
Change the exposure tier scoring	app/score.py:REGULATORY/HYDROLOGICAL/EMPIRICAL dicts + TIER_BREAKPOINTS; update METHODOLOGY.md
Debug why a specialist fired wrong	scripts/probe_mellea.py --query "<address>" --runs 1; check step events in SSE stream; look at final.mellea.requirements_failed
Rebuild the frontend	cd web/sveltekit && npm run build (new design-system UI); cd web/svelte && npm run build (legacy Svelte 5 custom elements to web/static/dist/riprap.js)
Run the full end-to-end test	.venv/bin/python scripts/probe_addresses.py
Rebuild the pre-computed registers	scripts/build_mta_entrances_register.py, scripts/build_nycha_register.py, scripts/build_schools_register.py
Rebuild Prithvi Ida polygons	scripts/run_prithvi_ida.py — needs GPU + TerraTorch
Rebuild the pitch deck	cd slides && make pdf html pptx (needs marp-cli)
Add a question-type framing	app/framing.py:_PATTERNS + _DIRECTIVES
Understand why a doc was missing from the briefing	Check build_documents() in app/reconcile.py — each block has an explicit gate condition; also check trim_docs_to_plan()
Understand the SSE stream structure	web/main.py:api_agent_stream, the _STEP_TO_STONE dict, and the stone_start/stone_done wrapping logic
Deploy to HF Space	git push && git push huggingface main; monitor rebuild via `curl -sf "https://huggingface.co/api/spaces/lablab-ai-amd-developer-hackathon/riprap-nyc/runtime"
Deploy to AMD droplet	scripts/deploy_droplet.sh <ip> <token>, then set Space env vars via huggingface-cli space variables, restart Space