v0.13: Tier-1 multi-city expansion — Chicago + NYC + SF + LA + Austin

Refactors the Chicago-only local_agent into a city-aware system driven
by a registry. Each registry entry encodes the city's Socrata dataset
IDs, field names, flood-related category codes, and a context blurb
that gets injected into the local-agent prompt so Gemma 4 reasons
about each city's actual sewer system (combined vs separated, dominant
flood mode, local hazard pattern).

Honest per-city availability — what each city's dossier actually shows:

Chicago: full — 311 (WIB/SFL) + permits with reported_cost
(e.g. $80M new medical office at 4822 S Cottage Grove)
NYC: 311 — 391 sewer-flood reports per 350 5th Ave query.
Permits intentionally deferred: DOB datasets are
fragmented (legacy is stale, modern lacks dates,
active is filtered to currently-open jobs).
SF: full — 941 sewer reports + 75 permits at $366M (Mission
test point: '595 basement reports, increasing
development pressure, concern: high')
LA: permits-only — 142 permits, $320M, top $99M downtown.
LA's separated storm-sanitary system means basement
sewer-backup is rare; 311 doesn't categorize floods
cleanly enough so it's deferred.
Austin: 311 + permits-count — 91 flood-coded 311 reports + 500
permits but no cost field in the Socrata dataset.
The dossier honestly says count-only.

Atlanta + every other city: graceful 'Tier 1 cities are X' message.

Verified end-to-end via scripts/smoke_test_cities.py and full pipeline
runs. Per-city context blurbs visibly steer Gemma's reasoning:
- NYC output references 'combined-sewer overflow (CSO) failures in
Manhattan' specifically
- SF output references 'fully combined sewer system'
- LA blurb (separated system, flash-flood mode) calibrates the model
away from sewer-backup framing

Backend changes:
+ backend/app/data/cities.py — registry of 5 cities with verified
dataset IDs, field names, and category values. Match function takes
geocoded city/state and returns the right config (or None for graceful
degrade).
~ backend/app/tools/chicago_311.py — refactored to take a config dict.
Generic across cities. Uses within_circle() when the dataset has a
Socrata Point column, falls back to bbox-with-:: number cast for
cities (NYC, LA) that store lat/lon as text.
~ backend/app/tools/building_permits.py — same refactor. Also handles
cities (SF) where the cost field itself is text-stored, casts via
PostgreSQL :: number syntax (to_number() doesn't exist on these
Socrata flavors).
~ backend/app/agents/local_agent.py — uses find_city() instead of
hardcoded 'is_chicago' check. Runs whatever signals the city has
(could be both, 311-only, permits-only). Prompt explicitly tells
Gemma which signals are available + what's missing so it doesn't
fabricate narrative for absent data. New flags surfaced on the
result dict: city_supported, city_id, has_311, has_permits,
has_permit_cost — frontend uses these for honest UI degradation.
+ backend/scripts/smoke_test_cities.py — pre-deploy regression check
for all 5 supported cities + 1 graceful-degrade case.

Bugs caught and fixed during the refactor:
- to_number() — doesn't exist on Socrata SoQL. Use PostgreSQL :: cast.
- Some cities store BOTH lat/lon AND cost as text strings — needs the
same :: cast trick on the cost filter.
- Austin 311 column was sr_location_long_text in the spec; real name
is sr_location with a separate sr_location_lat_long Point col.
- SF permits has a real Socrata Point 'location' column we can use
for within_circle() instead of bbox math.
- NYC dates are MM/DD/YYYY strings in the legacy dataset — string
compare with ISO format excludes everything.

Future work (deferred): Boston (CKAN, not Socrata), Dallas (no working
311 dataset ID), Houston/Miami (different platforms). Each requires
custom integration; Tier-1 5 cities is the realistic hackathon scope.

Version: chrome wordmark v0.12 → v0.13, app version 0.12.0 → 0.13.0.

app/agents/local_agent.py

@@ -1,25 +1,23 @@
-"""Local infrastructure / 311 + building-permits agent.
-
-Currently Chicago-only. Pulls TWO Socrata signals in parallel and asks
-Gemma 4 to interpret them together:
-
-  1. 311 flood reports (WIB / SFL) within 500m / 5y — the historical
-     symptom: where flooding has actually been reported.
-  2. Building permits (new construction + major renovations >$100K)
-     within 1km / 3y — the leading indicator: where the impervious
-     surface is growing and the combined sewer load is increasing.
-
-These signals compound. A property in a stable block with 0 311
-reports is one risk profile. A property in a stable block with 0
-311 reports BUT $80M of new construction permitted nearby is another
-— the model can read the trajectory, not just the snapshot.
-
-For non-Chicago cities, returns a graceful "no local dataset wired"
-message so the rest of the dossier still completes.
+"""Local infrastructure agent — 311 + building permits, city-aware.
+
+Now driven by the registry in app.data.cities. For any supported city
+we run the two Socrata signals in parallel and ask Gemma 4 to interpret
+them together, with city-specific context (combined-vs-separated
+sewers, dominant flood mode, local hazard pattern) injected into the
+prompt so the reasoning is calibrated to the right system.
+
+Honest about per-city data quality:
+  - Cities with both signals (Chicago, NYC, SF, Austin) get the full
+    "compound signal" narrative.
+  - Cities with only one signal (LA: permits-only) get a partial
+    narrative that explicitly says what's missing.
+  - Cities not in the registry get a clean "not supported here"
+    summary so the rest of the dossier still completes.
 """
 import asyncio
 import json
 
+from app.data.cities import find_city
 from app.llm.client import call_gemma4, extract_text, parse_json_response
 from app.llm.prompts import LOCAL_AGENT_SYSTEM_PROMPT
 from app.tools.building_permits import get_nearby_construction
@@ -32,43 +30,52 @@ async def run_local_agent(
     city: str,
     state: str,
 ) -> dict:
-    is_chicago = (
-        city.lower() == "chicago" or "chicago" in city.lower()
-    ) and state.lower() in ("illinois", "il")
+    cfg = find_city(city, state)
 
-    if not is_chicago:
+    if cfg is None:
         return {
             "city": city,
             "data_available": False,
             "summary": (
-                f"No local-311 dataset wired for {city or 'this location'}; "
-                "Chicago is the demo city for the 311 + permits signals."
+                f"No local-data integration wired for {city or 'this location'}; "
+                "Tier 1 cities are Chicago, NYC, San Francisco, Los Angeles, Austin."
             ),
             "basement_flooding_reports": 0,
             "street_flooding_reports": 0,
             "construction": {"permits_found": False},
         }
 
-    # Two Socrata calls in parallel — same platform, different datasets.
-    reports_task = asyncio.create_task(
-        get_flood_reports(lat, lon, radius_m=500, years=5)
-    )
-    construction_task = asyncio.create_task(
-        get_nearby_construction(lat, lon, radius_m=1000, years=3, min_cost=100_000)
-    )
-    reports, construction = await asyncio.gather(
-        reports_task, construction_task, return_exceptions=False
-    )
-
-    # Sanitize construction for the prompt — drop the verbose major-projects
-    # descriptions to keep the prompt tight; we'll keep the full data on
-    # the agent's return for the dossier UI.
+    has_311 = cfg.get("311") is not None
+    has_permits = cfg.get("permits") is not None
+
+    # Run whichever signals this city actually has, in parallel.
+    tasks = []
+    if has_311:
+        tasks.append(("reports", asyncio.create_task(
+            get_flood_reports(cfg, lat, lon, radius_m=500, years=5)
+        )))
+    if has_permits:
+        tasks.append(("construction", asyncio.create_task(
+            get_nearby_construction(cfg, lat, lon, radius_m=1000, years=3, min_cost=100_000)
+        )))
+    results: dict = {}
+    for name, t in tasks:
+        try:
+            results[name] = await t
+        except Exception as e:
+            results[name] = {"error": f"{type(e).__name__}: {str(e)[:100]}"}
+
+    reports = results.get("reports") or {}
+    construction = results.get("construction") or {}
+
+    # Trim construction for the prompt — don't dump 5 long descriptions
+    # into the system; we keep the full data on the agent's return for
+    # the dossier UI to render.
     construction_for_prompt = {
-        k: v for k, v in (construction or {}).items()
-        if k not in ("major_projects",)
+        k: v for k, v in construction.items() if k not in ("major_projects",)
     }
     construction_for_prompt["major_projects_count"] = len(
-        (construction or {}).get("major_projects") or []
+        construction.get("major_projects") or []
     )
     construction_for_prompt["major_projects_top3"] = [
         {
@@ -78,52 +85,54 @@ async def run_local_agent(
             "description": (p.get("description") or "")[:120],
             "address": p.get("address"),
         }
-        for p in ((construction or {}).get("major_projects") or [])[:3]
+        for p in (construction.get("major_projects") or [])[:3]
     ]
 
-    user_prompt = f"""Interpret these TWO Chicago Socrata signals together for the property at ({lat}, {lon}).
+    has_cost = construction.get("has_cost", False)
+    cost_note = (
+        ""
+        if has_cost
+        else (
+            "NOTE: this city's permits dataset does NOT expose project cost. "
+            "Reason about permit COUNT, project type, and trend direction — "
+            "do NOT report dollar amounts you don't actually have."
+        )
+    )
 
-## 311 flood reports (the historical symptom)
-{json.dumps(reports, indent=2, default=str)}
+    user_prompt = f"""You are interpreting LOCAL infrastructure signals for a property in {cfg['name']} ({lat}, {lon}).
 
-Context for 311:
-- "WIB" = Water in Basement, "SFL" = Street Flooding
-- Search radius: {reports.get('radius_m')} m, time window: {reports.get('years')} years
-- Chicago combined sewer overflows after ~0.67 in/hr of rain
+City context (use this to calibrate your reasoning):
+{cfg['context_blurb']}
 
-## Building permits (the leading indicator of impervious-surface change)
-{json.dumps(construction_for_prompt, indent=2, default=str)}
+## 311 service-request signal — historical symptom
+{f"Available for {cfg['name']}" if has_311 else "NOT AVAILABLE for this city — skip 311 reasoning."}
+{json.dumps(reports, indent=2, default=str) if has_311 else ""}
 
-Context for permits:
-- New construction + major renovations within 1km, last 3 years, > $100K
-- Each new structure replaces absorbent ground with roof + foundation
-- Each new parking lot replaces vegetation with asphalt
-- The combined sewer system serving these blocks does NOT get upgraded
-  when density increases — so each new permit shifts more stormwater
-  load onto the same shared pipes
-- Trend "increasing" = neighborhood is actively densifying = future
-  flood risk is rising even if current 311 signal is clean
+## Building permits signal — leading indicator of impervious-surface change
+{f"Available for {cfg['name']}" if has_permits else "NOT AVAILABLE for this city — skip permit reasoning."}
+{json.dumps(construction_for_prompt, indent=2, default=str) if has_permits else ""}
+{cost_note}
 
-Return a JSON object combining both signals with these fields:
+Return a JSON object combining whatever signals were available with these fields:
 {{
   "basement_flooding_reports": int,
   "street_flooding_reports": int,
   "total_reports": int,
-  "density_assessment": "low" | "moderate" | "high",
-  "pattern_notes": "1-2 sentences on the 311 recency / clustering",
+  "density_assessment": "low" | "moderate" | "high" | "n/a",
+  "pattern_notes": "1-2 sentences on the 311 pattern, or 'No 311 signal available for this city.'",
   "construction": {{
     "permits_count": int,
     "new_construction_count": int,
-    "total_cost": number,
+    "total_cost": number_or_null,
     "trend_direction": "increasing" | "stable" | "decreasing",
-    "interpretation": "1-2 sentences on what the development pressure means for THIS property's future flood risk — explicitly connect to impervious-surface change and the combined-sewer load",
+    "interpretation": "1-2 sentences on what the development pressure means for THIS property's future flood risk in THIS city's drainage system",
     "concern_level": "low" | "moderate" | "high"
   }},
-  "compound_signal": "1-2 sentences on how the 311 history and the permit trajectory interact — e.g. 'clean 311 today + heavy densification = rising risk' or 'high 311 + active densification = compounding risk'",
-  "summary": "1 sentence for the status feed (covers BOTH signals)"
+  "compound_signal": "1-2 sentences on how the available signals interact for {cfg['name']} specifically. If only one signal is available, say so explicitly.",
+  "summary": "1 sentence for the status feed"
 }}
 
-Return ONLY the JSON object, no other text."""
+Return ONLY the JSON object."""
 
     response = await call_gemma4(
         messages=[
@@ -137,15 +146,25 @@ Return ONLY the JSON object, no other text."""
     text = extract_text(response)
     parsed = parse_json_response(text)
     if parsed:
-        parsed["raw_311"] = reports
-        parsed["raw_construction"] = construction
+        parsed["raw_311"] = reports if has_311 else {"supported": False}
+        parsed["raw_construction"] = construction if has_permits else {"supported": False}
         parsed["data_available"] = True
+        parsed["city_supported"] = True
+        parsed["city_id"] = cfg["id"]
+        parsed["has_311"] = has_311
+        parsed["has_permits"] = has_permits
+        parsed["has_permit_cost"] = has_cost
         return parsed
 
-    # Fallback: still return both raw signals so the UI + risk analyst
-    # can see them even if Gemma's interpretation failed to parse.
+    # Fallback if Gemma's JSON didn't parse — still return the raw signals
+    # so the dossier shows something useful.
     return {
         "data_available": True,
+        "city_supported": True,
+        "city_id": cfg["id"],
+        "has_311": has_311,
+        "has_permits": has_permits,
+        "has_permit_cost": has_cost,
         "basement_flooding_reports": reports.get("basement_flooding", 0),
         "street_flooding_reports": reports.get("street_flooding", 0),
         "total_reports": reports.get("total_reports", 0),
@@ -153,8 +172,8 @@ Return ONLY the JSON object, no other text."""
         "summary": (
             f"{reports.get('basement_flooding', 0)} basement + "
             f"{reports.get('street_flooding', 0)} street flood reports · "
-            f"{construction_for_prompt.get('total_permits', 0)} construction "
-            f"permits within 1km / 3y"
+            f"{construction.get('total_permits', 0)} construction permits "
+            f"within 1km / 3y in {cfg['name']}"
         ),
         "raw_311": reports,
         "raw_construction": construction,

app/data/cities.py

@@ -0,0 +1,272 @@
+"""
+City registry for the local agent.
+
+Each entry encodes everything the 311 + permits tools need to query
+the city's Socrata-hosted open data: dataset IDs, the field names
+used for category/cost/date/location, the actual flood-related
+category values, and a short context blurb that gets injected into
+the local-agent prompt so Gemma 4 has accurate sewer-system info
+when it interprets the signals.
+
+All entries verified live on 2026-05-04 against the cities' open-data
+portals. The honesty-tax: most cities don't expose project cost in
+their permits dataset, and not every city categorizes 311 floods
+explicitly. Each config field documents what's actually available
+so the dossier can degrade gracefully (e.g. show permit COUNT but
+suppress the dollar narrative when no cost field exists).
+"""
+from typing import Optional
+
+
+# Standardize state matching: accept full name OR 2-letter code.
+def _state_match(input_state: str, codes: tuple[str, ...]) -> bool:
+    s = (input_state or "").strip().lower()
+    return any(s == c.lower() for c in codes)
+
+
+CITIES: list[dict] = [
+    # ---- CHICAGO --------------------------------------------------------
+    {
+        "id": "chicago",
+        "name": "Chicago",
+        "state_codes": ("IL", "Illinois"),
+        "match_fn": lambda city, state: "chicago" in (city or "").lower() and _state_match(state, ("IL", "Illinois")),
+        "context_blurb": (
+            "Chicago has a combined sewer system covering ~80% of the city. "
+            "Combined sewer overflows after ~0.67 in/hr of rain. 42% of Cook "
+            "County is impervious surface. MWRD's Deep Tunnel (TARP) provides "
+            "buffering but local sewers still bottleneck at neighborhood scale."
+        ),
+        "311": {
+            "url": "https://data.cityofchicago.org/resource/v6vf-nfxy.json",
+            "category_field": "sr_short_code",
+            # Chicago uses short codes: WIB = Water in Basement, SFL = Street Flooding
+            "flood_categories": ("WIB", "SFL"),
+            "category_in_clause": "sr_short_code in('WIB','SFL')",
+            "date_field": "created_date",
+            "location_field": "location",
+            "select_fields": "sr_short_code,created_date,street_address,ward",
+            "address_field_template": "street_address",
+        },
+        "permits": {
+            "url": "https://data.cityofchicago.org/resource/ydr8-5enu.json",
+            "permit_type_field": "permit_type",
+            "permit_type_values": (
+                "PERMIT - NEW CONSTRUCTION",
+                "PERMIT - RENOVATION/ALTERATION",
+            ),
+            "cost_field": "reported_cost",
+            "date_field": "issue_date",
+            "location_field": "location",
+            "select_fields": (
+                "permit_type,work_description,reported_cost,issue_date,"
+                "latitude,longitude,street_number,street_direction,"
+                "street_name,total_fee"
+            ),
+            "address_keys": ("street_number", "street_direction", "street_name"),
+            "new_construction_marker": "NEW CONSTRUCTION",
+            "renovation_marker": "RENOVATION",
+            "has_cost": True,
+        },
+    },
+    # ---- NEW YORK CITY --------------------------------------------------
+    {
+        "id": "nyc",
+        "name": "New York City",
+        "state_codes": ("NY", "New York"),
+        "match_fn": lambda city, state: any(t in (city or "").lower() for t in ("new york", "manhattan", "brooklyn", "queens", "bronx", "staten island")) and _state_match(state, ("NY", "New York")),
+        "context_blurb": (
+            "NYC has combined sewer systems across 60% of the city — including "
+            "all of Manhattan, much of Brooklyn, and parts of Queens and the "
+            "Bronx. Storm intensity above ~1.5 in/hr triggers combined-sewer "
+            "overflows into NY Harbor and basement backups. NYC DEP's bluebelts "
+            "and grey infrastructure are unevenly distributed."
+        ),
+        "311": {
+            "url": "https://data.cityofnewyork.us/resource/erm2-nwe9.json",
+            "category_field": "complaint_type",
+            # NYC complaint_type values verified 2026-05 (top flood-related)
+            "flood_categories": ("Sewer", "Sewer Maintenance"),
+            "category_in_clause": "complaint_type in('Sewer','Sewer Maintenance')",
+            "date_field": "created_date",
+            "location_field": "location",
+            # NYC uses lat/lon directly:
+            "select_fields": "complaint_type,descriptor,created_date,incident_address,borough",
+            "address_field_template": "incident_address",
+        },
+        # NYC permits intentionally DEFERRED. The DOB datasets are fragmented:
+        #   ipu4-2q9a (legacy "DOB Permit Issuance") — most recent NB rows
+        #     are from 2022; the dataset stopped being updated regularly.
+        #   rbx6-tga4 (DOB NOW: Build – Approved Permits) — has cost
+        #     (estimated_job_costs) and lat/lon, but NO date column
+        #     suitable for "last 3 years" filtering.
+        #   w9ak-ipjd (Active Construction Permits) — has filing_date and
+        #     initial_cost in the right format, but is filtered to currently-
+        #     active permits, so the historical 3-year window is empty for
+        #     most areas.
+        # The right fix is a custom NYC client that joins multiple datasets;
+        # for the hackathon scope NYC ships with 311-only and the dossier
+        # honestly says permits-deferred.
+        "permits": None,
+    },
+    # ---- SAN FRANCISCO --------------------------------------------------
+    {
+        "id": "sf",
+        "name": "San Francisco",
+        "state_codes": ("CA", "California"),
+        "match_fn": lambda city, state: "san francisco" in (city or "").lower() and _state_match(state, ("CA", "California")),
+        "context_blurb": (
+            "San Francisco operates a fully combined sewer system citywide — "
+            "the only major California city to do so. Heavy rain plus high "
+            "tide concentrates overflows. SF Public Utilities Commission has "
+            "documented chronic flooding hotspots in Mission, Bayview, and "
+            "the South of Market areas."
+        ),
+        "311": {
+            "url": "https://data.sfgov.org/resource/vw6y-z8j6.json",
+            "category_field": "service_name",
+            "flood_categories": ("Sewer Issues", "Sewer"),
+            "category_in_clause": "service_name in('Sewer Issues','Sewer')",
+            "date_field": "requested_datetime",
+            "location_field": "point",
+            "select_fields": "service_name,service_subtype,requested_datetime,address",
+            "address_field_template": "address",
+        },
+        "permits": {
+            "url": "https://data.sfgov.org/resource/i98e-djp9.json",
+            "permit_type_field": "permit_type_definition",
+            "permit_type_values": (
+                "new construction",
+                "new construction wood frame",
+                "additions alterations or repairs",
+            ),
+            "cost_field": "estimated_cost",
+            "cost_is_string": True,  # SF stores estimated_cost as text
+            "date_field": "issued_date",
+            "location_field": "location",  # SF permits has a real Socrata Point column
+            "select_fields": (
+                "permit_type,permit_type_definition,description,estimated_cost,"
+                "revised_cost,issued_date,filed_date,street_number,street_name,"
+                "street_suffix,zipcode"
+            ),
+            "address_keys": ("street_number", "street_name", "street_suffix"),
+            "new_construction_marker": "new construction",
+            "renovation_marker": "alterations",
+            "has_cost": True,
+        },
+    },
+    # ---- LOS ANGELES ----------------------------------------------------
+    {
+        "id": "la",
+        "name": "Los Angeles",
+        "state_codes": ("CA", "California"),
+        "match_fn": lambda city, state: any(t in (city or "").lower() for t in ("los angeles", "los-angeles")) and _state_match(state, ("CA", "California")),
+        "context_blurb": (
+            "Los Angeles has a separated storm-sanitary sewer system — the "
+            "two pipe networks don't co-mingle, so basement sewer-backup "
+            "flooding is rare. The dominant LA flood mode is FLASH FLOODING "
+            "during winter atmospheric-river events, when concrete-channelized "
+            "rivers (LA River, Ballona Creek) and soft-bottomed creeks rise "
+            "rapidly. Hillside debris flows after wildfire are a separate "
+            "wet-season hazard."
+        ),
+        "311": None,  # LA's 311 dataset doesn't categorize floods cleanly enough; deferred
+        "permits": {
+            "url": "https://data.lacity.org/resource/pi9x-tg5x.json",
+            "permit_type_field": "permit_type",
+            "permit_type_values": ("Bldg-New", "Bldg-Alter/Repair", "Bldg-Addition"),
+            "cost_field": "valuation",
+            "cost_is_string": True,  # LA stores valuation as text
+            "date_field": "issue_date",
+            "location_field": None,
+            "select_fields": (
+                "permit_type,permit_sub_type,work_desc,valuation,issue_date,"
+                "primary_address,zip_code,lat,lon"
+            ),
+            "address_keys": ("primary_address",),
+            "new_construction_marker": "New",
+            "renovation_marker": "Alter",
+            "has_cost": True,
+            "lat_field": "lat",
+            "lon_field": "lon",
+            "lat_lon_is_string": True,  # LA stores lat/lon as text — need cast
+        },
+    },
+    # ---- AUSTIN ---------------------------------------------------------
+    {
+        "id": "austin",
+        "name": "Austin",
+        "state_codes": ("TX", "Texas"),
+        "match_fn": lambda city, state: "austin" in (city or "").lower() and _state_match(state, ("TX", "Texas")),
+        "context_blurb": (
+            "Austin has separated storm and sanitary sewers, but the storm "
+            "drain system is undersized for the increasingly extreme rainfall "
+            "events of the post-2010 Texas climate. Onion Creek and Williamson "
+            "Creek have historic flash-flood corridors. Austin's hilly topo "
+            "concentrates runoff into well-known low-point intersections — the "
+            "city publishes a 'Flood Early Warning System' map for these spots."
+        ),
+        "311": {
+            "url": "https://data.austintexas.gov/resource/xwdj-i9he.json",
+            "category_field": "sr_type_desc",
+            "flood_categories": (
+                "Flooding Current (Non-Emergency)",
+                "Flooding - Past",
+                "WPD - Flooding Current",
+                "WPD - Flooding Past",
+                "WPD - Channels/Creek/Drainage Issues",
+                "WPD - Storm Drain Services",
+            ),
+            "category_in_clause": (
+                "sr_type_desc in("
+                "'Flooding Current (Non-Emergency)',"
+                "'Flooding - Past',"
+                "'WPD - Flooding Current',"
+                "'WPD - Flooding Past',"
+                "'WPD - Channels/Creek/Drainage Issues',"
+                "'WPD - Storm Drain Services'"
+                ")"
+            ),
+            "date_field": "sr_created_date",
+            "location_field": "sr_location_lat_long",  # real Point column
+            "select_fields": "sr_type_desc,sr_created_date,sr_location",
+            "address_field_template": "sr_location",
+        },
+        "permits": {
+            "url": "https://data.austintexas.gov/resource/3syk-w9eu.json",
+            "permit_type_field": "permittype",
+            # Austin permittype: BP=building, MP=mechanical, etc. We want the
+            # construction-relevant ones via permit_class_mapped + work_class.
+            "permit_type_values": ("BP",),
+            "cost_field": None,  # Austin permits dataset has no cost field
+            "date_field": "issue_date",
+            "location_field": "location",
+            "select_fields": (
+                "permittype,permit_type_desc,permit_class_mapped,work_class,"
+                "description,issue_date,permit_location,latitude,longitude,"
+                "original_address1,original_zip"
+            ),
+            "address_keys": ("original_address1",),
+            "new_construction_marker": "New",
+            "renovation_marker": "Remodel",
+            "has_cost": False,
+            "lat_field": "latitude",
+            "lon_field": "longitude",
+        },
+    },
+]
+
+
+def find_city(city: str, state: str) -> Optional[dict]:
+    """Look up a registry entry for the given geocoded city/state, or None."""
+    for entry in CITIES:
+        try:
+            if entry["match_fn"](city, state):
+                return entry
+        except Exception:
+            continue
+    return None
+
+
+def supported_city_names() -> list[str]:
+    return [c["name"] for c in CITIES]

app/main.py

@@ -8,7 +8,7 @@ from fastapi.staticfiles import StaticFiles
 from app.api.assess import router as assess_router
 from app.api.health import router as health_router
 
-app = FastAPI(title="FlutIQ", version="0.12.0")
+app = FastAPI(title="FlutIQ", version="0.13.0")
 
 # CORS still permissive for split-deployment scenarios. With the
 # bundled deploy (frontend served from FastAPI) it's a no-op because

app/tools/building_permits.py

@@ -1,136 +1,215 @@
 """
-Chicago Building Permits via Socrata SODA API.
-
-Why this matters for flood risk:
-A property's flood risk is not static. As the surrounding block
-densifies — new condos, parking lots, commercial buildings — more
-absorbent ground is replaced with impervious surface. The combined
-sewer system handling stormwater doesn't get upgraded; it just gets
-more overwhelmed. So a house that hasn't flooded in 50 years can
-suddenly be vulnerable because of what a developer built nearby.
-
-This tool surfaces that signal: significant construction projects
-(new builds + major renovations >$100K) within a configurable radius
-of the property in the last few years, with cost/scale information
-and a year-over-year trend.
-
-Free dataset (`ydr8-5enu`, no auth required) — same Socrata platform
-as our Chicago 311 data. Non-Chicago addresses get this from the
-local_agent's graceful degrade path, so this tool is Chicago-only by
-construction.
+City building-permits tool — Socrata SODA, city-aware.
+
+Was originally Chicago-only; now driven by app.data.cities so any
+supported city can plug in. The exported function name
+`get_nearby_construction` is preserved so callers don't change.
+
+Honest about per-city data quality:
+  - Some cities (Chicago, SF, LA, Dallas) expose a project cost
+    field — the dossier can show '$80M new medical office'.
+  - Other cities (NYC DOB, Austin) don't expose cost in their
+    public dataset — the dossier degrades to permit COUNT and
+    project type narrative ('14 new buildings, increasing trend').
+
+Each city's config encodes the right field names for permit_type,
+cost (if any), date, and the geo column type (Socrata Point column
+for `within_circle` vs. bbox-on-lat/lon for cities without one).
 """
+import math
 from datetime import datetime, timedelta, timezone
+from typing import Optional
 
 import httpx
 
-PERMITS_URL = "https://data.cityofchicago.org/resource/ydr8-5enu.json"
+
+def _bbox_clause(
+    lat: float,
+    lon: float,
+    radius_m: int,
+    lat_field: str,
+    lon_field: str,
+    is_string: bool = False,
+) -> str:
+    """SODA WHERE fragment that bounds rows within ~radius_m of (lat, lon).
+    When `is_string=True` (NYC DOB, LA permits) the fields get wrapped in
+    `to_number()` because the dataset stores lat/lon as text."""
+    lat_deg = radius_m / 111_000
+    lon_deg = radius_m / (111_000 * max(0.1, math.cos(math.radians(lat))))
+    # SoQL doesn't have to_number(); use PostgreSQL :: cast for cities
+    # that store lat/lon as text.
+    lf = f"{lat_field}::number" if is_string else lat_field
+    lnf = f"{lon_field}::number" if is_string else lon_field
+    return (
+        f"{lf} >= {lat - lat_deg} AND {lf} <= {lat + lat_deg} "
+        f"AND {lnf} >= {lon - lon_deg} AND {lnf} <= {lon + lon_deg}"
+    )
+
+
+def _coerce_float(v) -> Optional[float]:
+    if v is None or v == "":
+        return None
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None
 
 
 async def get_nearby_construction(
+    config: dict,
     lat: float,
     lon: float,
     radius_m: int = 1000,
     years: int = 3,
     min_cost: int = 100_000,
 ) -> dict:
-    """Find significant construction within `radius_m` over the last `years`.
+    """Fetch significant construction permits near a location for a city.
 
-    Returns a structured dict with counts, total cost, top-5 major
-    projects, and a YoY trend ("increasing" / "stable" / "decreasing").
+    Returns the same shape regardless of city, with `has_cost` flagging
+    whether the dollar-amount narrative is meaningful for this city.
     """
-    now = datetime.now(timezone.utc)
-    since = (now - timedelta(days=365 * years)).strftime("%Y-%m-%dT00:00:00")
+    cfg = (config or {}).get("permits")
+    if not cfg:
+        return {
+            "permits_found": False,
+            "supported": False,
+            "total_permits": 0,
+            "city": (config or {}).get("name", ""),
+        }
+
+    since = (
+        datetime.now(timezone.utc) - timedelta(days=365 * years)
+    ).strftime("%Y-%m-%dT00:00:00")
+
+    type_field = cfg["permit_type_field"]
+    type_values = cfg["permit_type_values"]
+    type_clause = " OR ".join(f"{type_field}='{v}'" for v in type_values)
+
+    cost_field = cfg.get("cost_field")
+    has_cost = bool(cost_field and cfg.get("has_cost"))
+
+    location_field = cfg.get("location_field")
+    if location_field:
+        geo_clause = f"within_circle({location_field}, {lat}, {lon}, {radius_m})"
+    else:
+        geo_clause = _bbox_clause(
+            lat, lon, radius_m,
+            cfg.get("lat_field", "latitude"),
+            cfg.get("lon_field", "longitude"),
+            is_string=cfg.get("lat_lon_is_string", False),
+        )
+
+    where_parts = [
+        f"({type_clause})",
+        f"{cfg['date_field']} > '{since}'",
+        f"({geo_clause})",
+    ]
+    if has_cost and min_cost:
+        # Some cities (SF) store cost as text — apply same :: cast as for lat/lon.
+        cost_expr = (
+            f"{cost_field}::number"
+            if cfg.get("cost_is_string")
+            else cost_field
+        )
+        where_parts.append(f"{cost_expr} > {min_cost}")
 
-    where = (
-        "permit_type in('PERMIT - NEW CONSTRUCTION','PERMIT - RENOVATION/ALTERATION')"
-        f" AND issue_date > '{since}'"
-        f" AND within_circle(location, {lat}, {lon}, {radius_m})"
-        f" AND reported_cost > {min_cost}"
-    )
     params = {
-        "$where": where,
+        "$where": " AND ".join(where_parts),
         "$limit": 500,
-        # Schema verified against the live dataset 2026-05-04: there is
-        # no `suffix`, `_total_sqft`, or `community_area` column despite
-        # what the source spec suggested. Reported cost is the best
-        # available proxy for project scale.
-        "$select": (
-            "permit_type,work_description,reported_cost,issue_date,"
-            "latitude,longitude,street_number,street_direction,"
-            "street_name,total_fee"
-        ),
-        "$order": "reported_cost DESC",
+        "$select": cfg["select_fields"],
+        "$order": f"{cost_field} DESC" if has_cost else f"{cfg['date_field']} DESC",
     }
 
-    async with httpx.AsyncClient(timeout=30) as client:
-        resp = await client.get(PERMITS_URL, params=params)
+    async with httpx.AsyncClient(timeout=30, follow_redirects=True) as client:
+        resp = await client.get(cfg["url"], params=params)
 
     if resp.status_code != 200:
         return {
+            "city": config["name"],
+            "supported": True,
             "error": f"HTTP {resp.status_code}",
             "permits_found": False,
             "total_permits": 0,
+            "has_cost": has_cost,
         }
 
     try:
         permits = resp.json()
     except ValueError:
-        return {"error": "non-JSON response", "permits_found": False, "total_permits": 0}
+        return {
+            "city": config["name"],
+            "supported": True,
+            "error": "non-JSON response",
+            "permits_found": False,
+            "total_permits": 0,
+            "has_cost": has_cost,
+        }
 
     if isinstance(permits, dict) and "error" in permits:
         return {
+            "city": config["name"],
+            "supported": True,
             "error": permits.get("message", "Socrata error"),
             "permits_found": False,
             "total_permits": 0,
+            "has_cost": has_cost,
         }
 
-    new_construction = [
-        p for p in permits if "NEW CONSTRUCTION" in (p.get("permit_type") or "")
-    ]
-    renovations = [
-        p for p in permits if "RENOVATION" in (p.get("permit_type") or "")
-    ]
+    new_marker = cfg.get("new_construction_marker", "")
+    reno_marker = cfg.get("renovation_marker", "")
+
+    new_construction = []
+    renovations = []
+    for p in permits:
+        ptype = (p.get(type_field) or "")
+        if new_marker and new_marker in ptype:
+            new_construction.append(p)
+        elif reno_marker and reno_marker in ptype:
+            renovations.append(p)
+        else:
+            renovations.append(p)
 
     total_cost = 0.0
     for p in permits:
-        try:
-            total_cost += float(p.get("reported_cost") or 0)
-        except (ValueError, TypeError):
-            pass
+        c = _coerce_float(p.get(cost_field) if cost_field else None)
+        if c:
+            total_cost += c
+
+    address_keys = cfg.get("address_keys") or ()
 
     def _addr(p: dict) -> str:
-        parts = [
-            p.get("street_number"),
-            p.get("street_direction"),
-            p.get("street_name"),
-        ]
-        return " ".join(part for part in parts if part).strip()
-
-    # Top 5 by reported cost (already sorted DESC by Socrata).
+        parts = [p.get(k) for k in address_keys]
+        return " ".join(str(part) for part in parts if part).strip()
+
+    # Top 5 — by cost if we have it, else by date.
     major = []
     for p in permits:
-        try:
-            cost = float(p.get("reported_cost") or 0)
-        except (ValueError, TypeError):
+        cost = _coerce_float(p.get(cost_field) if cost_field else None) or 0.0
+        if has_cost and cost <= 500_000:
             continue
-        if cost > 500_000:
-            major.append({
-                "type": "new" if "NEW CONSTRUCTION" in (p.get("permit_type") or "") else "renovation",
-                "description": (p.get("work_description") or "").strip()[:200],
-                "cost": cost,
-                "date": (p.get("issue_date") or "")[:10],
-                "address": _addr(p),
-            })
+        ptype = p.get(type_field) or ""
+        major.append({
+            "type": "new" if (new_marker and new_marker in ptype) else "renovation",
+            "description": (
+                p.get("work_description") or p.get("description") or p.get("work_desc") or ""
+            ).strip()[:200],
+            "cost": cost if has_cost else None,
+            "date": (
+                p.get(cfg["date_field"]) or ""
+            )[:10],
+            "address": _addr(p),
+        })
         if len(major) >= 5:
             break
 
-    # Year-over-year trend (last 12mo vs prior 12mo).
+    # Year-over-year trend (last 12mo vs prior 12mo)
+    now = datetime.now(timezone.utc)
     cutoff_12 = (now - timedelta(days=365)).strftime("%Y-%m-%d")
     cutoff_24 = (now - timedelta(days=730)).strftime("%Y-%m-%d")
-    last_12 = [p for p in permits if (p.get("issue_date") or "") > cutoff_12]
+    last_12 = [p for p in permits if (p.get(cfg["date_field"]) or "") > cutoff_12]
     prior_12 = [
         p for p in permits
-        if cutoff_24 < (p.get("issue_date") or "") <= cutoff_12
+        if cutoff_24 < (p.get(cfg["date_field"]) or "") <= cutoff_12
     ]
 
     if len(prior_12) == 0:
@@ -143,11 +222,14 @@ async def get_nearby_construction(
         direction = "stable"
 
     return {
+        "city": config["name"],
+        "supported": True,
         "permits_found": True,
+        "has_cost": has_cost,
         "total_permits": len(permits),
         "new_construction_count": len(new_construction),
         "renovation_count": len(renovations),
-        "total_reported_cost": round(total_cost, 2),
+        "total_reported_cost": round(total_cost, 2) if has_cost else None,
         "major_projects": major,
         "trend": {
             "last_12_months": len(last_12),
@@ -156,6 +238,6 @@ async def get_nearby_construction(
         },
         "radius_m": radius_m,
         "years": years,
-        "min_cost_filter": min_cost,
+        "min_cost_filter": min_cost if has_cost else None,
         "since": since,
     }

app/tools/chicago_311.py

@@ -1,48 +1,157 @@
-"""Chicago 311 service requests via Socrata SODA API. Free, no auth."""
+"""City 311 flood-report tool — Socrata SODA, city-aware.
+
+Was originally chicago_311 only; now driven by the registry in
+app.data.cities so any supported city can plug in without changing
+caller code. The exported function name `get_flood_reports` is kept
+for backward compat with the local_agent.
+
+Each city's 311 dataset has different field names (sr_short_code in
+Chicago, complaint_type in NYC, service_name in SF, sr_type_desc in
+Austin) and different flood-related category VALUES. The registry
+encodes both, plus the date field name and the geo column type
+(some cities expose a Socrata Point column for `within_circle`,
+others only have separate latitude/longitude columns and need a
+bbox query instead).
+"""
+import math
 from datetime import datetime, timedelta, timezone
 
 import httpx
 
-# v6vf-nfxy is the unified 311 service requests dataset.
-CHICAGO_311_URL = "https://data.cityofchicago.org/resource/v6vf-nfxy.json"
 
-# WIB = Water in Basement, SFL = Street Flooding (these are the
-# Chicago 311 sr_short_codes that signal urban flooding).
-FLOOD_CODES = ("WIB", "SFL")
+def _bbox_clause(
+    lat: float,
+    lon: float,
+    radius_m: int,
+    lat_field: str,
+    lon_field: str,
+    is_string: bool = False,
+) -> str:
+    """Build a SODA WHERE clause filtering to rows within ~radius_m of
+    (lat, lon) using a lat/lon bounding box. When `is_string=True` the
+    fields are wrapped in `to_number()` because some cities (NYC DOB,
+    LA building permits) store lat/lon as text rather than numeric."""
+    lat_deg = radius_m / 111_000
+    lon_deg = radius_m / (111_000 * max(0.1, math.cos(math.radians(lat))))
+    # SoQL doesn't have to_number(); use PostgreSQL :: cast syntax for
+    # cities that store lat/lon as text (NYC DOB, LA building permits).
+    lf = f"{lat_field}::number" if is_string else lat_field
+    lnf = f"{lon_field}::number" if is_string else lon_field
+    return (
+        f"{lf} >= {lat - lat_deg} AND {lf} <= {lat + lat_deg} "
+        f"AND {lnf} >= {lon - lon_deg} AND {lnf} <= {lon + lon_deg}"
+    )
 
 
 async def get_flood_reports(
+    config: dict,
     lat: float,
     lon: float,
     radius_m: int = 500,
     years: int = 5,
 ) -> dict:
+    """Fetch flood-related 311 reports near a location for the given city
+    config. Returns a dict ready for the local_agent to interpret.
+
+    The shape of the return is intentionally Chicago-shaped (basement /
+    street counts) so the rest of the pipeline doesn't have to change —
+    cities without that distinction surface under "total_reports".
+    """
+    cfg = config.get("311") if config else None
+    if not cfg:
+        return {
+            "city": (config or {}).get("name", ""),
+            "supported": False,
+            "total_reports": 0,
+            "basement_flooding": 0,
+            "street_flooding": 0,
+            "recent_reports": [],
+            "radius_m": radius_m,
+            "years": years,
+        }
+
     since = (
         datetime.now(timezone.utc) - timedelta(days=365 * years)
     ).strftime("%Y-%m-%dT00:00:00")
 
-    codes = ",".join(f"'{c}'" for c in FLOOD_CODES)
-    where = (
-        f"sr_short_code in({codes}) "
-        f"AND created_date > '{since}' "
-        f"AND within_circle(location, {lat}, {lon}, {radius_m})"
-    )
+    date_field = cfg["date_field"]
+    cat_clause = cfg["category_in_clause"]
+    location_field = cfg.get("location_field")
+
+    # Some cities have a Socrata Point column → within_circle. Others only
+    # expose lat/lon scalars → bbox.
+    if location_field:
+        geo_clause = f"within_circle({location_field}, {lat}, {lon}, {radius_m})"
+    else:
+        geo_clause = _bbox_clause(
+            lat, lon, radius_m,
+            cfg.get("lat_field", "latitude"),
+            cfg.get("lon_field", "longitude"),
+            is_string=cfg.get("lat_lon_is_string", False),
+        )
+
+    where = f"{cat_clause} AND {date_field} > '{since}' AND ({geo_clause})"
     params = {
         "$where": where,
         "$limit": 1000,
-        "$select": "sr_short_code,created_date,street_address,ward",
-        "$order": "created_date DESC",
+        "$select": cfg["select_fields"],
+        "$order": f"{date_field} DESC",
     }
 
-    async with httpx.AsyncClient(timeout=30) as client:
-        resp = await client.get(CHICAGO_311_URL, params=params)
-    resp.raise_for_status()
-    reports = resp.json()
+    async with httpx.AsyncClient(timeout=30, follow_redirects=True) as client:
+        resp = await client.get(cfg["url"], params=params)
+
+    if resp.status_code != 200:
+        return {
+            "city": config["name"],
+            "supported": True,
+            "error": f"HTTP {resp.status_code}",
+            "total_reports": 0,
+            "basement_flooding": 0,
+            "street_flooding": 0,
+            "recent_reports": [],
+            "radius_m": radius_m,
+            "years": years,
+        }
+
+    try:
+        reports = resp.json()
+    except ValueError:
+        return {
+            "city": config["name"],
+            "supported": True,
+            "error": "non-JSON response",
+            "total_reports": 0,
+            "basement_flooding": 0,
+            "street_flooding": 0,
+            "recent_reports": [],
+            "radius_m": radius_m,
+            "years": years,
+        }
+
+    # Heuristically split into "basement-flavored" vs "street-flavored"
+    # 311 reports for cities that surface that distinction. Chicago has
+    # explicit codes (WIB / SFL); other cities have to be inferred from
+    # the category value and descriptor.
+    cat_field = cfg["category_field"]
+    basement_keywords = ("WIB", "Sewer", "basement", "Basement")
+    street_keywords = ("SFL", "Street", "Drain", "Storm", "Flooding")
 
-    basement = [r for r in reports if r.get("sr_short_code") == "WIB"]
-    street = [r for r in reports if r.get("sr_short_code") == "SFL"]
+    basement = []
+    street = []
+    for r in reports:
+        cat = (r.get(cat_field) or "")
+        descr = " ".join(str(v) for v in r.values()).lower()
+        if any(k in cat for k in basement_keywords) or "basement" in descr:
+            basement.append(r)
+        elif any(k in cat for k in street_keywords):
+            street.append(r)
+        else:
+            street.append(r)  # default bucket
 
     return {
+        "city": config["name"],
+        "supported": True,
         "total_reports": len(reports),
         "basement_flooding": len(basement),
         "street_flooding": len(street),
@@ -50,4 +159,6 @@ async def get_flood_reports(
         "years": years,
         "since": since,
         "recent_reports": reports[:10],
+        "category_field": cat_field,
+        "categories_queried": list(cfg["flood_categories"]),
     }

scripts/smoke_test_cities.py

@@ -0,0 +1,67 @@
+"""End-to-end smoke test for all Tier-1 cities + a graceful-degrade check.
+
+Run:
+    cd backend && set -a && source .env && set +a
+    PYTHONPATH=. .venv/bin/python scripts/smoke_test_cities.py
+"""
+import asyncio
+
+from app.data.cities import find_city
+from app.tools.building_permits import get_nearby_construction
+from app.tools.chicago_311 import get_flood_reports
+
+
+TARGETS = [
+    ("Chicago",       41.8127, -87.6045,  "Chicago",       "Illinois"),
+    ("New York",      40.7589, -73.9851,  "New York",      "NY"),
+    ("San Francisco", 37.7749, -122.4194, "San Francisco", "California"),
+    ("Los Angeles",   34.0522, -118.2437, "Los Angeles",   "California"),
+    ("Austin",        30.2672, -97.7431,  "Austin",        "Texas"),
+    ("Atlanta",       33.7490, -84.3880,  "Atlanta",       "Georgia"),  # unsupported
+]
+
+
+async def main() -> None:
+    for name, lat, lon, city, state in TARGETS:
+        cfg = find_city(city, state)
+        if cfg is None:
+            print(f"\n=== {name} → unsupported (graceful degrade) ===")
+            continue
+        print(f"\n=== {name} ===")
+
+        if cfg.get("311"):
+            r = await get_flood_reports(cfg, lat, lon)
+            if r.get("error"):
+                print(f"  311 ERROR: {r['error']}")
+            else:
+                print(f"  311: {r.get('total_reports', 0)} reports "
+                      f"(basement={r.get('basement_flooding', 0)}, "
+                      f"street={r.get('street_flooding', 0)})")
+        else:
+            print("  311: not wired in registry")
+
+        if cfg.get("permits"):
+            p = await get_nearby_construction(cfg, lat, lon)
+            if p.get("error"):
+                print(f"  permits ERROR: {p['error']}")
+            else:
+                cost_str = (
+                    f"${p.get('total_reported_cost', 0):,.0f}"
+                    if p.get("has_cost") else "count-only"
+                )
+                print(f"  permits: {p.get('total_permits', 0)} permits, "
+                      f"{p.get('new_construction_count', 0)} new, "
+                      f"{cost_str}, trend={p.get('trend', {}).get('direction')}")
+                top = (p.get("major_projects") or [None])[0]
+                if top:
+                    cost_field = (
+                        f"${top.get('cost', 0):,.0f}" if top.get("cost") else ""
+                    )
+                    print(f"    top: {cost_field} {top.get('date', '')} "
+                          f"{(top.get('address') or '')[:60]}")
+        else:
+            print("  permits: not wired in registry (intentional)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

static/index.html

@@ -1594,7 +1594,7 @@ const Chrome = ({ screen, onJump, dark, onToggleDark, language, onLanguageChange
     <div className="wordmark" onClick={()=>onJump("search")} style={{cursor:"pointer"}}>
       <span className="glyph">F</span>
       <span>FlutIQ</span>
-      <span style={{color:"var(--ink-4)",fontSize:12,marginLeft:8,fontFamily:"JetBrains Mono"}}>v0.12 · beta</span>
+      <span style={{color:"var(--ink-4)",fontSize:12,marginLeft:8,fontFamily:"JetBrains Mono"}}>v0.13 · beta</span>
     </div>
     <div className="chrome-meta">
       <span className="pill static"><span className="dot"/>gemma-4 · OpenRouter</span>