deploy(l4): self-contained Riprap mirror

.env.example

@@ -0,0 +1,34 @@
+# Riprap environment configuration.
+#
+# Copy this file to `.env` and fill in the values that match the
+# inference backend you want to talk to. The default profile runs
+# only the app container, so both the LLM (vLLM serving Granite 4.1)
+# and the ML specialist service must be reachable at HTTP endpoints.
+#
+# Three common configurations:
+#
+#   1. Easiest — talk to the live demo's backends. Adam runs a public
+#      MI300X droplet for the hackathon; if it's still up at demo time,
+#      both endpoints are reachable from anywhere.
+#
+#   2. Self-hosted — bring up your own MI300X droplet via
+#      docs/DROPLET-RUNBOOK.md, then point both URLs at it.
+#
+#   3. Full local — use `docker compose --profile with-models up` to
+#      run the riprap-models service yourself (requires a GPU on your
+#      box) and point a separate vLLM container at Granite 4.1.
+
+# ---- Granite 4.1 reconciler (vLLM, OpenAI-compatible) -----------------
+# Set to "ollama" instead of "vllm" if you have a local Ollama with
+# granite4.1:8b pulled and want to use that.
+RIPRAP_LLM_PRIMARY=vllm
+RIPRAP_LLM_BASE_URL=http://your-vllm-host:8000/v1
+RIPRAP_LLM_API_KEY=your-token-here
+
+# ---- ML specialist service (Prithvi, TerraMind, GLiNER, etc.) ---------
+RIPRAP_ML_BASE_URL=http://your-ml-host:7860
+RIPRAP_ML_API_KEY=your-token-here
+
+# ---- Backend pill labels (cosmetic, shown top-right of the UI) --------
+RIPRAP_HARDWARE_LABEL=AMD MI300X
+RIPRAP_ENGINE_LABEL=Granite 4.1 / vLLM

.gitattributes

@@ -0,0 +1,54 @@
+# Riprap-specific LFS tracking
+*.geojson filter=lfs diff=lfs merge=lfs -text
+*.tif filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text
+# Pre-computed register paragraphs
+data/registers/*.json filter=lfs diff=lfs merge=lfs -text
+# Esri FileGDB internal binary files (DEP Stormwater scenario data)
+*.gdbtable filter=lfs diff=lfs merge=lfs -text
+*.gdbtablx filter=lfs diff=lfs merge=lfs -text
+*.gdbindexes filter=lfs diff=lfs merge=lfs -text
+*.atx filter=lfs diff=lfs merge=lfs -text
+*.spx filter=lfs diff=lfs merge=lfs -text
+*.freelist filter=lfs diff=lfs merge=lfs -text
+*.horizon filter=lfs diff=lfs merge=lfs -text
+*.FDO_UUID filter=lfs diff=lfs merge=lfs -text
+# Hugging Face's standard LFS rules (kept for forward-compat with model assets)
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pptx filter=lfs diff=lfs merge=lfs -text
+assets/screenshots/** filter=lfs diff=lfs merge=lfs -text
+slides/*.png filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,65 @@
+name: Bug report
+description: A briefing came back wrong, a Stone failed to fire, or the UI broke.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing! Riprap is a hackathon-period demo; the more
+        reproducible the report, the faster it gets fixed.
+  - type: input
+    id: address
+    attributes:
+      label: NYC address tested
+      description: The exact string you typed (or "n/a" if the bug is UI-only).
+      placeholder: 80 Pioneer Street, Brooklyn
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Paste the briefing text or describe the failure.
+    validations:
+      required: true
+  - type: dropdown
+    id: surface
+    attributes:
+      label: Where did you reproduce this?
+      options:
+        - Hosted demo (lablab Space)
+        - Local Docker (`docker compose up`)
+        - Local dev server (`uvicorn web.main:app`)
+        - Self-hosted GPU inference
+    validations:
+      required: true
+  - type: input
+    id: browser
+    attributes:
+      label: Browser / OS
+      placeholder: Chrome 142 on macOS 14
+  - type: textarea
+    id: console
+    attributes:
+      label: Browser console errors
+      description: DevTools → Console. Paste anything red.
+      render: text
+  - type: textarea
+    id: stream
+    attributes:
+      label: /api/agent/stream output (optional)
+      description: |
+        If the bug is a Stone failure, paste the relevant lines from the
+        SSE trace pane (or curl `/api/agent/stream?q=<address>` directly).
+      render: text
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Try the live demo
+    url: https://lablab-ai-amd-developer-hackathon-riprap-nyc.hf.space
+    about: Reproduce the issue against the hosted Space before filing.
+  - name: Read the architecture docs
+    url: https://github.com/msradam/riprap-nyc/tree/main/docs
+    about: ARCHITECTURE, METHODOLOGY, EMISSIONS, DEPLOY, BENCHMARKS, RESEARCH.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,54 @@
+name: Feature request
+description: Propose a new probe, a new Stone, or a new civic-tech use case.
+title: "[feat] "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: usecase
+    attributes:
+      label: Civic-tech use case
+      description: |
+        Who is the user, what decision are they making, and what
+        evidence would Riprap need to surface to support it?
+      placeholder: |
+        e.g. "A resilience office siting a capital project needs the
+        joint exposure of NYCHA + schools within 200m of a Sandy
+        100-year inundation polygon."
+    validations:
+      required: true
+  - type: textarea
+    id: data
+    attributes:
+      label: Data source(s)
+      description: |
+        Which public-record datasets should Riprap pull from? Include
+        URLs, agency owner, refresh cadence, and licence if known.
+    validations:
+      required: true
+  - type: dropdown
+    id: stone
+    attributes:
+      label: Which Stone does this belong in?
+      options:
+        - Cornerstone (hazard memory)
+        - Keystone (asset registers)
+        - Touchstone (live observation)
+        - Lodestone (forecast)
+        - Capstone (synthesis)
+        - Not sure / cross-cutting
+    validations:
+      required: true
+  - type: dropdown
+    id: contribute
+    attributes:
+      label: Willing to contribute the implementation?
+      options:
+        - "Yes — I can open the PR"
+        - "Maybe — with mentorship"
+        - "No — flagging the gap"
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else

.github/ISSUE_TEMPLATE/port_to_new_city.yml

@@ -0,0 +1,70 @@
+name: Port to a new city
+description: Plan a Riprap deployment for a city other than NYC.
+title: "[port] "
+labels: ["port", "enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Riprap's Five Stones taxonomy is city-agnostic; only the probes
+        plugged into each Stone change. See the "Five Stones beyond NYC"
+        section in the README. This template helps scope a port.
+  - type: input
+    id: city
+    attributes:
+      label: Target city / region
+      placeholder: e.g. Houston, TX
+    validations:
+      required: true
+  - type: textarea
+    id: cornerstone
+    attributes:
+      label: Cornerstone — hazard memory
+      description: |
+        Local historical inundation extents, regional DEM, regulatory
+        floodplain maps. Include dataset URLs and licences.
+    validations:
+      required: true
+  - type: textarea
+    id: keystone
+    attributes:
+      label: Keystone — asset registers
+      description: |
+        Transit, housing, education, healthcare polygons your jurisdiction
+        publishes.
+    validations:
+      required: true
+  - type: textarea
+    id: touchstone
+    attributes:
+      label: Touchstone — live observation
+      description: |
+        Live sensors, complaint streams (e.g. Houston has FloodNet
+        analogues; many cities expose 311 or equivalent).
+    validations:
+      required: true
+  - type: textarea
+    id: lodestone
+    attributes:
+      label: Lodestone — forecast
+      description: |
+        Local NWS / hydrologic / surge models, tide gauges, time-series
+        fine-tunes you'd retrain.
+    validations:
+      required: true
+  - type: dropdown
+    id: hardware
+    attributes:
+      label: Target inference hardware
+      options:
+        - AMD MI300X (or other ROCm)
+        - NVIDIA L4 / A10
+        - NVIDIA H100 / A100
+        - CPU-only (Ollama)
+        - Not decided
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Anything else

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,38 @@
+<!-- Thanks for opening a PR. The checklist below mirrors how Riprap
+     was kept stable through hackathon week. -->
+
+## Summary
+
+<!-- One paragraph: what changed, and why. Reference issues with #N. -->
+
+## Tested against
+
+- [ ] Local dev server (`uvicorn web.main:app`)
+- [ ] Local Docker (`docker compose up`)
+- [ ] Hosted lablab Space
+- [ ] Self-hosted GPU inference
+
+## Stones-fire probe
+
+<!-- Paste the tail of `scripts/probe_stones_fire.py` output. The PR
+     should not be merged unless all five Stones fire. -->
+
+```
+PYTHONPATH=. uv run python scripts/probe_stones_fire.py --timeout 600
+```
+
+## Energy-ledger sanity check
+
+<!-- If this PR touches inference, app/emissions.py, or app/llm.py:
+     paste the n_measured / n_calls ratio and confirm hardware label. -->
+
+## Checklist
+
+- [ ] No regression in `app/`, `web/`, `services/`, or
+      `inference-vllm/proxy.py` logic (typo-only edits OK).
+- [ ] Docs updated (`README.md`, relevant `docs/*.md`) if public
+      surface changed.
+- [ ] `CHANGELOG.md` entry under `[Unreleased]` with the right
+      `Added` / `Changed` / `Fixed` bucket.
+- [ ] Conventional-commit prefix on the squash title
+      (`feat:` / `fix:` / `docs:` / `chore:` / `build:`).

.github/workflows/check.yml

@@ -0,0 +1,43 @@
+name: check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: import + lightweight tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Create venv and install deps
+        run: |
+          uv venv --python 3.12
+          uv pip install -r requirements.txt
+
+      - name: Import smoke test
+        env:
+          PYTHONPATH: .
+        run: |
+          uv run python -c "from app import fsm, llm, inference, emissions; from web import main"
+
+      - name: Lightweight pytest subset
+        env:
+          PYTHONPATH: .
+        run: |
+          uv run pytest -q tests/test_stones.py tests/test_compare_shape.py tests/test_stone_envelope.py

.gitignore

@@ -0,0 +1,89 @@
+# Session artifacts (legacy agent reports — not for the public repo)
+*MORNING-BRIEF*.md
+*OVERNIGHT*.md
+*COMMS-OVERNIGHT*.md
+CODE-MORNING-BRIEF*.md
+MONDAY.md
+FRIDAY*.md
+*-REPORT.md
+docs/sessions/
+docs/design_handoff/
+
+# Local-only secrets / credentials
+AMD_TOKEN
+
+# Probe / batch / diagnostic output (regenerable; not for the repo)
+tests/batch_results.json
+tests/overnight_audit.json
+scripts/diagnostic_*.py
+scripts/find_top_locations.py
+scripts/verify_locations.py
+
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.DS_Store
+outputs/
+node_modules/
+*.tmp
+*.log
+.ruff_cache/
+.pytest_cache/
+.ipynb_checkpoints/
+
+# Claude Code context (per-machine, not for the public repo)
+CLAUDE.md
+CLAUDE.local.md
+.claude/
+
+# legacy / intermediate Prithvi artifacts (not shipped)
+data/hls_stack_*.tif
+data/prithvi_runs/
+data/*.legacy_*
+web/svelte/node_modules/
+web/sveltekit/node_modules/
+web/sveltekit/.svelte-kit/
+# web/sveltekit/build/ (uncommented to allow deployment to HF Space)
+# web/sveltekit/build/
+
+# Experiments — cached HF model downloads, training artifacts, intermediate
+# fixtures. RESULTS.md, NOTES.md, and source code stay tracked.
+experiments/**/.cache/
+experiments/**/restore/
+experiments/**/publish/
+experiments/**/*.tif
+experiments/**/*.png
+experiments/**/*.jpg
+experiments/**/*.parquet
+experiments/**/*.npy
+pitch/screenshots-*/
+
+# Marp deck render artefacts (regenerable via `make` in slides/)
+slides/deck.pdf
+slides/deck.html
+slides/deck.pptx
+
+# Session artifacts
+/tmp/riprap-*
+.deploy-state
+*.bak
+*.swp
+*.swo
+.playwright-mcp/
+
+# Demo recordings (large; not committed)
+assets/video/
+slides/*.mp4
+slides/asce/speaker_notes.md
+
+# Local env overlays
+.env.local
+*.local.env
+
+# Sensitive
+AMD_TOKEN
+submission.md

CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to Riprap. The hackathon submission tag is
+`v0.5.0` (build 2026-05-07); subsequent dates record polish work
+that landed on the hackathon-period production deploys.
+
+## [Unreleased] — 2026-05-09 (Saturday)
+
+### Added
+- **Per-query inference energy ledger** with real NVML readings off
+  the L4 GPU. The status row on the Findings region now reports
+  total Wh + total tokens for every briefing, with a leading icon
+  (`✓` / `◐` / `~`) disclosing whether the number was measured or
+  estimated. Full breakdown documented in
+  [`docs/EMISSIONS.md`](docs/EMISSIONS.md).
+- `inference-vllm/proxy.py`: 100 ms-cadence NVML sampler, response
+  headers `X-GPU-Power-W` / `X-GPU-Energy-J` on every forwarded
+  POST, and a `GET /v1/power` endpoint for bracket-sampling clients.
+- `app/emissions.py` — new module with a thread-local `Tracker` that
+  records every LLM and ML inference call (model, hardware, tokens,
+  duration, joules) with a `measured: bool` flag per row.
+- `scripts/probe_stones_fire.py` — programmatic CI that runs an
+  address query against the lablab UI and asserts all five Stones
+  fire, no `torchvision::nms` / `deps unavailable` dep regression,
+  and the `emissions` block carries `nvidia_l4` hardware.
+- `scripts/probe_benchmarks.py` — collects the canonical
+  four-address verification set into `outputs/benchmarks.json`
+  for the `docs/BENCHMARKS.md` page.
+- `docs/EMISSIONS.md`, `docs/DEPLOY.md`, `docs/BENCHMARKS.md`,
+  `CHANGELOG.md`, `CONTRIBUTING.md`.
+
+### Changed
+- The `RunHealthStrip` chip dropped the cloud-energy comparison
+  (the sign convention was misleading and the comparison is now
+  redundant given real measurements). New format:
+  `<icon> X.X Wh / Y.YK tok inference`.
+- `app/llm.py:_default_hardware_label` defaults to `"NVIDIA L4"`
+  when remote vLLM is configured (was `"AMD MI300X"`, a stale
+  string from the droplet days).
+- `app/llm.py:chat()` now brackets every completion with two GETs
+  to the inference Space's `/v1/power` endpoint; the average powers
+  the LLM-call energy reading instead of the data-sheet estimate.
+- `app/inference.py:_post()` reads NVML headers off the proxy
+  response and forwards real joules into `emissions.record_ml`.
+
+### Fixed
+- `app/flood_layers/prithvi_live.py`: when the configured remote
+  inference call fails (`RemoteUnreachable`), the specialist no
+  longer falls through to the local terratorch path. The local
+  path crashes with `RuntimeError: operator torchvision::nms does
+  not exist` on the cpu-basic UI Space; surfacing a clean
+  `remote prithvi-pluvial unreachable` skip is correct.
+- `app/context/terramind_nyc.py:_try_remote()`: returns a
+  `{"ok": False, "skipped": "remote terramind/<adapter>: ..."}`
+  sentinel on remote failure, instead of `None` which was
+  silently masked as `deps unavailable on this deployment`.
+- `web/main.py`: explicit `/favicon.svg`, `/favicon.png`,
+  `/favicon.ico`, `/robots.txt` routes — they were 404-ing under
+  the SvelteKit SPA fallback because only `/_app` was mounted off
+  the build directory.
+
+### Documentation
+- Full README rewrite reflecting the post-droplet L4 topology, the
+  new emissions feature, and updated repo structure. Hackathon
+  framing preserved.
+- New `docs/DEPLOY.md` with the production topology, env-var
+  reference, and per-Space deploy commands.
+- New `docs/EMISSIONS.md` documenting what's measured vs. estimated,
+  the NVML pipeline, and how to verify.
+
+### Infrastructure note
+- The DigitalOcean MI300X droplet was decommissioned 2026-05-06.
+  All production inference now serves from `msradam/riprap-vllm`
+  (NVIDIA L4). The MI300X runbook is preserved in
+  [`docs/DROPLET-RUNBOOK.md`](docs/DROPLET-RUNBOOK.md) for anyone
+  reproducing the AMD-judging setup; setting
+  `RIPRAP_HARDWARE_LABEL=AMD MI300X` swaps the emissions profile
+  back when redeploying to that hardware.
+
+---
+
+## [v0.5.0] — 2026-05-07
+
+Hackathon submission tag.
+
+### Added
+- Five-Stone Burr FSM with Granite-native document-role messages
+- Mellea four-check rejection sampling for the Capstone
+- SvelteKit UI with SSE streaming, briefing prose, evidence-card
+  grid, MapLibre overlay, citation drawer
+- Three NYC-specialised foundation models published Apache-2.0:
+  `msradam/TerraMind-NYC-Adapters` (LULC + Buildings + TiM LoRAs),
+  `msradam/Prithvi-EO-2.0-NYC-Pluvial`,
+  `msradam/Granite-TTM-r2-Battery-Surge`
+- 30+ FSM specialists across hazard memory, asset registers, live
+  observation, forecasting, and citation-grounded synthesis

CODE_OF_CONDUCT.md

@@ -0,0 +1,85 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at msrahmanadam@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

CONTRIBUTING.md

@@ -0,0 +1,127 @@
+# Contributing
+
+Riprap is the hackathon submission for the AMD × lablab.ai
+Developer Hackathon, but the source ships under Apache 2.0 and is
+intended to be reusable as a template for citation-grounded civic
+AI in any flood-vulnerable region. Pull requests welcome.
+
+## Quickstart
+
+Python 3.12 + `uv`:
+
+```bash
+git clone https://github.com/msradam/riprap-nyc
+cd riprap-nyc
+uv venv && uv pip install -r requirements.txt
+```
+
+SvelteKit (the build is committed; only rebuild when sources
+change under `web/sveltekit/src`):
+
+```bash
+cd web/sveltekit && npm ci && npm run build && cd ../..
+```
+
+Run the dev server locally pointing at the production inference
+Space (real Granite + EO models, real NVML energy readings):
+
+```bash
+RIPRAP_LLM_PRIMARY=vllm \
+RIPRAP_LLM_BASE_URL=https://msradam-riprap-vllm.hf.space/v1 \
+RIPRAP_LLM_API_KEY=<token> \
+RIPRAP_ML_BACKEND=remote \
+RIPRAP_ML_BASE_URL=https://msradam-riprap-vllm.hf.space \
+RIPRAP_ML_API_KEY=<token> \
+.venv/bin/uvicorn web.main:app --host 127.0.0.1 --port 7860
+```
+
+Or run pure-local with Ollama (no GPU readings; data-sheet estimate):
+
+```bash
+ollama pull granite4.1:3b granite4.1:8b
+.venv/bin/uvicorn web.main:app --host 127.0.0.1 --port 7860
+```
+
+## Verifying changes
+
+Two probe scripts exercise the live deployment end-to-end:
+
+```bash
+# All five Stones must fire on the canonical address; emissions
+# block must carry nvidia_l4 hardware; no torchvision/terratorch
+# dep regressions in the trace.
+PYTHONPATH=. uv run python scripts/probe_stones_fire.py --timeout 600
+
+# Full canonical suite — five NYC addresses, intent-aware checks,
+# Mellea grounding budget, no specialist crashes.
+.venv/bin/python scripts/probe_addresses.py \
+    --base https://lablab-ai-amd-developer-hackathon-riprap-nyc.hf.space
+```
+
+Both default to the lablab UI Space; pass `--base http://127.0.0.1:7860`
+to hit a local server.
+
+## Structure
+
+```
+app/                       Python package — the FSM and its specialists
+├── fsm.py                 Burr FSM, one @action per probe
+├── llm.py                 LiteLLM Router shim (Ollama / vLLM)
+├── inference.py           HTTP client for the riprap-models service
+├── emissions.py           Per-query energy + token tracker
+├── stones/                Stone taxonomy (NAME / TAGLINE / collect())
+├── flood_layers/          Cornerstone probes (sandy, dep, microtopo, …)
+├── context/               Keystone + Touchstone register + EO probes
+├── live/                  Lodestone forecast probes
+├── intents/               single_address / neighborhood / compare / live_now
+├── reconcile.py           Capstone — Granite-native document reconcile
+└── mellea_validator.py    Mellea four-check rejection sampling
+
+web/                       FastAPI + SvelteKit
+├── main.py                FastAPI app, SSE streaming, layer endpoints
+├── sveltekit/             Primary UI (adapter-static; build committed)
+└── static/                Legacy custom-element pages (still mounted)
+
+inference-vllm/            Inference Space source (vLLM + EO models + proxy)
+├── Dockerfile             L4 image, bakes Granite 4.1 8B FP8 + EO deps
+├── entrypoint.sh          Boots vllm, riprap-models, proxy as subprocesses
+└── proxy.py               Bearer-auth + NVML power sampler + SSE pass-through
+
+inference/                 Ollama-backed inference Space (fallback variant)
+services/riprap-models/    The EO/forecast specialist HTTP service
+
+scripts/
+├── probe_stones_fire.py   Programmatic Stone-fire CI
+├── probe_addresses.py     Canonical 5-address suite
+├── deploy_vllm_space.sh   Deploy the L4 inference Space
+├── deploy_personal_space.sh  Deploy the personal L4 mirror
+├── deploy_inference_space.sh Deploy the Ollama-backed inference Space
+└── …                       Register builders, raster bakers, etc.
+
+experiments/               Reproduction recipes for the three NYC fine-tunes
+docs/                      Architecture, methodology, deploy, emissions, runbooks
+tests/                     pytest suite (envelope + compare-shape tests)
+```
+
+## Style
+
+- Python 3.12; `uv` for package management.
+- LLM calls go through `app/llm.py` — never import `litellm` /
+  `ollama` directly from a specialist. The `chat()` shim wraps both
+  backends and the energy ledger reads off it.
+- Remote ML calls go through `app/inference.py::_post`. Specialists
+  may try local fallback only when `inference.remote_enabled()` is
+  False; once a remote call has been attempted, return a clean
+  `{ok: False, skipped: ...}` on failure rather than crashing
+  through to local code paths that may not be installed.
+- Every specialist emits one trace record per call with `step` /
+  `ok` / `elapsed_s` / `result` / `err` so the SSE stream and the
+  emissions tracker can reason about it.
+
+## Reporting issues
+
+GitHub issues at <https://github.com/msradam/riprap-nyc/issues>.
+For hackathon-period demo issues during May 4–10 2026, the live
+deploy at
+<https://lablab-ai-amd-developer-hackathon-riprap-nyc.hf.space>
+is the source of truth.

Dockerfile

@@ -0,0 +1,104 @@
+# Riprap — Hugging Face Spaces deployment for the personal Space
+# (msradam/riprap-nyc) on L4 hardware.
+#
+# Differences from the canonical Dockerfile:
+#
+#   1. L4 has 24 GB VRAM (vs 16 GB on T4 small), so we co-host the
+#      riprap-models service inside the same container instead of
+#      proxying to the AMD MI300X droplet. No external dependency.
+#
+#   2. We bake granite4.1:8b at *build* time. The build sandbox could
+#      not previously fit Granite + EO toolchain together; this Dockerfile
+#      keeps the EO install at runtime (entrypoint.l4.sh) and frees the
+#      sandbox budget for the 8B pull.
+#
+#   3. CUDA + ROCm-free torch — the inline riprap-models service uses
+#      the cu124 wheels installed via requirements.txt + the additional
+#      delta in services/riprap-models/requirements.txt.
+#
+# DO NOT push this image to the lablab Space — that one stays pointed
+# at the MI300X droplet for AMD-judging continuity.
+
+FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04 AS base
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        python3 python3-pip python3-venv python-is-python3 \
+        curl ca-certificates zstd procps git \
+        gdal-bin libgdal-dev libgeos-dev libproj-dev \
+        libgl1 libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin \
+    PYTHONUNBUFFERED=1 \
+    HF_HOME=/home/user/.cache/huggingface \
+    OLLAMA_HOST=127.0.0.1:11434 \
+    OLLAMA_NUM_PARALLEL=1 \
+    OLLAMA_KEEP_ALIVE=24h \
+    OLLAMA_MAX_LOADED_MODELS=2 \
+    OLLAMA_FLASH_ATTENTION=1 \
+    OLLAMA_KV_CACHE_TYPE=q8_0 \
+    OLLAMA_DEBUG=1 \
+    OLLAMA_MODELS=/home/user/.ollama/models \
+    RIPRAP_OLLAMA_3B_TAG=granite4.1:8b \
+    RIPRAP_LLM_PRIMARY=ollama \
+    RIPRAP_LLM_BASE_URL=http://127.0.0.1:11434/v1 \
+    RIPRAP_ML_BACKEND=remote \
+    RIPRAP_ML_BASE_URL=http://127.0.0.1:7861
+
+RUN curl -fsSL https://ollama.com/install.sh | sh
+
+WORKDIR /home/user/app
+
+# Web app deps (torch cu124 lands via sentence-transformers / etc.).
+COPY --chown=user:user requirements.txt ./
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# riprap-models delta deps. Use the existing requirements.txt at the
+# *service* level, but skip requirements-full.txt — its ROCm-frozen
+# torch pin would clobber the cu124 wheels installed above.
+COPY --chown=user:user services/riprap-models/requirements.txt /tmp/req-models.txt
+RUN pip install --no-cache-dir -r /tmp/req-models.txt
+
+# Bake torchvision (CUDA 12.4 wheel) and peft at build time. The
+# canonical entrypoint.sh runtime-installs torchvision via the EO
+# toolchain path because the canonical CPU Space's build sandbox is
+# too tight; L4 builds have more room, and a properly matched
+# torchvision avoids the `torchvision::nms does not exist` runtime
+# error the canonical setup hits. peft is required by the riprap-
+# models service for the TerraMind LoRA inference path.
+RUN pip install --no-cache-dir \
+        --index-url https://download.pytorch.org/whl/cu124 \
+        torchvision \
+    && pip install --no-cache-dir peft==0.18.1
+
+# Bake Granite 4.1 weights into the image (EO toolchain is installed
+# at runtime — see entrypoint.l4.sh — to keep the build sandbox under
+# its disk threshold).
+RUN mkdir -p $OLLAMA_MODELS && \
+    ollama serve & \
+    OPID=$! && \
+    for i in $(seq 1 30); do curl -sf http://127.0.0.1:11434/ > /dev/null && break; sleep 1; done && \
+    ollama pull granite4.1:8b && \
+    kill $OPID 2>/dev/null || true && \
+    sleep 2
+
+# App code, fixtures, and inline model service.
+COPY --chown=user:user app/ ./app/
+COPY --chown=user:user web/ ./web/
+COPY --chown=user:user scripts/ ./scripts/
+COPY --chown=user:user data/ ./data/
+COPY --chown=user:user corpus/ ./corpus/
+COPY --chown=user:user services/riprap-models/main.py ./riprap_models.py
+COPY --chown=user:user agent.py riprap.py ./
+COPY --chown=user:user entrypoint.sh ./entrypoint.sh
+RUN chmod +x ./entrypoint.sh
+
+RUN chown -R user:user /home/user
+USER user
+
+EXPOSE 7860
+CMD ["./entrypoint.sh"]

README.md

@@ -0,0 +1,26 @@
+---
+title: Riprap NYC (Personal Mirror, L4)
+emoji: 🌊
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+short_description: NYC flood-exposure briefings on L4 (self-contained).
+---
+
+# Riprap — NYC flood-exposure briefings (L4 self-contained mirror)
+
+This Space is a self-contained mirror of
+[`github.com/msradam/riprap-nyc`](https://github.com/msradam/riprap-nyc).
+
+It runs on a single L4 GPU and co-hosts everything in one container:
+Granite 4.1 8B (via Ollama), Prithvi-EO 2.0 NYC-Pluvial, TerraMind
+LULC + Buildings LoRAs, and Granite TTM r2 — no external droplet
+dependency. Sleeps on idle; first request after sleep takes ~45–60 s
+to wake.
+
+The hackathon submission Space (CPU UI, droplet proxy) lives at
+[`AMD-hackathon/riprap-nyc`](https://lablab-ai-amd-developer-hackathon-riprap-nyc.hf.space).
+
+Apache 2.0. See the GitHub repo for full source, architecture
+deep-dive, methodology, and licence map.

SECURITY.md

@@ -0,0 +1,54 @@
+# Security policy
+
+## Reporting a vulnerability
+
+If you find a security issue in Riprap, please report it privately so
+it can be triaged before disclosure.
+
+- Email: **msrahmanadam@gmail.com** (subject prefix: `[riprap-security]`)
+- Or open a [GitHub Security Advisory](https://github.com/msradam/riprap-nyc/security/advisories/new)
+  on this repository.
+
+Please do not file a public GitHub issue for security reports.
+
+We aim to acknowledge reports within 72 hours and to ship a fix or a
+mitigation plan within two weeks of triage. If the report concerns a
+vulnerability in an upstream model or service Riprap depends on
+(IBM Granite, vLLM, Hugging Face Spaces, NYC Open Data endpoints), we
+will help coordinate disclosure with the upstream maintainer.
+
+## Threat-surface notes
+
+Riprap is a citation-grounded synthesis layer over public-record
+data. By design, the runtime:
+
+- contacts only **public-record APIs** (NYC Open Data, FloodNet,
+  USGS, NOAA, NWS, NYS DOH, MTA, NYCHA, NYC DOE, OpenStreetMap /
+  Nominatim) and the configured inference Spaces;
+- does **not** authenticate against user accounts or store
+  user-identifying data — the address bar is the only input;
+- runs the SvelteKit UI as a static SPA over a FastAPI backend
+  with no persistent database.
+
+The vulnerability surface is therefore small. Plausible categories
+worth a report:
+
+- Prompt-injection paths via document content that escape the
+  Mellea grounding loop and surface unverifiable claims as cited.
+- SSRF / abuse via crafted address strings that drive backend
+  HTTP calls to unintended hosts.
+- Token leakage in proxy headers or SSE streams
+  (`inference-vllm/proxy.py`, `web/main.py`).
+- Denial-of-service patterns that exceed the hosted Space's
+  resource budget.
+- Supply-chain issues in pinned deps (`requirements.txt`,
+  `web/sveltekit/package.json`).
+
+## Out of scope
+
+- Self-hosted deployments running with custom configuration or
+  custom datasets — please file those as regular bugs.
+- Findings that require physical or local-network access to a
+  user's machine.
+- Issues in the lablab.ai or Hugging Face Spaces hosting platforms
+  themselves; please report those upstream.

agent.py

@@ -0,0 +1,52 @@
+"""Riprap agent CLI — address → cited briefing via the Burr FSM.
+
+Usage:
+    python agent.py "180 Beach 35 St, Queens"
+    python agent.py "280 Broome St, Manhattan"  --json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import warnings
+
+warnings.filterwarnings("ignore")
+
+from app.fsm import run  # noqa: E402
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("query", help="NYC address or natural-language location")
+    ap.add_argument("--json", action="store_true", help="emit full JSON state")
+    args = ap.parse_args()
+
+    print(f"\n  query: {args.query}", file=sys.stderr)
+    print("  running FSM... (Granite 4.1 + open data, all local)\n", file=sys.stderr)
+
+    result = run(args.query)
+
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+        return 0
+
+    print("─── trace " + "─" * 56)
+    for step in result["trace"]:
+        ok = "✓" if step["ok"] else "✗"
+        line = f"  {ok} {step['step']:22s} {step.get('elapsed_s', 0):>5.2f}s"
+        if step.get("result"):
+            line += "  " + json.dumps(step["result"], default=str)
+        elif step.get("err"):
+            line += "  ERR: " + step["err"]
+        print(line)
+
+    print("\n─── cited report " + "─" * 49)
+    print()
+    print(result["paragraph"])
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

app/areas/nta.py

@@ -0,0 +1,224 @@
+"""NYC Neighborhood Tabulation Area (NTA 2020) resolver.
+
+NTAs are NYC Department of City Planning's official neighborhood unit:
+~262 polygons covering all 5 boroughs, including some park / airport
+slivers. They are the canonical "neighborhood" unit for NYC civic data.
+
+This module provides:
+  - load() → GeoDataFrame with all NTAs (cached)
+  - resolve(name) → list of matching NTAs by fuzzy name match, or by borough
+  - by_code(code) → exact lookup
+  - polygon_for(code) → shapely Polygon in EPSG:4326
+"""
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import geopandas as gpd
+from shapely.geometry import Polygon
+
+DATA_PATH = Path(__file__).resolve().parents[2] / "data" / "nyc_ntas_2020.geojson"
+
+# Common alias map: user-typed strings → canonical NTA names. We don't need to
+# be exhaustive here; the fuzzy matcher catches most cases. This handles the
+# few hard ones where the official NTA name differs from local usage.
+ALIASES = {
+    "the rockaways":    "Rockaway Beach-Arverne-Edgemere",
+    "rockaway":         "Rockaway Beach-Arverne-Edgemere",
+    "brighton":         "Brighton Beach",
+    "lower east side":  "Lower East Side",
+    "les":              "Lower East Side",
+    "soho":             "SoHo-Little Italy-Hudson Square",
+    "tribeca":          "Tribeca-Civic Center",
+    "fidi":             "Financial District-Battery Park City",
+    "downtown brooklyn":"Downtown Brooklyn-DUMBO-Boerum Hill",
+    "dumbo":            "Downtown Brooklyn-DUMBO-Boerum Hill",
+    "park slope":       "Park Slope",
+    "carroll gardens":  "Carroll Gardens-Cobble Hill-Gowanus-Red Hook",
+    "red hook":         "Carroll Gardens-Cobble Hill-Gowanus-Red Hook",
+    "gowanus":          "Carroll Gardens-Cobble Hill-Gowanus-Red Hook",
+    "hollis":           "Queens Village-Hollis-Bellerose",
+    "long island city": "Hunters Point-Sunnyside-West Maspeth",
+    "lic":              "Hunters Point-Sunnyside-West Maspeth",
+    "astoria":          "Astoria (Central)",
+    "flushing":         "Flushing-Willets Point",
+    "harlem":           "Central Harlem (North)",
+    "east harlem":      "East Harlem (North)",
+    "washington heights":"Washington Heights (North)",
+    "midtown":          "Midtown South-Flatiron-Union Square",
+    "upper east side":  "Upper East Side-Carnegie Hill",
+    "ues":              "Upper East Side-Carnegie Hill",
+    "upper west side":  "Upper West Side-Lincoln Square",
+    "uws":              "Upper West Side-Lincoln Square",
+    "coney island":     "Coney Island-Sea Gate",
+}
+
+BOROUGH_NORMALIZE = {
+    "manhattan": "Manhattan", "mn": "Manhattan",
+    "brooklyn":  "Brooklyn",  "bk": "Brooklyn",  "kings": "Brooklyn",
+    "queens":    "Queens",    "qn": "Queens",
+    "bronx":     "Bronx",     "the bronx": "Bronx", "bx": "Bronx",
+    "staten island": "Staten Island", "si": "Staten Island", "richmond": "Staten Island",
+}
+
+
+def _normalize(s: str) -> str:
+    return re.sub(r"[^a-z]+", "", (s or "").lower())
+
+
+@lru_cache(maxsize=1)
+def load() -> gpd.GeoDataFrame:
+    """Load the NTA 2020 GeoJSON; coerce CRS to EPSG:4326. Cached."""
+    g = gpd.read_file(DATA_PATH)
+    if g.crs is None or g.crs.to_string() != "EPSG:4326":
+        g = g.to_crs("EPSG:4326")
+    return g
+
+
+def by_code(code: str) -> dict | None:
+    g = load()
+    hit = g[g["nta2020"] == code]
+    if hit.empty:
+        return None
+    return _row_to_dict(hit.iloc[0])
+
+
+def _row_to_dict(row) -> dict:
+    return {
+        "nta_code":  row["nta2020"],
+        "nta_name":  row["ntaname"],
+        "borough":   row["boroname"],
+        "cdta":      row.get("cdtaname"),
+        "geometry":  row["geometry"],
+    }
+
+
+def borough_match(query: str) -> str | None:
+    """If query matches a borough name (or common abbreviation), return the
+    canonical name. Otherwise return None."""
+    q = query.strip().lower()
+    return BOROUGH_NORMALIZE.get(q)
+
+
+def resolve(query: str) -> list[dict[str, Any]]:
+    """Resolve a free-text query to NTA(s).
+
+    Strategy (in priority order):
+      1. Borough match → all NTAs in borough.
+      2. Alias map → exact NTA name match.
+      3. Case-insensitive EXACT name match (so 'Kew Gardens' wins over
+         'Kew Gardens Hills' when both exist).
+      4. Substring match on normalized NTA name. When multiple match,
+         prefer the one whose normalized name length is closest to the
+         query — avoids 'Kew Gardens' resolving to 'Kew Gardens Hills'.
+      5. CDTA-name substring fallback.
+    """
+    g = load()
+    q = (query or "").strip()
+    if not q:
+        return []
+    boro = borough_match(q)
+    if boro:
+        hits = g[g["boroname"] == boro]
+        return [_row_to_dict(r) for _, r in hits.iterrows()]
+
+    alias = ALIASES.get(q.lower())
+    if alias:
+        hits = g[g["ntaname"] == alias]
+        if not hits.empty:
+            return [_row_to_dict(r) for _, r in hits.iterrows()]
+
+    # Exact (case-insensitive) — preferred over substring
+    name_lower = g["ntaname"].fillna("").str.lower()
+    exact = g[name_lower == q.lower()]
+    if not exact.empty:
+        return [_row_to_dict(r) for _, r in exact.iterrows()]
+
+    qn = _normalize(q)
+    if not qn:
+        return []
+    name_norm = g["ntaname"].fillna("").map(_normalize)
+    contains = g[name_norm.str.contains(qn, na=False)].copy()
+    if not contains.empty:
+        contains["_diff"] = contains["ntaname"].fillna("").map(
+            lambda s: abs(len(_normalize(s)) - len(qn))
+        )
+        contains = contains.sort_values("_diff")
+        return [_row_to_dict(r) for _, r in contains.iterrows()]
+
+    cdta_norm = g["cdtaname"].fillna("").map(_normalize)
+    contains = g[cdta_norm.str.contains(qn, na=False)]
+    if not contains.empty:
+        return [_row_to_dict(r) for _, r in contains.iterrows()]
+
+    return []
+
+
+def polygon_for(code: str) -> Polygon | None:
+    hit = by_code(code)
+    return hit["geometry"] if hit else None
+
+
+def resolve_from_text(text: str) -> list[dict[str, Any]]:  # TODO(cleanup): cc-grade-D (25)
+    """Scan free-text (e.g. a full natural-language query) for any known NTA
+    name, alias, or borough. Returns the first match. This is the fallback
+    when the planner failed to extract a clean target.
+
+    Strategy: walk ALIASES first (cheap), then iterate NTA names and look
+    for the longest match contained in the text. We prefer the longest
+    match so 'Carroll Gardens' wins over 'Gardens'.
+    """
+    t = (text or "").lower()
+    if not t:
+        return []
+    # Boroughs first (whole-word-ish — avoid false hits inside "queensland" etc.)
+    for boro_key, canon in BOROUGH_NORMALIZE.items():
+        if f" {boro_key} " in f" {t} " or t.startswith(boro_key + " ") or t.endswith(" " + boro_key):
+            hits = resolve(canon)
+            if hits:
+                return hits
+    # Alias keys, longest first
+    for key in sorted(ALIASES.keys(), key=len, reverse=True):
+        if key in t:
+            hits = resolve(key)
+            if hits:
+                return hits
+    # NTA names. Order: longest first so multi-word names match before
+    # shorter substrings, AND preferring the WORD-BOUNDARY match so
+    # "Kew Gardens" in the query doesn't collide with "Kew Gardens Hills"
+    # (the latter is longer; without word-boundary checking it'd match
+    # nothing, but with substring-in-text it'd match if the query ever
+    # contained the longer phrase). Caller picks the closest-length match.
+    g = load()
+    names = sorted(set(g["ntaname"].dropna().str.lower().tolist()), key=len, reverse=True)
+    matches = []
+    for name in names:
+        if not name or len(name) < 4:
+            continue
+        # Word-boundary-ish check: name must appear bounded by start/end or
+        # whitespace/punct (so "kew gardens hills" matches but "kew gardens"
+        # alone doesn't trigger "kew gardens hills" because of the trailing
+        # space requirement).
+        padded_t = f" {t} "
+        if f" {name} " in padded_t or f" {name}." in padded_t or f" {name}," in padded_t or f" {name}?" in padded_t:
+            matches.append(name)
+    if matches:
+        # Prefer the longest word-boundary match — most specific.
+        best = sorted(matches, key=len, reverse=True)[0]
+        hits = resolve(best)
+        if hits:
+            return hits
+    # Fallback: any substring (no boundary). Less precise, but catches
+    # casual queries like "show me red hook" where "red hook" is a
+    # neighborhood-name fragment within a longer NTA name.
+    for name in names:
+        if not name or len(name) < 4:
+            continue
+        if name in t:
+            hits = resolve(name)
+            if hits:
+                return hits
+    return []

app/assets/mta_entrances.py

@@ -0,0 +1,73 @@
+"""MTA Subway Entrances and Exits (NY OpenData i9wp-a4ja).
+
+~1,900 subway entrances city-wide. The MTA Climate Resilience Roadmap
+(Oct 2025) names ~1,500 of these as priorities for sealing — this is
+exactly the asset class our RAG corpus has the most to say about, and
+exactly the audience (MTA capital planners, transit advocacy) the
+register is built for.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import geopandas as gpd
+import httpx
+
+from app.spatial import DATA, NYC_CRS
+
+URL = "https://data.ny.gov/api/geospatial/i9wp-a4ja?method=export&format=GeoJSON"
+LOCAL = DATA / "mta_entrances.geojson"
+
+
+def _ensure_fixture() -> Path:
+    if LOCAL.exists():
+        return LOCAL
+    print("downloading MTA Subway Entrances (one-time)...", flush=True)
+    r = httpx.get(URL, timeout=60)
+    r.raise_for_status()
+    LOCAL.write_text(r.text)
+    return LOCAL
+
+
+def load() -> gpd.GeoDataFrame:
+    _ensure_fixture()
+    g = gpd.read_file(LOCAL)
+    if g.crs is None:
+        g.set_crs("EPSG:4326", inplace=True)
+    g = g.to_crs(NYC_CRS)
+    rename_map = {
+        "stop_name": "name",
+        "constrained_floor_to_floor_height": None,
+        "borough": "borough",
+        "entrance_type": "entrance_type",
+        "ada": "ada",
+        "north_south_street": "ns_street",
+        "east_west_street": "ew_street",
+        "corner": "corner",
+    }
+    for k, v in rename_map.items():
+        if v and k in g.columns and k != v:
+            g = g.rename(columns={k: v})
+
+    # build a usable address-style label
+    def label(row):
+        nm = (row.get("name") or "").strip()
+        ns = (row.get("ns_street") or "").strip()
+        ew = (row.get("ew_street") or "").strip()
+        cn = (row.get("corner") or "").strip()
+        bits = [nm]
+        cross = " & ".join(b for b in [ns, ew] if b)
+        if cross: bits.append(cross)
+        if cn: bits.append(f"({cn})")
+        return ", ".join([b for b in bits if b])
+
+    g["address"] = g.apply(label, axis=1)
+    if "borough" in g.columns:
+        boro_map = {"M": "Manhattan", "Bk": "Brooklyn", "B": "Brooklyn",
+                    "Q": "Queens", "Bx": "Bronx", "SI": "Staten Island"}
+        g["borough"] = g["borough"].astype(str).map(lambda v: boro_map.get(v, v.title()))
+
+    keep = [c for c in ["name", "address", "borough", "entrance_type",
+                        "ada", "ns_street", "ew_street", "corner", "geometry"]
+            if c in g.columns]
+    return g[keep].copy()

app/assets/nycha.py

@@ -0,0 +1,28 @@
+"""NYCHA Developments (NYC OpenData phvi-damg).
+
+326 public-housing developments across NYC. Used as an asset class for
+the bulk-mode register; the parent rationale for surfacing this layer
+is that NYCHA was hit hard by Sandy and remains a published Tier-1
+flood-resilience priority in the city's Hazard Mitigation Plan.
+"""
+from __future__ import annotations
+
+import geopandas as gpd
+
+from app.spatial import DATA, load_layer
+
+
+def load() -> gpd.GeoDataFrame:
+    g = load_layer(DATA / "nycha.geojson")
+    # NYCHA developments come back as polygons; the FSM expects point
+    # geometry for spatial joins. Use centroid.
+    g = g.copy()
+    g["geometry"] = g.geometry.centroid
+
+    # NYCHA Developments has only `developmen` (truncated label), tds_num, borough.
+    g = g.rename(columns={"developmen": "name"})
+    g["address"] = g["name"]  # the field doubles as both
+    g["borough"] = g["borough"].str.title()  # "BRONX" -> "Bronx" to match Riprap convention
+
+    keep = [c for c in ["name", "address", "borough", "tds_num", "geometry"] if c in g.columns]
+    return g[keep].copy()

app/assets/schools.py

@@ -0,0 +1,27 @@
+"""NYC DOE School Point Locations (Socrata a3nt-yts4)."""
+from __future__ import annotations
+
+import geopandas as gpd
+
+from app.spatial import DATA, load_layer
+
+BORO = {"1": "Manhattan", "2": "Bronx", "3": "Brooklyn", "4": "Queens", "5": "Staten Island"}
+
+
+def load() -> gpd.GeoDataFrame:
+    g = load_layer(DATA / "schools.geojson")
+    g = g.rename(columns={
+        "loc_code": "loc_code",
+        "loc_name": "name",
+        "address": "address",
+        "bbl": "bbl",
+        "bin": "bin",
+        "boronum": "boro_num",
+        "geodistric": "geo_district",
+        "adimindist": "admin_district",
+    })
+    g["borough"] = g["boro_num"].astype(str).map(BORO)
+    g["bbl"] = g["bbl"].astype(str).str.replace(r"\.0$", "", regex=True)
+    keep = ["loc_code", "name", "address", "borough", "bbl", "bin",
+            "geo_district", "admin_district", "geometry"]
+    return g[keep].copy()

app/context/_polygonize.py

@@ -0,0 +1,165 @@
+"""Vectorize a uint8 prediction raster (binary mask or class index)
+into an EPSG:4326 GeoJSON FeatureCollection so the frontend can paint
+it on the MapLibre map.
+
+The droplet's `/v1/prithvi-pluvial` and `/v1/terramind` routes return
+their predictions as base64-encoded uint8 with a shape and (where
+relevant) a class-label list. This module reconstructs the affine
+transform from the chip's geographic bounds (which the HF Space
+already knows) and walks `rasterio.features.shapes` to build polygons
+in the chip's native CRS, then reprojects to WGS84 for the map.
+
+Best-effort: any failure returns an empty FeatureCollection rather
+than raising into the caller's path. The map layer is decorative —
+the briefing is the deliverable.
+"""
+from __future__ import annotations
+
+import base64
+import logging
+
+log = logging.getLogger("riprap.polygonize")
+
+EMPTY: dict = {"type": "FeatureCollection", "features": []}
+
+
+def _decode_pred(pred_b64: str, pred_shape: list[int]):
+    """Inverse of the droplet's `base64(pred.tobytes())`. Returns a
+    uint8 numpy array of shape `pred_shape`, or None on decode error."""
+    try:
+        import numpy as np
+        raw = base64.b64decode(pred_b64)
+        return np.frombuffer(raw, dtype="uint8").reshape(pred_shape)
+    except Exception:
+        log.exception("polygonize: pred decode failed")
+        return None
+
+
+def polygonize_class_raster(
+    pred_b64: str,
+    pred_shape: list[int],
+    class_labels: list[str] | None,
+    bounds_4326: tuple[float, float, float, float],
+    *,
+    drop_classes: tuple[int, ...] = (0,),
+    simplify_tolerance: float = 0.0,
+) -> dict:
+    """Vectorize a categorical prediction raster (one integer class per
+    pixel) into a FeatureCollection with one Feature per connected
+    polygon. `bounds_4326` is `(minlon, minlat, maxlon, maxlat)` of the
+    chip; the raster is assumed to span those bounds at uniform
+    pixel size. Each feature carries `class_idx` and `class_label`
+    so the frontend can color by class.
+
+    `drop_classes`: skip pixels matching these class indices (default
+    drops 0 = "Background" / "outside" / etc).
+    """
+    pred = _decode_pred(pred_b64, pred_shape)
+    if pred is None:
+        return EMPTY
+    try:
+        from rasterio.features import shapes
+        from rasterio.transform import from_bounds
+        from shapely.geometry import shape
+        h, w = pred.shape
+        minlon, minlat, maxlon, maxlat = bounds_4326
+        # The chip is in EPSG:4326 for our use — Sentinel-2 chips are
+        # natively in their UTM zone, but we can polygonize against the
+        # WGS84 extent because the inference chip is a small bbox where
+        # the pixel-grid → lat/lon mapping is locally affine (sub-pixel
+        # error at NYC scale).
+        transform = from_bounds(minlon, minlat, maxlon, maxlat, w, h)
+        feats = []
+        for geom, value in shapes(pred, mask=pred > 0, transform=transform):
+            v = int(value)
+            if v in drop_classes:
+                continue
+            label = (class_labels[v]
+                     if class_labels and 0 <= v < len(class_labels)
+                     else f"class_{v}")
+            poly = shape(geom)
+            if simplify_tolerance > 0:
+                poly = poly.simplify(simplify_tolerance, preserve_topology=True)
+            if poly.is_empty:
+                continue
+            feats.append({
+                "type": "Feature",
+                "geometry": poly.__geo_interface__,
+                "properties": {
+                    "class_idx": v,
+                    "class_label": label,
+                    "fill_color": _PALETTE.get(label.lower(), _DEFAULT_FILL),
+                },
+            })
+        return {"type": "FeatureCollection", "features": feats}
+    except Exception:
+        log.exception("polygonize: class raster vectorisation failed")
+        return EMPTY
+
+
+def polygonize_binary_mask(
+    pred_b64: str,
+    pred_shape: list[int],
+    bounds_4326: tuple[float, float, float, float],
+    *,
+    label: str = "water",
+    fill_color: str = "#4A90E2",
+    simplify_tolerance: float = 0.0,
+) -> dict:
+    """Vectorize a binary prediction raster (e.g. Prithvi water mask;
+    1 = water, 0 = not). Returns one Feature per connected positive
+    region. Use this for prithvi_eo_live and the buildings LoRA."""
+    pred = _decode_pred(pred_b64, pred_shape)
+    if pred is None:
+        return EMPTY
+    try:
+        from rasterio.features import shapes
+        from rasterio.transform import from_bounds
+        from shapely.geometry import shape
+        h, w = pred.shape
+        minlon, minlat, maxlon, maxlat = bounds_4326
+        transform = from_bounds(minlon, minlat, maxlon, maxlat, w, h)
+        feats = []
+        for geom, _value in shapes(pred, mask=pred > 0, transform=transform):
+            poly = shape(geom)
+            if simplify_tolerance > 0:
+                poly = poly.simplify(simplify_tolerance, preserve_topology=True)
+            if poly.is_empty:
+                continue
+            feats.append({
+                "type": "Feature",
+                "geometry": poly.__geo_interface__,
+                "properties": {
+                    "class_label": label,
+                    "fill_color": fill_color,
+                },
+            })
+        return {"type": "FeatureCollection", "features": feats}
+    except Exception:
+        log.exception("polygonize: binary mask vectorisation failed")
+        return EMPTY
+
+
+# Lightweight palette used by the LULC + buildings layers. Frontend
+# may override via `fill_color` per feature; this is a sensible
+# default keyed on lowercase class labels.
+_DEFAULT_FILL = "#A0A0A0"
+_PALETTE = {
+    # ESRI 2020 LULC schema (terramind v1 base generative)
+    "water":              "#1F77B4",
+    "trees":              "#2CA02C",
+    "grass":              "#7FBF53",
+    "flooded vegetation": "#74C476",
+    "crops":              "#E1C75A",
+    "scrub/shrub":        "#A6BC44",
+    "built":              "#D62728",
+    "bare ground":        "#B07A4C",
+    "snow/ice":            "#E0E7EC",
+    "clouds":              "#CCCCCC",
+    # NYC LoRA LULC schema
+    "cropland":           "#E1C75A",
+    "bare":               "#B07A4C",
+    # Buildings LoRA
+    "building":           "#D62728",
+    "background":         _DEFAULT_FILL,
+}

app/context/dob_permits.py

@@ -0,0 +1,258 @@
+"""NYC DOB construction-permit specialist — "what are they building".
+
+Pulls active NYC DOB Permit Issuance records (Socrata `ipu4-2q9a`)
+inside a polygon, filtered to recent New Building (NB), major
+Alteration (A1), and Demolition (DM) jobs. Each project is then
+cross-referenced against the static flood layers (Sandy 2012, DEP
+Stormwater scenarios) so the reconciler can write things like:
+
+  "12 active major construction projects in Gowanus. Of these,
+   8 sit inside the DEP Extreme-2080 stormwater scenario."
+
+The dataset uses separate gis_latitude / gis_longitude columns rather
+than a Socrata Point, so we bbox-filter via SoQL then do exact
+point-in-polygon containment client-side with shapely.
+"""
+from __future__ import annotations
+
+import logging
+from collections import Counter
+from dataclasses import asdict, dataclass
+from datetime import date, datetime, timedelta
+from typing import Any
+
+import geopandas as gpd
+import httpx
+from shapely.geometry import Point
+
+log = logging.getLogger("riprap.dob_permits")
+
+URL = "https://data.cityofnewyork.us/resource/ipu4-2q9a.json"
+DOC_ID = "dob_permits"
+CITATION = ("NYC DOB Permit Issuance (NYC OpenData ipu4-2q9a) — "
+            "issued/in-progress construction permits")
+
+JOB_TYPE_LABELS = {
+    "NB": "new building",
+    "A1": "major alteration (use/occupancy)",
+    "A2": "minor alteration",
+    "A3": "minor work / interior",
+    "DM": "demolition",
+    "SG": "sign",
+    "PL": "plumbing",
+    "EQ": "equipment",
+}
+
+# Default filter: focus on "what are they building" — new construction,
+# major alterations, demolitions. Skip minor mechanical permits.
+DEFAULT_JOB_TYPES = ("NB", "A1", "DM")
+
+
+@dataclass
+class Permit:
+    job_id: str
+    job_type: str
+    job_type_label: str
+    permit_status: str
+    issuance_date: str
+    expiration_date: str | None
+    address: str
+    borough: str
+    bbl: str | None
+    lat: float
+    lon: float
+    owner_business: str | None
+    permittee_business: str | None
+    nta_name: str | None
+
+
+def permits_in_bbox(min_lat: float, min_lon: float,
+                    max_lat: float, max_lon: float,
+                    job_types: tuple[str, ...] = DEFAULT_JOB_TYPES,
+                    since: date | None = None,
+                    limit: int = 5000) -> list[Permit]:
+    """Pull DOB permits intersecting a bounding box, recently issued, with
+    matching job types. We expand from polygon to bbox and rely on the
+    caller to do exact point-in-polygon filtering."""
+    if since is None:
+        since = date.today() - timedelta(days=540)  # ~18 months
+    # gis_latitude/gis_longitude are stored as text in this dataset; cast
+    # to number for the bbox compare. issuance_date is a floating timestamp
+    # surfaced as 'MM/DD/YYYY' string — cast explicitly to floating_timestamp
+    # so the comparator parses ISO dates correctly. BETWEEN is picky on text
+    # columns, so use explicit >= / <= operators.
+    where = (
+        f"job_type IN ({','.join(repr(t) for t in job_types)})"
+        f" AND issuance_date::floating_timestamp >= '{since.isoformat()}'"
+        f" AND gis_latitude::number >= {min_lat}"
+        f" AND gis_latitude::number <= {max_lat}"
+        f" AND gis_longitude::number >= {min_lon}"
+        f" AND gis_longitude::number <= {max_lon}"
+    )
+    r = httpx.get(URL, params={
+        "$select": ",".join([
+            "job__", "job_type", "permit_status", "issuance_date",
+            "expiration_date", "house__", "street_name", "borough",
+            "block", "lot",
+            "gis_latitude", "gis_longitude", "owner_s_business_name",
+            "permittee_s_business_name", "gis_nta_name",
+        ]),
+        "$where": where,
+        "$order": "issuance_date desc",
+        "$limit": str(limit),
+    }, timeout=60)
+    r.raise_for_status()
+    out: list[Permit] = []
+    for row in r.json():
+        try:
+            lat = float(row["gis_latitude"])
+            lon = float(row["gis_longitude"])
+        except (KeyError, ValueError, TypeError):
+            continue
+        addr = " ".join(filter(None, [
+            row.get("house__"),
+            (row.get("street_name") or "").title(),
+        ])).strip()
+        # DOB has no `bbl` column; compose from borough + block + lot.
+        # Borough codes: MAN=1, BX=2, BK=3, QN=4, SI=5.
+        boro_code = {"MANHATTAN": "1", "BRONX": "2", "BROOKLYN": "3",
+                     "QUEENS": "4", "STATEN ISLAND": "5"}.get(
+                     (row.get("borough") or "").upper())
+        block = (row.get("block") or "").lstrip("0")
+        lot = (row.get("lot") or "").lstrip("0")
+        bbl = (f"{boro_code}-{block.zfill(5)}-{lot.zfill(4)}"
+               if boro_code and block and lot else None)
+        out.append(Permit(
+            job_id=row.get("job__", ""),
+            job_type=row.get("job_type", ""),
+            job_type_label=JOB_TYPE_LABELS.get(row.get("job_type", ""), row.get("job_type", "")),
+            permit_status=row.get("permit_status", ""),
+            issuance_date=(row.get("issuance_date") or "")[:10],
+            expiration_date=(row.get("expiration_date") or "")[:10] or None,
+            address=addr,
+            borough=(row.get("borough") or "").title(),
+            bbl=bbl,
+            lat=lat,
+            lon=lon,
+            owner_business=row.get("owner_s_business_name"),
+            permittee_business=row.get("permittee_s_business_name"),
+            nta_name=row.get("gis_nta_name"),
+        ))
+    return out
+
+
+def permits_in_polygon(polygon, polygon_crs: str = "EPSG:4326",
+                       job_types: tuple[str, ...] = DEFAULT_JOB_TYPES,
+                       since: date | None = None) -> list[Permit]:
+    """Permits inside a polygon. Uses bbox prefilter + shapely contains."""
+    g = gpd.GeoDataFrame(geometry=[polygon], crs=polygon_crs).to_crs("EPSG:4326")
+    geom = g.iloc[0].geometry
+    minx, miny, maxx, maxy = geom.bounds
+    raw = permits_in_bbox(miny, minx, maxy, maxx, job_types=job_types, since=since)
+    out: list[Permit] = []
+    for p in raw:
+        pt = Point(p.lon, p.lat)
+        if geom.contains(pt) or geom.intersects(pt):
+            out.append(p)
+    # Dedupe by job_id (one job can have multiple permits as work proceeds)
+    seen: dict[str, Permit] = {}
+    for p in out:
+        # Keep the most-recently-issued permit per job
+        cur = seen.get(p.job_id)
+        if cur is None or (p.issuance_date or "") > (cur.issuance_date or ""):
+            seen[p.job_id] = p
+    return list(seen.values())
+
+
+def cross_reference_flood(permits: list[Permit]) -> list[dict[str, Any]]:
+    """Tag each permit with which flood layers cover its point.
+    Adds: in_sandy (bool), dep_class (highest depth class hit across DEP scenarios),
+    dep_scenarios (list of scenario ids that fired)."""
+    if not permits:
+        return []
+    from app.flood_layers import dep_stormwater, sandy_inundation
+    pts = gpd.GeoDataFrame(
+        geometry=[Point(p.lon, p.lat) for p in permits],
+        crs="EPSG:4326",
+    ).to_crs("EPSG:2263")
+    pts["_pid"] = list(range(len(pts)))
+
+    sandy_flags = sandy_inundation.join(pts).reset_index(drop=True).tolist()
+
+    dep_hits = {scen: dep_stormwater.join(pts, scen)["depth_class"].astype(int).tolist()
+                for scen in ("dep_extreme_2080", "dep_moderate_2050", "dep_moderate_current")}
+
+    out = []
+    for i, p in enumerate(permits):
+        scen_hits = {s: dep_hits[s][i] for s in dep_hits}
+        max_class = max(scen_hits.values(), default=0)
+        active_scens = [s for s, c in scen_hits.items() if c > 0]
+        out.append({
+            **asdict(p),
+            "in_sandy":      bool(sandy_flags[i]),
+            "dep_max_class": max_class,
+            "dep_scenarios": active_scens,
+            "any_flood_layer_hit": bool(sandy_flags[i] or max_class > 0),
+        })
+    return out
+
+
+def summary_for_polygon(polygon, polygon_crs: str = "EPSG:4326",
+                        since_days: int = 540,
+                        top_n: int = 8) -> dict:
+    """Full polygon-mode summary: list active permits, cross-reference each
+    with flood layers, return aggregate counts + a top-N projects-of-concern
+    list (those that hit at least one flood layer, ranked by max DEP class
+    + Sandy hit)."""
+    since = date.today() - timedelta(days=since_days)
+    permits = permits_in_polygon(polygon, polygon_crs=polygon_crs, since=since)
+    enriched = cross_reference_flood(permits)
+
+    by_type: Counter = Counter(e["job_type_label"] for e in enriched)
+    by_status: Counter = Counter(e["permit_status"] for e in enriched)
+    n_total = len(enriched)
+    n_sandy = sum(1 for e in enriched if e["in_sandy"])
+    n_dep_any = sum(1 for e in enriched if e["dep_max_class"] > 0)
+    n_dep_severe = sum(1 for e in enriched if e["dep_max_class"] >= 2)
+    n_any_flood = sum(1 for e in enriched if e["any_flood_layer_hit"])
+
+    # Rank: severity = (in_sandy * 3) + dep_max_class
+    def severity(e):
+        return (3 if e["in_sandy"] else 0) + e["dep_max_class"]
+    flagged = sorted(
+        [e for e in enriched if e["any_flood_layer_hit"]],
+        key=severity, reverse=True,
+    )[:top_n]
+
+    # Light projection of every permit for map pinning (no need to ship the
+    # full permit record for the not-flagged ones — the map only needs lat,
+    # lon, address, job_type_label, and the flood-flag fields).
+    all_pins = [
+        {
+            "lat":           e["lat"],
+            "lon":           e["lon"],
+            "address":       e["address"],
+            "job_type":      e["job_type"],
+            "in_sandy":      e["in_sandy"],
+            "dep_max_class": e["dep_max_class"],
+            "any_flood":     e["any_flood_layer_hit"],
+        }
+        for e in enriched
+    ]
+    return {
+        "since":           since.isoformat(),
+        "n_total":         n_total,
+        "n_in_sandy":      n_sandy,
+        "n_in_dep_any":    n_dep_any,
+        "n_in_dep_severe": n_dep_severe,
+        "n_any_flood":     n_any_flood,
+        "by_job_type":     dict(by_type.most_common()),
+        "by_permit_status":dict(by_status.most_common()),
+        "flagged_top":     flagged,
+        "all_pins":        all_pins,
+        "all_count":       n_total,
+    }
+
+
+def now_iso() -> str:
+    return datetime.utcnow().date().isoformat()

app/context/eo_chip_cache.py

@@ -0,0 +1,345 @@
+"""Per-query EO chip cache — Sentinel-2 L2A, Sentinel-1 RTC, DEM.
+
+Fetches a co-registered (S2L2A, S1RTC, DEM) chip centered on (lat, lon)
+and returns a dict of torch tensors ready for TerraMind-NYC inference.
+The TerraMind base was trained with `temporal_n_timestamps=4`, so this
+helper expands a single S2/S1 acquisition to T=4 by repetition along
+the temporal axis. Single-timestep nowcasting trades some training-
+distribution match for a much simpler runtime — the published LoRA
+adapters still produce sensible argmax masks at T=1 / tiled.
+
+Failure semantics mirror prithvi_live: every dependency or network
+failure is converted to a clean `{ok: False, skipped: <reason>}`
+result, never a raised exception. Callers (FSM specialists) that
+chain off the chip can short-circuit on `ok=False` and skip the
+specialist instead of surfacing a noisy error.
+"""
+from __future__ import annotations
+
+import concurrent.futures
+import logging
+import os
+import threading
+import time
+from typing import Any
+
+log = logging.getLogger("riprap.eo_chip_cache")
+
+ENABLE = os.environ.get("RIPRAP_EO_CHIP_ENABLE", "1").lower() in ("1", "true", "yes")
+SEARCH_DAYS = int(os.environ.get("RIPRAP_EO_CHIP_SEARCH_DAYS", "120"))
+MAX_CLOUD_PCT = float(os.environ.get("RIPRAP_EO_CHIP_MAX_CLOUD", "30"))
+CHIP_PX = int(os.environ.get("RIPRAP_EO_CHIP_PX", "224"))
+PIXEL_M = 10
+N_TIMESTEPS = 4
+
+# 12-band S2 L2A in TerraMind's expected order.
+S2_BANDS = ["B01", "B02", "B03", "B04", "B05", "B06", "B07",
+            "B08", "B8A", "B09", "B11", "B12"]
+
+# Sentinel-1 RTC on Planetary Computer publishes vv/vh polarisations.
+S1_BANDS = ["vv", "vh"]
+
+
+def _has_required_deps() -> tuple[bool, str | None]:
+    missing: list[str] = []
+    for name in ("planetary_computer", "pystac_client",
+                 "rioxarray", "xarray", "torch", "numpy"):
+        try:
+            __import__(name)
+        except ImportError:
+            missing.append(name)
+    if missing:
+        return False, ", ".join(missing)
+    return True, None
+
+
+_DEPS_OK, _DEPS_MISSING = _has_required_deps()
+_FETCH_LOCK = threading.Lock()
+
+
+def _search_s2(lat: float, lon: float):
+    """Return (item, cloud_cover) for the most recent low-cloud S2L2A
+    acquisition near (lat, lon), or (None, None) if no scene exists."""
+    import datetime as dt
+
+    import planetary_computer as pc
+    from pystac_client import Client
+    end = dt.datetime.utcnow().date()
+    start = end - dt.timedelta(days=SEARCH_DAYS)
+    client = Client.open(
+        "https://planetarycomputer.microsoft.com/api/stac/v1",
+        modifier=pc.sign_inplace,
+    )
+    delta = 0.02
+    search = client.search(
+        collections=["sentinel-2-l2a"],
+        bbox=[lon - delta, lat - delta, lon + delta, lat + delta],
+        datetime=f"{start}/{end}",
+        query={"eo:cloud_cover": {"lt": MAX_CLOUD_PCT}},
+        max_items=20,
+    )
+    items = sorted(
+        search.items(),
+        key=lambda it: (it.properties.get("eo:cloud_cover", 100),
+                        -(it.datetime.timestamp() if it.datetime else 0)),
+    )
+    if not items:
+        return None, None
+    item = items[0]
+    cc = float(item.properties.get("eo:cloud_cover", -1))
+    return item, cc
+
+
+def _search_s1(item_dt, lat: float, lon: float):
+    """Return the closest Sentinel-1 RTC acquisition to the given S2
+    datetime, or None if Planetary Computer has nothing nearby."""
+    import datetime as dt
+
+    import planetary_computer as pc
+    from pystac_client import Client
+    win = dt.timedelta(days=10)
+    start = item_dt - win
+    end = item_dt + win
+    client = Client.open(
+        "https://planetarycomputer.microsoft.com/api/stac/v1",
+        modifier=pc.sign_inplace,
+    )
+    delta = 0.02
+    search = client.search(
+        collections=["sentinel-1-rtc"],
+        bbox=[lon - delta, lat - delta, lon + delta, lat + delta],
+        datetime=f"{start.isoformat()}/{end.isoformat()}",
+        max_items=10,
+    )
+    items = list(search.items())
+    if not items:
+        return None
+    items.sort(key=lambda it:
+               abs((it.datetime - item_dt).total_seconds())
+               if it.datetime else 1e18)
+    return items[0]
+
+
+def _read_band(href, bbox_xy_meters, epsg):
+    """Read a single COG band, clipped to the bbox, and resample to
+    CHIP_PX × CHIP_PX. Returns a numpy array (CHIP_PX, CHIP_PX) float32.
+    """
+    import numpy as np
+    import rioxarray  # noqa: F401
+    da = rioxarray.open_rasterio(href, masked=False).squeeze(drop=True)
+    da = da.rio.clip_box(minx=bbox_xy_meters[0], miny=bbox_xy_meters[1],
+                          maxx=bbox_xy_meters[2], maxy=bbox_xy_meters[3])
+    if da.shape[-2] != CHIP_PX or da.shape[-1] != CHIP_PX:
+        # Resample (nearest is fine for the 10/20/60 m S2 mix; S1 is 10 m,
+        # DEM is 30 m and benefits from bilinear; we keep nearest for
+        # simplicity — the TerraMind LoRA was trained against terratorch's
+        # default resampler which is also nearest).
+        da = da.rio.reproject(
+            f"EPSG:{epsg}", shape=(CHIP_PX, CHIP_PX), resampling=0
+        )
+    arr = da.values.astype("float32")
+    return np.nan_to_num(arr)
+
+
+def _fetch_modalities(lat: float, lon: float, timeout_s: float = 60.0) -> dict[str, Any]:
+    """Fetch S2L2A + S1RTC + DEM as numpy arrays, resampled to a common
+    CHIP_PX × CHIP_PX grid centered on (lat, lon).
+    """
+    import numpy as np
+    from pyproj import Transformer
+
+    t0 = time.time()
+    item, cc = _search_s2(lat, lon)
+    if item is None:
+        return {"ok": False,
+                "skipped": f"no <{MAX_CLOUD_PCT}% cloud S2 in last "
+                           f"{SEARCH_DAYS}d"}
+    if "proj:epsg" in item.properties:
+        epsg = int(item.properties["proj:epsg"])
+    else:
+        code = item.properties.get("proj:code", "")
+        if not code.startswith("EPSG:"):
+            return {"ok": False,
+                    "skipped": "STAC item missing proj:epsg / proj:code"}
+        epsg = int(code.split(":", 1)[1])
+
+    fwd = Transformer.from_crs("EPSG:4326", f"EPSG:{epsg}", always_xy=True)
+    cx, cy = fwd.transform(lon, lat)
+    half_m = CHIP_PX / 2 * PIXEL_M
+    bbox = (cx - half_m, cy - half_m, cx + half_m, cy + half_m)
+
+    if time.time() - t0 > timeout_s:
+        return {"ok": False, "skipped": "STAC search exceeded budget"}
+
+    # ---- S2L2A: 12 bands ------------------------------------------------
+    s2_arrs = []
+    try:
+        for b in S2_BANDS:
+            href = item.assets[b].href
+            s2_arrs.append(_read_band(href, bbox, epsg))
+    except Exception as e:
+        log.warning("eo_chip: S2 band fetch failed (%s); aborting", e)
+        return {"ok": False, "err": f"S2 fetch failed: {type(e).__name__}: {e}"}
+    s2 = np.stack(s2_arrs)  # (12, H, W)
+    if s2.mean() > 1.0:
+        s2 = s2 / 10000.0  # scale L2A reflectance from int16 to ~[0, 1]
+
+    # ---- S1RTC: 2 polarisations (best effort) ---------------------------
+    s1: np.ndarray | None = None
+    s1_meta: dict[str, Any] = {}
+    if time.time() - t0 < timeout_s:
+        try:
+            s1_item = _search_s1(item.datetime, lat, lon)
+            if s1_item is not None:
+                s1_arrs = []
+                for b in S1_BANDS:
+                    href = s1_item.assets[b].href
+                    s1_arrs.append(_read_band(href, bbox, epsg))
+                s1 = np.stack(s1_arrs)
+                s1_meta = {
+                    "scene_id": s1_item.id,
+                    "datetime": (s1_item.datetime.isoformat()
+                                 if s1_item.datetime else None),
+                }
+        except Exception as e:
+            log.warning("eo_chip: S1 fetch best-effort failed: %s", e)
+
+    # ---- DEM: Copernicus 30 m via planetary_computer (best effort) ------
+    dem: np.ndarray | None = None
+    if time.time() - t0 < timeout_s:
+        try:
+            import planetary_computer as pc
+            from pystac_client import Client
+            client = Client.open(
+                "https://planetarycomputer.microsoft.com/api/stac/v1",
+                modifier=pc.sign_inplace,
+            )
+            dem_search = client.search(
+                collections=["cop-dem-glo-30"],
+                bbox=[lon - 0.02, lat - 0.02, lon + 0.02, lat + 0.02],
+                max_items=1,
+            )
+            dem_items = list(dem_search.items())
+            if dem_items:
+                href = dem_items[0].assets["data"].href
+                dem = _read_band(href, bbox, epsg)
+                dem = dem[None, :, :]  # add channel dim
+        except Exception as e:
+            log.warning("eo_chip: DEM fetch best-effort failed: %s", e)
+
+    return {
+        "ok": True,
+        "lat": lat, "lon": lon,
+        "epsg": epsg, "chip_px": CHIP_PX, "pixel_m": PIXEL_M,
+        "s2": s2, "s1": s1, "dem": dem,
+        "s2_meta": {
+            "scene_id": item.id,
+            "datetime": (item.datetime.isoformat() if item.datetime else None),
+            "cloud_cover": cc,
+        },
+        "s1_meta": s1_meta,
+        "elapsed_s": round(time.time() - t0, 2),
+    }
+
+
+def _to_terramind_tensors(modalities: dict[str, Any]) -> dict[str, Any]:
+    """Shape numpy modality arrays into the (B, C, T, H, W) tensors
+    TerraMind expects with `temporal_n_timestamps=4`. Single-timestep
+    fetches get tiled to T=4 — same observation in every slot.
+    """
+    import torch
+    s2 = modalities["s2"]  # (12, H, W)
+    s2_t = torch.from_numpy(s2).float().unsqueeze(1)  # (12, 1, H, W)
+    s2_t = s2_t.repeat(1, N_TIMESTEPS, 1, 1).unsqueeze(0)  # (1, 12, T, H, W)
+    chips = {"S2L2A": s2_t}
+    if modalities.get("s1") is not None:
+        s1 = modalities["s1"]  # (2, H, W)
+        s1_t = torch.from_numpy(s1).float().unsqueeze(1)
+        s1_t = s1_t.repeat(1, N_TIMESTEPS, 1, 1).unsqueeze(0)
+        chips["S1RTC"] = s1_t
+    if modalities.get("dem") is not None:
+        dem = modalities["dem"]  # (1, H, W)
+        dem_t = torch.from_numpy(dem).float().unsqueeze(1)
+        dem_t = dem_t.repeat(1, N_TIMESTEPS, 1, 1).unsqueeze(0)
+        chips["DEM"] = dem_t
+    return chips
+
+
+def _fetch_and_build(lat: float, lon: float, timeout_s: float) -> dict[str, Any]:
+    """Inner fetch + tensor build, run inside a bounded thread."""
+    with _FETCH_LOCK:
+        try:
+            modalities = _fetch_modalities(lat, lon, timeout_s=timeout_s)
+        except Exception as e:
+            log.exception("eo_chip: fetch failed")
+            return {"ok": False, "err": f"{type(e).__name__}: {e}"}
+        if not modalities.get("ok"):
+            return modalities
+        try:
+            modalities["tensors"] = _to_terramind_tensors(modalities)
+        except Exception as e:
+            log.exception("eo_chip: tensor build failed")
+            return {"ok": False,
+                    "err": f"tensor build failed: {type(e).__name__}: {e}"}
+        # Compute the chip's WGS84 bbox so downstream TerraMind specialists
+        # can polygonise their predictions onto the map. The chip is
+        # CHIP_PX × CHIP_PX at PIXEL_M (10 m) in the scene's UTM zone;
+        # reproject the four corners to EPSG:4326 and use the
+        # axis-aligned envelope.
+        try:
+            from pyproj import Transformer
+            half_m = (CHIP_PX * PIXEL_M) / 2.0
+            t_to_utm = Transformer.from_crs(
+                "EPSG:4326", f"EPSG:{modalities['epsg']}", always_xy=True)
+            t_to_4326 = Transformer.from_crs(
+                f"EPSG:{modalities['epsg']}", "EPSG:4326", always_xy=True)
+            cx, cy = t_to_utm.transform(lon, lat)
+            corners_utm = [
+                (cx - half_m, cy - half_m),
+                (cx - half_m, cy + half_m),
+                (cx + half_m, cy - half_m),
+                (cx + half_m, cy + half_m),
+            ]
+            corners_ll = [t_to_4326.transform(x, y) for x, y in corners_utm]
+            lons = [c[0] for c in corners_ll]
+            lats = [c[1] for c in corners_ll]
+            modalities["bounds_4326"] = (
+                min(lons), min(lats), max(lons), max(lats))
+        except Exception:
+            log.exception("eo_chip: bounds_4326 reprojection failed")
+        return modalities
+
+
+def fetch(lat: float, lon: float, timeout_s: float = 60.0) -> dict[str, Any]:
+    """Run the chip pipeline. Always returns a dict with at minimum
+    `{ok, skipped|err, ...}`; on success the dict carries the
+    co-registered numpy arrays plus `tensors` (the TerraMind-shaped
+    torch dict).
+
+    Runs in a daemon thread so that STAC searches and COG band downloads
+    (which use requests/rioxarray without per-call timeouts) are bounded
+    by a hard wall-clock deadline even when the network hangs.
+    """
+    if not ENABLE:
+        return {"ok": False, "skipped": "RIPRAP_EO_CHIP_ENABLE=0"}
+    if not _DEPS_OK:
+        return {"ok": False,
+                "skipped": f"deps unavailable on this deployment: "
+                           f"{_DEPS_MISSING}"}
+    # Hard wall-clock cap: pystac_client / rioxarray COG reads don't expose
+    # uniform per-request timeouts, so we bound the whole pipeline here.
+    hard_timeout = timeout_s + 15.0
+    # Propagate the parent thread's emissions tracker into the worker so
+    # any inference._post calls made inside _fetch_and_build are recorded.
+    from app import emissions as _emissions
+    _parent_tracker = _emissions.current()
+    with concurrent.futures.ThreadPoolExecutor(
+        max_workers=1,
+        initializer=lambda t=_parent_tracker: _emissions.install(t),
+    ) as pool:
+        future = pool.submit(_fetch_and_build, lat, lon, timeout_s)
+        try:
+            return future.result(timeout=hard_timeout)
+        except concurrent.futures.TimeoutError:
+            log.warning("eo_chip: hard timeout after %.0fs (STAC/COG hung)", hard_timeout)
+            return {"ok": False, "skipped": f"eo_chip timed out after {hard_timeout:.0f}s"}

app/context/floodnet.py

@@ -0,0 +1,148 @@
+"""FloodNet NYC — live ultrasonic flood sensor network.
+
+Hasura GraphQL endpoint, no auth, ~350 sensors. Used for:
+  - sensors_near(lat, lon, radius_m) → list of deployments
+  - flood_events_for(deployment_ids, since) → labeled flood events per sensor
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+import httpx
+
+URL = "https://api.floodnet.nyc/v1/graphql"
+DOC_ID = "floodnet"
+CITATION = "FloodNet NYC ultrasonic depth sensors (api.floodnet.nyc)"
+
+
+@dataclass
+class Sensor:
+    deployment_id: str
+    name: str
+    street: str
+    borough: str
+    status: str
+    deployed_at: str | None
+    lat: float | None = None
+    lon: float | None = None
+
+
+@dataclass
+class FloodEvent:
+    deployment_id: str
+    start_time: str
+    end_time: str | None
+    max_depth_mm: int | None
+    label: str | None
+
+
+def _gql(query: str, variables: dict[str, Any]) -> dict:
+    r = httpx.post(URL, json={"query": query, "variables": variables},
+                   timeout=20, verify=False)
+    r.raise_for_status()
+    j = r.json()
+    if "errors" in j:
+        raise RuntimeError(f"FloodNet GraphQL error: {j['errors']}")
+    return j["data"]
+
+
+_NEAR_Q = """
+query Near($lat: Float!, $lon: Float!, $r: Float!) {
+  deployments_within_radius(args:{lat:$lat, lon:$lon, radius_meters:$r},
+                            order_by:{date_deployed: asc}) {
+    deployment_id
+    name
+    sensor_address_street
+    sensor_address_borough
+    sensor_status
+    date_deployed
+    location
+  }
+}"""
+
+
+def _parse_location(loc) -> tuple[float | None, float | None]:
+    """Hasura PostGIS geometry returned as a GeoJSON object."""
+    if not loc or not isinstance(loc, dict):
+        return None, None
+    coords = loc.get("coordinates")
+    if not coords or len(coords) < 2:
+        return None, None
+    return coords[1], coords[0]  # (lat, lon) from (lon, lat)
+
+
+def sensors_near(lat: float, lon: float, radius_m: float = 1000) -> list[Sensor]:
+    d = _gql(_NEAR_Q, {"lat": lat, "lon": lon, "r": radius_m})
+    out = []
+    for row in d["deployments_within_radius"]:
+        slat, slon = _parse_location(row.get("location"))
+        out.append(Sensor(
+            deployment_id=row["deployment_id"],
+            name=row["name"] or "",
+            street=row.get("sensor_address_street") or "",
+            borough=row.get("sensor_address_borough") or "",
+            status=row.get("sensor_status") or "",
+            deployed_at=row.get("date_deployed"),
+            lat=slat,
+            lon=slon,
+        ))
+    return out
+
+
+_EVENTS_Q = """
+query Events($ids: [String!], $since: timestamp!) {
+  sensor_events(where:{
+      deployment_id:{_in:$ids},
+      start_time:{_gte:$since},
+      label:{_eq:"flood"}
+  }, order_by:{start_time: desc}, limit: 200) {
+    deployment_id
+    start_time
+    end_time
+    max_depth_proc_mm
+    label
+  }
+}"""
+
+
+def flood_events_for(deployment_ids: list[str],
+                     since: datetime | None = None) -> list[FloodEvent]:
+    if not deployment_ids:
+        return []
+    if since is None:
+        since = datetime.now(timezone.utc) - timedelta(days=365 * 3)
+    d = _gql(_EVENTS_Q, {
+        "ids": deployment_ids,
+        "since": since.isoformat(timespec="seconds").replace("+00:00", ""),
+    })
+    return [
+        FloodEvent(
+            deployment_id=row["deployment_id"],
+            start_time=row["start_time"],
+            end_time=row.get("end_time"),
+            max_depth_mm=row.get("max_depth_proc_mm"),
+            label=row.get("label"),
+        )
+        for row in d["sensor_events"]
+    ]
+
+
+def summary_for_point(lat: float, lon: float, radius_m: float = 600) -> dict:
+    """One-shot summary used by the FSM node and the cited paragraph."""
+    sensors = sensors_near(lat, lon, radius_m)
+    ids = [s.deployment_id for s in sensors]
+    events = flood_events_for(ids)
+    by_dep: dict[str, list[FloodEvent]] = {}
+    for e in events:
+        by_dep.setdefault(e.deployment_id, []).append(e)
+    peak = max((e for e in events if e.max_depth_mm is not None),
+               key=lambda e: e.max_depth_mm or 0, default=None)
+    return {
+        "n_sensors": len(sensors),
+        "sensors": [vars(s) for s in sensors],
+        "n_flood_events_3y": len(events),
+        "n_sensors_with_events": len(by_dep),
+        "peak_event": vars(peak) if peak else None,
+    }

app/context/gliner_extract.py

@@ -0,0 +1,147 @@
+"""GLiNER (urchade/gliner_medium-v2.1) typed-entity extraction over the
+RAG retriever's top paragraphs.
+
+Adds structured fields to the reconciler's grounding context. For each
+RAG chunk the specialist emits, GLiNER produces a list of typed spans
+with one of five labels:
+
+    nyc_location          (e.g. "Coney Island")
+    dollar_amount         (e.g. "$5.6 million")
+    date_range            (e.g. "fiscal year 2025-2027")
+    agency                (e.g. "NYC DEP")
+    infrastructure_project (e.g. "Bluebelt expansion")
+
+The doc_id for emission is `gliner_<source>` where `<source>` is the
+RAG chunk's doc_id stripped of its `rag_` prefix. So `rag_comptroller`
+becomes `gliner_comptroller`. The reconciler can then cite typed
+fields with `[gliner_comptroller]`.
+
+License: Apache-2.0 — `urchade/gliner_medium-v2.1` (NOT the
+`gliner_base` variant, which is CC-BY-NC-4.0). See
+experiments/shared/licenses.md.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+
+log = logging.getLogger("riprap.gliner")
+
+ENTITY_LABELS = [
+    "nyc_location",
+    "dollar_amount",
+    "date_range",
+    "agency",
+    "infrastructure_project",
+]
+
+DEFAULT_THRESHOLD = float(os.environ.get("RIPRAP_GLINER_THRESHOLD", "0.45"))
+MODEL_NAME = os.environ.get("RIPRAP_GLINER_MODEL", "urchade/gliner_medium-v2.1")
+ENABLE = os.environ.get("RIPRAP_GLINER_ENABLE", "1").lower() in ("1", "true", "yes")
+
+_MODEL = None  # lazy
+
+
+@dataclass
+class Extraction:
+    label: str
+    text: str
+    score: float
+
+
+def _ensure_model():
+    """Lazy GLiNER load. Returns None if disabled or load fails so
+    callers can silently fall back to no-op."""
+    global _MODEL
+    if not ENABLE:
+        return None
+    if _MODEL is not None:
+        return _MODEL
+    try:
+        from gliner import GLiNER
+        log.info("gliner: loading %s", MODEL_NAME)
+        _MODEL = GLiNER.from_pretrained(MODEL_NAME)
+    except Exception:
+        log.exception("gliner: load failed; specialist will no-op")
+        _MODEL = False  # sentinel
+    return _MODEL or None
+
+
+def warm():
+    _ensure_model()
+
+
+def _source_short(rag_doc_id: str) -> str:
+    """`rag_comptroller` -> `comptroller`. Anything not prefixed `rag_`
+    passes through unchanged."""
+    return rag_doc_id[4:] if rag_doc_id.startswith("rag_") else rag_doc_id
+
+
+def extract_for_chunk(text: str, threshold: float = DEFAULT_THRESHOLD) -> list[Extraction]:
+    if not text:
+        return []
+
+    # v0.4.5 — try the MI300X service first. The remote handles its
+    # own GLiNER load; this lets cpu-basic surfaces run typed
+    # extraction without baking gliner into the image.
+    try:
+        from app import inference as _inf
+        if _inf.remote_enabled():
+            remote = _inf.gliner_extract(text, ENTITY_LABELS)
+            if remote.get("ok"):
+                return [
+                    Extraction(label=e["label"], text=e["text"],
+                               score=float(e.get("score", 0)))
+                    for e in remote.get("entities", [])
+                    if e.get("score", 0) >= threshold
+                ]
+    except _inf.RemoteUnreachable as e:
+        log.info("gliner: remote unreachable (%s); local fallback", e)
+    except Exception:
+        log.exception("gliner: remote call failed; local fallback")
+
+    model = _ensure_model()
+    if model is None:
+        return []
+    raw = model.predict_entities(text, ENTITY_LABELS, threshold=threshold)
+    return [Extraction(label=r["label"], text=r["text"],
+                       score=float(r["score"])) for r in raw]
+
+
+def extract_for_rag_hits(hits: list[dict],
+                         threshold: float = DEFAULT_THRESHOLD,
+                         max_hits: int = 3) -> dict[str, dict]:
+    """Run GLiNER on the top-`max_hits` RAG hits. Returns a dict keyed by
+    short source id (e.g. "comptroller") with the structured payload
+    that the FSM stores into state["gliner"] and that
+    reconcile.build_documents() consumes."""
+    out: dict[str, dict] = {}
+    if not hits:
+        return out
+    for h in hits[:max_hits]:
+        source = _source_short(h.get("doc_id", "rag_unknown"))
+        ents = extract_for_chunk(h.get("text", ""), threshold=threshold)
+        if not ents:
+            continue
+        # Dedup verbatim repeats (common in agency PDFs that repeat
+        # "DEP" 13 times in a methodology section).
+        seen = set()
+        deduped: list[Extraction] = []
+        for e in ents:
+            key = (e.label, e.text.lower())
+            if key in seen:
+                continue
+            seen.add(key)
+            deduped.append(e)
+        out[source] = {
+            "rag_doc_id": h.get("doc_id"),
+            "title": h.get("title"),
+            "paragraph_excerpt": h.get("text", "")[:240]
+            + ("…" if len(h.get("text", "")) > 240 else ""),
+            "n_entities": len(deduped),
+            "entities": [{"label": e.label, "text": e.text,
+                          "score": round(e.score, 3)} for e in deduped],
+        }
+    return out

app/context/microtopo.py

@@ -0,0 +1,274 @@
+"""LiDAR/DEM-derived micro-topography specialist.
+
+Reads a window from a precomputed NYC-wide DEM (data/nyc_dem_30m.tif)
+fetched from USGS 3DEP via py3dep. Computes per-address terrain numbers
+that the static FEMA/DEP scenario maps don't expose.
+
+Metrics (all derived from the same small AOI raster):
+
+    point_elev_m          elevation at the address (m)
+    rel_elev_pct_750m     percentile of point elev in a 750-m radius
+    rel_elev_pct_200m     percentile of point elev in a 200-m radius
+                          (block-scale "is this a bowl?")
+    basin_relief_m        max-elev in 750-m AOI minus point elev
+    aoi_min_m, aoi_max_m  for context
+    resolution_m
+
+We deliberately stop at "shape-of-the-terrain" metrics rather than full
+hydrology — depression-fill / D8 flow accumulation on a flat coastal
+DEM are noisy and slow. Percentile + relief is what the reconciler
+actually needs to write a useful sentence.
+"""
+from __future__ import annotations
+
+import logging
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+warnings.filterwarnings("ignore")
+
+log = logging.getLogger("riprap.microtopo")
+
+DOC_ID = "microtopo"
+CITATION = "USGS 3DEP 30 m DEM (precomputed citywide GeoTIFF, WGS84)"
+
+DATA_DIR = Path(__file__).resolve().parent.parent.parent / "data"
+DEM_PATH = DATA_DIR / "nyc_dem_30m.tif"
+TWI_PATH = DATA_DIR / "twi.tif"
+HAND_PATH = DATA_DIR / "hand.tif"
+
+
+@dataclass
+class Microtopo:
+    point_elev_m: float
+    rel_elev_pct_750m: float    # 0..100
+    rel_elev_pct_200m: float    # 0..100
+    basin_relief_m: float
+    aoi_min_m: float
+    aoi_max_m: float
+    aoi_radius_m: int
+    resolution_m: int
+    # Hydrology indices computed on the same DEM (whitebox-workflows)
+    twi: float | None = None              # Topographic Wetness Index, ln(SCA / tan(slope))
+    hand_m: float | None = None           # Height Above Nearest Drainage (m)
+
+
+def _percentile_in_window(arr: np.ndarray, iy: int, ix: int, point_val: float,
+                          window_radius_cells: int) -> float:
+    H, W = arr.shape
+    y0 = max(0, iy - window_radius_cells)
+    y1 = min(H, iy + window_radius_cells + 1)
+    x0 = max(0, ix - window_radius_cells)
+    x1 = min(W, ix + window_radius_cells + 1)
+    sub = arr[y0:y1, x0:x1]
+    finite = sub[np.isfinite(sub)]
+    if finite.size == 0:
+        return float("nan")
+    return float((finite < point_val).sum()) / finite.size * 100.0
+
+
+_DEM_CACHE: dict = {}
+
+
+def _read_full_raster(path: Path) -> tuple[np.ndarray | None, dict | None]:
+    import rasterio
+    if not path.exists():
+        return None, None
+    with rasterio.open(path) as ds:
+        arr = ds.read(1).astype("float32")
+        nodata = ds.nodata
+        meta = {"H": ds.height, "W": ds.width,
+                "transform": ds.transform, "crs": ds.crs, "nodata": nodata}
+    if nodata is not None:
+        arr = np.where(arr == nodata, np.nan, arr)
+    return arr, meta
+
+
+def _load_dem():
+    """Read the precomputed NYC DEM + TWI + HAND rasters into memory.
+
+    All three are aligned (same grid, same transform). We hold them as
+    numpy arrays so per-query slicing is safe under threading.
+    """
+    if "arr" in _DEM_CACHE:
+        return _DEM_CACHE
+    arr, meta = _read_full_raster(DEM_PATH)
+    if arr is None:
+        log.warning("microtopo DEM not found at %s — run scripts/fetch_nyc_dem.py", DEM_PATH)
+        return None
+    twi, _   = _read_full_raster(TWI_PATH)
+    hand, _  = _read_full_raster(HAND_PATH)
+    _DEM_CACHE.update({
+        "arr": arr, "H": meta["H"], "W": meta["W"],
+        "transform": meta["transform"], "crs": meta["crs"],
+        "twi": twi, "hand": hand,
+    })
+    note = []
+    if twi is not None:  note.append(f"TWI {TWI_PATH.name}")
+    if hand is not None: note.append(f"HAND {HAND_PATH.name}")
+    log.info("microtopo: loaded NYC DEM %s (%dx%d, %s); aux: %s",
+             DEM_PATH.name, meta["H"], meta["W"], meta["crs"],
+             ", ".join(note) if note else "(none — algorithmic only)")
+    return _DEM_CACHE
+
+
+def warm():
+    _load_dem()
+
+
+def _row_col(transform, lat: float, lon: float) -> tuple[int, int]:
+    """Inverse-affine: WGS84 (lon,lat) -> raster (row, col).
+    Mirrors rasterio.transform.rowcol but without holding a dataset handle.
+    """
+    # Diagonal affine (north-up raster): x = a*col + c, y = e*row + f.
+    a, c = transform.a, transform.c
+    e, f = transform.e, transform.f
+    col = int(round((lon - c) / a))
+    row = int(round((lat - f) / e))
+    return row, col
+
+
+def microtopo_at(lat: float, lon: float, radius_m: int = 750) -> Microtopo | None:
+    state = _load_dem()
+    if state is None:
+        return None
+    arr_full = state["arr"]
+    transform = state["transform"]
+
+    try:
+        row, col = _row_col(transform, lat, lon)
+    except Exception as e:
+        log.warning("microtopo index failed: %s", e)
+        return None
+
+    res_m = abs(transform.a) * 111_000.0 * np.cos(np.radians(lat))
+    cells_radius = max(2, int(np.ceil(radius_m / max(res_m, 1.0))))
+
+    H, W = state["H"], state["W"]
+    y0 = max(0, row - cells_radius); y1 = min(H, row + cells_radius + 1)
+    x0 = max(0, col - cells_radius); x1 = min(W, col + cells_radius + 1)
+    if y1 <= y0 or x1 <= x0:
+        return None
+
+    arr = arr_full[y0:y1, x0:x1].copy()
+
+    iy = row - y0
+    ix = col - x0
+    if not (0 <= iy < arr.shape[0] and 0 <= ix < arr.shape[1]):
+        return None
+
+    point_elev = float(arr[iy, ix])
+    if not np.isfinite(point_elev):
+        for r in range(1, 6):
+            ya, yb = max(0, iy - r), min(arr.shape[0], iy + r + 1)
+            xa, xb = max(0, ix - r), min(arr.shape[1], ix + r + 1)
+            sub = arr[ya:yb, xa:xb]
+            if np.isfinite(sub).any():
+                point_elev = float(np.nanmean(sub))
+                break
+        else:
+            return None
+
+    finite = arr[np.isfinite(arr)]
+    if finite.size == 0:
+        return None
+    aoi_min = float(finite.min())
+    aoi_max = float(finite.max())
+
+    pct_750 = float((finite < point_elev).sum()) / finite.size * 100.0
+    cells_200m = max(1, int(round(200 / max(res_m, 1.0))))
+    pct_200 = _percentile_in_window(arr, iy, ix, point_elev, cells_200m)
+
+    twi_arr = state.get("twi")
+    hand_arr = state.get("hand")
+    twi_v: float | None = None
+    hand_v: float | None = None
+    if twi_arr is not None and 0 <= row < H and 0 <= col < W:
+        v = float(twi_arr[row, col])
+        twi_v = round(v, 2) if np.isfinite(v) else None
+    if hand_arr is not None and 0 <= row < H and 0 <= col < W:
+        v = float(hand_arr[row, col])
+        hand_v = round(v, 2) if np.isfinite(v) else None
+
+    return Microtopo(
+        point_elev_m=round(point_elev, 2),
+        rel_elev_pct_750m=round(pct_750, 1),
+        rel_elev_pct_200m=round(pct_200, 1),
+        basin_relief_m=round(aoi_max - point_elev, 2),
+        aoi_min_m=round(aoi_min, 2),
+        aoi_max_m=round(aoi_max, 2),
+        aoi_radius_m=radius_m,
+        resolution_m=int(round(res_m)),
+        twi=twi_v,
+        hand_m=hand_v,
+    )
+
+
+def microtopo_for_polygon(polygon, polygon_crs: str = "EPSG:4326") -> dict | None:
+    """Polygon-mode aggregation: distributional summary of the DEM/HAND/TWI
+    rasters clipped to the polygon. Returns medians + fraction of cells
+    in flood-prone bands. Used for neighborhood-mode queries."""
+    state = _load_dem()
+    if state is None:
+        return None
+    try:
+        import rasterio
+        from rasterio.mask import mask as rio_mask
+    except Exception:
+        return None
+    import geopandas as gpd
+
+    poly = gpd.GeoDataFrame(geometry=[polygon], crs=polygon_crs).to_crs("EPSG:4326")
+    geom = [poly.iloc[0].geometry.__geo_interface__]
+
+    def _stats(path: Path) -> dict | None:
+        if not path.exists():
+            return None
+        try:
+            with rasterio.open(path) as src:
+                clipped, _ = rio_mask(src, geom, crop=True, filled=False)
+                arr = clipped[0]
+                vals = arr.compressed() if hasattr(arr, "compressed") else arr.flatten()
+                vals = vals[np.isfinite(vals)]
+                if vals.size == 0:
+                    return None
+                return {
+                    "n_cells":   int(vals.size),
+                    "min":       float(np.min(vals)),
+                    "median":    float(np.median(vals)),
+                    "p10":       float(np.percentile(vals, 10)),
+                    "p90":       float(np.percentile(vals, 90)),
+                    "max":       float(np.max(vals)),
+                    "raw":       vals,
+                }
+        except Exception as e:
+            log.warning("polygon raster mask failed for %s: %r", path.name, e)
+            return None
+
+    elev = _stats(DEM_PATH)
+    hand = _stats(HAND_PATH)
+    twi = _stats(TWI_PATH)
+    if elev is None:
+        return None
+
+    # Fraction of polygon cells in canonical flood-prone bands
+    frac_hand_lt1 = (
+        round(float((hand["raw"] < 1.0).mean()), 4) if hand else None
+    )
+    frac_twi_gt10 = (
+        round(float((twi["raw"] > 10.0).mean()), 4) if twi else None
+    )
+    return {
+        "n_cells": elev["n_cells"],
+        "elev_min_m":     round(elev["min"], 2),
+        "elev_median_m":  round(elev["median"], 2),
+        "elev_p10_m":     round(elev["p10"], 2),
+        "elev_max_m":     round(elev["max"], 2),
+        "hand_median_m":  round(hand["median"], 2) if hand else None,
+        "twi_median":     round(twi["median"], 2) if twi else None,
+        "frac_hand_lt1":  frac_hand_lt1,
+        "frac_twi_gt10":  frac_twi_gt10,
+    }

app/context/noaa_tides.py

@@ -0,0 +1,110 @@
+"""NOAA CO-OPS Tides & Currents — live coastal water level.
+
+api.tidesandcurrents.noaa.gov, no auth, 6-min cadence.
+
+We pick the nearest of three NYC-region stations to the queried address:
+  - 8518750 The Battery, NY
+  - 8516945 Kings Point, NY (Long Island Sound entrance)
+  - 8531680 Sandy Hook, NJ (NY Harbor approach)
+
+The verified-water-level API returns instantaneous water elevation
+relative to MLLW (Mean Lower Low Water — the local tidal datum). To
+distinguish "high tide" from "storm surge" we also fetch the published
+predicted tide and report the residual.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import asin, cos, radians, sin, sqrt
+
+import httpx
+
+DOC_ID = "noaa_tides"
+CITATION = "NOAA CO-OPS Tides & Currents (api.tidesandcurrents.noaa.gov)"
+URL = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter"
+
+STATIONS = [
+    # (id, name, lat, lon)
+    # NYC harbor + Long Island Sound
+    ("8518750", "The Battery, NY",         40.7006, -74.0142),
+    ("8516945", "Kings Point, NY",         40.8103, -73.7649),
+    ("8531680", "Sandy Hook, NJ",          40.4669, -74.0094),
+    # Hudson tidal corridor (head-of-tide is Troy / Albany; Hudson is tidal
+    # all the way up to the Federal Lock at Troy)
+    ("8518995", "Albany, NY (Hudson)",     42.6469, -73.7464),
+    ("8518962", "Turkey Point Hudson, NY", 41.7569, -73.9433),
+    ("8519483", "West Point, NY",          41.3845, -73.9536),
+]
+
+
+@dataclass
+class TideReading:
+    station_id: str
+    station_name: str
+    distance_km: float
+    observed_ft: float | None      # current water level above MLLW
+    predicted_ft: float | None     # astronomical prediction at same instant
+    residual_ft: float | None      # observed - predicted (≈ storm surge)
+    obs_time: str | None
+    error: str | None = None
+
+
+def _haversine_km(lat1, lon1, lat2, lon2) -> float:
+    R = 6371.0
+    p1, p2 = radians(lat1), radians(lat2)
+    dp = radians(lat2 - lat1); dl = radians(lon2 - lon1)
+    a = sin(dp/2)**2 + cos(p1)*cos(p2)*sin(dl/2)**2
+    return 2 * R * asin(sqrt(a))
+
+
+def _nearest_station(lat: float, lon: float):
+    return min(STATIONS, key=lambda s: _haversine_km(lat, lon, s[2], s[3]))
+
+
+def _fetch(station_id: str, product: str) -> dict:
+    r = httpx.get(URL, params={
+        "date": "latest", "station": station_id, "product": product,
+        "datum": "MLLW", "units": "english", "time_zone": "lst_ldt",
+        "format": "json",
+    }, timeout=8.0)
+    r.raise_for_status()
+    return r.json()
+
+
+def reading_at(lat: float, lon: float) -> TideReading:
+    sid, name, slat, slon = _nearest_station(lat, lon)
+    dist_km = round(_haversine_km(lat, lon, slat, slon), 1)
+    out = TideReading(station_id=sid, station_name=name, distance_km=dist_km,
+                      observed_ft=None, predicted_ft=None, residual_ft=None,
+                      obs_time=None)
+    try:
+        obs = _fetch(sid, "water_level").get("data") or []
+        pred = _fetch(sid, "predictions").get("predictions") or []
+        if obs:
+            out.observed_ft = round(float(obs[0]["v"]), 2)
+            out.obs_time = obs[0].get("t")
+        if pred:
+            out.predicted_ft = round(float(pred[0]["v"]), 2)
+        if out.observed_ft is not None and out.predicted_ft is not None:
+            out.residual_ft = round(out.observed_ft - out.predicted_ft, 2)
+    except Exception as e:
+        out.error = str(e)
+    return out
+
+
+def summary_for_point(lat: float, lon: float) -> dict:
+    r = reading_at(lat, lon)
+    # Look up station coords for the map marker.
+    sta = next((s for s in STATIONS if s[0] == r.station_id), None)
+    return {
+        "station_id": r.station_id,
+        "station_name": r.station_name,
+        "station_lat": sta[2] if sta else None,
+        "station_lon": sta[3] if sta else None,
+        "distance_km": r.distance_km,
+        "observed_ft_mllw": r.observed_ft,
+        "predicted_ft_mllw": r.predicted_ft,
+        "residual_ft": r.residual_ft,
+        "obs_time": r.obs_time,
+        "error": r.error,
+    }

app/context/npcc4_slr.py

@@ -0,0 +1,42 @@
+"""NPCC4 sea-level rise projections for NYC (static lookup).
+
+Source: New York City Panel on Climate Change 4th Assessment (2024),
+Chapter 3, Table 3.2 — sea-level rise relative to 2000–2004 baseline,
+Battery Tide Gauge (NOAA 8518750), primary NYC harbor reference.
+
+Values are in inches above the 2000–2004 mean. The NPCC4 uses a
+probabilistic framework across RCP/SSP scenarios; the table excerpted
+here represents the "likely range" (10th–90th) plus the high-end
+"extreme" scenario (99th).
+"""
+
+DOC_ID = "npcc4_slr"
+CITATION = (
+    "New York City Panel on Climate Change 4th Assessment (NPCC4 2024), "
+    "Chapter 3 — Sea Level Rise, Table 3.2. "
+    "Published by the New York Academy of Sciences. "
+    "Reference gauge: NOAA Battery (8518750), baseline 2000–2004."
+)
+
+# Sea-level rise projections in INCHES above the 2000–2004 baseline,
+# Battery Tide Gauge. Percentiles: 10th (low), 50th (mid), 90th (high),
+# 99th (extreme). All values from NPCC4 (2024) Ch. 3 Table 3.2.
+_TABLE_IN = {
+    2050: {10: 8,  50: 15, 90: 29, 99: 40},
+    2100: {10: 13, 50: 31, 90: 65, 99: 96},
+}
+
+
+def _in_to_m(inches: float) -> float:
+    return round(inches * 0.0254, 2)
+
+
+def get_projections() -> dict:
+    """Return NPCC4 SLR projection dict, always available (static table)."""
+    result: dict = {"available": True, "baseline": "2000–2004", "gauge": "NOAA Battery (8518750)"}
+    for year, pcts in _TABLE_IN.items():
+        result[str(year)] = {
+            str(pct): {"in": v, "m": _in_to_m(v)}
+            for pct, v in pcts.items()
+        }
+    return result

app/context/nws_alerts.py

@@ -0,0 +1,71 @@
+"""NWS API — active alerts at a point.
+
+api.weather.gov/alerts/active?point={lat},{lon}, no auth, JSON.
+A User-Agent header is required (NWS rate-limits anonymous traffic).
+
+We surface only flood-relevant categories so the doc the reconciler
+sees is short and on-topic.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+DOC_ID = "nws_alerts"
+CITATION = "NWS public alert API (api.weather.gov/alerts)"
+
+USER_AGENT = "Riprap-NYC/0.1 (civic-flood-tool; +https://huggingface.co/spaces/msradam/riprap-nyc)"
+
+_FLOOD_EVENT_KEYWORDS = (
+    "flood", "flash flood", "coastal flood", "high surf", "storm surge",
+    "hurricane", "tropical storm", "tornado warning",  # high-impact context
+    "rip current",
+)
+
+
+def _is_flood_relevant(event_name: str) -> bool:
+    e = (event_name or "").lower()
+    return any(k in e for k in _FLOOD_EVENT_KEYWORDS)
+
+
+def alerts_at(lat: float, lon: float) -> list[dict[str, Any]]:
+    r = httpx.get(
+        "https://api.weather.gov/alerts/active",
+        params={"point": f"{lat:.4f},{lon:.4f}"},
+        headers={"User-Agent": USER_AGENT, "Accept": "application/geo+json"},
+        timeout=8.0,
+    )
+    r.raise_for_status()
+    out = []
+    for f in r.json().get("features", []):
+        p = f.get("properties", {}) or {}
+        event = p.get("event") or ""
+        if not _is_flood_relevant(event):
+            continue
+        out.append({
+            "id": p.get("id"),
+            "event": event,
+            "severity": p.get("severity"),
+            "urgency": p.get("urgency"),
+            "certainty": p.get("certainty"),
+            "headline": p.get("headline"),
+            "sent": p.get("sent"),
+            "effective": p.get("effective"),
+            "expires": p.get("expires"),
+            "sender_name": p.get("senderName"),
+            "areaDesc": p.get("areaDesc"),
+        })
+    return out
+
+
+def summary_for_point(lat: float, lon: float) -> dict:
+    try:
+        active = alerts_at(lat, lon)
+    except Exception as e:
+        return {"n_active": 0, "alerts": [], "error": str(e)}
+    return {
+        "n_active": len(active),
+        "alerts": active,
+        "error": None,
+    }

app/context/nws_obs.py

@@ -0,0 +1,108 @@
+"""NWS station observations — latest hourly METAR for the nearest NYC airport.
+
+api.weather.gov/stations/{id}/observations/latest.
+
+Five NYC-region ASOS stations cover the city; we pick the nearest.
+Most useful field for flood context is hourly precipitation (the
+`precipitationLastHour` quantity, mm). The latest observation is
+typically <60 min old.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import asin, cos, radians, sin, sqrt
+
+import httpx
+
+DOC_ID = "nws_obs"
+CITATION = "NWS station observations API (api.weather.gov/stations)"
+
+USER_AGENT = "Riprap-NYC/0.1 (civic-flood-tool; +https://huggingface.co/spaces/msradam/riprap-nyc)"
+
+# NYC + Hudson Corridor ASOS stations. Picker is haversine-nearest, so adding
+# upstate stations enables Albany / Poughkeepsie / Newburgh queries without
+# breaking NYC behaviour (NYC stations stay closer for NYC lat/lon).
+STATIONS = [
+    # NYC region
+    ("KNYC", "Central Park, NY",         40.7794, -73.9692),
+    ("KLGA", "LaGuardia Airport, NY",    40.7794, -73.8800),
+    ("KJFK", "JFK Airport, NY",          40.6413, -73.7781),
+    ("KEWR", "Newark Liberty, NJ",       40.6925, -74.1687),
+    ("KFRG", "Republic Farmingdale, NY", 40.7288, -73.4134),
+    # Hudson Corridor (south → north)
+    ("KHPN", "White Plains, NY",         41.0670, -73.7076),
+    ("KSWF", "Newburgh-Stewart, NY",     41.5042, -74.1048),
+    ("KPOU", "Poughkeepsie, NY",         41.6262, -73.8842),
+    ("KALB", "Albany Intl, NY",          42.7475, -73.8025),
+]
+
+
+@dataclass
+class Obs:
+    station_id: str
+    station_name: str
+    distance_km: float
+    obs_time: str | None
+    temp_c: float | None
+    precip_last_hour_mm: float | None
+    precip_last_3h_mm: float | None
+    precip_last_6h_mm: float | None
+    error: str | None = None
+
+
+def _haversine_km(lat1, lon1, lat2, lon2) -> float:
+    R = 6371.0
+    p1, p2 = radians(lat1), radians(lat2)
+    dp = radians(lat2 - lat1); dl = radians(lon2 - lon1)
+    a = sin(dp/2)**2 + cos(p1)*cos(p2)*sin(dl/2)**2
+    return 2 * R * asin(sqrt(a))
+
+
+def _val_mm(props, key) -> float | None:
+    """NWS returns {value: ..., unitCode: 'wmoUnit:mm'} per quantity. Convert
+    to mm; if value is null, return None."""
+    q = (props or {}).get(key) or {}
+    v = q.get("value")
+    if v is None:
+        return None
+    return round(float(v), 2)
+
+
+def obs_at(lat: float, lon: float) -> Obs:
+    sid, name, slat, slon = min(STATIONS, key=lambda s: _haversine_km(lat, lon, s[2], s[3]))
+    dist_km = round(_haversine_km(lat, lon, slat, slon), 1)
+    out = Obs(station_id=sid, station_name=name, distance_km=dist_km,
+              obs_time=None, temp_c=None,
+              precip_last_hour_mm=None, precip_last_3h_mm=None,
+              precip_last_6h_mm=None)
+    try:
+        r = httpx.get(
+            f"https://api.weather.gov/stations/{sid}/observations/latest",
+            headers={"User-Agent": USER_AGENT, "Accept": "application/geo+json"},
+            timeout=8.0,
+        )
+        r.raise_for_status()
+        p = r.json().get("properties", {}) or {}
+        out.obs_time = p.get("timestamp")
+        out.temp_c = _val_mm(p, "temperature")
+        out.precip_last_hour_mm = _val_mm(p, "precipitationLastHour")
+        out.precip_last_3h_mm = _val_mm(p, "precipitationLast3Hours")
+        out.precip_last_6h_mm = _val_mm(p, "precipitationLast6Hours")
+    except Exception as e:
+        out.error = str(e)
+    return out
+
+
+def summary_for_point(lat: float, lon: float) -> dict:
+    o = obs_at(lat, lon)
+    return {
+        "station_id": o.station_id,
+        "station_name": o.station_name,
+        "distance_km": o.distance_km,
+        "obs_time": o.obs_time,
+        "temp_c": o.temp_c,
+        "precip_last_hour_mm": o.precip_last_hour_mm,
+        "precip_last_3h_mm": o.precip_last_3h_mm,
+        "precip_last_6h_mm": o.precip_last_6h_mm,
+        "error": o.error,
+    }

app/context/nyc311.py

@@ -0,0 +1,161 @@
+"""NYC 311 — flood-related complaints around a point.
+
+Live dataset: erm2-nwe9. Filter by descriptor (the flood signal is in
+descriptor, not complaint_type) within a buffer.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+import httpx
+
+URL = "https://data.cityofnewyork.us/resource/erm2-nwe9.json"
+DOC_ID = "nyc311"
+CITATION = "NYC 311 service requests (Socrata erm2-nwe9, 2010-present)"
+
+FLOOD_DESCRIPTORS = [
+    "Street Flooding (SJ)",
+    "Sewer Backup (Use Comments) (SA)",
+    "Catch Basin Clogged/Flooding (Use Comments) (SC)",
+    "Highway Flooding (SH)",
+    "Manhole Overflow (Use Comments) (SA1)",
+    "Flooding on Street",
+    "RAIN GARDEN FLOODING (SRGFLD)",
+]
+
+_DESC_CLAUSE = "(" + " OR ".join(f"descriptor='{d}'" for d in FLOOD_DESCRIPTORS) + ")"
+
+
+@dataclass
+class Complaint:
+    unique_key: str
+    descriptor: str
+    created_date: str
+    address: str | None
+    status: str | None
+    lat: float | None = None
+    lon: float | None = None
+
+
+def complaints_near(lat: float, lon: float, radius_m: float = 200,
+                    since: datetime | None = None,
+                    limit: int = 1000) -> list[Complaint]:
+    where = f"{_DESC_CLAUSE} AND within_circle(location, {lat}, {lon}, {radius_m})"
+    if since:
+        # Socrata floating-timestamp: drop tz suffix
+        ts = since.replace(tzinfo=None).isoformat(timespec="seconds")
+        where += f" AND created_date >= '{ts}'"
+    r = httpx.get(URL, params={
+        "$select": "unique_key, descriptor, created_date, incident_address, "
+                   "status, latitude, longitude",
+        "$where": where,
+        "$order": "created_date desc",
+        "$limit": str(limit),
+    }, timeout=30)
+    r.raise_for_status()
+    out = []
+    for row in r.json():
+        lat = row.get("latitude")
+        lon = row.get("longitude")
+        try:
+            lat = float(lat) if lat is not None else None
+            lon = float(lon) if lon is not None else None
+        except Exception:
+            lat, lon = None, None
+        out.append(Complaint(
+            unique_key=row.get("unique_key", ""),
+            descriptor=row.get("descriptor", ""),
+            created_date=row.get("created_date", ""),
+            address=row.get("incident_address"),
+            status=row.get("status"),
+            lat=lat, lon=lon,
+        ))
+    return out
+
+
+def summary_for_point(lat: float, lon: float, radius_m: float = 200,
+                      years: int = 5) -> dict:
+    since = datetime.now(timezone.utc) - timedelta(days=365 * years)
+    cs = complaints_near(lat, lon, radius_m, since=since, limit=2000)
+    return _summarize(cs, years=years, radius_m=radius_m)
+
+
+def complaints_in_polygon(polygon, polygon_crs: str = "EPSG:4326",
+                          since: datetime | None = None,
+                          limit: int = 5000,
+                          simplify_tolerance: float = 0.0005) -> list[Complaint]:
+    """Pull flood-related complaints inside an arbitrary polygon via
+    Socrata's `within_polygon(location, 'MULTIPOLYGON(...)')` predicate.
+
+    NYC NTA polygons can have thousands of vertices and exceed Socrata's
+    URL length limit (414). We simplify in EPSG:4326 with a default
+    ~50 m tolerance, which collapses vertex count ~10-20× without
+    materially changing the contained-points result.
+
+    Polygon must be EPSG:4326 (lat/lon) for the Socrata query.
+    """
+    import geopandas as gpd
+    g = gpd.GeoDataFrame(geometry=[polygon], crs=polygon_crs).to_crs("EPSG:4326")
+    geom = g.iloc[0].geometry.simplify(simplify_tolerance, preserve_topology=True)
+    wkt = geom.wkt
+    where = f"{_DESC_CLAUSE} AND within_polygon(location, '{wkt}')"
+    if since:
+        ts = since.replace(tzinfo=None).isoformat(timespec="seconds")
+        where += f" AND created_date >= '{ts}'"
+    r = httpx.get(URL, params={
+        "$select": "unique_key, descriptor, created_date, incident_address, status",
+        "$where": where,
+        "$order": "created_date desc",
+        "$limit": str(limit),
+    }, timeout=60)
+    r.raise_for_status()
+    return [
+        Complaint(
+            unique_key=row.get("unique_key", ""),
+            descriptor=row.get("descriptor", ""),
+            created_date=row.get("created_date", ""),
+            address=row.get("incident_address"),
+            status=row.get("status"),
+        )
+        for row in r.json()
+    ]
+
+
+def summary_for_polygon(polygon, polygon_crs: str = "EPSG:4326",
+                        years: int = 5) -> dict:
+    """Polygon-mode aggregation: counts of flood-related 311 complaints
+    inside the polygon over the trailing window."""
+    since = datetime.now(timezone.utc) - timedelta(days=365 * years)
+    cs = complaints_in_polygon(polygon, polygon_crs=polygon_crs, since=since)
+    return _summarize(cs, years=years, radius_m=None)
+
+
+def _summarize(cs: list[Complaint], years: int, radius_m: float | None) -> dict:
+    by_year: Counter = Counter(c.created_date[:4] for c in cs if c.created_date)
+    by_descriptor: Counter = Counter(c.descriptor for c in cs)
+    # Cap at 60 most-recent points for the map layer — keeps the SSE
+    # payload small while still showing meaningful clustering.
+    points = [
+        {"lat": c.lat, "lon": c.lon,
+         "descriptor": c.descriptor,
+         "date": c.created_date[:10],
+         "address": c.address}
+        for c in cs[:60]
+        if c.lat is not None and c.lon is not None
+    ]
+    return {
+        "n": len(cs),
+        "radius_m": radius_m,
+        "years": years,
+        "by_year": dict(sorted(by_year.items())),
+        "by_descriptor": dict(by_descriptor.most_common(6)),
+        "most_recent": [
+            {"date": c.created_date[:10],
+             "descriptor": c.descriptor,
+             "address": c.address}
+            for c in cs[:5]
+        ],
+        "points": points,
+    }

app/context/terramind_nyc.py

@@ -0,0 +1,485 @@
+"""TerraMind-NYC adapters — LULC and Buildings inference for NYC chips.
+
+Wraps the Apache-2.0 [`msradam/TerraMind-NYC-Adapters`](https://huggingface.co/msradam/TerraMind-NYC-Adapters)
+LoRA family fine-tuned on NYC EO chips (Sentinel-2 L2A + Sentinel-1 RTC
++ Copernicus DEM, temporal stack of 4) on AMD MI300X via AMD Developer
+Cloud. Exposes two specialist entry points:
+
+    lulc(s2l2a, s1rtc, dem)       -> 5-class macro NYC LULC mask
+    buildings(s2l2a, s1rtc, dem)  -> binary NYC building footprint mask
+
+The base TerraMind 1.0 weights are downloaded by terratorch on first
+call; the LoRA adapter + UNet decoder weights come from the HF repo and
+are cached to `~/.cache/huggingface/hub`.
+
+CHIP-SIZE TRAP. TerraMind's positional embeddings don't generalise off
+its training resolution (224×224). Calling `task.model({...})` on a
+chip ≠ 224×224 produces silent garbage. We therefore wrap inference
+with `terratorch.tasks.tiled_inference.tiled_inference`, which slides
+a 224×224 crop window across the chip and stitches per-window logits.
+This matches the patch in
+`experiments/18_terramind_nyc_lora/shared/inference_ensemble.py` that
+the plan flags as required for production.
+
+Gated by RIPRAP_TERRAMIND_NYC_ENABLE — deployments without the deps
+installed (HF Spaces' Py3.10 cone, plain Ollama dev VMs) silently no-op
+through the same skipped-result shape every other heavy specialist
+emits.
+
+This module does NOT fetch its own S2/S1/DEM chips. C4 wires it into
+the FSM with a shared chip cache so the LULC and Buildings calls
+don't each refetch ~150 MB of imagery.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from typing import Any
+
+log = logging.getLogger("riprap.terramind_nyc")
+
+ENABLE = os.environ.get("RIPRAP_TERRAMIND_NYC_ENABLE", "1").lower() in ("1", "true", "yes")
+DEVICE = os.environ.get("RIPRAP_TERRAMIND_NYC_DEVICE", "cpu")
+ADAPTERS_REPO = "msradam/TerraMind-NYC-Adapters"
+
+# Per-task config knobs the HF README's quick-start fixes for these
+# adapters. Mirrored from experiments/18_terramind_nyc_lora/adapters/*/
+# config.yaml so a single source of truth lives next to the inference
+# code rather than being scraped from YAML at runtime.
+ADAPTER_SPECS: dict[str, dict[str, Any]] = {
+    "lulc": {
+        "subdir": "lulc_nyc",
+        "num_classes": 5,
+        "class_labels": [
+            "Trees / vegetation",
+            "Cropland",
+            "Built / impervious",
+            "Bare ground",
+            "Water",
+        ],
+    },
+    "buildings": {
+        "subdir": "buildings_nyc",
+        "num_classes": 2,
+        # The decoder emits class 0 = background, class 1 = building.
+        "class_labels": ["Background", "Building footprint"],
+    },
+}
+
+# Tile-window size — TerraMind's training resolution. Stride < window
+# yields overlap (smooths seams from window-boundary classification
+# noise); 96 px overlap matches the experiments/18 ensemble.
+TILE_SIZE = 224
+TILE_STRIDE = 128
+
+# One-shot lazy-init guards. The base TerraMind weights are heavy
+# (~1.6 GB) and we want to load them once across LULC and Buildings.
+_INIT_LOCK = threading.Lock()
+_BASE_LOADED = False
+_ADAPTERS: dict[str, Any] = {}  # name -> built terratorch task on DEVICE
+
+
+def _has_required_deps() -> tuple[bool, str | None]:
+    """Probe the heavy-EO deps. Same shape as prithvi_live's check —
+    a missing dep (terratorch / peft / safetensors / hf_hub) returns a
+    clean `skipped: deps_unavailable` outcome instead of a noisy
+    ModuleNotFoundError in the trace.
+
+    On the HF Space, terratorch's import chain itself can raise
+    RuntimeError("operator torchvision::nms does not exist") when the
+    torchvision binary extension can't load against our CPU torch
+    wheel. Treat that as 'unavailable' too — the local inference path
+    is dead-on-arrival there."""
+    missing: list[str] = []
+    for name in ("terratorch", "peft", "safetensors", "huggingface_hub",
+                 "torch", "yaml"):
+        try:
+            __import__(name)
+        except ImportError:
+            missing.append(name)
+        except Exception as e:
+            # torchvision::nms RuntimeError, libcuda load failure, etc.
+            log.warning("terramind_nyc: %s import raised %s; treating as "
+                        "unavailable", name, type(e).__name__)
+            missing.append(f"{name} ({type(e).__name__})")
+    if missing:
+        return False, ", ".join(missing)
+    return True, None
+
+
+_DEPS_OK, _DEPS_MISSING = _has_required_deps()
+
+
+def _ensure_adapter(adapter_name: str):
+    """Build the terratorch SemanticSegmentationTask, inject the LoRA
+    scaffold, load the published Δ + decoder weights, return the task.
+
+    Per-task tasks share the TerraMind base inside terratorch's model
+    factory — calling SemanticSegmentationTask twice loads the base
+    twice in fp32 (~3.3 GB resident on CPU). For a two-task family this
+    is acceptable; we don't need the cross-task weight sharing the
+    experiments/18 ensemble does. If memory becomes a problem, swap
+    this for a single-task / hot-swap-adapter implementation.
+    """
+    if adapter_name not in ADAPTER_SPECS:
+        raise KeyError(f"unknown adapter {adapter_name!r}; "
+                       f"expected one of {list(ADAPTER_SPECS)}")
+    if adapter_name in _ADAPTERS:
+        return _ADAPTERS[adapter_name]
+
+    with _INIT_LOCK:
+        if adapter_name in _ADAPTERS:
+            return _ADAPTERS[adapter_name]
+
+        spec = ADAPTER_SPECS[adapter_name]
+        log.info("terramind_nyc: building task for %s", adapter_name)
+
+        from huggingface_hub import snapshot_download
+        from peft import LoraConfig, inject_adapter_in_model
+        from safetensors.torch import load_file
+        from terratorch.tasks import SemanticSegmentationTask
+
+        # 1. Pull the requested adapter subtree from the HF repo.
+        adapter_root = snapshot_download(
+            ADAPTERS_REPO,
+            allow_patterns=[f"{spec['subdir']}/*"],
+        )
+
+        # 2. Build the standard terratorch task with the same model_args
+        #    the published HF_README quick-start uses.
+        task = SemanticSegmentationTask(
+            model_factory="EncoderDecoderFactory",
+            model_args=dict(
+                backbone="terramind_v1_base",
+                backbone_pretrained=True,
+                backbone_modalities=["S2L2A", "S1RTC", "DEM"],
+                backbone_use_temporal=True,
+                backbone_temporal_pooling="concat",
+                backbone_temporal_n_timestamps=4,
+                necks=[
+                    {"name": "SelectIndices", "indices": [2, 5, 8, 11]},
+                    {"name": "ReshapeTokensToImage", "remove_cls_token": False},
+                    {"name": "LearnedInterpolateToPyramidal"},
+                ],
+                decoder="UNetDecoder",
+                decoder_channels=[512, 256, 128, 64],
+                head_dropout=0.1,
+                num_classes=spec["num_classes"],
+            ),
+            loss="ce", lr=1e-4, freeze_backbone=False, freeze_decoder=False,
+        )
+
+        # 3. Inject the LoRA scaffold the adapter weights were trained
+        #    against. Same hyperparameters every adapter in this family
+        #    used (see experiments/18 adapters/_template/config.yaml).
+        inject_adapter_in_model(LoraConfig(
+            r=16, lora_alpha=32, lora_dropout=0.05,
+            target_modules=["attn.qkv", "attn.proj"], bias="none",
+        ), task.model.encoder)
+
+        # 4. Restore Δ matrices (encoder LoRA) and the decoder/neck/head
+        #    weights from the safetensors bundle. The encoder.* prefix
+        #    is stripped because the encoder state-dict is rooted at
+        #    the encoder module, not the task.
+        adapter_dir = f"{adapter_root}/{spec['subdir']}"
+        lora_state = load_file(f"{adapter_dir}/adapter_model.safetensors")
+        head_state = load_file(f"{adapter_dir}/decoder_head.safetensors")
+        encoder_state = {
+            k.removeprefix("encoder."): v
+            for k, v in lora_state.items() if k.startswith("encoder.")
+        }
+        task.model.encoder.load_state_dict(encoder_state, strict=False)
+        for sub in ("decoder", "neck", "head", "aux_heads"):
+            sub_state = {
+                k[len(sub) + 1:]: v
+                for k, v in head_state.items() if k.startswith(sub + ".")
+            }
+            if sub_state and hasattr(task.model, sub):
+                getattr(task.model, sub).load_state_dict(sub_state,
+                                                          strict=False)
+
+        # 5. Move to the configured device. CUDA only if the caller
+        #    asked AND a CUDA device is actually available — silently
+        #    fall back to CPU otherwise.
+        target_device = DEVICE
+        if target_device == "cuda":
+            import torch
+            if not torch.cuda.is_available():
+                log.warning("terramind_nyc: CUDA unavailable, falling back to CPU")
+                target_device = "cpu"
+        task = task.to(target_device).eval()
+
+        _ADAPTERS[adapter_name] = task
+        log.info("terramind_nyc: %s ready on %s", adapter_name, target_device)
+        return task
+
+
+def _tiled_predict(task, modality_chips: dict, num_classes: int):
+    """Run the task's encoder-decoder forward in 224×224 tiles, returning
+    a (1, num_classes, H, W) logits tensor stitched from the windows.
+
+    TerraMind's positional embeddings are tied to the 224×224 training
+    resolution. terratorch's tiled_inference helper slides a window
+    across the input modalities (it accepts a dict of per-modality
+    tensors as long as all modalities share H×W), runs the model on
+    each crop, and averages overlapping logits. Without it, larger
+    chips return silent garbage; smaller chips error on the encoder
+    ViT.
+    """
+    import torch
+    from terratorch.tasks.tiled_inference import tiled_inference
+
+    # tiled_inference invokes `model_forward(patch)` per tile. The task
+    # model returns a ModelOutput-like with .output OR a plain tensor;
+    # coerce to tensor either way.
+    def _forward(x, **_extra):
+        out = task.model(x)
+        return out.output if hasattr(out, "output") else out
+
+    with torch.no_grad():
+        logits = tiled_inference(
+            _forward,
+            modality_chips,
+            out_channels=num_classes,
+            h_crop=TILE_SIZE,
+            w_crop=TILE_SIZE,
+            h_stride=TILE_STRIDE,
+            w_stride=TILE_STRIDE,
+            average_patches=True,
+            blend_overlaps=True,
+            padding="reflect",
+        )
+    return logits
+
+
+def _summarize_lulc(pred, class_labels: list[str]) -> dict[str, Any]:
+    """Per-class pixel fraction + dominant class from an integer mask."""
+    import numpy as np
+    pred_np = pred.detach().cpu().numpy() if hasattr(pred, "detach") else np.asarray(pred)
+    flat = pred_np.reshape(-1)
+    n = max(int(flat.size), 1)
+    fractions: dict[str, float] = {}
+    for idx, label in enumerate(class_labels):
+        pct = 100.0 * float((flat == idx).sum()) / n
+        if pct > 0:
+            fractions[label] = round(pct, 2)
+    dominant_idx = int(max(range(len(class_labels)),
+                            key=lambda i: int((flat == i).sum())))
+    return {
+        "ok": True,
+        "n_pixels": int(flat.size),
+        "shape": list(pred_np.shape),
+        "class_fractions": fractions,
+        "dominant_class": class_labels[dominant_idx],
+        "dominant_pct": fractions.get(class_labels[dominant_idx], 0.0),
+    }
+
+
+def _summarize_buildings(pred, class_labels: list[str]) -> dict[str, Any]:
+    """Building-pixel coverage + simple connected-component count."""
+    import numpy as np
+    pred_np = pred.detach().cpu().numpy() if hasattr(pred, "detach") else np.asarray(pred)
+    mask = (pred_np == 1).astype("uint8")
+    n_total = max(int(mask.size), 1)
+    pct_built = 100.0 * float(mask.sum()) / n_total
+    # Connected-component count is a cheap signal of "how many distinct
+    # buildings does this chip cover" — useful for the briefing without
+    # paying for full polygonisation.
+    n_components: int | None = None
+    try:
+        from scipy.ndimage import label
+        _, n_components = label(mask)
+    except Exception:  # scipy is optional in some HF Spaces build cones
+        log.debug("terramind_nyc: scipy.ndimage unavailable; "
+                  "skipping component count")
+    return {
+        "ok": True,
+        "n_pixels": int(mask.size),
+        "shape": list(mask.shape),
+        "pct_buildings": round(pct_built, 2),
+        "n_building_components": n_components,
+        "class_labels": class_labels,
+    }
+
+
+def _try_remote(adapter_name: str, modality_chips: dict) -> dict | None:
+    """POST to the riprap-models inference service if configured.
+
+    Returns:
+      - successful result dict on a 200/ok=True remote response
+      - {"ok": False, "skipped": "<reason>"} when remote was attempted
+        but failed (RemoteUnreachable, ok=False, or other error). The
+        caller MUST NOT fall through to local terratorch in this case
+        — local has been broken on the CPU-tier UI Spaces since the
+        torchvision binary mismatch landed, and we'd rather show a
+        clean "remote unreachable" reason than a noisy crash.
+      - None ONLY when remote isn't configured at all (caller may
+        legitimately try local then)."""
+    try:
+        from app import inference as _inf
+        if not _inf.remote_enabled():
+            return None
+        s2 = modality_chips.get("S2L2A")
+        s1 = modality_chips.get("S1RTC")
+        dem = modality_chips.get("DEM")
+        # The router serializes torch tensors to base64 numpy float32 —
+        # the chip cache hands us [B, C, T, H, W]; keep that shape, the
+        # service rebuilds the temporal stack on its end.
+        result = _inf.terramind(adapter_name, s2, s1, dem)
+        if not result.get("ok"):
+            err = result.get("error") or result.get("err") or "unknown"
+            return {"ok": False,
+                    "skipped": f"remote terramind/{adapter_name} non-ok: {err}"}
+        result.setdefault("adapter", adapter_name)
+        result.setdefault("repo", ADAPTERS_REPO)
+        result["compute"] = f"remote · {result.get('device', 'gpu')}"
+        # Polygonize the prediction raster onto the chip's bounds so
+        # the map can paint the LULC / buildings overlay. Bounds come
+        # via the modality_chips dict — the eo_chip layer threads them
+        # through. Best-effort; never raises into the FSM.
+        bounds = modality_chips.get("bounds_4326") if modality_chips else None
+        pred_b64 = result.get("pred_b64")
+        pred_shape = result.get("pred_shape")
+        class_labels = result.get("class_labels")
+        if bounds and pred_b64 and pred_shape:
+            try:
+                from app.context._polygonize import (
+                    polygonize_binary_mask, polygonize_class_raster,
+                )
+                if adapter_name == "buildings":
+                    polys = polygonize_binary_mask(
+                        pred_b64, pred_shape, tuple(bounds),
+                        label="building", fill_color="#D62728",
+                        simplify_tolerance=2e-5,
+                    )
+                else:
+                    polys = polygonize_class_raster(
+                        pred_b64, pred_shape, class_labels, tuple(bounds),
+                        simplify_tolerance=2e-5,
+                    )
+                result["polygons_geojson"] = polys
+            except Exception:
+                log.exception("terramind/%s: polygonize failed", adapter_name)
+                result["polygons_geojson"] = None
+        return result
+    except _inf.RemoteUnreachable as e:
+        log.info("terramind/%s: remote unreachable (%s)", adapter_name, e)
+        return {"ok": False,
+                "skipped": f"remote terramind/{adapter_name} unreachable: {e}"}
+    except Exception as e:
+        log.exception("terramind/%s: remote call failed", adapter_name)
+        return {"ok": False,
+                "skipped": f"remote terramind/{adapter_name} error: "
+                           f"{type(e).__name__}: {e}"}
+
+
+def _run(adapter_name: str, modality_chips: dict, summarizer):
+    """Common boilerplate: gate, time, [remote attempt], load, tiled
+    predict, summarize."""
+    if not ENABLE:
+        return {"ok": False,
+                "skipped": "RIPRAP_TERRAMIND_NYC_ENABLE=0"}
+
+    # v0.4.5 — try remote first. The remote service has its own deps,
+    # so this path works even when local _DEPS_OK is False (the most
+    # common HF Spaces case until terratorch + peft are baked in).
+    remote = _try_remote(adapter_name, modality_chips or {})
+    if remote is not None:
+        return remote
+
+    if not _DEPS_OK:
+        return {"ok": False,
+                "skipped": f"deps unavailable on this deployment: "
+                           f"{_DEPS_MISSING}"}
+    if not modality_chips:
+        return {"ok": False, "err": "no modality chips supplied"}
+    t0 = time.time()
+    try:
+        task = _ensure_adapter(adapter_name)
+        spec = ADAPTER_SPECS[adapter_name]
+        # Strip out bounds_4326 (auxiliary metadata, not a tensor) before
+        # handing the dict to terratorch's tiled_inference, which iterates
+        # all values as modalities.
+        tensors_only = {k: v for k, v in modality_chips.items()
+                        if k != "bounds_4326"}
+        logits = _tiled_predict(task, tensors_only, spec["num_classes"])
+        # logits: (B, C, H, W). Argmax to per-pixel class id.
+        pred = logits.argmax(dim=1).squeeze(0)
+        result = summarizer(pred, spec["class_labels"])
+        result["elapsed_s"] = round(time.time() - t0, 2)
+        result["adapter"] = adapter_name
+        result["repo"] = ADAPTERS_REPO
+        result["compute"] = "local"
+        return result
+    except Exception as e:
+        msg = str(e)
+        # Translate torchvision binary-extension failures into a clean
+        # skip. terratorch + torchvision both ride a transitive
+        # dep cone on the HF Space (sentence-transformers pulls torch
+        # CPU; torchvision's C extension can't load against that wheel),
+        # so a local _ensure_adapter() raises RuntimeError with this
+        # signature when remote is also unreachable. Clean skip is the
+        # honest demo outcome — same as terramind_synthesis.
+        if "torchvision::nms" in msg or "torchvision_C" in msg:
+            log.warning("terramind_nyc/%s: torchvision binary unavailable; "
+                        "remote unreachable too; clean skip", adapter_name)
+            return {"ok": False,
+                    "skipped": "remote inference unreachable + local "
+                               "torchvision binary unavailable on this "
+                               "deployment",
+                    "elapsed_s": round(time.time() - t0, 2)}
+        log.exception("terramind_nyc.%s failed", adapter_name)
+        return {"ok": False, "err": f"{type(e).__name__}: {e}",
+                "elapsed_s": round(time.time() - t0, 2)}
+
+
+def lulc(s2l2a, s1rtc=None, dem=None,
+          bounds_4326: tuple[float, float, float, float] | None = None,
+          ) -> dict[str, Any]:
+    """5-class NYC macro land-cover.
+
+    Inputs are torch tensors. The temporal models we trained expect
+    [C, T, H, W] (preferred) or [C, H, W] (will be expanded to T=1).
+    Pass S1 and DEM if you have them — the published adapter was
+    trained on the full triplet and accuracy degrades when modalities
+    are dropped.
+
+    `bounds_4326` is `(minlon, minlat, maxlon, maxlat)` of the chip
+    in WGS84; when provided, the LULC raster is polygonised onto the
+    chip's geographic extent so the map can render an overlay.
+    """
+    chips = {"S2L2A": s2l2a}
+    if bounds_4326 is not None:
+        chips["bounds_4326"] = bounds_4326
+    if s1rtc is not None:
+        chips["S1RTC"] = s1rtc
+    if dem is not None:
+        chips["DEM"] = dem
+    return _run("lulc", chips, _summarize_lulc)
+
+
+def buildings(s2l2a, s1rtc=None, dem=None,
+               bounds_4326: tuple[float, float, float, float] | None = None,
+               ) -> dict[str, Any]:
+    """Binary NYC building-footprint mask. Same input contract as lulc()."""
+    chips = {"S2L2A": s2l2a}
+    if bounds_4326 is not None:
+        chips["bounds_4326"] = bounds_4326
+    if s1rtc is not None:
+        chips["S1RTC"] = s1rtc
+    if dem is not None:
+        chips["DEM"] = dem
+    return _run("buildings", chips, _summarize_buildings)
+
+
+def warm():
+    """Optional pre-load — amortizes the first-query model build cost."""
+    if not ENABLE or not _DEPS_OK:
+        return
+    try:
+        for name in ADAPTER_SPECS:
+            _ensure_adapter(name)
+    except Exception:
+        log.exception("terramind_nyc: warm() failed; specialists will no-op")

app/context/terramind_synthesis.py

@@ -0,0 +1,468 @@
+"""TerraMind v1 base as a real-time FSM node — DEM → ESRI LULC.
+
+Per user query: take the geocoded (lat, lon), pull a DEM patch from
+Riprap's existing NYC-wide LiDAR raster (already used by the microtopo
+specialist — no STAC dependency), run TerraMind to generate a
+plausible categorical land-cover map from the terrain context, and
+emit class fractions the reconciler can cite as a synthetic-prior
+context layer alongside the empirical and modeled flood evidence.
+
+Why DEM → LULC (and not DEM → S2L2A as initially prototyped):
+  - LULC is *categorical* and *interpretable*. The output is one of
+    10 ESRI Land Cover classes per pixel; class fractions like "78%
+    Built Area" go straight into the briefing as cite-able claims.
+  - S2L2A is 12-channel reflectance — uninterpretable downstream
+    without a separate segmentation head.
+  - LULC is *comparable to ground truth*: NYC PLUTO land-use class
+    is already in the data layer; future calibration possible.
+
+Class label mapping is *tentative* against ESRI 2020-2022 schema
+(which TerraMesh's LULC tokenizer was trained on). The doc body
+discloses the mapping as tentative and the reconciler is instructed
+to use hedged framing ("the synthetic land-cover prior identifies …
+likely class …") rather than asserting hard labels.
+
+Why this shape:
+  - **No STAC dependency.** Microsoft Planetary Computer search has
+    been intermittent during this hackathon; the DEM raster is local
+    and always available.
+  - **Real-time.** < 0.3 s synthesis + < 0.5 s DEM patch read on M3
+    CPU once warm.
+  - **Honesty discipline.** Synthetic-prior tier, fourth epistemic
+    class alongside empirical / modeled / proxy.
+
+License: Apache-2.0 — `ibm-esa-geospatial/TerraMind-1.0-base`.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import random
+import threading
+import time
+from typing import Any
+
+log = logging.getLogger("riprap.terramind")
+
+ENABLE = os.environ.get("RIPRAP_TERRAMIND_ENABLE", "1").lower() in ("1", "true", "yes")
+DEFAULT_STEPS = int(os.environ.get("RIPRAP_TERRAMIND_STEPS", "10"))
+DEFAULT_SEED = int(os.environ.get("RIPRAP_TERRAMIND_SEED", "42"))
+CHIP_PX = int(os.environ.get("RIPRAP_TERRAMIND_CHIP_PX", "224"))
+CHIP_M = CHIP_PX * 30  # NYC DEM is at 30 m -> 6.72 km square
+HALF_M = CHIP_M / 2
+
+_MODEL = None
+_INIT_LOCK = threading.Lock()
+
+# Tentative ESRI 2020-2022 Land Cover class mapping for TerraMind v1's
+# LULC tokenizer output (10 channels, argmax over channel axis -> class
+# index 0-9). The README/docs don't expose the exact mapping and the
+# tokenizer source confirms only "ESRI LULC" without a label table, so
+# the names below are best-effort. The doc body discloses tentativeness.
+LULC_CLASSES = [
+    "water",                # 0
+    "trees",                # 1
+    "grass",                # 2
+    "flooded_vegetation",   # 3
+    "crops",                # 4
+    "scrub_shrub",          # 5
+    "built_area",           # 6
+    "bare_ground",          # 7
+    "snow_ice",             # 8
+    "clouds_or_no_data",    # 9
+]
+
+
+def _has_required_deps() -> tuple[bool, str | None]:
+    """Probe deps. terramind_synthesis runs only locally (no remote path
+    in app/inference.py for DEM-driven synthesis), so it always needs
+    terratorch. On the HF Space terratorch isn't installed, so this
+    specialist returns a clean `skipped: deps unavailable` outcome.
+
+    Distinguishes a *truly missing* package (ModuleNotFoundError) from
+    a *transient race* (other ImportError — typically sklearn's
+    "partially initialized module" from concurrent imports)."""
+    missing = []
+    for name in ("terratorch", "rasterio"):
+        try:
+            __import__(name)
+        except ModuleNotFoundError:
+            missing.append(name)
+        except ImportError:
+            log.debug("terramind: import race on %s, will retry on demand", name)
+        except Exception as e:
+            # torchvision::nms RuntimeError on HF Space — local inference
+            # is unavailable; treat as missing so fetch() returns a clean
+            # skip rather than crashing in _ensure_model.
+            log.warning("terramind: %s import raised %s; treating as "
+                        "unavailable", name, type(e).__name__)
+            missing.append(f"{name} ({type(e).__name__})")
+    return (not missing, ", ".join(missing) if missing else None)
+
+
+_DEPS_OK, _DEPS_MISSING = _has_required_deps()
+
+
+def _ensure_model():
+    """Lazy load with a lock so the parallel-block worker can't double-init."""
+    global _MODEL
+    if _MODEL is not None:
+        return _MODEL
+    with _INIT_LOCK:
+        if _MODEL is not None:
+            return _MODEL
+        # Heavy import deferred to first call so module import stays cheap
+        # and HF Spaces (no terratorch) doesn't pay it at all.
+        import terratorch.models.backbones.terramind.model.terramind_register  # noqa
+        from terratorch.registry import FULL_MODEL_REGISTRY
+        log.info("terramind: loading v1 base generate (DEM -> LULC)")
+        m = FULL_MODEL_REGISTRY.build(
+            "terratorch_terramind_v1_base_generate",
+            modalities=["DEM"],
+            output_modalities=["LULC"],
+            pretrained=True,
+            timesteps=DEFAULT_STEPS,
+        )
+        m.eval()
+        _MODEL = m
+        log.info("terramind: model ready")
+    return _MODEL
+
+
+def warm():
+    """Call at app boot to amortize the ~6 s checkpoint load + first-call
+    JIT. No-op when deps are absent."""
+    if ENABLE and _DEPS_OK:
+        try:
+            _ensure_model()
+        except Exception:
+            log.exception("terramind: warm() failed; specialist will no-op")
+
+
+def _read_dem_patch(lat: float, lon: float):
+    """Read a CHIP_PX×CHIP_PX DEM patch centered on (lat, lon) from the
+    local NYC-wide LiDAR raster. Returns (array, bounds_4326) where
+    bounds_4326 is (minlon, minlat, maxlon, maxlat) so the synthesised
+    LULC can be georeferenced onto the same extent for map rendering.
+    Returns None if outside the raster's extent."""
+    from pathlib import Path
+
+    import numpy as np
+    import rasterio
+    from rasterio.windows import from_bounds
+    dem_path = (Path(__file__).resolve().parents[2]
+                / "data" / "nyc_dem_30m.tif")
+    if not dem_path.exists():
+        return None
+    with rasterio.open(dem_path) as src:
+        # The DEM is in EPSG:4326 (geographic) in our cache — convert
+        # the chip extent in the same CRS by building a rough degree
+        # bbox from a meters-square half-side at NYC latitude.
+        # 1 degree lat ≈ 111 km, 1 degree lon ≈ 85 km at 40.7°N.
+        d_lat = (HALF_M / 111_000.0)
+        d_lon = (HALF_M / 85_000.0)
+        win = from_bounds(lon - d_lon, lat - d_lat,
+                          lon + d_lon, lat + d_lat,
+                          src.transform)
+        arr = src.read(1, window=win, boundless=True, fill_value=0).astype("float32")
+    if arr.size == 0 or arr.shape[0] < 8 or arr.shape[1] < 8:
+        return None
+    # Resize to CHIP_PX × CHIP_PX via torch interpolation. The exact
+    # pixel-perfect alignment doesn't matter for a synthetic prior; the
+    # model just needs a real terrain patch to condition on.
+    import torch
+    t = torch.from_numpy(arr).unsqueeze(0).unsqueeze(0)
+    t = torch.nn.functional.interpolate(t, size=(CHIP_PX, CHIP_PX),
+                                         mode="bilinear", align_corners=False)
+    out = t.squeeze(0).numpy()  # (1, CHIP_PX, CHIP_PX)
+    # Replace NaN sentinel values with median elevation so the model
+    # doesn't see NaN tokens.
+    if np.isnan(out).any():
+        med = float(np.nanmedian(out))
+        out = np.nan_to_num(out, nan=med)
+    bounds_4326 = (lon - d_lon, lat - d_lat, lon + d_lon, lat + d_lat)
+    return out, bounds_4326
+
+
+# Map class index -> visual color for the categorical fill on the
+# MapLibre layer. Colors picked to be visually distinct from the
+# existing red (Sandy) / blue (DEP) / cyan (Prithvi) / orange (Ida HWM).
+LULC_FILL_COLORS = {
+    "water":              "#0284c7",  # not used (we keep water clear so
+                                       # the underlying basemap shows)
+    "trees":              "#16a34a",  # green
+    "grass":              "#86efac",  # pale green
+    "flooded_vegetation": "#a3e635",  # lime
+    "crops":              "#fde047",  # yellow
+    "scrub_shrub":        "#bef264",
+    "built_area":         "#9ca3af",  # neutral gray
+    "bare_ground":        "#d6d3d1",  # warm light gray
+    "snow_ice":           "#f3f4f6",
+    "clouds_or_no_data":  "#000000",  # not used (kept transparent)
+}
+# Classes we don't render at all (transparent) — water is best left
+# uncolored so the basemap shoreline reads through; clouds/no-data is
+# semantically meaningless to fill.
+LULC_HIDE_CLASSES = {"water", "clouds_or_no_data"}
+
+
+def _polygonize_lulc(class_idx, bounds_4326: tuple) -> dict:
+    """Vectorize the per-pixel argmax classification into one MultiPolygon
+    per class label, then dump as a single GeoJSON FeatureCollection in
+    EPSG:4326. Each feature carries `label` + `class_idx` properties so
+    the frontend can colour by category.
+    """
+    import json
+
+    import geopandas as gpd
+    from rasterio.features import shapes
+    from rasterio.transform import from_bounds as transform_from_bounds
+    from shapely.geometry import shape
+
+    minlon, minlat, maxlon, maxlat = bounds_4326
+    h, w = class_idx.shape
+    transform = transform_from_bounds(minlon, minlat, maxlon, maxlat, w, h)
+    feats = []
+    for i, label in enumerate(LULC_CLASSES):
+        if label in LULC_HIDE_CLASSES:
+            continue
+        mask = (class_idx == i).astype("uint8")
+        if mask.sum() < 8:  # skip tiny noise
+            continue
+        polys = []
+        for geom, value in shapes(mask, mask=mask.astype(bool),
+                                   transform=transform):
+            if value != 1:
+                continue
+            polys.append(shape(geom))
+        if not polys:
+            continue
+        # Dissolve via geopandas + simplify lightly. The chip is 30 m
+        # per pixel and we don't need pixel-edge fidelity at urban zoom.
+        gdf = gpd.GeoDataFrame({"geometry": polys}, crs="EPSG:4326")
+        gdf["geometry"] = gdf.geometry.simplify(1e-4, preserve_topology=True)
+        for geom in gdf.geometry:
+            feats.append({
+                "type": "Feature",
+                "geometry": json.loads(gpd.GeoSeries([geom],
+                                                    crs="EPSG:4326").to_json())["features"][0]["geometry"],
+                "properties": {"label": label, "class_idx": i,
+                               "fill_color": LULC_FILL_COLORS.get(label, "#9ca3af")},
+            })
+    return {"type": "FeatureCollection", "features": feats}
+
+
+def fetch(lat: float, lon: float, timeout_s: float = 60.0) -> dict[str, Any]:
+    """Run the specialist. Returns:
+        { ok: bool,
+          skipped: str | None,
+          synthetic_modality: bool,
+          tim_chain: list[str],
+          diffusion_steps: int, diffusion_seed: int,
+          dem_mean_m: float,
+          class_fractions: dict[str, float],  # tentative ESRI labels
+          dominant_class: str,                 # highest-fraction label
+          dominant_pct: float,
+          n_classes_observed: int,
+          chip_shape: list[int],
+          elapsed_s: float,
+          err: str | None }
+
+    Designed never to raise. Failures show up as ok=False with reason.
+    """
+    if not ENABLE:
+        return {"ok": False, "skipped": "RIPRAP_TERRAMIND_ENABLE=0"}
+    t0 = time.time()
+    try:
+        import numpy as np
+        patch = _read_dem_patch(lat, lon)
+        if patch is None:
+            return {"ok": False, "skipped": "no DEM coverage at this point"}
+        dem, bounds_4326 = patch
+        dem_mean = float(dem.mean())
+
+        # v0.4.5+ — try the MI300X inference service first if configured.
+        # The droplet's /v1/terramind dispatch handles adapter='synthesis'
+        # via _terramind_synthesis_inference (DEM -> generative LULC). On
+        # the HF Space terratorch's torchvision binary doesn't load, so
+        # this is the only working path there.
+        try:
+            from app import inference as _inf
+            if _inf.remote_enabled():
+                # The terramind v1 base generative encoder embedding
+                # layer unpacks `B, C, H, W = x.shape` (verified against
+                # terratorch_terramind_v1_base_generate). DEM has C=1, so
+                # the on-the-wire shape is (1, 1, H, W) 4-D.
+                # `_read_dem_patch` returns a 3-D (1, H, W) array (it
+                # interpolates to CHIP_PX×CHIP_PX through a 4-D
+                # torch.functional.interpolate then squeezes the batch),
+                # so we add only the batch dim — not two.
+                import numpy as _np_local
+                dem_arr = _np_local.asarray(dem, dtype="float32")
+                if dem_arr.ndim == 2:                # (H, W)
+                    dem_remote = dem_arr[None, None, :, :]
+                elif dem_arr.ndim == 3:              # (1, H, W)
+                    dem_remote = dem_arr[None, :, :, :]
+                elif dem_arr.ndim == 4:              # already (1, 1, H, W)
+                    dem_remote = dem_arr
+                else:
+                    raise ValueError(
+                        f"unexpected DEM shape {dem_arr.shape}; "
+                        "expected 2/3/4-D")
+                remote = _inf.terramind("synthesis", None, None, dem_remote,
+                                          timeout=timeout_s)
+                if remote.get("ok"):
+                    elapsed = round(time.time() - t0, 2)
+                    # Polygonize the prediction raster for the map
+                    # layer. The droplet returns the per-pixel argmax;
+                    # we vectorize against the chip's bounds.
+                    polys = None
+                    pred_b64 = remote.get("pred_b64")
+                    pred_shape = remote.get("pred_shape")
+                    class_labels = (remote.get("class_labels")
+                                    or LULC_CLASSES)
+                    if pred_b64 and pred_shape:
+                        try:
+                            from app.context._polygonize import (
+                                polygonize_class_raster,
+                            )
+                            polys = polygonize_class_raster(
+                                pred_b64, pred_shape, class_labels,
+                                tuple(bounds_4326),
+                                simplify_tolerance=2e-5,
+                            )
+                        except Exception:
+                            log.exception("terramind/synthesis: "
+                                          "polygonize failed")
+                            polys = None
+                    out = {
+                        "ok": True,
+                        "synthetic_modality": True,
+                        "tim_chain": ["DEM", "LULC_synthetic"],
+                        "diffusion_steps": remote.get("diffusion_steps",
+                                                       DEFAULT_STEPS),
+                        "diffusion_seed": DEFAULT_SEED,
+                        "dem_mean_m": round(dem_mean, 2),
+                        "class_fractions": remote.get("class_fractions") or {},
+                        "dominant_class": remote.get("dominant_class") or "unknown",
+                        "dominant_pct": remote.get("dominant_pct") or 0.0,
+                        "n_classes_observed": remote.get("n_classes_observed") or 0,
+                        "chip_shape": remote.get("shape") or [],
+                        "bounds_4326": list(bounds_4326),
+                        "polygons_geojson": polys,
+                        "label_schema": remote.get("label_schema") or "",
+                        "compute": f"remote · {remote.get('device', 'gpu')}",
+                        "elapsed_s": elapsed,
+                    }
+                    return out
+                # remote returned non-ok — surface that signal directly
+                return {"ok": False,
+                        "skipped": f"remote terramind synthesis non-ok: "
+                                   f"{remote.get('error') or remote.get('detail') or 'unknown'}",
+                        "elapsed_s": round(time.time() - t0, 2)}
+        except _inf.RemoteUnreachable as e:
+            log.info("terramind_synthesis: remote unreachable (%s); local fallback", e)
+        except Exception as e:
+            log.exception("terramind_synthesis: remote call failed")
+            return {"ok": False,
+                    "skipped": f"remote terramind synthesis error: "
+                               f"{type(e).__name__}: {e}",
+                    "elapsed_s": round(time.time() - t0, 2)}
+
+        # Local fallback — original path; only available where terratorch
+        # imports without the torchvision::nms RuntimeError.
+        if not _DEPS_OK:
+            return {"ok": False, "skipped": f"deps unavailable: {_DEPS_MISSING}"}
+        import torch
+        random.seed(DEFAULT_SEED)
+        torch.manual_seed(DEFAULT_SEED)
+
+        model = _ensure_model()
+        # `dem` is 2-D (H, W) from `_read_dem_patch.src.read(1, ...)`. The
+        # terramind v1 base generative encoder wants (B=1, C=1, H, W) 4-D.
+        dem_t = torch.from_numpy(dem).unsqueeze(0).unsqueeze(0).float()
+        if time.time() - t0 > timeout_s:
+            return {"ok": False, "skipped": "terramind exceeded budget"}
+
+        with torch.no_grad():
+            out = model({"DEM": dem_t}, timesteps=DEFAULT_STEPS,
+                        verbose=False)
+        lulc = out["LULC"]
+        if hasattr(lulc, "detach"):
+            lulc = lulc.detach().cpu().numpy()
+        if lulc.ndim == 4:
+            lulc = lulc[0]  # (n_classes, H, W)
+        # Argmax over class channel -> per-pixel class index, then
+        # fraction by class. This is the cite-able structured output.
+        class_idx = lulc.argmax(axis=0)  # (H, W)
+        unique, counts = np.unique(class_idx, return_counts=True)
+        total = float(class_idx.size)
+        fractions: dict[str, float] = {}
+        for u, c in zip(unique, counts, strict=False):
+            label = (LULC_CLASSES[int(u)] if 0 <= int(u) < len(LULC_CLASSES)
+                     else f"class_{int(u)}")
+            fractions[label] = round(100.0 * c / total, 2)
+        # Sort dominant -> tail for deterministic doc body ordering.
+        ordered = dict(sorted(fractions.items(),
+                              key=lambda kv: kv[1], reverse=True))
+        dominant_class = next(iter(ordered)) if ordered else "unknown"
+        dominant_pct = ordered.get(dominant_class, 0.0)
+        # Class indices map to TerraMesh's LULC tokenizer codebook; the
+        # exact label-to-index mapping isn't published. Surface a tentative
+        # name plus the raw index so a reader can see we're not asserting
+        # ground truth.
+        dominant_idx = next((i for i, lbl in enumerate(LULC_CLASSES)
+                             if lbl == dominant_class), -1)
+        dominant_display = (
+            f"class_{dominant_idx} (tentative: {dominant_class})"
+            if dominant_idx >= 0 else dominant_class
+        )
+
+        # Polygonize the categorical raster for the map layer.
+        # Best-effort — failure here doesn't fail the specialist.
+        try:
+            polygons_geojson = _polygonize_lulc(class_idx, bounds_4326)
+        except Exception:
+            log.exception("terramind: polygonize failed; skipping map layer")
+            polygons_geojson = None
+
+        return {
+            "ok": True,
+            "synthetic_modality": True,
+            "tim_chain": ["DEM", "LULC_synthetic"],
+            "diffusion_steps": DEFAULT_STEPS,
+            "diffusion_seed": DEFAULT_SEED,
+            "dem_mean_m": round(dem_mean, 2),
+            "class_fractions": ordered,
+            "dominant_class": dominant_class,
+            "dominant_class_display": dominant_display,
+            "dominant_pct": dominant_pct,
+            "n_classes_observed": len(ordered),
+            "chip_shape": list(lulc.shape),
+            "bounds_4326": list(bounds_4326),
+            "polygons_geojson": polygons_geojson,
+            "label_schema": "ESRI 2020-2022 Land Cover (tentative — "
+                            "TerraMind tokenizer source confirms ESRI but "
+                            "not exact label-to-index mapping)",
+            "elapsed_s": round(time.time() - t0, 2),
+        }
+    except Exception as e:
+        msg = str(e)
+        # Translate the torchvision binary-extension failure into a clean
+        # skip. The HF Space ships torchvision via a transitive sentence-
+        # transformers dep, but its C extension can't load alongside our
+        # CPU torch wheel, so terratorch's NMS call raises RuntimeError.
+        # Surface this honestly — the local inference path is unavailable
+        # on this deployment, same outcome as a missing terratorch.
+        if "torchvision::nms" in msg or "torchvision_C" in msg:
+            log.warning("terramind: torchvision binary unavailable on this "
+                        "deployment; skipping local inference")
+            return {"ok": False,
+                    "skipped": "local inference unavailable on this "
+                               "deployment (torchvision binary extension "
+                               "not loadable); no remote synthesis path",
+                    "elapsed_s": round(time.time() - t0, 2)}
+        log.exception("terramind: fetch failed")
+        return {"ok": False, "err": f"{type(e).__name__}: {e}",
+                "elapsed_s": round(time.time() - t0, 2)}

app/emissions.py

@@ -0,0 +1,269 @@
+"""Per-query emissions tracker for inference calls.
+
+Records every LLM and ML-inference call made during a single query and
+summarizes:
+  - wallclock duration per call
+  - prompt + completion tokens (LLM)
+  - energy in watt-hours, **measured from the L4 GPU when available**
+    (the inference proxy reports per-call `X-GPU-Power-W` /
+    `X-GPU-Energy-J` headers from a 100 ms-cadence NVML sampler).
+    Falls back to a duration × data-sheet-power estimate when the
+    proxy is unreachable / NVML init failed / call went to a backend
+    that doesn't surface power readings.
+
+Each call record carries a `measured: bool` flag indicating which path
+was used, so the UI can disclose. `summarize()` aggregates total Wh,
+total tokens, by-kind and by-hardware splits — no cloud comparison.
+
+Thread propagation
+------------------
+The tracker is held in a thread-local. The dispatch layer
+(web/main.py) installs one per request; `app/fsm.py:iter_steps`
+captures and re-installs it on the FSM runner thread (mirroring the
+existing `_captured_token_cb` pattern). Worker threads spawned inside
+specialists (prithvi_live, eo_chip_cache) inherit nothing — those calls
+are silently dropped, which is acceptable: those specialists do <1 s of
+inference each and are off the hot path for the energy story.
+"""
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+# (label, fallback_sustained_power_w, source). Used only when the
+# proxy doesn't surface a real measurement (NVML disabled, backend
+# unreachable, local-fallback path). The fallback figure is a
+# conservative public-record estimate; the `measured: bool` flag on
+# each call record indicates whether the row used the fallback.
+HARDWARE: dict[str, tuple[str, float, str]] = {
+    "nvidia_l4": (
+        "NVIDIA L4",
+        60.0,
+        "NVIDIA L4 Tensor Core GPU data sheet (72 W TGP, Ada Lovelace, "
+        "24 GB); ~60 W sustained during transformer inference. The "
+        "active backend for the Riprap inference Space "
+        "(msradam/riprap-vllm). When the proxy is reachable and NVML "
+        "is initialized, real per-call power is read off the device "
+        "via nvmlDeviceGetPowerUsage and this fallback is unused.",
+    ),
+    "amd_mi300x": (
+        "AMD MI300X",
+        600.0,
+        "AMD Instinct MI300X data sheet (750 W TDP); ~600 W sustained "
+        "during vLLM generation. Selected only when an operator deploys "
+        "against an MI300X droplet and sets RIPRAP_HARDWARE_LABEL=AMD "
+        "MI300X explicitly. The hackathon submission used to run on "
+        "this hardware; the droplet was decommissioned 2026-05-06.",
+    ),
+    "nvidia_t4": (
+        "NVIDIA T4",
+        50.0,
+        "NVIDIA T4 data sheet (70 W max); ~50 W sustained during "
+        "transformer inference.",
+    ),
+    "apple_m": (
+        "Apple M-series",
+        20.0,
+        "ml.energy / community measurements: ~20 W package power "
+        "during Granite 4.1 q4_K_M inference on Apple M3/M4 (the "
+        "local-dev path, no remote backend configured).",
+    ),
+    "cpu_server": (
+        "x86 CPU",
+        30.0,
+        "Typical sustained x86 server-core load (~30 W) for CPU-only "
+        "inference fallbacks.",
+    ),
+}
+
+
+def _wh(power_w: float, duration_s: float) -> float:
+    return power_w * max(duration_s, 0.0) / 3600.0
+
+
+class Tracker:
+    """Append-only call ledger for one query. Thread-safe."""
+
+    def __init__(self) -> None:
+        self.calls: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+
+    def _record(self, *, base: dict[str, Any], hardware: str,
+                duration_s: float,
+                joules_real: float | None,
+                power_w_real: float | None) -> None:
+        """Shared body of record_llm / record_ml.
+
+        When `joules_real` is provided (NVML-derived from the proxy),
+        we use it directly and stamp `measured=True`. Otherwise we
+        fall back to the data-sheet sustained-power estimate.
+        """
+        hw_label, fallback_w, _src = HARDWARE.get(hardware,
+                                                  HARDWARE["cpu_server"])
+        if joules_real is not None and joules_real >= 0:
+            joules = float(joules_real)
+            wh = joules / 3600.0
+            measured = True
+            avg_w = (joules / duration_s) if duration_s > 0 else (
+                power_w_real if power_w_real is not None else fallback_w)
+        else:
+            avg_w = fallback_w
+            wh = _wh(avg_w, duration_s)
+            joules = wh * 3600.0
+            measured = False
+        record = {
+            **base,
+            "hardware": hardware,
+            "hardware_label": hw_label,
+            "power_w": round(avg_w, 2),
+            "duration_s": round(duration_s, 3),
+            "measured": measured,
+            "wh": round(wh, 5),
+            "joules": round(joules, 3),
+        }
+        with self._lock:
+            self.calls.append(record)
+
+    def record_llm(self, *, model: str, backend: str, hardware: str,
+                   prompt_tokens: int | None,
+                   completion_tokens: int | None,
+                   duration_s: float,
+                   stream: bool = False,
+                   joules_real: float | None = None,
+                   power_w_real: float | None = None) -> None:
+        total = None
+        if prompt_tokens is not None or completion_tokens is not None:
+            total = (prompt_tokens or 0) + (completion_tokens or 0)
+        self._record(
+            base={
+                "kind": "llm",
+                "model": model,
+                "backend": backend,
+                "prompt_tokens": prompt_tokens,
+                "completion_tokens": completion_tokens,
+                "total_tokens": total,
+                "stream": stream,
+            },
+            hardware=hardware,
+            duration_s=duration_s,
+            joules_real=joules_real,
+            power_w_real=power_w_real,
+        )
+
+    def record_ml(self, *, endpoint: str, backend: str, hardware: str,
+                  duration_s: float,
+                  joules_real: float | None = None,
+                  power_w_real: float | None = None) -> None:
+        self._record(
+            base={
+                "kind": "ml",
+                "endpoint": endpoint,
+                "backend": backend,
+            },
+            hardware=hardware,
+            duration_s=duration_s,
+            joules_real=joules_real,
+            power_w_real=power_w_real,
+        )
+
+    def summarize(self) -> dict[str, Any]:
+        with self._lock:
+            calls = list(self.calls)
+        total_wh = sum(c["wh"] for c in calls)
+        total_dur = sum(c["duration_s"] for c in calls)
+        n_measured = sum(1 for c in calls if c.get("measured"))
+        prompt = sum((c.get("prompt_tokens") or 0)
+                     for c in calls if c["kind"] == "llm")
+        completion = sum((c.get("completion_tokens") or 0)
+                         for c in calls if c["kind"] == "llm")
+
+        by_kind: dict[str, dict[str, Any]] = {}
+        for c in calls:
+            slot = by_kind.setdefault(c["kind"], {"wh": 0.0, "n": 0,
+                                                  "duration_s": 0.0})
+            slot["wh"] += c["wh"]
+            slot["n"] += 1
+            slot["duration_s"] += c["duration_s"]
+        for slot in by_kind.values():
+            slot["wh"] = round(slot["wh"], 5)
+            slot["mwh"] = round(slot["wh"] * 1000, 2)
+            slot["duration_s"] = round(slot["duration_s"], 3)
+
+        by_hw: dict[str, dict[str, Any]] = {}
+        for c in calls:
+            slot = by_hw.setdefault(c["hardware"], {
+                "label": c["hardware_label"],
+                "wh": 0.0, "n": 0, "duration_s": 0.0,
+            })
+            slot["wh"] += c["wh"]
+            slot["n"] += 1
+            slot["duration_s"] += c["duration_s"]
+        for slot in by_hw.values():
+            slot["wh"] = round(slot["wh"], 5)
+            slot["mwh"] = round(slot["wh"] * 1000, 2)
+            slot["duration_s"] = round(slot["duration_s"], 3)
+
+        return {
+            "n_calls": len(calls),
+            "n_measured": n_measured,
+            "total_wh": round(total_wh, 5),
+            "total_mwh": round(total_wh * 1000, 2),
+            "total_joules": round(total_wh * 3600, 1),
+            "total_duration_s": round(total_dur, 3),
+            "tokens": {
+                "prompt": prompt or None,
+                "completion": completion or None,
+                "total": (prompt + completion) or None,
+            },
+            "by_kind": by_kind,
+            "by_hardware": by_hw,
+            "calls": calls,
+            "method": (
+                "Energy is read off the L4 GPU per call via "
+                "nvmlDeviceGetPowerUsage on the inference proxy "
+                "(X-GPU-Energy-J response header). Calls flagged "
+                "measured=false fall back to "
+                "(data-sheet sustained_power_w × duration_s ÷ 3600) "
+                "— see app/emissions.HARDWARE for sources. Tokens "
+                "are reported by the backend (LiteLLM usage) when "
+                "available, else estimated from response text length "
+                "(~4 chars/token)."
+            ),
+        }
+
+
+# Thread-local install. Calls made on threads without an installed
+# tracker hit a no-op stub — always safe to call active().record_*().
+_tl = threading.local()
+
+
+class _NullTracker:
+    def record_llm(self, **_kw: Any) -> None:
+        return None
+
+    def record_ml(self, **_kw: Any) -> None:
+        return None
+
+
+_NULL = _NullTracker()
+
+
+def install(tracker: Tracker | None) -> None:
+    _tl.tracker = tracker
+
+
+def current() -> Tracker | None:
+    return getattr(_tl, "tracker", None)
+
+
+def active() -> Tracker | _NullTracker:
+    """Return the installed tracker for this thread, or a no-op stub.
+    Always safe to call in instrumentation hot paths."""
+    return getattr(_tl, "tracker", None) or _NULL
+
+
+def estimate_completion_tokens(text: str) -> int:
+    """Rough char/4 estimator used when the backend doesn't report usage
+    (e.g. streaming through Ollama, where LiteLLM's stream wrapper does
+    not always surface a final usage block)."""
+    return max(1, len(text) // 4)

app/energy.py

@@ -0,0 +1,56 @@
+"""Per-query energy footprint estimate.
+
+Conservative, defensible numbers — no overclaim. We measure local
+inference time and apply a published-range package-power figure for
+Apple-Silicon LLM inference; we compare to the most recent published
+estimate of frontier-cloud per-query energy (Epoch AI, 2025).
+
+This is not a benchmark — it's a transparent rule-of-thumb that the
+user can audit. The system prompt and the UI both surface the
+underlying numbers and the citation.
+"""
+from __future__ import annotations
+
+# Local: Granite 4.1:3b on Apple M-series (M3/M4 Pro range)
+# Sustained package power during ~5 s of LLM inference, q4_K_M quant.
+# Source: ml.energy + community measurements; conservative midpoint.
+LOCAL_PACKAGE_POWER_W = 20.0
+
+# Frontier cloud per-query inference energy.
+# Source: Epoch AI, "How much energy does ChatGPT use?" (2025).
+# https://epoch.ai/gradient-updates/how-much-energy-does-chatgpt-use
+# This is a typical-query estimate for GPT-4o-class inference; long-context
+# queries scale roughly linearly with token count.
+CLOUD_PER_QUERY_WH = 0.30
+
+# Citation strings used in the UI.
+LOCAL_SOURCE = ("ml.energy / community measurements; ~20 W package power "
+                "during Granite 4.1:3b q4_K_M inference on Apple M-series.")
+CLOUD_SOURCE = ('Epoch AI (2025), "How much energy does ChatGPT use?", '
+                "estimating ~0.3 Wh per typical GPT-4o query.")
+
+
+def estimate(reconcile_seconds: float, total_seconds: float | None = None) -> dict:
+    """Return a per-query energy estimate.
+
+    Args:
+      reconcile_seconds: wallclock of the Granite reconcile step (the
+        only step that meaningfully draws CPU/GPU power).
+      total_seconds: optional full-FSM wallclock for context.
+    """
+    local_wh = LOCAL_PACKAGE_POWER_W * reconcile_seconds / 3600.0
+    return {
+        "local_wh": round(local_wh, 4),
+        "local_mwh": round(local_wh * 1000, 1),
+        "cloud_wh": CLOUD_PER_QUERY_WH,
+        "cloud_mwh": round(CLOUD_PER_QUERY_WH * 1000, 1),
+        "ratio_cloud_over_local": round(CLOUD_PER_QUERY_WH / local_wh, 1) if local_wh > 0 else None,
+        "method": {
+            "local": f"{LOCAL_PACKAGE_POWER_W} W × {reconcile_seconds:.2f} s ÷ 3600",
+            "local_source": LOCAL_SOURCE,
+            "cloud": f"{CLOUD_PER_QUERY_WH} Wh per query (published estimate)",
+            "cloud_source": CLOUD_SOURCE,
+        },
+        "reconcile_seconds": round(reconcile_seconds, 2),
+        "total_seconds": round(total_seconds, 2) if total_seconds is not None else None,
+    }

app/flood_layers/dep_stormwater.py

@@ -0,0 +1,168 @@
+"""NYC DEP Stormwater Flood Maps — pluvial scenarios.
+
+Four scenarios, all in EPSG:2263. Polygons are categorized by depth class:
+    1 = Nuisance Flooding (>4" and ≤1 ft)
+    2 = Deep and Contiguous Flooding (>1 ft and ≤4 ft)
+    3 = Deep Contiguous Flooding (>4 ft)
+
+Two query paths exist:
+    join_raster(point) — fast path. Samples the baked GeoTIFFs in
+        data/baked/. ~3 ms per scenario, ~70 ms cold-open. Used by
+        step_dep in the FSM.
+    join(assets)       — legacy GDB path via gpd.sjoin. Retained as
+        a fallback when baked rasters are absent (local dev) and as
+        the polygon-overlap path used by coverage_for_polygon for
+        neighborhood mode.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from functools import lru_cache
+
+import geopandas as gpd
+
+from app.spatial import DATA, NYC_CRS
+
+log = logging.getLogger(__name__)
+BAKED = DATA / "baked"
+_TLOCAL = threading.local()
+_FALLBACK_WARNED = False
+
+ROOT = DATA / "dep"
+
+SCENARIOS = {
+    "dep_extreme_2080": {
+        "gdb": "dep_extreme_2080.gdb",
+        "label": "DEP Extreme Stormwater (3.66 in/hr, 2080 SLR)",
+    },
+    "dep_moderate_2050": {
+        "gdb": "dep_moderate_2050.gdb",
+        "label": "DEP Moderate Stormwater (2.13 in/hr, 2050 SLR)",
+    },
+    "dep_moderate_current": {
+        "gdb": "dep_moderate_current.gdb",
+        "label": "DEP Moderate Stormwater (2.13 in/hr, current SLR)",
+    },
+}
+
+DEPTH_CLASS = {
+    1: "Nuisance (>4 in to 1 ft)",
+    2: "Deep & Contiguous (1-4 ft)",
+    3: "Deep Contiguous (>4 ft)",
+}
+
+
+@lru_cache(maxsize=4)
+def load(scenario: str) -> gpd.GeoDataFrame:
+    s = SCENARIOS[scenario]
+    path = ROOT / s["gdb"]
+    g = gpd.read_file(str(path))
+    if g.crs.to_string() != NYC_CRS:
+        g = g.to_crs(NYC_CRS)
+    return g
+
+
+def join(assets: gpd.GeoDataFrame, scenario: str) -> gpd.GeoDataFrame:
+    """Per-asset depth class, or 0 if outside scenario.
+
+    Returns a frame indexed like assets with columns: depth_class, depth_label.
+    Higher class wins on overlap.
+    """
+    z = load(scenario)
+    a = assets[["geometry"]].copy()
+    a["_aid"] = range(len(a))
+    j = gpd.sjoin(a, z[["Flooding_Category", "geometry"]],
+                  how="left", predicate="intersects")
+    # for each asset, take max category hit (3 dominates 1)
+    cat = (j.groupby("_aid")["Flooding_Category"].max()
+              .reindex(range(len(a)))
+              .fillna(0).astype(int))
+    out = a[["_aid"]].copy()
+    out["depth_class"] = cat.values
+    out["depth_label"] = out["depth_class"].map(lambda c: DEPTH_CLASS.get(c, "outside"))
+    return out[["depth_class", "depth_label"]].reset_index(drop=True)
+
+
+def label(scenario: str) -> str:
+    return SCENARIOS[scenario]["label"]
+
+
+def _raster_handles():
+    """Per-thread rasterio handle cache. rasterio.DatasetReader is not
+    safe to share across threads for concurrent .sample() calls; the
+    FSM runs each request on its own executor thread, so we keep one
+    handle set per thread."""
+    h = getattr(_TLOCAL, "handles", None)
+    if h is not None:
+        return h
+    import rasterio
+    h = {}
+    for s in SCENARIOS:
+        p = BAKED / f"{s}.tif"
+        if not p.exists():
+            return None
+        h[s] = rasterio.open(str(p))
+    _TLOCAL.handles = h
+    return h
+
+
+def join_raster(pt_geom_2263, scenario: str) -> int:
+    """Fast path. Returns the integer depth class (0=outside, 1/2/3) for a
+    single shapely Point in EPSG:2263. Falls back to the GDB join() path
+    if baked rasters are missing — emits a one-time warning so local dev
+    still works without the bake artifacts."""
+    global _FALLBACK_WARNED
+    h = _raster_handles()
+    if h is None:
+        if not _FALLBACK_WARNED:
+            log.warning(
+                "data/baked/dep_*.tif not found — falling back to GDB sjoin. "
+                "Run: uv run python scripts/bake_cornerstone_rasters.py"
+            )
+            _FALLBACK_WARNED = True
+        # legacy fallback — wrap point in a one-row GeoDataFrame
+        a = gpd.GeoDataFrame(geometry=[pt_geom_2263], crs=NYC_CRS)
+        return int(join(a, scenario).iloc[0]["depth_class"])
+    ds = h[scenario]
+    v = next(ds.sample([(pt_geom_2263.x, pt_geom_2263.y)]))
+    return int(v[0])
+
+
+def coverage_for_polygon(polygon, scenario: str,
+                         polygon_crs: str = "EPSG:4326") -> dict:
+    """Polygon-level summary: what fraction of the input polygon falls into
+    each depth class for a given DEP scenario? Used in neighborhood mode.
+
+    Returns:
+      {
+        'scenario':        scenario id,
+        'label':           human-readable scenario name,
+        'fraction_any':    fraction of polygon inside any flooded class,
+        'fraction_class':  {1: f, 2: f, 3: f} fraction in each class,
+        'polygon_area_m2': total polygon area,
+      }
+    """
+    z = load(scenario)
+    poly_gdf = gpd.GeoDataFrame(geometry=[polygon], crs=polygon_crs).to_crs(NYC_CRS)
+    poly_geom = poly_gdf.iloc[0].geometry
+    poly_ft2 = float(poly_geom.area)
+    sqft_to_m2 = 0.092903
+    fraction_class = {1: 0.0, 2: 0.0, 3: 0.0}
+    if poly_ft2:
+        for cat in (1, 2, 3):
+            sub = z[z["Flooding_Category"] == cat]
+            if sub.empty:
+                continue
+            inter = sub.geometry.intersection(poly_geom)
+            inter = inter[~inter.is_empty]
+            ft2 = float(inter.area.sum()) if len(inter) else 0.0
+            fraction_class[cat] = round(ft2 / poly_ft2, 4)
+    fraction_any = round(sum(fraction_class.values()), 4)
+    return {
+        "scenario":        scenario,
+        "label":           label(scenario),
+        "fraction_any":    fraction_any,
+        "fraction_class":  fraction_class,
+        "polygon_area_m2": round(poly_ft2 * sqft_to_m2, 1),
+    }

app/flood_layers/ida_hwm.py

@@ -0,0 +1,96 @@
+"""Hurricane Ida (Sept 2021) empirical flood extent — USGS high-water marks.
+
+This specialist plays the same role as Prithvi-EO 2.0 (Sen1Floods11)
+in the parent triangulation-engine: it provides empirical post-event
+flood evidence (versus the modeled scenarios from FEMA/DEP). Where
+Prithvi derives extent from Sentinel-1 SAR, USGS HWMs are surveyed
+ground-truth water marks. Both are valid empirical signals; HWMs
+are the public record for Ida specifically.
+
+Output per address: number of HWMs within radius, max water elevation
+(ft), nearest site description.
+"""
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+DATA = Path(__file__).resolve().parent.parent.parent / "data" / "ida_2021_hwms_ny.geojson"
+DOC_ID = "ida_hwm"
+CITATION = "USGS STN Hurricane Ida 2021 high-water marks (Event 312, NY)"
+
+
+@dataclass
+class HWMSummary:
+    n_within_radius: int
+    radius_m: int
+    max_elev_ft: float | None
+    max_height_above_gnd_ft: float | None
+    nearest_dist_m: float | None
+    nearest_site: str | None
+    nearest_elev_ft: float | None
+    sample_sites: list[str]
+    points: list[dict] | None = None  # per-mark for the map layer
+
+
+def _haversine_m(lat1, lon1, lat2, lon2):
+    R = 6371000.0
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp = math.radians(lat2 - lat1); dl = math.radians(lon2 - lon1)
+    a = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * R * math.asin(math.sqrt(a))
+
+
+@lru_cache(maxsize=1)
+def _load() -> list[dict]:
+    if not DATA.exists():
+        return []
+    with open(DATA) as f:
+        return json.load(f).get("features", [])
+
+
+def summary_for_point(lat: float, lon: float, radius_m: int = 1000) -> HWMSummary | None:
+    feats = _load()
+    if not feats:
+        return None
+    in_radius = []
+    nearest = (None, float("inf"), None)
+    for f in feats:
+        flon, flat = f["geometry"]["coordinates"]
+        d = _haversine_m(lat, lon, flat, flon)
+        if d <= radius_m:
+            in_radius.append((d, f))
+        if d < nearest[1]:
+            nearest = (f, d, None)
+    nf, nd, _ = nearest
+    elevs = [f["properties"].get("elev_ft") for _, f in in_radius
+             if f["properties"].get("elev_ft") is not None]
+    heights = [f["properties"].get("height_above_gnd") for _, f in in_radius
+               if f["properties"].get("height_above_gnd") is not None]
+    sites = [f["properties"].get("site_description") for _, f in in_radius]
+    sites = [s for s in sites if s][:5]
+    points = []
+    for d, f in in_radius[:50]:  # cap so SSE payload stays small
+        flon, flat = f["geometry"]["coordinates"]
+        p = f["properties"]
+        points.append({
+            "lat": flat, "lon": flon,
+            "site": p.get("site_description"),
+            "elev_ft": p.get("elev_ft"),
+            "height_above_gnd_ft": p.get("height_above_gnd"),
+            "distance_m": round(d, 1),
+        })
+    return HWMSummary(
+        n_within_radius=len(in_radius),
+        radius_m=radius_m,
+        max_elev_ft=round(max(elevs), 2) if elevs else None,
+        max_height_above_gnd_ft=round(max(heights), 2) if heights else None,
+        nearest_dist_m=round(nd, 0) if nf is not None else None,
+        nearest_site=nf["properties"].get("site_description") if nf else None,
+        nearest_elev_ft=nf["properties"].get("elev_ft") if nf else None,
+        sample_sites=sites,
+        points=points,
+    )

app/flood_layers/prithvi_live.py

@@ -0,0 +1,563 @@
+"""Prithvi-EO 2.0 (NYC Pluvial v2 fine-tune) live water segmentation.
+
+A per-query specialist: pulls the most recent low-cloud Sentinel-2 L2A
+scene over the address from Microsoft Planetary Computer, runs the
+NYC-specialized fine-tune, and reports % water within 500 m.
+
+Distinct from `app/flood_layers/prithvi_water.py`, which serves the
+offline-precomputed 2021 Ida polygons. This one is *fresh observation*
+each query — same doc_id (`prithvi_live`), but the underlying model
+has been swapped from the Sen1Floods11 base to
+`msradam/Prithvi-EO-2.0-NYC-Pluvial` (Apache-2.0, fine-tuned on AMD
+Instinct MI300X via AMD Developer Cloud — test flood IoU 0.5979,
+6× over the base). The base model is still loadable by setting
+RIPRAP_PRITHVI_LIVE_REPO to the IBM repo as a fallback.
+
+Network calls (STAC search + COG band reads) and a 300M-param model
+forward pass make this the slowest specialist after the LLM. Gated by
+RIPRAP_PRITHVI_LIVE_ENABLE so deployments without the deps installed
+silently skip it. Cloud-cover refuses out at 30%+ to honor the
+Sen1Floods11 training distribution.
+
+License: Apache-2.0. See experiments/shared/licenses.md.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import logging
+import os
+import threading
+import time
+from typing import Any
+
+log = logging.getLogger("riprap.prithvi_live")
+
+ENABLE = os.environ.get("RIPRAP_PRITHVI_LIVE_ENABLE", "1").lower() in ("1", "true", "yes")
+SEARCH_DAYS = int(os.environ.get("RIPRAP_PRITHVI_LIVE_SEARCH_DAYS", "120"))
+MAX_CLOUD_PCT = float(os.environ.get("RIPRAP_PRITHVI_LIVE_MAX_CLOUD", "30"))
+DEVICE = os.environ.get("RIPRAP_PRITHVI_LIVE_DEVICE", "cpu")
+
+# Default to the NYC Pluvial v2 fine-tune; override to the IBM-NASA base
+# (`ibm-nasa-geospatial/Prithvi-EO-2.0-300M-TL-Sen1Floods11`) when the v2
+# artifact is unreachable or for A/B comparisons.
+REPO = os.environ.get(
+    "RIPRAP_PRITHVI_LIVE_REPO",
+    "msradam/Prithvi-EO-2.0-NYC-Pluvial",
+)
+BASE_REPO = "ibm-nasa-geospatial/Prithvi-EO-2.0-300M-TL-Sen1Floods11"
+
+# Sen1Floods11 expects 6 bands in this exact order.
+BANDS = ["B02", "B03", "B04", "B8A", "B11", "B12"]
+IMG_SIZE = 512  # Sen1Floods11 training crop
+CHIP_PX = 1024
+CHIP_M = CHIP_PX * 10
+HALF_M = CHIP_M / 2
+CENTER_RADIUS_M = 500
+PIXEL_M = 10
+
+_MODEL = None
+_RUN_MODEL = None
+_INIT_LOCK = threading.Lock()  # serializes lazy load if multiple threads
+                               # hit fetch() before _MODEL is populated
+
+
+def _has_required_deps() -> tuple[bool, str | None]:
+    """Probe deps in two tiers.
+
+    Tier 1 — chip fetching (planetary_computer / pystac_client / rioxarray
+    / xarray / einops) is always required: prithvi_live always pulls a
+    Sentinel-2 chip from Microsoft Planetary Computer regardless of where
+    inference runs.
+
+    Tier 2 — local inference (terratorch) is only required when remote
+    inference is unavailable. On the HF Space we have remote inference
+    on the AMD MI300X via app/inference.py, so terratorch is not needed
+    even though chip-fetch is.
+
+    Returns (False, missing) if any required dep is missing. Splitting
+    the gate this way lets the HF Space deployment fetch chips and run
+    remote inference even though it doesn't fit terratorch's transitive
+    dep cone (~250 MB) in the HF build sandbox."""
+    chip_deps = ("planetary_computer", "pystac_client",
+                 "rioxarray", "xarray", "einops")
+    missing = [n for n in chip_deps
+               if not _has_module(n)]
+    if missing:
+        return False, ", ".join(missing)
+    # Tier 2: only need terratorch if we'd run inference locally.
+    try:
+        from app import inference as _inf
+        if _inf.remote_enabled():
+            return True, None
+    except Exception:
+        pass
+    if not _has_module("terratorch"):
+        return False, "terratorch (local inference)"
+    return True, None
+
+
+def _has_module(name: str) -> bool:
+    """True if `name` imports cleanly. ImportError → not installed.
+    Other exceptions (e.g. torchvision::nms RuntimeError on the HF
+    Space) → treat as unavailable too; we don't want a clean-skip
+    intent to crash the FSM at deps-probe time."""
+    try:
+        __import__(name)
+        return True
+    except ImportError:
+        return False
+    except Exception as e:
+        log.warning("prithvi_live: %s import raised %s; treating as "
+                    "unavailable", name, type(e).__name__)
+        return False
+
+
+_DEPS_OK, _DEPS_MISSING = _has_required_deps()
+
+
+def warm():
+    """Optional pre-load. The FSM action is lazy too — calling warm()
+    here just amortizes the first-query cost at app boot."""
+    if not ENABLE:
+        return
+    try:
+        _ensure_model()
+    except Exception:
+        log.exception("prithvi_live: warm() failed; specialist will no-op")
+
+
+def _ensure_model():
+    """Load Prithvi-EO 2.0 once into RAM.
+
+    The v2 NYC Pluvial fine-tune (`msradam/Prithvi-EO-2.0-NYC-Pluvial`)
+    is **architecturally distinct** from the IBM-NASA Sen1Floods11
+    base: v2 ships a `UNetDecoder` + 2-class head, the base ships a
+    UperNet with PSP / FPN. The model has to be built from each
+    repo's own config.yaml — there's no key-mapping shim that bridges
+    them.
+
+    Strategy:
+
+      1. If the active REPO != BASE_REPO, try to build from the v2
+         yaml + v2 ckpt. The v2 yaml's data: paths point at the
+         training droplet's filesystem (`/root/terramind_nyc/...`)
+         which doesn't exist locally; that's fine — the
+         GenericNonGeoSegmentationDataModule constructor only
+         records the paths, splits aren't read until `setup()`.
+      2. On any v2 failure (yaml not present, datamodule constructor
+         strict, weights mismatch), fall back to the base yaml + base
+         ckpt. The base path is the proven pre-C5 behaviour.
+
+    The shared `inference.run_model` helper is only published by the
+    IBM-NASA base repo; we always pull it from there.
+    """
+    global _MODEL, _RUN_MODEL
+    if _MODEL is not None:
+        return _MODEL, _RUN_MODEL
+    with _INIT_LOCK:
+        if _MODEL is not None:  # double-check inside the lock
+            return _MODEL, _RUN_MODEL
+        import importlib.util
+
+        from huggingface_hub import hf_hub_download
+        from terratorch.cli_tools import LightningInferenceModel
+        log.info("prithvi_live: loading model from %s", REPO)
+
+        # Inference helper only lives in the IBM-NASA base repo.
+        inference_py = hf_hub_download(BASE_REPO, "inference.py")
+
+        m = None
+        # ---- v2 path: yaml + ckpt from the published repo ----------
+        if REPO != BASE_REPO:
+            try:
+                # The v2 repo publishes `prithvi_nyc_phase14.yaml` and
+                # `prithvi_nyc_pluvial_v2.ckpt`. Be tolerant of small
+                # naming drift (best_val_loss.ckpt etc.) by probing.
+                v2_yaml = None
+                for name in ("prithvi_nyc_phase14.yaml",
+                              "config.yaml", "phase14.yaml",
+                              "prithvi_nyc_v2.yaml"):
+                    try:
+                        v2_yaml = hf_hub_download(REPO, name)
+                        break
+                    except Exception:
+                        continue
+                v2_ckpt = None
+                for name in ("prithvi_nyc_pluvial_v2.ckpt",
+                              "best_val_loss.ckpt", "model.ckpt",
+                              "last.ckpt"):
+                    try:
+                        v2_ckpt = hf_hub_download(REPO, name)
+                        break
+                    except Exception:
+                        continue
+                if v2_yaml and v2_ckpt:
+                    log.info("prithvi_live: building v2 model from "
+                             "yaml=%s ckpt=%s", v2_yaml, v2_ckpt)
+                    m = LightningInferenceModel.from_config(v2_yaml, v2_ckpt)
+                    # prithvi_nyc_phase14.yaml uses GenericNonGeoSegmentationDataModule
+                    # which omits test_transform (→ None) and uses terratorch Normalize
+                    # for aug (only handles 4D/5D). IBM inference.py:run_model() calls
+                    # both on a 3D dict. Patch both to match the IBM base contract:
+                    # ToTensorV2 for test_transform; Kornia AugmentationSequential
+                    # (accepts dict input, adds batch dim) for aug.
+                    if getattr(getattr(m, 'datamodule', None),
+                               'test_transform', None) is None:
+                        import albumentations as A
+                        import torch as _torch
+                        from albumentations.pytorch import ToTensorV2
+                        m.datamodule.test_transform = A.Compose([ToTensorV2()])
+                        _old = m.datamodule.aug
+
+                        # IBM's inference.py:188 calls
+                        # `datamodule.aug({'image': tensor})['image']`.
+                        # kornia's AugmentationSequential doesn't accept
+                        # dict input cleanly and tripped the
+                        # `'list' object has no attribute 'view'`
+                        # error on the L4 deploy. Use a hand-rolled
+                        # dict-aware normalizer instead — same math,
+                        # fewer moving parts, no kornia version skew.
+                        class _DictNormalize:
+                            def __init__(self, mean, std):
+                                self.mean = _torch.as_tensor(mean).view(-1, 1, 1).float()
+                                self.std = _torch.as_tensor(std).view(-1, 1, 1).float()
+
+                            def __call__(self, sample):
+                                if isinstance(sample, dict):
+                                    img = sample["image"]
+                                    mean = self.mean.to(img.device)
+                                    std = self.std.to(img.device)
+                                    return {**sample, "image": (img - mean) / std}
+                                mean = self.mean.to(sample.device)
+                                std = self.std.to(sample.device)
+                                return (sample - mean) / std
+
+                        # `_old.means` / `_old.stds` come from the
+                        # yaml as Python lists — calling `.view()` on
+                        # them is what tripped the original
+                        # `'list' object has no attribute 'view'`.
+                        # _DictNormalize handles the conversion via
+                        # torch.as_tensor internally; just pass the
+                        # raw values whatever their type.
+                        m.datamodule.aug = _DictNormalize(_old.means, _old.stds)
+                        log.info("prithvi_live: patched v2 datamodule transforms "
+                                 "for IBM inference.py compat (dict-aware Normalize)")
+                else:
+                    log.warning("prithvi_live: v2 yaml/ckpt not "
+                                "discoverable in %s; falling back to base",
+                                REPO)
+            except Exception as e:
+                log.warning("prithvi_live: v2 build failed (%s); "
+                             "falling back to base", e)
+                m = None
+
+        # ---- base path: proven IBM-NASA Sen1Floods11 fine-tune -----
+        if m is None:
+            base_config = hf_hub_download(BASE_REPO, "config.yaml")
+            base_ckpt = hf_hub_download(
+                BASE_REPO, "Prithvi-EO-V2-300M-TL-Sen1Floods11.pt")
+            m = LightningInferenceModel.from_config(base_config, base_ckpt)
+
+        m.model.eval()
+        if DEVICE == "cuda":
+            try:
+                import torch
+                if torch.cuda.is_available():
+                    m.model.cuda()
+            except Exception:
+                log.exception("prithvi_live: cuda move failed")
+
+        spec = importlib.util.spec_from_file_location("_prithvi_inference",
+                                                       inference_py)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        _MODEL = m
+        _RUN_MODEL = mod.run_model
+        return _MODEL, _RUN_MODEL
+
+
+def _search_recent_scene(lat: float, lon: float):
+    """Most recent low-cloud S2 L2A item near (lat, lon) in the last
+    SEARCH_DAYS days, or None."""
+    import datetime as dt
+
+    import planetary_computer as pc
+    from pystac_client import Client
+    end = dt.datetime.utcnow().date()
+    start = end - dt.timedelta(days=SEARCH_DAYS)
+    client = Client.open(
+        "https://planetarycomputer.microsoft.com/api/stac/v1",
+        modifier=pc.sign_inplace,
+    )
+    delta = 0.02
+    search = client.search(
+        collections=["sentinel-2-l2a"],
+        bbox=[lon - delta, lat - delta, lon + delta, lat + delta],
+        datetime=f"{start}/{end}",
+        query={"eo:cloud_cover": {"lt": MAX_CLOUD_PCT}},
+        max_items=20,
+    )
+    items = sorted(
+        search.items(),
+        key=lambda it: (it.properties.get("eo:cloud_cover", 100),
+                        -(it.datetime.timestamp() if it.datetime else 0)),
+    )
+    return items[0] if items else None
+
+
+def _build_chip(item, lat: float, lon: float):
+    """Returns (img, ref_da, epsg) — img is the (6, H, W) center-cropped
+    float32 array; ref_da is the rioxarray DataArray of the reference
+    band BEFORE the center crop (kept so we can compute the affine
+    transform for polygonization in EPSG:4326)."""
+    import numpy as np
+    import rioxarray  # noqa: F401
+    import xarray as xr
+    from pyproj import Transformer
+    if "proj:epsg" in item.properties:
+        epsg = int(item.properties["proj:epsg"])
+    else:
+        code = item.properties.get("proj:code", "")
+        if code.startswith("EPSG:"):
+            epsg = int(code.split(":", 1)[1])
+        else:
+            raise RuntimeError("STAC item missing proj:epsg / proj:code")
+    fwd = Transformer.from_crs("EPSG:4326", f"EPSG:{epsg}", always_xy=True)
+    cx, cy = fwd.transform(lon, lat)
+    xmin, xmax = cx - HALF_M, cx + HALF_M
+    ymin, ymax = cy - HALF_M, cy + HALF_M
+    ref = rioxarray.open_rasterio(item.assets[BANDS[0]].href, masked=False).squeeze(drop=True)
+    ref = ref.rio.clip_box(minx=xmin, miny=ymin, maxx=xmax, maxy=ymax)
+    ref = ref.isel(y=slice(0, CHIP_PX), x=slice(0, CHIP_PX))
+    arrs = [ref.astype("float32")]
+    for b in BANDS[1:]:
+        da = rioxarray.open_rasterio(item.assets[b].href, masked=False).squeeze(drop=True)
+        da = da.rio.clip_box(minx=xmin, miny=ymin, maxx=xmax, maxy=ymax)
+        if da.shape != ref.shape:
+            da = da.rio.reproject_match(ref)
+        arrs.append(da.astype("float32"))
+    stacked = xr.concat(arrs, dim="band", join="override").assign_coords(band=BANDS)
+    img = stacked.values  # (6, H, W)
+    # Center crop to IMG_SIZE x IMG_SIZE.
+    _, h, w = img.shape
+    sy, sx = (h - IMG_SIZE) // 2, (w - IMG_SIZE) // 2
+    img = img[:, sy:sy + IMG_SIZE, sx:sx + IMG_SIZE]
+    if img.mean() > 1:
+        img = img / 10000.0
+    return np.nan_to_num(img.astype("float32")), ref, epsg
+
+
+def _polygonize_mask(pred, ref_da, epsg: int) -> dict | None:
+    """Vectorize the binary water mask into an EPSG:4326 GeoJSON
+    FeatureCollection so the frontend can paint it on the MapLibre
+    map. Returns None on failure (best-effort — never raises into the
+    caller path)."""
+    try:
+        import json
+
+        import geopandas as gpd
+        from rasterio.features import shapes
+        from rasterio.transform import from_origin
+        from shapely.geometry import shape
+        # Reconstruct the affine transform of the center-cropped pred.
+        # ref_da has 1024 px at 10 m; we cropped to the central 512.
+        xs = ref_da.x.values
+        ys = ref_da.y.values
+        if len(xs) < IMG_SIZE or len(ys) < IMG_SIZE:
+            return None
+        # rioxarray gives pixel-centered coords; offset by half a pixel
+        # to the upper-left to build a from_origin transform.
+        sy = (len(ys) - IMG_SIZE) // 2
+        sx = (len(xs) - IMG_SIZE) // 2
+        # ys are descending (top-to-bottom); take the top of the crop.
+        top_y = float(ys[sy]) + (PIXEL_M / 2.0)
+        left_x = float(xs[sx]) - (PIXEL_M / 2.0)
+        transform = from_origin(left_x, top_y, PIXEL_M, PIXEL_M)
+        # Polygonize only the water class (1).
+        mask = (pred == 1).astype("uint8")
+        polys = []
+        for geom, value in shapes(mask, mask=mask.astype(bool),
+                                   transform=transform):
+            if value != 1:
+                continue
+            polys.append(shape(geom))
+        if not polys:
+            return {"type": "FeatureCollection", "features": []}
+        gdf = gpd.GeoDataFrame({"geometry": polys},
+                                crs=f"EPSG:{epsg}").to_crs("EPSG:4326")
+        # Simplify slightly to keep the SSE payload small (10 m raster
+        # over 5 km square = up to ~10 k tiny squares; simplification
+        # collapses adjacent water pixels into smooth polygons).
+        gdf["geometry"] = gdf.geometry.simplify(0.00005, preserve_topology=True)
+        return json.loads(gdf.to_json())
+    except Exception:
+        log.exception("prithvi_live: polygonize failed")
+        return None
+
+
+def _fetch_inner(lat: float, lon: float, timeout_s: float) -> dict[str, Any]:
+    """Core fetch logic — run inside a bounded thread via fetch()."""
+    t0 = time.time()
+    try:
+        item = _search_recent_scene(lat, lon)
+        if item is None:
+            return {"ok": False, "skipped": f"no <{MAX_CLOUD_PCT}% cloud "
+                    f"S2 in last {SEARCH_DAYS}d"}
+        cc = float(item.properties.get("eo:cloud_cover", -1))
+        if time.time() - t0 > timeout_s:
+            return {"ok": False, "skipped": "stac search exceeded budget"}
+        img, ref_da, epsg = _build_chip(item, lat, lon)
+        if time.time() - t0 > timeout_s:
+            return {"ok": False, "skipped": "chip build exceeded budget"}
+
+        # v0.4.5 — try the MI300X inference service first if configured.
+        # On RemoteUnreachable (service down / not configured / 5xx) fall
+        # through to the local terratorch path. When remote is configured
+        # but returns non-ok we surface that signal directly: the local
+        # path on this machine has been brittle (v2 datamodule
+        # `test_transform=None` race), so a configured remote is more
+        # reliable than the fallback.
+        remote_attempted = False
+        try:
+            from app import inference as _inf
+            if _inf.remote_enabled():
+                remote_attempted = True
+                remote = _inf.prithvi_pluvial(
+                    img, scene_id=item.id,
+                    scene_datetime=str(item.datetime),
+                    cloud_cover=cc,
+                    timeout=timeout_s,
+                )
+                if remote.get("ok"):
+                    # Vectorize the remote prediction raster so the map
+                    # actually renders the live water polygons. The
+                    # droplet returns `pred_b64` (uint8 binary mask);
+                    # we polygonize against the chip's WGS84 bounds
+                    # which we know locally from `ref_da`.
+                    polys = None
+                    pred_b64 = remote.get("pred_b64")
+                    pred_shape = remote.get("pred_shape")
+                    if pred_b64 and pred_shape:
+                        try:
+                            xs = ref_da.x.values
+                            ys = ref_da.y.values
+                            from pyproj import Transformer
+                            t_inv = Transformer.from_crs(
+                                f"EPSG:{epsg}", "EPSG:4326",
+                                always_xy=True)
+                            minx, maxx = float(xs.min()), float(xs.max())
+                            miny, maxy = float(ys.min()), float(ys.max())
+                            minlon, minlat = t_inv.transform(minx, miny)
+                            maxlon, maxlat = t_inv.transform(maxx, maxy)
+                            from app.context._polygonize import (
+                                polygonize_binary_mask,
+                            )
+                            polys = polygonize_binary_mask(
+                                pred_b64, pred_shape,
+                                (minlon, minlat, maxlon, maxlat),
+                                label="water", fill_color="#1F77B4",
+                                simplify_tolerance=2e-5,
+                            )
+                        except Exception:
+                            log.exception("prithvi_live: remote polygonize failed")
+                            polys = None
+                    return {
+                        "ok": True,
+                        "item_id": item.id,
+                        "item_datetime": str(item.datetime),
+                        "cloud_cover": cc,
+                        "pct_water_full": remote.get("pct_water_full"),
+                        "pct_water_within_500m": remote.get("pct_water_within_500m"),
+                        "polygons_geojson": polys,
+                        "compute": f"remote · {remote.get('device', 'gpu')}",
+                        "elapsed_s": round(time.time() - t0, 2),
+                    }
+                err = (remote.get("err")
+                       or remote.get("error")
+                       or remote.get("skipped")
+                       or "unknown")
+                return {"ok": False,
+                        "skipped": f"remote prithvi-pluvial non-ok: {err}",
+                        "elapsed_s": round(time.time() - t0, 2)}
+        except _inf.RemoteUnreachable as e:
+            log.info("prithvi_live: remote unreachable (%s)", e)
+            if remote_attempted:
+                # Don't fall to local — torchvision::nms is broken on the
+                # CPU-tier UI Spaces and crashes the FSM specialist with
+                # a confusing RuntimeError. Return a clean skipped row so
+                # the trace says "remote unreachable" instead.
+                return {"ok": False,
+                        "skipped": f"remote prithvi-pluvial unreachable: {e}",
+                        "elapsed_s": round(time.time() - t0, 2)}
+        except Exception as e:
+            log.exception("prithvi_live: remote call failed")
+            if remote_attempted:
+                return {"ok": False,
+                        "skipped": f"remote prithvi-pluvial error: "
+                                   f"{type(e).__name__}: {e}",
+                        "elapsed_s": round(time.time() - t0, 2)}
+
+        # Local fallback — the path that's been live since v0.4.4.
+        # Reached only when remote_attempted is False (i.e. remote
+        # backend not configured at all).
+        model, run_model = _ensure_model()
+        x = img[None, :, None, :, :]  # (1, 6, 1, H, W)
+        pred_t = run_model(x, None, None, model.model, model.datamodule, IMG_SIZE)
+        import numpy as np
+        pred = pred_t[0].cpu().numpy().astype("uint8")
+        pct_full = float(100.0 * pred.mean())
+        yy, xx = np.indices(pred.shape)
+        cy, cx = pred.shape[0] // 2, pred.shape[1] // 2
+        radius_px = CENTER_RADIUS_M / PIXEL_M
+        circle = (yy - cy) ** 2 + (xx - cx) ** 2 <= radius_px ** 2
+        pct_500 = float(100.0 * pred[circle].mean()) if circle.sum() else 0.0
+        polygons_geojson = _polygonize_mask(pred, ref_da, epsg)
+        return {
+            "ok": True,
+            "item_id": item.id,
+            "item_datetime": str(item.datetime),
+            "cloud_cover": cc,
+            "pct_water_full": pct_full,
+            "pct_water_within_500m": pct_500,
+            "polygons_geojson": polygons_geojson,
+            "compute": "local",
+            "elapsed_s": round(time.time() - t0, 2),
+        }
+    except Exception as e:
+        log.exception("prithvi_live: fetch failed")
+        return {"ok": False, "err": f"{type(e).__name__}: {e}",
+                "elapsed_s": round(time.time() - t0, 2)}
+
+
+def fetch(lat: float, lon: float, timeout_s: float = 60.0) -> dict[str, Any]:
+    """Run the specialist. Wraps _fetch_inner in a bounded thread so that
+    STAC searches and COG band reads (which lack per-request HTTP timeouts)
+    cannot hang the FSM indefinitely.
+
+    Returns a dict with at minimum:
+        { "ok": bool, "skipped": str | None, "item_id": str | None,
+          "cloud_cover": float | None, "pct_water_within_500m": float | None }
+    Designed to never raise; failures show up as ok=False with an `err`.
+    """
+    if not ENABLE:
+        return {"ok": False, "skipped": "RIPRAP_PRITHVI_LIVE_ENABLE=0"}
+    if not _DEPS_OK:
+        return {"ok": False,
+                "skipped": f"deps unavailable on this deployment: "
+                           f"{_DEPS_MISSING}"}
+    hard_timeout = timeout_s + 15.0
+    from app import emissions as _emissions
+    _parent_tracker = _emissions.current()
+    with concurrent.futures.ThreadPoolExecutor(
+        max_workers=1,
+        initializer=lambda t=_parent_tracker: _emissions.install(t),
+    ) as pool:
+        future = pool.submit(_fetch_inner, lat, lon, timeout_s)
+        try:
+            return future.result(timeout=hard_timeout)
+        except concurrent.futures.TimeoutError:
+            log.warning("prithvi_live: hard timeout after %.0fs (STAC/COG hung)",
+                        hard_timeout)
+            return {"ok": False,
+                    "skipped": f"prithvi_live timed out after {hard_timeout:.0f}s"}

app/flood_layers/prithvi_water.py

@@ -0,0 +1,120 @@
+"""Prithvi-EO 2.0 (Sen1Floods11) satellite flood inundation specialist.
+
+The 300M-parameter Prithvi-EO foundation model (NASA/IBM, Apache-2.0)
+was run twice offline on Hurricane Ida 2021 pre/post HLS Sentinel-2
+scenes over central NYC:
+
+    pre :  HLS.S30.T18TWK.2021237T153809  (2021-08-25,  3% cloud)
+    post:  HLS.S30.T18TWK.2021245T154911  (2021-09-02,  1% cloud,
+                                           ~12 hours after peak rainfall)
+
+The diff (post-water minus pre-water, filtered to ≥3-cell polygons)
+isolates surface water present 12 hours after Ida that wasn't present
+the prior week — i.e., candidate Ida-attributable inundation. We ship
+the resulting polygons as a flood-layer specialist; per query we
+compute proximity from the address to the nearest such polygon.
+
+Honest scope:
+- Sub-surface flooding (subway entrances, basement apartments — the
+  dominant Ida damage mode in NYC) is not visible to optical satellites.
+- Pluvial street water had largely drained by the Sep 2 16:02Z pass,
+  so the residual Prithvi signal mostly captures marsh ponding,
+  riverside spillover, and low-lying park inundation.
+- The model fired on Ida itself (a real flood event), not a synthetic
+  fallback — that's the architectural value.
+"""
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+DATA_DIR = Path(__file__).resolve().parent.parent.parent / "data"
+DOC_ID = "prithvi_water"
+CITATION = ("Prithvi-EO-2.0-300M-TL-Sen1Floods11 (NASA/IBM, Apache-2.0, via "
+            "TerraTorch). Hurricane Ida pre/post diff: pre HLS T18TWK "
+            "2021-08-25 (3% cloud), post HLS T18TWK 2021-09-02 (1% cloud, "
+            "~12h after peak rainfall).")
+
+
+@dataclass
+class PrithviSummary:
+    inside_water_polygon: bool
+    nearest_distance_m: float | None
+    n_polygons_within_500m: int
+    scene_id: str
+    scene_date: str
+
+
+def _haversine_m(lat1, lon1, lat2, lon2):
+    R = 6371000.0
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp = math.radians(lat2 - lat1); dl = math.radians(lon2 - lon1)
+    a = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * R * math.asin(math.sqrt(a))
+
+
+@lru_cache(maxsize=1)
+def _load():
+    """Load the merged Prithvi water mask (combined across NYC MGRS tiles)
+    as a GeoDataFrame in NYC state plane (EPSG:2263) for fast metric
+    distance queries."""
+    import geopandas as gpd
+    # Prefer the Ida flood-event diff (real flood-attribution signal);
+    # fall back to clear-day permanent-water masks if the Ida file is absent.
+    candidates = [
+        DATA_DIR / "prithvi_ida_2021.geojson",
+        DATA_DIR / "prithvi_flood_nyc.geojson",
+    ]
+    candidates += sorted(DATA_DIR.glob("prithvi_flood_*.geojson"), reverse=True)
+    path = next((p for p in candidates if p.exists()), None)
+    if path is None:
+        return None, None
+    with open(path) as f:
+        meta = json.load(f)
+    g = gpd.read_file(path)
+    if g.crs is None:
+        g.set_crs("EPSG:4326", inplace=True)
+    g = g.to_crs("EPSG:2263")
+    return g, meta
+
+
+def warm() -> None:
+    _load()
+
+
+def summary_for_point(lat: float, lon: float) -> PrithviSummary | None:
+    import geopandas as gpd
+    from shapely.geometry import Point
+    g, meta = _load()
+    if g is None:
+        return None
+    pt_wgs = gpd.GeoSeries([Point(lon, lat)], crs="EPSG:4326")
+    pt_2263 = pt_wgs.to_crs("EPSG:2263").iloc[0]
+    inside = bool(g.contains(pt_2263).any())
+
+    # nearest distance (feet -> metres)
+    distances_ft = g.geometry.distance(pt_2263)
+    nearest_ft = float(distances_ft.min()) if len(distances_ft) else None
+    nearest_m = round(nearest_ft / 3.281, 1) if nearest_ft is not None else None
+
+    within_500m = int((distances_ft <= 500 * 3.281).sum())
+
+    # The Ida pre/post artifact carries pre_/post_ scene info; the clear-day
+    # artifact carries scene_ids[]. Format compactly for either case.
+    if "post_scene_id" in meta:
+        sid = f"pre {meta['pre_scene_id']} | post {meta['post_scene_id']}"
+        sdate = f"pre {meta['pre_scene_date']}, post {meta['post_scene_date']}"
+    else:
+        sid = meta.get("scene_id") or ", ".join(meta.get("scene_ids", []) or ["unknown"])
+        sdate = meta.get("scene_date") or ", ".join(meta.get("scene_dates", []) or ["unknown"])
+
+    return PrithviSummary(
+        inside_water_polygon=inside,
+        nearest_distance_m=nearest_m,
+        n_polygons_within_500m=within_500m,
+        scene_id=sid,
+        scene_date=sdate,
+    )

app/flood_layers/sandy_inundation.py

@@ -0,0 +1,110 @@
+"""NYC Sandy Inundation Zone (empirical 2012 extent, NYC OD 5xsi-dfpx).
+
+Two query paths exist:
+    inside_raster(point) — fast path. Samples data/baked/sandy.tif.
+        ~1 ms; used by step_sandy in the FSM.
+    join(assets)         — legacy GeoJSON sjoin path. Retained as a
+        fallback when the baked raster is absent (local dev) and
+        for coverage_for_polygon (neighborhood mode).
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from functools import lru_cache
+
+import geopandas as gpd
+
+from app.spatial import DATA, NYC_CRS, load_layer
+
+DOC_ID = "sandy_inundation"
+CITATION = "NYC Sandy Inundation Zone (NYC OpenData 5xsi-dfpx, empirical 2012 extent)"
+
+log = logging.getLogger(__name__)
+BAKED = DATA / "baked"
+_TLOCAL = threading.local()
+_FALLBACK_WARNED = False
+
+
+@lru_cache(maxsize=1)
+def load() -> gpd.GeoDataFrame:
+    g = load_layer(DATA / "sandy_inundation.geojson")
+    return g[["geometry"]]
+
+
+def join(assets: gpd.GeoDataFrame) -> gpd.pd.Series:
+    """Return a boolean Series indexed like assets: True if inside Sandy zone."""
+    z = load()
+    # spatial join avoids fragile unary union over messy public polygons
+    hits = gpd.sjoin(
+        assets[["geometry"]].assign(_aid=range(len(assets))),
+        z[["geometry"]],
+        how="left",
+        predicate="intersects",
+    )
+    flagged = hits.dropna(subset=["index_right"])["_aid"].unique()
+    s = assets.geometry.copy().astype(bool)
+    s[:] = False
+    s.iloc[list(flagged)] = True
+    return s.reset_index(drop=True)
+
+
+def _raster_handle():
+    """Per-thread rasterio handle. See dep_stormwater._raster_handles."""
+    h = getattr(_TLOCAL, "handle", None)
+    if h is not None:
+        return h
+    p = BAKED / "sandy.tif"
+    if not p.exists():
+        return None
+    import rasterio
+    h = rasterio.open(str(p))
+    _TLOCAL.handle = h
+    return h
+
+
+def inside_raster(pt_geom_2263) -> bool:
+    """Fast path. True if the shapely Point (in EPSG:2263) falls inside the
+    2012 Sandy inundation extent. Falls back to the GeoJSON sjoin path if
+    data/baked/sandy.tif is missing."""
+    global _FALLBACK_WARNED
+    h = _raster_handle()
+    if h is None:
+        if not _FALLBACK_WARNED:
+            log.warning(
+                "data/baked/sandy.tif not found — falling back to GeoJSON sjoin. "
+                "Run: uv run python scripts/bake_cornerstone_rasters.py"
+            )
+            _FALLBACK_WARNED = True
+        a = gpd.GeoDataFrame(geometry=[pt_geom_2263], crs=NYC_CRS)
+        return bool(join(a).iloc[0])
+    v = next(h.sample([(pt_geom_2263.x, pt_geom_2263.y)]))
+    return bool(int(v[0]))
+
+
+def coverage_for_polygon(polygon, polygon_crs: str = "EPSG:4326") -> dict:
+    """Polygon-level summary: what fraction of the input polygon overlaps
+    the 2012 Sandy inundation extent? Used in neighborhood-mode queries.
+
+    Returns:
+      {
+        'overlap_area_m2':   absolute overlap in m2,
+        'polygon_area_m2':   total polygon area in m2,
+        'fraction':          overlap / polygon_area, range [0, 1],
+        'inside':            True if any overlap exists,
+      }
+    """
+    z = load().to_crs("EPSG:2263")  # NY State Plane Long Island, units = ft
+    poly_gdf = gpd.GeoDataFrame(geometry=[polygon], crs=polygon_crs).to_crs("EPSG:2263")
+    poly_geom = poly_gdf.iloc[0].geometry
+    inter = z.intersection(poly_geom)
+    inter = inter[~inter.is_empty]
+    overlap_ft2 = float(inter.area.sum()) if len(inter) else 0.0
+    poly_ft2 = float(poly_geom.area)
+    sqft_to_m2 = 0.092903
+    return {
+        "overlap_area_m2":   round(overlap_ft2 * sqft_to_m2, 1),
+        "polygon_area_m2":   round(poly_ft2 * sqft_to_m2, 1),
+        "fraction":          round(overlap_ft2 / poly_ft2, 4) if poly_ft2 else 0.0,
+        "inside":            overlap_ft2 > 0,
+    }

app/framing.py

@@ -0,0 +1,249 @@
+"""Question-aware framing for the Capstone briefing opening.
+
+The four-section structure (Status / Empirical / Modeled / Policy) is
+load-bearing for the Mellea grounding checks and stays unchanged. What
+this module does is detect the *shape* of the user's question from the
+raw query string + planner intent, then return a single-sentence
+directive that conditions only the opening Status sentence.
+
+Eleven question types are recognised; they mirror the rubric in
+`tests/integration/stakeholder_queries.py:FRAMING_RUBRICS`. Detection
+is deterministic regex matching — no extra LLM call, no added latency.
+
+Usage:
+
+    from app.framing import augment_system_prompt
+    system_prompt = augment_system_prompt(
+        EXTRA_SYSTEM_PROMPT, query=user_query, intent=plan.intent,
+    )
+
+The returned prompt has the original text plus a trailing
+`QUESTION-AWARE OPENING:` block. Granite 4.1 attends to this through
+the system-prompt cache and applies it to the Status sentence.
+"""
+from __future__ import annotations
+
+import re
+from typing import Final
+
+QUESTION_TYPES: Final[tuple[str, ...]] = (
+    "habitability_decision",
+    "legal_disclosure",
+    "capital_planning",
+    "underwriting",
+    "journalism",
+    "development_siting",
+    "grant_evidence",
+    "retrospective",
+    "emergency_response",
+    "comparison",
+    "generic_exposure",
+)
+
+
+# ---- Per-type opening directives ------------------------------------------
+#
+# Each directive is one sentence that supplements (does not replace) the
+# Status section's existing instruction. Granite 4.1 has a strong prior
+# toward "this address is exposed to ..." openings; the directive
+# overrides that in a question-shaped way without disturbing the four
+# grounding invariants.
+
+_DIRECTIVES: dict[str, str] = {
+    "habitability_decision": (
+        "The Status sentence MUST start with a direct verdict word "
+        "(\"Yes\" if the documents show meaningful flood evidence, \"No\" "
+        "if they don't), then name the single strongest piece of "
+        "evidence with its [doc_id]. The user is deciding whether to "
+        "live here — answer the question, then cite."
+    ),
+    "legal_disclosure": (
+        "The Status sentence MUST state whether the documents contain "
+        "facts a NY RPL §462(2) or §231-b disclosure would need to "
+        "record. Begin with \"Disclosure is warranted\" or \"Disclosure "
+        "is not triggered\" based on the evidence, then name the "
+        "specific fact with its [doc_id]. The user is a real-estate "
+        "professional checking the disclosure threshold."
+    ),
+    "capital_planning": (
+        "The Status sentence MUST frame the place as a capital-planning "
+        "candidate: name the dominant exposure with its [doc_id] and "
+        "indicate whether the evidence supports prioritization "
+        "(\"merits prioritization\", \"ranks high for hardening\") or "
+        "not. The user allocates infrastructure investment."
+    ),
+    "underwriting": (
+        "The Status sentence MUST emphasize that every figure in the "
+        "briefing is independently sourced — open with the dominant "
+        "exposure and the specific [doc_id], then add a half-clause "
+        "noting that the audit chain follows below. The user is an "
+        "underwriter who needs a defensible loss narrative."
+    ),
+    "journalism": (
+        "The Status sentence MUST be reproducible reporting prose: "
+        "name the place, name the dominant exposure with [doc_id], "
+        "and avoid editorial verbs like \"shocking\" or \"alarming\". "
+        "The user is a data journalist who will cite this prose verbatim."
+    ),
+    "development_siting": (
+        "The Status sentence MUST start with the count of active "
+        "construction filings cited from [dob_permits] (e.g. \"N "
+        "active construction filings sit inside ...\") and indicate "
+        "which flood layer they intersect. The user is a developer or "
+        "architect doing a pre-design siting check."
+    ),
+    "grant_evidence": (
+        "The Status sentence MUST open with \"Vulnerability "
+        "assessment:\" and name the place + dominant exposure with "
+        "[doc_id]. Treat the briefing as the evidence section of a "
+        "HUD CDBG-DR or FEMA BRIC application — formal, third-person, "
+        "free of advocacy framing."
+    ),
+    "retrospective": (
+        "Riprap currently runs on present-day data sources. The Status "
+        "sentence MUST acknowledge the question is retrospective and "
+        "state explicitly that the briefing reflects the CURRENT state "
+        "of these data sources, not a snapshot from the requested date. "
+        "Then proceed with the present-day exposure picture so the user "
+        "still gets the geography. Silence-over-confabulation: never "
+        "reconstruct historical conditions you can't verify."
+    ),
+    "emergency_response": (
+        "The Status sentence MUST quantify what is at risk in the "
+        "next few hours, citing the live signal that triggered the "
+        "query and any active alerts with [doc_id]. The user needs an "
+        "operational picture, not a historical exposure summary."
+    ),
+    "comparison": (
+        "The Status sentence MUST name BOTH places the user is "
+        "comparing and indicate which one shows greater exposure on "
+        "the strongest cited signal. If only one place's data is "
+        "available in the documents, say so explicitly. The user is "
+        "doing a head-to-head decision."
+    ),
+    "generic_exposure": "",  # default — no override
+}
+
+
+# ---- Detector -------------------------------------------------------------
+#
+# Patterns are ordered: the FIRST type whose pattern matches wins. Order
+# matters — more specific question shapes (legal_disclosure, grant_evidence,
+# emergency_response) come before more general ones (habitability_decision,
+# capital_planning) so the obvious specialist tags don't get swallowed.
+
+_PATTERNS: list[tuple[str, list[re.Pattern]]] = [
+    ("retrospective", [
+        re.compile(r"\b(would have|would Riprap|on (the )?date of|as of (the )?(date|day)|"
+                   r"day before|prior to|before (Hurricane|Ida|Sandy|the storm)|"
+                   r"on (August|September|October|November|December|January|February|March|"
+                   r"April|May|June|July) \d{1,2},? ?\d{4}|"
+                   r"time.?machine|retrospective|court (exhibit|testimony))\b", re.I),
+    ]),
+    ("emergency_response", [
+        re.compile(r"\b(just triggered|right now|next (few |six |\d+ )?hours?|"
+                   r"in the next \d+|currently flooding|flood (warning|watch) is active|"
+                   r"sensor [A-Z]{2}-?\d+|live (alert|trigger))\b", re.I),
+    ]),
+    ("legal_disclosure", [
+        re.compile(r"\b(disclos(e|ure|ed)|RPL\s*§?\s*\d+|Property Condition Disclosure|"
+                   r"§\s*462|§\s*231-?b|seller'?s? disclosure|landlord'?s? disclosure|"
+                   r"required to disclose|need to disclose)\b", re.I),
+    ]),
+    ("grant_evidence", [
+        re.compile(r"\b(vulnerability assessment|CDBG-?DR|HUD|BRIC|"
+                   r"grant application|funding application|community resilience grant|"
+                   r"FEMA application|disaster recovery (application|funding))\b", re.I),
+    ]),
+    ("development_siting", [
+        re.compile(r"\b(what (are|is) (they|being) build(ing)?|new construction|"
+                   r"under construction|active (construction|filing|project|permit)|"
+                   r"projects? (in progress|underway|planned)|architects?|"
+                   r"siting check|pre.?design|"
+                   r"DOB filing|developer)\b", re.I),
+    ]),
+    ("comparison", [
+        # `prioritize X over Y` can have many words between, hence the
+        # bounded non-greedy span — capped at 80 chars to avoid runaway.
+        re.compile(r"\b(compare\b|comparison|\bvs\b|\bversus\b|"
+                   r"head-?to-?head|\brank\s+the\s+top)\b", re.I),
+        re.compile(r"\bprioritize\b.{1,80}\bover\b", re.I | re.S),
+        re.compile(r"\bover\s+\w+(?:\s+\w+){0,3}\s+for\s+(hardening|investment)\b", re.I),
+    ]),
+    ("capital_planning", [
+        re.compile(r"\b(prioritiz(e|ation)|capital plan(ning)?|harden(ing|s)?|"
+                   r"infrastructure investment|where (should|to) (we |the )(invest|"
+                   r"prioritize|harden)|MTA.+prioritize|DEP.+prioritize|"
+                   r"protection envelope|outside (it|the protection)|"
+                   r"resilien(ce|cy) project)\b", re.I),
+    ]),
+    ("habitability_decision", [
+        re.compile(r"\b(should I worry|should I (be|consider)|is (it|this) safe|"
+                   r"can I (rent|live|move|raise (my )?kids?)|considering (renting|leasing|moving)|"
+                   r"(thinking about|planning to) (rent|lease|move|buy)|"
+                   r"is (this|that|the landlord) true|landlord (says|claims|told)|"
+                   r"no flood history|just got a lease|new lease|signing a lease|"
+                   r"\bworry\b)", re.I),
+    ]),
+    ("underwriting", [
+        re.compile(r"\b(underwrit(e|er|ing|able)|actuarial|loss history|"
+                   r"insurabl[ey]|catastrophe (model|risk)|"
+                   r"insurance (audit|memo|profile)|"
+                   r"audit (chain|trail))\b", re.I),
+    ]),
+    ("journalism", [
+        re.compile(r"\b(reporter|journalist|newsroom|story|coverage|"
+                   r"published?|publish (this|the))", re.I),
+    ]),
+]
+
+
+def detect(query: str, intent: str | None = None) -> str:
+    """Classify the question shape from the raw query and planner intent.
+
+    Returns one of `QUESTION_TYPES`. Falls back to `generic_exposure`
+    when no pattern matches — that's the existing behavior, preserved.
+
+    `intent` is currently advisory only (the patterns don't read it),
+    but the parameter is part of the API so future refinements can
+    use it (e.g. an `intent=neighborhood` query without a verdict
+    keyword could default to `journalism` rather than `generic_exposure`).
+    """
+    if not query:
+        return "generic_exposure"
+    q = query.strip()
+    for qt, patterns in _PATTERNS:
+        if any(p.search(q) for p in patterns):
+            return qt
+    # Heuristic fallback: bare neighborhood/borough names from a planner
+    # context default to journalism (most common stakeholder reading a
+    # neighborhood-only query is a reporter or planner). For
+    # single_address with no question keyword, fall back to generic.
+    if intent == "neighborhood" and len(q.split()) <= 3:
+        return "journalism"
+    return "generic_exposure"
+
+
+def opening_instruction(question_type: str) -> str:
+    """Return the directive sentence(s) for a question type.
+    Returns empty string for `generic_exposure` (no override)."""
+    return _DIRECTIVES.get(question_type, "")
+
+
+def augment_system_prompt(base: str, *, query: str,
+                           intent: str | None = None) -> str:
+    """Wrap a base system prompt with a question-aware opening directive.
+
+    No-op when the detector returns `generic_exposure` — the original
+    behavior is preserved.
+    """
+    qt = detect(query, intent)
+    directive = opening_instruction(qt)
+    if not directive:
+        return base
+    return (
+        f"{base}\n\n"
+        f"QUESTION-AWARE OPENING (this directive overrides ONLY the opening "
+        f"**Status.** sentence; the four-section structure and citation "
+        f"discipline above remain in force):\n{directive}"
+    )

app/fsm.py

@@ -0,0 +1,1394 @@
+"""Riprap Burr FSM — linear specialist pipeline for one address.
+
+Each action either produces a structured fact (which becomes a document
+the reconciler can cite) or stays silent on failure. The reconciler
+(Granite 4.1) only sees documents from specialists that actually
+produced data — the silence-over-confabulation contract.
+"""
+from __future__ import annotations
+
+import logging
+import threading as _threading
+import time
+from typing import Any
+
+import geopandas as gpd
+from burr.core import ApplicationBuilder, State, action
+from shapely.geometry import Point
+
+from app import emissions
+from app.context import floodnet, microtopo, noaa_tides, npcc4_slr, nws_alerts, nws_obs, nyc311
+from app.energy import estimate as energy_estimate
+from app.flood_layers import dep_stormwater, ida_hwm, prithvi_water, sandy_inundation
+from app.geocode import geocode_one
+from app.live import floodnet_forecast as fn_forecast
+from app.live import ttm_forecast
+from app.rag import retrieve as rag_retrieve
+from app.reconcile import citations_from_docs, reconcile as run_reconcile
+from app.registers import doe_schools as r_schools
+from app.registers import doh_hospitals as r_hospitals
+from app.registers import mta_entrances as r_mta
+from app.registers import nycha as r_nycha
+
+log = logging.getLogger("riprap.fsm")
+
+# NYC five-borough bbox. Specialists whose data sources are NYC-only
+# (Sandy 2012, NYC DEP Stormwater, FloodNet, NYC 311, NYC microtopo
+# raster, NYC Hurricane Ida Prithvi polygons) skip with an explicit
+# "out of NYC scope" reason when geocode lands outside this envelope.
+# Live specialists (NWS / NOAA / TTM) and the NY-State Ida HWMs run
+# unconditionally.
+_NYC_S, _NYC_W, _NYC_N, _NYC_E = 40.49, -74.27, 40.92, -73.69
+
+
+def _in_nyc(lat, lon) -> bool:
+    if lat is None or lon is None:
+        return False
+    return _NYC_S <= lat <= _NYC_N and _NYC_W <= lon <= _NYC_E
+
+# Thread-local hook so the streaming endpoint can subscribe to per-token
+# Granite output during reconcile, without threading a callback through
+# every Burr action signature.
+_FSM_LOCAL = _threading.local()
+
+
+def set_token_callback(on_token):
+    """Install a per-thread on_token(delta) callable for the next reconcile.
+    Pass None to clear."""
+    _FSM_LOCAL.on_token = on_token
+
+
+def _current_token_callback():
+    return getattr(_FSM_LOCAL, "on_token", None)
+
+
+def set_mellea_attempt_callback(fn):
+    _FSM_LOCAL.on_mellea_attempt = fn
+
+
+def _current_mellea_attempt_callback():
+    return getattr(_FSM_LOCAL, "on_mellea_attempt", None)
+
+
+def set_strict_mode(strict: bool):
+    """Per-thread flag — when True the linear FSM's reconcile step routes
+    through Mellea-validated rejection sampling instead of the standard
+    streaming reconciler. Disables token streaming for that step."""
+    _FSM_LOCAL.strict = bool(strict)
+
+
+def _current_strict_mode() -> bool:
+    return bool(getattr(_FSM_LOCAL, "strict", False))
+
+
+def set_planned_specialists(spec_names):
+    """Install a per-thread set of specialist names from the planner.
+
+    Used by step_reconcile to trim doc messages: documents whose family
+    prefix doesn't match any planned specialist are dropped before the
+    Mellea call. Cuts ~30-50% of prompt tokens on local Ollama, where
+    the FSM otherwise hands the reconciler every specialist's output
+    even if the planner only asked for a subset."""
+    _FSM_LOCAL.planned_specialists = set(spec_names) if spec_names else None
+
+
+def _current_planned_specialists():
+    return getattr(_FSM_LOCAL, "planned_specialists", None)
+
+
+def set_user_query(query: str | None):
+    """Install the user's original natural-language query for question-aware
+    framing in step_reconcile. The FSM's state["query"] is the geocoder
+    input (often just the street address), which doesn't carry the
+    user's question shape — set this separately so Capstone can detect
+    'should I worry' / 'is disclosure required' / etc."""
+    _FSM_LOCAL.user_query = query
+
+
+def _current_user_query() -> str | None:
+    return getattr(_FSM_LOCAL, "user_query", None)
+
+
+def set_planner_intent(intent: str | None):
+    """Install the planner's classified intent so step_reconcile can pass
+    it to the framing detector as a tiebreaker on bare-place queries."""
+    _FSM_LOCAL.planner_intent = intent
+
+
+def _current_planner_intent() -> str | None:
+    return getattr(_FSM_LOCAL, "planner_intent", None)
+
+
+# Canonical Burr: one action per specialist, sequential transitions.
+# A previous version of this module wrapped 16 specialists in a single
+# fan-out action that ran them concurrently in a ThreadPoolExecutor;
+# that path was removed because it sometimes hung after the fan-out
+# completed (Burr-internal post-action cleanup with custom executors)
+# and made the trace UI's per-step timing harder to reason about.
+# Parallelism, when wanted, belongs at the inference layer
+# (vLLM / Ollama NUM_PARALLEL), not the FSM.
+
+def _step(state: State, name: str) -> dict[str, Any]:
+    """Append a step record to the trace; returns the dict so the action
+    can mutate timing/result fields."""
+    trace = list(state.get("trace", []))
+    rec = {"step": name, "started_at": time.time(), "ok": None}
+    trace.append(rec)
+    return rec, trace
+
+
+@action(reads=["query"], writes=["geocode", "lat", "lon", "trace"])
+def step_geocode(state: State) -> State:
+    rec, trace = _step(state, "geocode")
+    try:
+        hit = geocode_one(state["query"])
+        if hit is None:
+            rec["ok"] = False
+            rec["err"] = "no geocoder match"
+            # Burr requires every declared write to be populated. Emit
+            # explicit None rather than leaving keys absent.
+            return state.update(geocode=None, lat=None, lon=None, trace=trace)
+        rec["ok"] = True
+        rec["result"] = {"address": hit.address, "lat": hit.lat, "lon": hit.lon}
+        return state.update(
+            geocode={"address": hit.address, "borough": hit.borough,
+                     "lat": hit.lat, "lon": hit.lon,
+                     "bbl": hit.bbl, "bin": hit.bin},
+            lat=hit.lat, lon=hit.lon, trace=trace,
+        )
+    except Exception as e:
+        rec["ok"] = False
+        rec["err"] = str(e)
+        log.exception("geocode failed")
+        return state.update(geocode=None, lat=None, lon=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["sandy", "trace"])
+def step_sandy(state: State) -> State:
+    rec, trace = _step(state, "sandy_inundation")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(sandy=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(sandy=None, trace=trace)
+        pt_geom = (gpd.GeoDataFrame(geometry=[Point(state["lon"], state["lat"])],
+                                    crs="EPSG:4326")
+                   .to_crs("EPSG:2263").iloc[0].geometry)
+        flag = sandy_inundation.inside_raster(pt_geom)
+        rec["ok"] = True; rec["result"] = {"inside": flag}
+        return state.update(sandy=flag, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("sandy failed")
+        return state.update(sandy=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["dep", "trace"])
+def step_dep(state: State) -> State:
+    rec, trace = _step(state, "dep_stormwater")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(dep=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(dep=None, trace=trace)
+        pt_geom = (gpd.GeoDataFrame(geometry=[Point(state["lon"], state["lat"])],
+                                    crs="EPSG:4326")
+                   .to_crs("EPSG:2263").iloc[0].geometry)
+        out: dict[str, Any] = {}
+        for scen in ["dep_extreme_2080", "dep_moderate_2050", "dep_moderate_current"]:
+            cls = dep_stormwater.join_raster(pt_geom, scen)
+            out[scen] = {
+                "depth_class": cls,
+                "depth_label": dep_stormwater.DEPTH_CLASS.get(cls, "outside"),
+                "citation": f"NYC DEP Stormwater Flood Map — {dep_stormwater.label(scen)}",
+            }
+        rec["ok"] = True; rec["result"] = {k: v["depth_label"] for k, v in out.items()}
+        return state.update(dep=out, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("dep failed")
+        return state.update(dep=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["floodnet", "trace"])
+def step_floodnet(state: State) -> State:
+    rec, trace = _step(state, "floodnet")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(floodnet=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(floodnet=None, trace=trace)
+        s = floodnet.summary_for_point(state["lat"], state["lon"], radius_m=600)
+        s["radius_m"] = 600
+        rec["ok"] = True
+        rec["result"] = {"n_sensors": s["n_sensors"],
+                         "n_events_3y": s["n_flood_events_3y"]}
+        return state.update(floodnet=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("floodnet failed")
+        return state.update(floodnet=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["nyc311", "trace"])
+def step_311(state: State) -> State:
+    rec, trace = _step(state, "nyc311")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(nyc311=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(nyc311=None, trace=trace)
+        s = nyc311.summary_for_point(state["lat"], state["lon"], radius_m=200, years=5)
+        rec["ok"] = True; rec["result"] = {"n": s["n"]}
+        return state.update(nyc311=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("311 failed")
+        return state.update(nyc311=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["ida_hwm", "trace"])
+def step_ida_hwm(state: State) -> State:
+    rec, trace = _step(state, "ida_hwm_2021")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(ida_hwm=None, trace=trace)
+        s = ida_hwm.summary_for_point(state["lat"], state["lon"], radius_m=800)
+        if s is None:
+            rec["ok"] = False; rec["err"] = "HWM data missing"
+            return state.update(ida_hwm=None, trace=trace)
+        rec["ok"] = True
+        rec["result"] = {
+            "n_within_800m": s.n_within_radius,
+            "max_height_above_gnd_ft": s.max_height_above_gnd_ft,
+            "nearest_m": s.nearest_dist_m,
+        }
+        return state.update(ida_hwm=vars(s), trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("ida_hwm failed")
+        return state.update(ida_hwm=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["prithvi_water", "trace"])
+def step_prithvi(state: State) -> State:
+    rec, trace = _step(state, "prithvi_eo_v2")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(prithvi_water=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(prithvi_water=None, trace=trace)
+        s = prithvi_water.summary_for_point(state["lat"], state["lon"])
+        if s is None:
+            rec["ok"] = False; rec["err"] = "Prithvi mask missing"
+            return state.update(prithvi_water=None, trace=trace)
+        rec["ok"] = True
+        rec["result"] = {
+            "inside_water_polygon": s.inside_water_polygon,
+            "nearest_distance_m": s.nearest_distance_m,
+            "n_polygons_within_500m": s.n_polygons_within_500m,
+        }
+        return state.update(prithvi_water=vars(s), trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("prithvi failed")
+        return state.update(prithvi_water=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["prithvi_live", "trace"])
+def step_prithvi_live(state: State) -> State:
+    """Live Sentinel-2 water segmentation via Prithvi-EO 2.0.
+
+    Network + 300M-param forward pass per query, so it's the slowest
+    specialist by far. Gracefully no-ops via the underlying module if
+    `RIPRAP_PRITHVI_LIVE_ENABLE=0` or if STAC / model load fails.
+    """
+    rec, trace = _step(state, "prithvi_eo_live")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(prithvi_live=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(prithvi_live=None, trace=trace)
+        from app.flood_layers import prithvi_live
+        s = prithvi_live.fetch(state["lat"], state["lon"])
+        rec["ok"] = bool(s.get("ok"))
+        if not s.get("ok"):
+            rec["err"] = s.get("err") or s.get("skipped") or "no observation"
+        else:
+            rec["result"] = {
+                "scene_date": (s.get("item_datetime") or "")[:10],
+                "cloud_cover": s.get("cloud_cover"),
+                "pct_water_500m": s.get("pct_water_within_500m"),
+                "pct_water_5km": s.get("pct_water_full"),
+            }
+        return state.update(prithvi_live=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("prithvi_live failed")
+        return state.update(prithvi_live=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["ttm_311_forecast", "trace"])
+def step_ttm_311_forecast(state: State) -> State:
+    """TTM r2 zero-shot forecast on weekly 311 flood-complaint counts
+    at this specific address (200 m radius). 52 weeks of context →
+    4 weeks of forecast. Per-query, per-address, citable."""
+    rec, trace = _step(state, "ttm_311_forecast")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(ttm_311_forecast=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(ttm_311_forecast=None, trace=trace)
+        s = ttm_forecast.weekly_311_forecast_for_point(state["lat"], state["lon"])
+        rec["ok"] = bool(s.get("available"))
+        if not rec["ok"]:
+            rec["err"] = s.get("reason", "unavailable")
+        else:
+            rec["result"] = {
+                "history_total": s.get("history_total_complaints"),
+                "history_recent_mean": s.get("history_recent_3mo_mean"),
+                "forecast_mean": s.get("forecast_mean_per_week"),
+                "forecast_peak": s.get("forecast_peak_per_week"),
+                "accelerating": s.get("accelerating"),
+            }
+        return state.update(ttm_311_forecast=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("ttm_311_forecast failed")
+        return state.update(ttm_311_forecast=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["terramind", "trace"])
+def step_terramind(state: State) -> State:
+    """TerraMind v1 base — DEM → S2L2A synthesis as a per-query
+    cognitive-engine node. ~3-7s on M3 CPU. Output is a
+    *synthetic-prior* — explicitly fourth epistemic class alongside
+    empirical / modeled / proxy. Frame the doc body and reconciler
+    narration as 'plausible synthesis from terrain context', never
+    'imaged' or 'reconstructed'."""
+    rec, trace = _step(state, "terramind_synthesis")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(terramind=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(terramind=None, trace=trace)
+        from app.context import terramind_synthesis
+        s = terramind_synthesis.fetch(state["lat"], state["lon"])
+        rec["ok"] = bool(s.get("ok"))
+        if not s.get("ok"):
+            rec["err"] = s.get("err") or s.get("skipped") or "terramind unavailable"
+        else:
+            rec["result"] = {
+                "tim_chain": s.get("tim_chain"),
+                "diffusion_steps": s.get("diffusion_steps"),
+                "dem_mean_m": s.get("dem_mean_m"),
+                "synth_chip_shape": s.get("synth_chip_shape"),
+                "elapsed_s": s.get("elapsed_s"),
+            }
+        return state.update(terramind=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("terramind failed")
+        return state.update(terramind=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["noaa_tides", "trace"])
+def step_noaa_tides(state: State) -> State:
+    rec, trace = _step(state, "noaa_tides")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(noaa_tides=None, trace=trace)
+        s = noaa_tides.summary_for_point(state["lat"], state["lon"])
+        rec["ok"] = s.get("error") is None
+        rec["result"] = {
+            "station": s["station_id"],
+            "observed_ft_mllw": s["observed_ft_mllw"],
+            "residual_ft": s["residual_ft"],
+        }
+        if s.get("error"): rec["err"] = s["error"]
+        return state.update(noaa_tides=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("noaa_tides failed")
+        return state.update(noaa_tides=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["nws_alerts", "trace"])
+def step_nws_alerts(state: State) -> State:
+    rec, trace = _step(state, "nws_alerts")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(nws_alerts=None, trace=trace)
+        s = nws_alerts.summary_for_point(state["lat"], state["lon"])
+        rec["ok"] = s.get("error") is None
+        rec["result"] = {"n_active": s["n_active"]}
+        if s.get("error"): rec["err"] = s["error"]
+        return state.update(nws_alerts=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("nws_alerts failed")
+        return state.update(nws_alerts=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["nws_obs", "trace"])
+def step_nws_obs(state: State) -> State:
+    rec, trace = _step(state, "nws_obs")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(nws_obs=None, trace=trace)
+        s = nws_obs.summary_for_point(state["lat"], state["lon"])
+        rec["ok"] = s.get("error") is None
+        rec["result"] = {
+            "station": s["station_id"],
+            "p1h_mm": s["precip_last_hour_mm"],
+            "p6h_mm": s["precip_last_6h_mm"],
+        }
+        if s.get("error"): rec["err"] = s["error"]
+        return state.update(nws_obs=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("nws_obs failed")
+        return state.update(nws_obs=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["ttm_forecast", "trace"])
+def step_ttm_forecast(state: State) -> State:
+    """Granite TTM r2 zero-shot forecast of the Battery surge residual."""
+    rec, trace = _step(state, "ttm_forecast")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(ttm_forecast=None, trace=trace)
+        s = ttm_forecast.summary_for_point(state["lat"], state["lon"])
+        if not s.get("available"):
+            rec["ok"] = False
+            rec["err"] = s.get("reason", "TTM unavailable")
+            return state.update(ttm_forecast=None, trace=trace)
+        rec["ok"] = True
+        rec["result"] = {
+            "context": s["context_length"],
+            "horizon": s["horizon_steps"],
+            "forecast_peak_ft": s["forecast_peak_ft"],
+            "forecast_peak_min_ahead": s["forecast_peak_minutes_ahead"],
+            "interesting": s["interesting"],
+        }
+        return state.update(ttm_forecast=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("ttm_forecast failed")
+        return state.update(ttm_forecast=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["ttm_battery_surge", "trace"])
+def step_ttm_battery_surge(state: State) -> State:
+    """Granite TTM r2 fine-tune — 96 h hourly Battery surge nowcast.
+
+    Same TTM r2 backbone family as step_ttm_forecast but a different
+    artefact: msradam/Granite-TTM-r2-Battery-Surge, trained on AMD
+    MI300X. Hourly cadence vs the zero-shot's 6-min, 4-day vs 9.6 h
+    horizon. Both can fire on the same query — the reconciler frames
+    each as a distinct forecast in the briefing."""
+    rec, trace = _step(state, "ttm_battery_surge")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(ttm_battery_surge=None, trace=trace)
+        # Battery gauge is a single point; the forecast applies citywide
+        # to NYC harbor entrance, so we don't gate by NYC bbox.
+        from app.live import ttm_battery_surge
+        s = ttm_battery_surge.fetch()
+        rec["ok"] = bool(s.get("available"))
+        if not rec["ok"]:
+            rec["err"] = s.get("reason", "unavailable")
+            return state.update(ttm_battery_surge=None, trace=trace)
+        rec["result"] = {
+            "context_h": s.get("context_hours"),
+            "horizon_h": s.get("horizon_hours"),
+            "forecast_peak_m": s.get("forecast_peak_m"),
+            "forecast_peak_hours_ahead": s.get("forecast_peak_hours_ahead"),
+            "interesting": s.get("interesting"),
+        }
+        return state.update(ttm_battery_surge=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("ttm_battery_surge failed")
+        return state.update(ttm_battery_surge=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["floodnet_forecast", "trace"])
+def step_floodnet_forecast(state: State) -> State:
+    """TTM r2 forecast of flood-event recurrence at the nearest FloodNet
+    sensor. Reuses the same (512, 96) singleton as ttm_311_forecast — no
+    additional model loaded into memory. Silent when the sensor has too
+    few historical events for a defensible forecast."""
+    rec, trace = _step(state, "floodnet_forecast")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(floodnet_forecast=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(floodnet_forecast=None, trace=trace)
+        s = fn_forecast.summary_for_point(state["lat"], state["lon"])
+        rec["ok"] = bool(s.get("available"))
+        if not rec["ok"]:
+            rec["err"] = s.get("reason", "unavailable")
+        else:
+            rec["result"] = {
+                "sensor_id": s.get("sensor_id"),
+                "distance_m": s.get("distance_from_query_m"),
+                "history_28d": s.get("history_recent_28d_events"),
+                "forecast_28d": s.get("forecast_28d_expected_events"),
+                "accelerating": s.get("accelerating"),
+            }
+        return state.update(floodnet_forecast=s if rec["ok"] else None,
+                            trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("floodnet_forecast failed")
+        return state.update(floodnet_forecast=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["npcc4_slr", "trace"])
+def step_npcc4_projection(state: State) -> State:
+    """NPCC4 (2024) sea-level rise table — static lookup, always available."""
+    rec, trace = _step(state, "npcc4_projection")
+    try:
+        s = npcc4_slr.get_projections()
+        rec["ok"] = True
+        rec["result"] = {
+            "2050_10th_in": s["2050"]["10"]["in"],
+            "2050_50th_in": s["2050"]["50"]["in"],
+            "2050_90th_in": s["2050"]["90"]["in"],
+            "2100_90th_in": s["2100"]["90"]["in"],
+        }
+        return state.update(npcc4_slr=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("npcc4_projection failed")
+        return state.update(npcc4_slr=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["mta_entrances", "trace"])
+def step_mta_entrances(state: State) -> State:
+    rec, trace = _step(state, "mta_entrance_exposure")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(mta_entrances=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(mta_entrances=None, trace=trace)
+        s = r_mta.summary_for_point(state["lat"], state["lon"])
+        if not s.get("available"):
+            rec["ok"] = False; rec["err"] = "no entrances within radius"
+            return state.update(mta_entrances=None, trace=trace)
+        rec["ok"] = True
+        rec["result"] = {
+            "n_entrances": s["n_entrances"],
+            "n_inside_sandy_2012": s["n_inside_sandy_2012"],
+            "n_in_dep_extreme_2080": s["n_in_dep_extreme_2080"],
+        }
+        return state.update(mta_entrances=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("mta_entrances failed")
+        return state.update(mta_entrances=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["nycha_developments", "trace"])
+def step_nycha(state: State) -> State:
+    rec, trace = _step(state, "nycha_development_exposure")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(nycha_developments=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(nycha_developments=None, trace=trace)
+        s = r_nycha.summary_for_point(state["lat"], state["lon"])
+        if not s.get("available"):
+            rec["ok"] = False; rec["err"] = "no NYCHA developments within radius"
+            return state.update(nycha_developments=None, trace=trace)
+        rec["ok"] = True
+        rec["result"] = {
+            "n_developments": s["n_developments"],
+            "n_inside_sandy_2012": s["n_inside_sandy_2012"],
+            "n_in_dep_extreme_2080": s["n_in_dep_extreme_2080"],
+        }
+        return state.update(nycha_developments=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("nycha failed")
+        return state.update(nycha_developments=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["doe_schools", "trace"])
+def step_doe_schools(state: State) -> State:
+    rec, trace = _step(state, "doe_school_exposure")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(doe_schools=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(doe_schools=None, trace=trace)
+        s = r_schools.summary_for_point(state["lat"], state["lon"])
+        if not s.get("available"):
+            rec["ok"] = False; rec["err"] = "no schools within radius"
+            return state.update(doe_schools=None, trace=trace)
+        rec["ok"] = True
+        rec["result"] = {
+            "n_schools": s["n_schools"],
+            "n_inside_sandy_2012": s["n_inside_sandy_2012"],
+            "n_in_dep_extreme_2080": s["n_in_dep_extreme_2080"],
+        }
+        return state.update(doe_schools=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("doe_schools failed")
+        return state.update(doe_schools=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["doh_hospitals", "trace"])
+def step_doh_hospitals(state: State) -> State:
+    rec, trace = _step(state, "doh_hospital_exposure")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(doh_hospitals=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(doh_hospitals=None, trace=trace)
+        s = r_hospitals.summary_for_point(state["lat"], state["lon"])
+        if not s.get("available"):
+            rec["ok"] = False; rec["err"] = "no hospitals within radius"
+            return state.update(doh_hospitals=None, trace=trace)
+        rec["ok"] = True
+        rec["result"] = {
+            "n_hospitals": s["n_hospitals"],
+            "n_inside_sandy_2012": s["n_inside_sandy_2012"],
+            "n_in_dep_extreme_2080": s["n_in_dep_extreme_2080"],
+        }
+        return state.update(doh_hospitals=s, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("doh_hospitals failed")
+        return state.update(doh_hospitals=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon"], writes=["microtopo", "trace"])
+def step_microtopo(state: State) -> State:
+    rec, trace = _step(state, "microtopo_lidar")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(microtopo=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(microtopo=None, trace=trace)
+        m = microtopo.microtopo_at(state["lat"], state["lon"])
+        if m is None:
+            rec["ok"] = False; rec["err"] = "DEM fetch failed"
+            return state.update(microtopo=None, trace=trace)
+        rec["ok"] = True
+        rec["result"] = {
+            "elev_m": m.point_elev_m,
+            "pct_200m": m.rel_elev_pct_200m,
+            "relief_m": m.basin_relief_m,
+        }
+        return state.update(microtopo=vars(m), trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("microtopo failed")
+        return state.update(microtopo=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+
+
+@action(reads=["lat", "lon"], writes=["eo_chip", "trace"])
+def step_eo_chip(state: State) -> State:
+    """Fetch one S2L2A + S1RTC + DEM chip per query and stash it in
+    state for the TerraMind-NYC specialists.
+
+    Centralised so step_terramind_lulc and step_terramind_buildings
+    don't each re-fetch ~150 MB of imagery. Best-effort by design —
+    a deps-missing or no-scene outcome writes `{ok: False, skipped: ...}`
+    and the downstream TerraMind specialists silently no-op."""
+    rec, trace = _step(state, "eo_chip_fetch")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(eo_chip=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(eo_chip=None, trace=trace)
+        from app.context import eo_chip_cache
+        chip = eo_chip_cache.fetch(state["lat"], state["lon"])
+        rec["ok"] = bool(chip.get("ok"))
+        if not rec["ok"]:
+            rec["err"] = chip.get("skipped") or chip.get("err") or "unavailable"
+        else:
+            rec["result"] = {
+                "scene_id": (chip.get("s2_meta") or {}).get("scene_id"),
+                "scene_date": ((chip.get("s2_meta") or {}).get("datetime") or "")[:10],
+                "cloud_cover": (chip.get("s2_meta") or {}).get("cloud_cover"),
+                "has_s1": chip.get("s1") is not None,
+                "has_dem": chip.get("dem") is not None,
+            }
+        return state.update(eo_chip=chip, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("eo_chip failed")
+        return state.update(eo_chip=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon", "eo_chip"], writes=["terramind_lulc", "trace"])
+def step_terramind_lulc(state: State) -> State:
+    """5-class macro NYC LULC via msradam/TerraMind-NYC-Adapters.
+
+    Consumes the shared chip from step_eo_chip; if that didn't fire
+    cleanly this no-ops. Adapter loading (~1.6 GB base + ~325 MB LoRA)
+    is lazy on first call and cached across queries."""
+    rec, trace = _step(state, "terramind_lulc")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(terramind_lulc=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(terramind_lulc=None, trace=trace)
+        chip = state.get("eo_chip") or {}
+        if not chip.get("ok"):
+            rec["ok"] = False
+            rec["err"] = chip.get("skipped") or chip.get("err") or "no chip"
+            return state.update(terramind_lulc=None, trace=trace)
+        from app.context import terramind_nyc
+        tensors = chip.get("tensors") or {}
+        out = terramind_nyc.lulc(
+            tensors.get("S2L2A"),
+            s1rtc=tensors.get("S1RTC"),
+            dem=tensors.get("DEM"),
+            bounds_4326=chip.get("bounds_4326"),
+        )
+        rec["ok"] = bool(out.get("ok"))
+        if not rec["ok"]:
+            rec["err"] = out.get("skipped") or out.get("err") or "unavailable"
+        else:
+            rec["result"] = {
+                "dominant_class": out.get("dominant_class"),
+                "dominant_pct": out.get("dominant_pct"),
+                "n_classes_observed": len(out.get("class_fractions") or {}),
+            }
+        return state.update(terramind_lulc=out, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("terramind_lulc failed")
+        return state.update(terramind_lulc=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["lat", "lon", "eo_chip"],
+        writes=["terramind_buildings", "trace"])
+def step_terramind_buildings(state: State) -> State:
+    """Binary NYC building-footprint mask via msradam/TerraMind-NYC-Adapters."""
+    rec, trace = _step(state, "terramind_buildings")
+    try:
+        if state.get("lat") is None:
+            rec["ok"] = False; rec["err"] = "no coords"
+            return state.update(terramind_buildings=None, trace=trace)
+        if not _in_nyc(state["lat"], state["lon"]):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(terramind_buildings=None, trace=trace)
+        chip = state.get("eo_chip") or {}
+        if not chip.get("ok"):
+            rec["ok"] = False
+            rec["err"] = chip.get("skipped") or chip.get("err") or "no chip"
+            return state.update(terramind_buildings=None, trace=trace)
+        from app.context import terramind_nyc
+        tensors = chip.get("tensors") or {}
+        out = terramind_nyc.buildings(
+            tensors.get("S2L2A"),
+            s1rtc=tensors.get("S1RTC"),
+            dem=tensors.get("DEM"),
+            bounds_4326=chip.get("bounds_4326"),
+        )
+        rec["ok"] = bool(out.get("ok"))
+        if not rec["ok"]:
+            rec["err"] = out.get("skipped") or out.get("err") or "unavailable"
+        else:
+            rec["result"] = {
+                "pct_buildings": out.get("pct_buildings"),
+                "n_building_components": out.get("n_building_components"),
+            }
+        return state.update(terramind_buildings=out, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("terramind_buildings failed")
+        return state.update(terramind_buildings=None, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["geocode", "sandy", "dep", "floodnet", "nyc311", "microtopo",
+               "ida_hwm", "prithvi_water", "noaa_tides", "nws_alerts", "nws_obs",
+               "ttm_forecast"],
+        writes=["rag", "trace"])
+def step_rag(state: State) -> State:
+    rec, trace = _step(state, "rag_granite_embedding")
+    try:
+        geo = state.get("geocode") or {}
+        if not _in_nyc(geo.get("lat"), geo.get("lon")):
+            rec["ok"] = False; rec["err"] = "out of NYC scope"
+            return state.update(rag=[], trace=trace)
+        sandy = state.get("sandy")
+        dep = state.get("dep") or {}
+        # Build a context-rich query so retrieval pulls policy paragraphs
+        # relevant to *this* address, not generic flood text.
+        bits = []
+        if geo.get("address"):
+            bits.append(f"address {geo['address']}")
+        if geo.get("borough"):
+            bits.append(f"in {geo['borough']}")
+        if sandy:
+            bits.append("inside Hurricane Sandy 2012 inundation zone")
+        for v in dep.values():
+            if v.get("depth_class", 0) > 0:
+                bits.append(f"in {v['depth_label']} pluvial scenario")
+        bits.append("flood resilience plan, vulnerability, hardening, mitigation")
+        q = "; ".join(bits)
+        hits = rag_retrieve(q, k=3, min_score=0.45)
+        rec["ok"] = True
+        rec["result"] = {"hits": len(hits),
+                         "top": [(h["doc_id"], round(h["score"], 2)) for h in hits]}
+        return state.update(rag=hits, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("rag failed")
+        return state.update(rag=[], trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+@action(reads=["rag"], writes=["gliner", "trace"])
+def step_gliner(state: State) -> State:
+    """GLiNER typed-entity extraction over the top RAG paragraphs.
+
+    Adds structured fields (`agency`, `dollar_amount`,
+    `infrastructure_project`, `nyc_location`, `date_range`) the
+    reconciler can cite with `[gliner_<source>]`. Silent no-op when
+    disabled via RIPRAP_GLINER_ENABLE=0 or when the model failed to
+    load — preserves the existing FSM contract.
+    """
+    rec, trace = _step(state, "gliner_extract")
+    try:
+        from app.context.gliner_extract import extract_for_rag_hits
+        hits = state.get("rag") or []
+        if not hits:
+            rec["ok"] = True
+            rec["result"] = {"sources": 0, "skipped": "no rag hits"}
+            return state.update(gliner={}, trace=trace)
+        out = extract_for_rag_hits(hits)
+        rec["ok"] = True
+        rec["result"] = {
+            "sources": len(out),
+            "totals_by_label": _label_counts(out),
+        }
+        return state.update(gliner=out, trace=trace)
+    except Exception as e:
+        rec["ok"] = False
+        rec["err"] = str(e)
+        log.exception("gliner failed")
+        return state.update(gliner={}, trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+def _label_counts(gliner_out: dict[str, dict]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for src in gliner_out.values():
+        for e in src.get("entities", []):
+            counts[e["label"]] = counts.get(e["label"], 0) + 1
+    return counts
+
+
+@action(reads=["geocode", "sandy", "dep", "floodnet", "nyc311", "microtopo",
+               "ida_hwm", "prithvi_water", "prithvi_live", "terramind",
+               "terramind_lulc", "terramind_buildings",
+               "noaa_tides", "nws_alerts", "nws_obs", "ttm_forecast",
+               "ttm_311_forecast", "floodnet_forecast", "npcc4_slr",
+               "ttm_battery_surge",
+               "mta_entrances",
+               "nycha_developments", "doe_schools", "doh_hospitals",
+               "rag", "gliner"],
+        writes=["paragraph", "audit", "mellea", "citations", "trace"])
+def step_reconcile(state: State) -> State:
+    is_strict = _current_strict_mode()
+    rec, trace = _step(state, "mellea_reconcile_address" if is_strict else "reconcile_granite41")
+    mellea_meta = None
+    try:
+        snap = {
+            "geocode": state.get("geocode"),
+            "sandy": state.get("sandy"),
+            "dep": state.get("dep"),
+            "floodnet": state.get("floodnet"),
+            "nyc311": state.get("nyc311"),
+            "microtopo": state.get("microtopo"),
+            "ida_hwm": state.get("ida_hwm"),
+            "prithvi_water": state.get("prithvi_water"),
+            "noaa_tides": state.get("noaa_tides"),
+            "nws_alerts": state.get("nws_alerts"),
+            "nws_obs": state.get("nws_obs"),
+            "ttm_forecast": state.get("ttm_forecast"),
+            "ttm_311_forecast": state.get("ttm_311_forecast"),
+            "floodnet_forecast": state.get("floodnet_forecast"),
+            "npcc4_slr": state.get("npcc4_slr"),
+            "ttm_battery_surge": state.get("ttm_battery_surge"),
+            "rag": state.get("rag"),
+            "gliner": state.get("gliner"),
+            "prithvi_live": state.get("prithvi_live"),
+            "terramind": state.get("terramind"),
+            "terramind_lulc": state.get("terramind_lulc"),
+            "terramind_buildings": state.get("terramind_buildings"),
+            "mta_entrances": state.get("mta_entrances"),
+            "nycha_developments": state.get("nycha_developments"),
+            "doe_schools": state.get("doe_schools"),
+            "doh_hospitals": state.get("doh_hospitals"),
+        }
+        if is_strict:
+            from app.framing import augment_system_prompt
+            from app.mellea_validator import DEFAULT_LOOP_BUDGET, reconcile_strict_streaming
+            from app.reconcile import EXTRA_SYSTEM_PROMPT, build_documents, trim_docs_to_plan
+            doc_msgs = build_documents(snap)
+            doc_msgs = trim_docs_to_plan(doc_msgs, _current_planned_specialists())
+            if not doc_msgs:
+                para = "No grounded data available for this address."
+                audit = {"raw": para, "dropped": []}
+            else:
+                token_cb = _current_token_callback()
+                attempt_cb = _current_mellea_attempt_callback()
+                framed_prompt = augment_system_prompt(
+                    EXTRA_SYSTEM_PROMPT,
+                    query=_current_user_query() or state.get("query") or "",
+                    intent=_current_planner_intent() or "single_address",
+                )
+                # Forward the (delta, attempt_idx) pair through. Older
+                # token_cb signatures were single-arg; we detect by
+                # introspecting the callable's expected positional count
+                # so single_address.py's old shape still works while new
+                # callbacks see the attempt index they need to clear the
+                # frontend buffer on a Mellea reroll.
+                def _fwd_token(delta: str, attempt_idx: int) -> None:
+                    if token_cb is None:
+                        return
+                    try:
+                        token_cb(delta, attempt_idx)
+                    except TypeError:
+                        token_cb(delta)
+                mres = reconcile_strict_streaming(
+                    doc_msgs, framed_prompt,
+                    user_prompt="Write the cited paragraph now.",
+                    loop_budget=DEFAULT_LOOP_BUDGET,
+                    on_token=_fwd_token if token_cb else None,
+                    on_attempt_end=attempt_cb,
+                )
+                para = mres["paragraph"]
+                audit = {"raw": para, "dropped": []}
+                mellea_meta = {
+                    "rerolls": mres["rerolls"],
+                    "n_attempts": mres["n_attempts"],
+                    "requirements_passed": mres["requirements_passed"],
+                    "requirements_failed": mres["requirements_failed"],
+                    "requirements_total": mres["requirements_total"],
+                    "model": mres["model"],
+                    "loop_budget": mres["loop_budget"],
+                }
+            rec["result"] = {
+                "rerolls": (mellea_meta or {}).get("rerolls"),
+                "passed": (f"{len((mellea_meta or {}).get('requirements_passed') or [])}/"
+                           f"{(mellea_meta or {}).get('requirements_total') or 0}"),
+                "paragraph_chars": len(para),
+            }
+        else:
+            para, audit = run_reconcile(snap, return_audit=True,
+                                        on_token=_current_token_callback())
+            rec["result"] = {
+                "paragraph_chars": len(para),
+                "dropped_sentences": len(audit["dropped"]),
+            }
+        # Build citation metadata list from whichever doc_msgs were used.
+        from app.reconcile import build_documents, trim_docs_to_plan
+        _cite_msgs = build_documents(snap)
+        _cite_msgs = trim_docs_to_plan(_cite_msgs, _current_planned_specialists())
+        cite_list = citations_from_docs(_cite_msgs)
+        rec["ok"] = True
+        return state.update(paragraph=para, audit=audit,
+                            mellea=mellea_meta, citations=cite_list, trace=trace)
+    except Exception as e:
+        rec["ok"] = False; rec["err"] = str(e)
+        log.exception("reconcile failed")
+        return state.update(paragraph="", audit={"raw": "", "dropped": []},
+                            mellea=None, citations=[], trace=trace)
+    finally:
+        rec["elapsed_s"] = round(time.time() - rec["started_at"], 2)
+
+
+import os as _os  # noqa: E402
+
+
+# Specialists that involve large spatial joins (every NYCHA development
+# overlapped against multiple flood layers, every DOE school footprint
+# joined to DEM/HAND, etc.) or per-query model inference (Prithvi-EO live
+# STAC + ViT, TerraMind diffusion). They're ~1-3 minutes apiece on a
+# laptop on the FIRST call (the lru_caches inside the registers warm up
+# afterwards). The previous parallel-fan-out FSM hid that cost behind
+# the longest single specialist; the linear FSM exposes it.
+#
+# Default OFF on local-Ollama so the demo briefing returns in well under
+# 90 s. Enable explicitly with RIPRAP_HEAVY_SPECIALISTS=1 (e.g. on the
+# AMD-vLLM path, where the reconciler's ~5 s leaves room for the joins).
+#
+# Remote ML lift: when RIPRAP_ML_BACKEND=remote (or auto with a base URL
+# set) the heavy specialists' GPU work runs on the droplet, so the local
+# wall-clock cost drops from ~60 s to ~5 s. Default ON in that case so
+# the public demo never silently disables them.
+def _remote_ml_configured() -> bool:
+    backend = _os.environ.get("RIPRAP_ML_BACKEND", "auto").lower()
+    if backend == "local":
+        return False
+    return bool(_os.environ.get("RIPRAP_ML_BASE_URL", "").strip())
+
+
+_HEAVY_DEFAULT = (
+    "1" if (
+        _os.environ.get("RIPRAP_LLM_PRIMARY", "ollama").lower() != "ollama"
+        or _remote_ml_configured()
+    ) else "0"
+)
+_HEAVY_SPECIALISTS_ENABLED = _os.environ.get(
+    "RIPRAP_HEAVY_SPECIALISTS", _HEAVY_DEFAULT,
+).lower() in ("1", "true", "yes")
+
+# NYCHA / DOE / DOH registers load a 91 MB sandy_inundation.geojson via
+# geopandas on first call.  On machines with slow I/O or single-threaded
+# Python GIL contention (M3 local dev) this takes 3–5 min and makes the
+# first single_address query appear hung.  Disable by default; enable on
+# the AMD droplet where the server pre-warms these at startup.
+_NYCHA_REGISTERS_ENABLED = _os.environ.get(
+    "RIPRAP_NYCHA_REGISTERS", "0",
+).lower() in ("1", "true", "yes")
+
+
+def build_app(query: str):
+    """Linear, single-action-per-step Burr application.
+
+    Order: cheap-first geo + flood layers, then live live network signals,
+    then RAG → reconcile. Heavy specialists (NYCHA / DOE / DOH register
+    joins, Prithvi-EO live STAC, TerraMind diffusion) are gated behind
+    RIPRAP_HEAVY_SPECIALISTS — see the module-level note above.
+    """
+    builder = (
+        ApplicationBuilder()
+        .with_state(query=query, trace=[])
+        .with_entrypoint("geocode")
+    )
+
+    actions: dict[str, Any] = {
+        "geocode": step_geocode,
+        "sandy": step_sandy,
+        "dep": step_dep,
+        "floodnet": step_floodnet,
+        "nyc311": step_311,
+        "noaa_tides": step_noaa_tides,
+        "nws_alerts": step_nws_alerts,
+        "nws_obs": step_nws_obs,
+        "ttm_forecast": step_ttm_forecast,
+        "ttm_311_forecast": step_ttm_311_forecast,
+        "floodnet_forecast": step_floodnet_forecast,
+        "npcc4_projection": step_npcc4_projection,
+        "ttm_battery_surge": step_ttm_battery_surge,
+        "microtopo": step_microtopo,
+        "ida_hwm": step_ida_hwm,
+        "mta_entrances": step_mta_entrances,
+        "prithvi": step_prithvi,  # baked GeoJSON polygons for Ida; cheap
+    }
+    if _HEAVY_SPECIALISTS_ENABLED and _NYCHA_REGISTERS_ENABLED:
+        actions["nycha"] = step_nycha
+        actions["doe_schools"] = step_doe_schools
+        actions["doh_hospitals"] = step_doh_hospitals
+    if _HEAVY_SPECIALISTS_ENABLED:
+        actions["prithvi_live"] = step_prithvi_live
+        actions["terramind"] = step_terramind
+        # New TerraMind-NYC LoRA family — one chip fetch feeds two
+        # specialists. Keep eo_chip directly before the two consumers
+        # so the chip stays warm in memory and isn't garbage-collected
+        # by anything in between.
+        actions["eo_chip"] = step_eo_chip
+        actions["terramind_lulc"] = step_terramind_lulc
+        actions["terramind_buildings"] = step_terramind_buildings
+    actions["rag"] = step_rag
+    actions["gliner"] = step_gliner
+    actions["reconcile"] = step_reconcile
+
+    # Sequential transitions — pair every adjacent action in the dict order.
+    keys = list(actions.keys())
+    transitions = list(zip(keys, keys[1:]))
+
+    return (
+        builder.with_actions(**actions).with_transitions(*transitions).build()
+    )
+
+
+def _summarize_energy(trace: list) -> dict | None:
+    rec_step = next((t for t in trace if t.get("step") == "reconcile_granite41"
+                     and t.get("ok")), None)
+    if not rec_step:
+        return None
+    total_s = sum(t.get("elapsed_s", 0) or 0 for t in trace)
+    return energy_estimate(rec_step.get("elapsed_s", 0) or 0, total_s)
+
+
+def _summarize_emissions() -> dict | None:
+    """Snapshot the active per-call emissions tracker, if installed.
+
+    Returns None when no tracker is bound to this thread (e.g. unit
+    tests that call `fsm.run` directly without going through the
+    web/intent layer that installs one)."""
+    t = emissions.current()
+    return t.summarize() if t is not None else None
+
+
+def run(query: str) -> dict[str, Any]:
+    app = build_app(query)
+    final_action, _, final_state = app.run(halt_after=["reconcile"])
+    trace = final_state.get("trace", [])
+    return {
+        "query": query,
+        "geocode": final_state.get("geocode"),
+        "sandy": final_state.get("sandy"),
+        "dep": final_state.get("dep"),
+        "floodnet": final_state.get("floodnet"),
+        "nyc311": final_state.get("nyc311"),
+        "microtopo": final_state.get("microtopo"),
+        "ida_hwm": final_state.get("ida_hwm"),
+        "prithvi_water": final_state.get("prithvi_water"),
+        "terramind": final_state.get("terramind"),
+        "terramind_lulc": final_state.get("terramind_lulc"),
+        "terramind_buildings": final_state.get("terramind_buildings"),
+        "eo_chip": final_state.get("eo_chip"),
+        "noaa_tides": final_state.get("noaa_tides"),
+        "nws_alerts": final_state.get("nws_alerts"),
+        "nws_obs": final_state.get("nws_obs"),
+        "ttm_forecast": final_state.get("ttm_forecast"),
+        "ttm_311_forecast": final_state.get("ttm_311_forecast"),
+        "floodnet_forecast": final_state.get("floodnet_forecast"),
+        "ttm_battery_surge": final_state.get("ttm_battery_surge"),
+        "mta_entrances": final_state.get("mta_entrances"),
+        "nycha_developments": final_state.get("nycha_developments"),
+        "doe_schools": final_state.get("doe_schools"),
+        "doh_hospitals": final_state.get("doh_hospitals"),
+        "rag": final_state.get("rag"),
+        "paragraph": final_state.get("paragraph"),
+        "audit": final_state.get("audit"),
+        "mellea": final_state.get("mellea"),
+        "energy": _summarize_energy(trace),
+        "emissions": _summarize_emissions(),
+        "trace": trace,
+    }
+
+
+def iter_steps(query: str):
+    """Yield SSE-friendly events as the FSM runs.
+
+    Each Burr action emits exactly one trace record on completion; we
+    yield it as a `step` event the moment the iterate loop returns from
+    that action. Reconciler tokens stream through the threadlocal
+    `set_token_callback` (installed before this generator is iterated),
+    not through this queue.
+
+    Burr's `app.iterate(halt_after=["reconcile"])` runs synchronously,
+    yielding `(action, result, state)` after every action. We drive it
+    in a background thread so the per-action SSE events reach the
+    client as soon as each action returns, while the reconciler's
+    token callback fires concurrently from the same thread.
+    """
+    import queue
+
+    q: queue.Queue[tuple[str, Any] | None] = queue.Queue()
+    seen_keys: set[tuple[str, float]] = set()
+
+    def _push_step(rec: dict) -> None:
+        key = (rec.get("step", ""), rec.get("started_at", 0.0))
+        if key in seen_keys:
+            return
+        seen_keys.add(key)
+        q.put(("step", rec))
+
+    app = build_app(query)
+    final_state_holder: dict[str, Any] = {}
+
+    # Threadlocals are per-thread; the request thread (single_address.run
+    # / neighborhood.run) sets the strict-mode flag, planner specialist
+    # set, and token / Mellea-attempt callbacks, but Burr's app.iterate
+    # runs in this generator's thread. Snapshot the request-thread state
+    # and re-install on the iterate thread so step_reconcile sees them.
+    _captured_strict = _current_strict_mode()
+    _captured_planned = _current_planned_specialists()
+    _captured_token_cb = _current_token_callback()
+    _captured_mellea_cb = _current_mellea_attempt_callback()
+    _captured_tracker = emissions.current()
+
+    def _run_iterate():
+        set_strict_mode(_captured_strict)
+        set_planned_specialists(_captured_planned)
+        set_token_callback(_captured_token_cb)
+        set_mellea_attempt_callback(_captured_mellea_cb)
+        emissions.install(_captured_tracker)
+        try:
+            for _action_obj, _result, state in app.iterate(halt_after=["reconcile"]):
+                final_state_holder["state"] = state
+                # Each action appends one record to state.trace; emit the
+                # most recent so the SSE client gets the step event the
+                # moment Burr returns from that action.
+                trace = state.get("trace") or []
+                if trace:
+                    _push_step(trace[-1])
+        except Exception as e:
+            log.exception("iterate raised")
+            q.put(("error", {"err": f"{type(e).__name__}: {e}"}))
+        finally:
+            set_strict_mode(False)
+            set_planned_specialists(None)
+            set_token_callback(None)
+            set_mellea_attempt_callback(None)
+            emissions.install(None)
+            q.put(None)  # sentinel
+
+    runner = _threading.Thread(target=_run_iterate, name="riprap-fsm",
+                               daemon=True)
+    runner.start()
+
+    while True:
+        item = q.get()
+        if item is None:
+            break
+        kind, payload = item
+        if kind == "step":
+            yield {
+                "kind": "step",
+                "step": payload.get("step"),
+                "ok": payload.get("ok"),
+                "elapsed_s": payload.get("elapsed_s"),
+                "result": payload.get("result"),
+                "err": payload.get("err"),
+            }
+        elif kind == "error":
+            yield {"kind": "error", **payload}
+
+    runner.join(timeout=5)
+    state = final_state_holder.get("state")
+    if state is None:
+        yield {"kind": "final", "paragraph": "", "error": "FSM failed before any action completed"}
+        return
+    trace = state.get("trace", [])
+    yield {
+        "kind": "final",
+        "geocode": state.get("geocode"),
+        "sandy": state.get("sandy"),
+        "dep": state.get("dep"),
+        "floodnet": state.get("floodnet"),
+        "nyc311": state.get("nyc311"),
+        "microtopo": state.get("microtopo"),
+        "ida_hwm": state.get("ida_hwm"),
+        "prithvi_water": state.get("prithvi_water"),
+        "prithvi_live": state.get("prithvi_live"),
+        "terramind": state.get("terramind"),
+        "terramind_lulc": state.get("terramind_lulc"),
+        "terramind_buildings": state.get("terramind_buildings"),
+        "noaa_tides": state.get("noaa_tides"),
+        "nws_alerts": state.get("nws_alerts"),
+        "nws_obs": state.get("nws_obs"),
+        "ttm_forecast": state.get("ttm_forecast"),
+        "ttm_311_forecast": state.get("ttm_311_forecast"),
+        "floodnet_forecast": state.get("floodnet_forecast"),
+        "ttm_battery_surge": state.get("ttm_battery_surge"),
+        "mta_entrances": state.get("mta_entrances"),
+        "nycha_developments": state.get("nycha_developments"),
+        "doe_schools": state.get("doe_schools"),
+        "doh_hospitals": state.get("doh_hospitals"),
+        "rag": state.get("rag"),
+        "gliner": state.get("gliner"),
+        "paragraph": state.get("paragraph"),
+        "audit": state.get("audit"),
+        "mellea": state.get("mellea"),
+        "citations": state.get("citations"),
+        "energy": _summarize_energy(trace),
+        "emissions": _summarize_emissions(),
+    }

app/geocode.py

@@ -0,0 +1,138 @@
+"""Address geocoding — NYC primary + national fallback.
+
+NYC primary: NYC DCP Geosearch (geosearch.planninglabs.nyc), no auth,
+NYC-only. It will fuzzy-match upstate addresses to NYC streets — e.g.
+'257 Washington Ave, Albany NY' silently maps to Clinton Hill, Brooklyn.
+We detect this via a non-NYC region or non-NYC ZIP and fall back to
+OpenStreetMap Nominatim (no key, free, rate-limited per usage policy).
+
+Includes a borough-hint post-filter so Queens hyphenated-style addresses
+(e.g. '153-09 90 Ave, Jamaica, Queens') preferentially resolve to the
+borough the user named.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+
+import httpx
+
+log = logging.getLogger("riprap.geocode")
+
+URL = "https://geosearch.planninglabs.nyc/v2/search"
+NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
+NOMINATIM_UA = "Riprap-NYC/0.5 (civic-flood-tool; +https://huggingface.co/spaces/msradam/riprap-nyc)"
+
+# NYC-bbox guard: lat 40.49–40.92, lon -74.27 to -73.69.
+NYC_BBOX = (40.49, -74.27, 40.92, -73.69)
+
+_UPSTATE_ZIP_RE = re.compile(r"\b1[2-4]\d{3}\b")
+_BOROUGHS = ("Manhattan", "Bronx", "Brooklyn", "Queens", "Staten Island")
+
+def _detect_borough(text: str) -> str | None:
+    t = text.lower()
+    for b in _BOROUGHS:
+        if b.lower() in t:
+            return b
+    # neighborhood -> borough hints
+    hints = {
+        "queens": "Queens", "jamaica": "Queens", "rockaway": "Queens",
+        "astoria": "Queens", "flushing": "Queens",
+        "manhattan": "Manhattan", "harlem": "Manhattan", "soho": "Manhattan",
+        "brooklyn": "Brooklyn", "bushwick": "Brooklyn", "red hook": "Brooklyn",
+        "bronx": "Bronx", "fordham": "Bronx",
+        "staten island": "Staten Island",
+    }
+    for needle, boro in hints.items():
+        if needle in t:
+            return boro
+    return None
+
+@dataclass
+class GeocodeHit:
+    address: str
+    borough: str | None
+    lat: float
+    lon: float
+    bbl: str | None
+    bin: str | None
+    raw: dict
+
+def geocode(text: str, limit: int = 5) -> list[GeocodeHit]:
+    """NYC Geosearch primary."""
+    try:
+        r = httpx.get(URL, params={"text": text, "size": limit}, timeout=5)
+        r.raise_for_status()
+        feats = r.json().get("features", [])
+        out = []
+        for f in feats:
+            p = f.get("properties", {})
+            coords = (f.get("geometry") or {}).get("coordinates") or [None, None]
+            out.append(GeocodeHit(
+                address=p.get("label") or p.get("name") or text,
+                borough=p.get("borough"),
+                lat=coords[1],
+                lon=coords[0],
+                bbl=p.get("addendum", {}).get("pad", {}).get("bbl"),
+                bin=p.get("addendum", {}).get("pad", {}).get("bin"),
+                raw=p,
+            ))
+        return out
+    except Exception as e:
+        log.warning("Geosearch failed: %r", e)
+        return []
+
+def geocode_nominatim(text: str) -> GeocodeHit | None:
+    """National OSM Nominatim fallback."""
+    try:
+        r = httpx.get(NOMINATIM_URL, params={
+            "q": text, "format": "jsonv2", "addressdetails": "1",
+            "limit": 1, "countrycodes": "us",
+        }, headers={"User-Agent": NOMINATIM_UA}, timeout=10)
+        r.raise_for_status()
+        rows = r.json()
+    except Exception as e:
+        log.warning("Nominatim fetch failed: %r", e)
+        return None
+    if not rows:
+        return None
+    row = rows[0]
+    addr = row.get("address") or {}
+    
+    # Try to map Nominatim borough/county back to NYC standard
+    boro = addr.get("suburb") or addr.get("city_district") or addr.get("county")
+    if boro and "Kings" in boro: boro = "Brooklyn"
+    if boro and "New York County" in boro: boro = "Manhattan"
+    if boro and "Queens" in boro: boro = "Queens"
+    if boro and "Bronx" in boro: boro = "Bronx"
+    if boro and "Richmond" in boro: boro = "Staten Island"
+
+    return GeocodeHit(
+        address=row.get("display_name") or text,
+        borough=boro,
+        lat=float(row["lat"]),
+        lon=float(row["lon"]),
+        bbl=None, # Nominatim doesn't have BBLs
+        bin=None,
+        raw={"source": "nominatim", **row},
+    )
+
+def geocode_one(text: str) -> GeocodeHit | None:
+    """Dynamic geocoder with failover."""
+    # 1. Try Geosearch
+    hits = geocode(text)
+    hint = _detect_borough(text)
+    
+    if hint:
+        in_boro = [h for h in hits if h.borough and h.borough.lower() == hint.lower()]
+        if in_boro: return in_boro[0]
+    
+    if hits:
+        top = hits[0]
+        if top.lat and 40.4 <= top.lat <= 41.0: # Broad NYC check
+            return top
+
+    # 2. Fall back to Nominatim
+    log.info("Falling back to Nominatim for %r", text)
+    return geocode_nominatim(text)

app/inference.py

@@ -0,0 +1,268 @@
+"""Remote-vs-local ML inference router.
+
+Mirrors the call-surface shape of `app/llm.py` but for the non-LLM
+heavy models (Prithvi, TerraMind, TTM, Granite Embedding, GLiNER).
+
+The droplet runs a `riprap-models` FastAPI service alongside vLLM that
+exposes an OpenAI-style endpoint per model class. When configured the
+router POSTs the relevant payload there and returns the parsed response;
+on connection error / 5xx / timeout it surfaces a typed exception that
+caller modules catch and fall back to a local in-process model load.
+
+Backend selection (env):
+
+  RIPRAP_ML_BACKEND   = "remote" | "local" | "auto"  (default: auto)
+                        - remote: use only the droplet, raise if it errors
+                        - local : never call the droplet, always use the
+                                  in-process model
+                        - auto  : try remote first, fall back to local if
+                                  remote is unreachable / errors out;
+                                  same semantics as app/llm.py
+  RIPRAP_ML_BASE_URL  = http://129.212.181.238:8002    (no trailing slash)
+  RIPRAP_ML_API_KEY   = <bearer token>
+
+The router is *transport*-only — it does not own model bytes, weights,
+or framework imports. Each specialist that wants remote inference calls
+into the helpers below and provides its own local fallback. That keeps
+the dependency graph clean: the local code path keeps working when the
+RIPRAP_ML_* env is unset (e.g. on first-light dev or in unit tests).
+"""
+from __future__ import annotations
+
+import base64
+import logging
+import os
+import time
+from collections.abc import Iterable
+from typing import Any
+
+import httpx
+
+from app import emissions
+
+log = logging.getLogger("riprap.inference")
+
+_BACKEND = os.environ.get("RIPRAP_ML_BACKEND", "auto").lower()
+_BASE_URL = os.environ.get("RIPRAP_ML_BASE_URL", "").rstrip("/")
+_API_KEY = os.environ.get("RIPRAP_ML_API_KEY", "")
+_DEFAULT_TIMEOUT = float(os.environ.get("RIPRAP_ML_TIMEOUT_S", "60"))
+
+
+class RemoteUnreachable(RuntimeError):
+    """Raised when the remote inference service is unconfigured, down,
+    times out, or returns 5xx. Callers catch this to fall through to a
+    local model load. 4xx errors propagate as the generic exception so
+    a caller bug doesn't get masked by a "fallback to local" path."""
+
+
+def remote_enabled() -> bool:
+    """True iff the router is configured to attempt remote calls.
+    Returns False under explicit `local` mode or when the base URL is
+    empty (the auto-default with no env config)."""
+    if _BACKEND == "local":
+        return False
+    if not _BASE_URL:
+        return False
+    return True
+
+
+def _client(timeout: float | None = None) -> httpx.Client:
+    headers = {"User-Agent": "riprap-app/0.4.5"}
+    if _API_KEY:
+        headers["Authorization"] = f"Bearer {_API_KEY}"
+    return httpx.Client(
+        base_url=_BASE_URL,
+        headers=headers,
+        timeout=timeout if timeout is not None else _DEFAULT_TIMEOUT,
+    )
+
+
+def _post(path: str, payload: dict[str, Any], timeout: float | None = None) -> dict:
+    """POST {payload} as JSON to the remote service's `path`. Returns the
+    parsed JSON body. Raises RemoteUnreachable on transport errors;
+    raises HTTPStatusError on 4xx so caller bugs surface."""
+    if not remote_enabled():
+        raise RemoteUnreachable("remote ML backend not configured "
+                                "(RIPRAP_ML_BASE_URL empty or BACKEND=local)")
+    t0 = time.monotonic()
+    try:
+        with _client(timeout) as c:
+            r = c.post(path, json=payload)
+    except (httpx.ConnectError, httpx.ReadError, httpx.WriteError,
+             httpx.TimeoutException, httpx.RemoteProtocolError) as e:
+        raise RemoteUnreachable(f"{type(e).__name__}: {e}") from e
+    if r.status_code >= 500:
+        raise RemoteUnreachable(f"HTTP {r.status_code} from {path}: {r.text[:200]}")
+    r.raise_for_status()
+    duration_s = time.monotonic() - t0
+    # Hardware: msradam/riprap-vllm runs on NVIDIA L4. Operators can
+    # override via RIPRAP_HARDWARE_LABEL. The proxy reports per-call
+    # GPU energy off NVML in the X-GPU-Energy-J / X-GPU-Power-W headers
+    # — read those for a real measurement instead of the data-sheet
+    # estimate when present.
+    override = (os.environ.get("RIPRAP_HARDWARE_LABEL") or "").lower()
+    if "mi300x" in override or "amd" in override:
+        hw = "amd_mi300x"
+    elif "t4" in override:
+        hw = "nvidia_t4"
+    else:
+        hw = "nvidia_l4"
+    joules_real, power_w_real = _parse_gpu_headers(r.headers)
+    emissions.active().record_ml(
+        endpoint=path,
+        backend="riprap-models",
+        hardware=hw,
+        duration_s=duration_s,
+        joules_real=joules_real,
+        power_w_real=power_w_real,
+    )
+    return r.json()
+
+
+def _parse_gpu_headers(headers) -> tuple[float | None, float | None]:
+    """Pull (joules, watts) from X-GPU-Energy-J / X-GPU-Power-W if the
+    proxy attached them. Returns (None, None) if the headers are absent
+    (older proxy build, NVML init failed, or the call streamed)."""
+    def _f(name: str) -> float | None:
+        v = headers.get(name)
+        if v is None or v == "":
+            return None
+        try:
+            return float(v)
+        except ValueError:
+            return None
+    return _f("x-gpu-energy-j"), _f("x-gpu-power-w")
+
+
+def _serialize_array(arr) -> str:
+    """numpy/torch tensor → base64-encoded float32 raw bytes for transport.
+    Each remote handler decodes to (shape, dtype=float32) and reconstructs.
+    Reasonable round-trip for chips up to a few MB; large rasters should
+    use compressed numpy-savez instead — TODO when a model needs > 8 MB."""
+    import numpy as np
+    np_arr = arr if isinstance(arr, np.ndarray) else _to_numpy(arr)
+    np_arr = np_arr.astype("float32", copy=False)
+    return base64.b64encode(np_arr.tobytes()).decode("ascii")
+
+
+def _to_numpy(t):
+    """Best-effort tensor → numpy. Accepts torch.Tensor or numpy already."""
+    try:
+        import torch
+        if isinstance(t, torch.Tensor):
+            return t.detach().cpu().numpy()
+    except ImportError:
+        pass
+    import numpy as np
+    return np.asarray(t)
+
+
+def _deserialize_array(b64: str, shape: list[int]):
+    """Inverse of _serialize_array — bytes → numpy float32 with given shape."""
+    import numpy as np
+    raw = base64.b64decode(b64)
+    return np.frombuffer(raw, dtype="float32").reshape(shape)
+
+
+# ---- Public router entry points -------------------------------------------
+
+def healthcheck(timeout: float = 3.0) -> bool:
+    """Quick reachability probe. True if the service responds 200 to GET
+    /healthz within `timeout` seconds. Used by /api/backend so the UI can
+    show whether the remote ML backend is currently live."""
+    if not remote_enabled():
+        return False
+    try:
+        with _client(timeout) as c:
+            r = c.get("/healthz")
+        return r.status_code == 200
+    except Exception:
+        return False
+
+
+def backend_info() -> dict[str, Any]:
+    """Snapshot for /api/backend — what the UI should advertise."""
+    return {
+        "backend": _BACKEND,
+        "base_url": _BASE_URL or None,
+        "remote_enabled": remote_enabled(),
+        "reachable": healthcheck() if remote_enabled() else False,
+    }
+
+
+def prithvi_pluvial(s2_chip, *, scene_id: str | None = None,
+                     scene_datetime: str | None = None,
+                     cloud_cover: float | None = None,
+                     timeout: float | None = None) -> dict[str, Any]:
+    """Remote forward pass through Prithvi-NYC-Pluvial v2.
+    Input: 6-band Sentinel-2 chip (numpy or torch, shape [6, H, W]).
+    Output: { ok, pct_water_within_500m, pct_water_full, scene_id, ... }.
+    Raises RemoteUnreachable if the service is down."""
+    arr = _to_numpy(s2_chip)
+    return _post("/v1/prithvi-pluvial", {
+        "s2": _serialize_array(arr),
+        "shape": list(arr.shape),
+        "scene_id": scene_id,
+        "scene_datetime": scene_datetime,
+        "cloud_cover": cloud_cover,
+    }, timeout=timeout)
+
+
+def terramind(adapter: str, s2l2a=None, s1rtc=None, dem=None, *,
+               timeout: float | None = None) -> dict[str, Any]:
+    """Remote forward through TerraMind-NYC-Adapters (LULC or Buildings)
+    or the v1 base generative path (synthesis). `adapter` is one of:
+    lulc, buildings, synthesis. Each modality is a numpy array, torch
+    tensor, or None — `synthesis` only needs DEM; the LoRA adapters
+    need at minimum S2L2A."""
+    payload: dict[str, Any] = {"adapter": adapter}
+    if s2l2a is not None:
+        s2_np = _to_numpy(s2l2a)
+        payload["s2"] = _serialize_array(s2_np)
+        payload["s2_shape"] = list(s2_np.shape)
+    if s1rtc is not None:
+        s1_np = _to_numpy(s1rtc)
+        payload["s1"] = _serialize_array(s1_np)
+        payload["s1_shape"] = list(s1_np.shape)
+    if dem is not None:
+        dem_np = _to_numpy(dem)
+        payload["dem"] = _serialize_array(dem_np)
+        payload["dem_shape"] = list(dem_np.shape)
+    return _post("/v1/terramind", payload, timeout=timeout)
+
+
+def ttm_forecast(model: str, history: Iterable[float], *,
+                  context_length: int, prediction_length: int,
+                  cadence: str = "h",
+                  timeout: float | None = None) -> dict[str, Any]:
+    """Remote Granite TTM r2 forecast.
+    `model` is one of: zero_shot_battery, fine_tune_battery, weekly_311,
+    floodnet_recurrence — the service decides which checkpoint to use.
+    `history` is a 1-D iterable of floats (the time series); `cadence`
+    is for the service's labelling (h / d / w / 6m). Output shape is
+    `{ ok, forecast: [...], peak_index, peak_value }`."""
+    series = list(map(float, history))
+    return _post("/v1/ttm-forecast", {
+        "model": model,
+        "history": series,
+        "context_length": context_length,
+        "prediction_length": prediction_length,
+        "cadence": cadence,
+    }, timeout=timeout)
+
+
+def granite_embed(texts: list[str], *,
+                   timeout: float | None = None) -> dict[str, Any]:
+    """Remote Granite Embedding 278M batch encode.
+    Output: { ok, vectors: [[float, ...], ...] }. Vector dimension fixed
+    at 768 (granite-embedding-278m-multilingual)."""
+    return _post("/v1/granite-embed", {"texts": list(texts)}, timeout=timeout)
+
+
+def gliner_extract(text: str, labels: list[str], *,
+                    timeout: float | None = None) -> dict[str, Any]:
+    """Remote GLiNER typed-entity extraction.
+    Output: { ok, entities: [{label, text, start, end, score}, ...] }."""
+    return _post("/v1/gliner-extract", {
+        "text": text, "labels": list(labels),
+    }, timeout=timeout)

app/intents/__init__.py

@@ -0,0 +1,3 @@
+"""Per-intent execution modules. Each intent knows how to take a planner
+Plan and run only the specialists relevant to it, returning a
+reconciler-ready set of documents and a paragraph."""