DEMO-PLAYBOOK.md

Riprap Demo Playbook

For: AMD Developer Cloud Hackathon · May 4–10, 2026 Live URL: https://lablab-ai-amd-developer-hackathon-riprap-nyc.hf.space

What was fixed for the demo

1. Cornerstone (Hazard Reader) latency — DEP stormwater + Sandy 2012 join went from a 33-second cold-load to <100ms. Both layers are baked to compact GeoTIFFs (data/baked/, 7 MB total) sampled with rasterio. The 33s ReadTimeouts in batch testing are gone.

2. Heavy register specialists no longer hang — step_nycha, step_doe_schools, step_doh_hospitals previously did 20 polygon×polygon intersections per query (8+ minute hang on HF Space CPU). They now read pre-computed exposure flags from data/registers/*.json (sub-millisecond). Hospitals don't have a pre-built register but read the 30 KB GeoJSON directly and sample the new Cornerstone rasters per hit.

3. Live EO chain — every fine-tune renders on the map — every Sentinel-2-driven specialist now produces polygons that surface as a MapLibre layer:

   • prithvi_live (NYC Pluvial flood segmentation) → blue water polygons (prithvi-live-fill/-line)
   • terramind_lulc (NYC LoRA, 5-class land cover) → categorical fill keyed on fill_color per feature (terramind-lulc-fill/-line)
   • terramind_buildings (NYC LoRA, binary building mask) → red building footprints (terramind-buildings-fill/-line)
   • terramind (IBM v1 base synthesis, DEM→LULC) → uses the same LULC layer, falls back when the LoRA didn't fire Wire format: droplet returns pred_b64 (uint8 per-pixel argmax raster) + pred_shape + class_labels; HF polygonises against the chip's WGS84 bounds via app/context/_polygonize.py. Verified live on Beach Channel: 118 LULC polygons, 6 building polygons, 101 synthesis polygons; prithvi correctly returns 0 (address is inland and dry). Three droplet bugs fixed along the way: _build_chip_tensor 5D-input crash for the LoRAs; missing synthesis adapter route; DEM shape mismatch ((1,H,W) vs (1,1,H,W)).

4. Misleading UI copy fixed — three Stone specialists (TerraMind Buildings/LULC/Synthesis, Prithvi-NYC-Pluvial) previously claimed RIPRAP_HEAVY_SPECIALISTS=0 when they silently skipped. Heavy specialists are actually enabled in production — the new copy reflects the actual cause (no recent <30% cloud Sentinel-2 chip / inference unavailable).

The 3 demo queries

1. 2508 Beach Channel Drive, Queens — full single_address activation

What it shows: the deep-data-density address from FRIDAY-REPORT. Single_address intent triggers every specialist:

• Cornerstone: Sandy outside, all DEP scenarios outside (this is Bayswater, just inland of the Sandy zone — useful counter-example)
• Touchstone: 2 FloodNet sensors (600m radius), 64 NYC 311 flood complaints, NOAA station 8516945 live, NWS hourly METAR
• Lodestone: Granite TTM forecasts (peak 0.47 ft surge ~2h ahead), TTM 311-forecast, NWS alerts
• Keystone: 7 MTA entrances (6 in Sandy, 5 in DEP-2080), 2 NYCHA developments, 5 schools (4 in Sandy, 3 in DEP-2080), 1 hospital — all with elevation/HAND from baked rasters
• Live EO: prithvi_eo_live fires with a real Sentinel-2 chip (≤30% cloud, ≤120 days old) — flood segmentation runs on the MI300X; eo_chip_fetch pulls multi-modal S2L2A + S1RTC chip
• Capstone: Granite Embedding RAG (3 hits) + GLiNER typed extraction + Mellea-grounded Granite-4.1 8B reconciliation (4/4 requirements pass)

Talking points: "This is what 'resilient infrastructure briefing' produces when every specialist fires. The Touchstone and Cornerstone disagree — Bayswater is just inland of Sandy 2012 but its subway entrances 200m away are deep in the zone. Live data: the Prithvi specialist just pulled a Sentinel-2 image from this month and ran flood segmentation on the MI300X."

2. Coney Island I Houses, Brooklyn — neighborhood path, narrative briefing

What it shows: neighborhood intent routing. Planner reads "Houses" with no street number → resolves to NTA polygon, runs the neighborhood specialist set (sandy_nta, dep_*_nta, nyc311_nta).

• Returns a Markdown briefing structured as Status / Empirical / Modeled / Policy
• Uses NTA-aggregated metrics ("X% of the neighborhood was inundated during Sandy")
• ~7-second total latency

Talking points: "Same system, different intent. The planner picks neighborhood for queries that name an area without a house number. The briefing is denser narrative; the underlying data is NTA-aggregated, which is the right unit for emergency-management framing."

3. 80 Pioneer Street, Brooklyn (Red Hook) — single_address, full activation

What it shows: Red Hook is canonical Sandy turf. All Stones populated:

• Cornerstone: Sandy inside, DEP-2080 outside, microtopo 0.83m elevation (low-lying)
• NYCHA: Red Hook Houses (East/West) — both inside Sandy
• Schools: PS 27, PS 30 — both inside Sandy
• Hospitals: 3 nearby
• MTA: entrances inside Sandy
• Live Sentinel-2 chip + Prithvi flood segmentation runs

Talking points: "Red Hook is the canonical 'this is what we got wrong in 2012' address. The system surfaces a NYCHA development, a school, a hospital, and a subway entrance — all at risk in the same query. That's the demo: one query, four asset classes, every Stone audited, plus a live Sentinel-2 chip."

Reading the trace

The trace UI groups specialists by Stone. Each row shows status (fired / silent / errored) and a one-line skip reason if silent. Silent isn't broken — it's the engineering-honest contract: when a specialist's preconditions aren't met, it stays silent rather than fabricating.

Honest skips you'll see in the demo:

• "FloodNet sensor recurrence: sensor has < silent-floor historical events; forecast omitted" — sensor too new to forecast
• "NPCC4 SLR projection: not yet wired into FSM" — out of scope, listed for transparency
• "NWS public alerts: no active flood-relevant alerts at this address" — true, no active alert today

Specialists that may show as skipped/errored on the demo:

• TerraMind LULC + Buildings: LIVE — finetuned NYC adapters running on the MI300X. Hits live Sentinel-2 + Sentinel-1 chips. TerraMind Synthesis (the third terramind variant, DEM-driven LULC synthesis) has no remote inference route, so it returns a clean "deps unavailable: terratorch (RuntimeError)" on the HF Space — not on the demo critical path.
• floodnet_forecast — sensors with <5 historical events skip the forecast.
• nws_alerts — when no flood-relevant alert is active at the address (most days).

Caveats to be ready for

• NYCHA cards are binary, not pct-overlap — per-query view shows inside_sandy_2012: bool and dep_*_class: int instead of pct_inside_sandy_2012 floats. Same source data, less precise representation but fast (~ms instead of 8 min). The /api/register/nycha city-wide register is unchanged.
• Heavy specialists are enabled but may silently skip if Sentinel-2 chip fetch returns nothing recent for the query address. Prithvi-EO Live looks back 120 days for <30% cloud — most NYC addresses have a recent hit; very edge-of-NYC ones may not.
• Inference is remote on AMD MI300X via vLLM at 165.245.141.218:8001. If the droplet is down, the reconciler will fail and the Capstone Stone won't render a paragraph; specialists will still fire and surface their data.
• Bake re-runs — data/baked/*.tif (7 MB) was generated once via scripts/bake_cornerstone_rasters.py. Re-bake when DEP scenarios get republished by NYC DEP (rare, ~every 5 years).
• Register rebuilds — data/registers/*.json are regenerated by scripts/build_*_register.py when the underlying NYCHA / DOE / NYS DOH datasets refresh.

End-to-end smoke test

To verify before showtime:

.venv/bin/python scripts/probe_addresses.py \
  --base https://lablab-ai-amd-developer-hackathon-riprap-nyc.hf.space \
  --addresses "2508 Beach Channel Drive, Queens|Coney Island I Houses, Brooklyn|80 Pioneer Street, Brooklyn" \
  --timeout 240

Expected: 3/3 PASS, each in 6–17 s after warm-up. If 2508 Beach Channel takes >60s, that's the post-restart pre-warm finishing — re-run.

Final summary of changes shipped this cycle

Change	Files	Effect
Cornerstone raster bake	app/flood_layers/{dep_stormwater,sandy_inundation}.py, scripts/bake_cornerstone_rasters.py, data/baked/*.tif	33s → <100ms cold; <5ms per query
Register refactor	app/registers/{nycha,doe_schools,doh_hospitals}.py, app/registers/_loader.py	8+ min hang → <100ms total
EO deps	requirements.txt (planetary-computer/pystac-client/rioxarray/xarray/einops)	Live Sentinel-2 + Prithvi remote inference
Deps gate split	app/flood_layers/prithvi_live.py, app/context/terramind_synthesis.py, app/context/terramind_nyc.py	Tier-1 chip-fetch separated from Tier-2 local-inference
UI honesty	web/sveltekit/src/lib/data/stoneRegistry.ts, web/sveltekit/src/lib/client/registerAdapter.ts, web/sveltekit/src/routes/q/[queryId]/+page.svelte	"RIPRAP_HEAVY_SPECIALISTS=0" copy gone; new NYCHA schema
HF env	scripts/update_hf_env.sh (RIPRAP_NYCHA_REGISTERS=1), set on live Space	Heavy register specialists actually attached to FSM
FSM consumers	app/fsm.py, app/reconcile.py	Match new NYCHA schema
Warmup hygiene	web/main.py	Drop 91 MB Sandy GeoJSON pre-load (no longer needed)