Initial commit: Extreme Heat Risk Engine

6-step ML pipeline for parametric heat insurance in East Africa.
Three XGBoost models (UHI correction, heat wave prediction, actuarial pricing),
Claude AI healing agent, interactive program designer with budget allocation.
20 urban zones across Nairobi, Dar es Salaam, Kampala, Kigali.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.env.example

@@ -0,0 +1,2 @@
+ANTHROPIC_API_KEY=
+DATABASE_URL=

.gitattributes

@@ -0,0 +1,4 @@
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+data/era5land_dar.json filter=lfs diff=lfs merge=lfs -text
+*.faiss filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+.env
+.venv
+venv/
+node_modules/
+dist/
+.DS_Store
+*.log
+.cache/
+.vercel/

Dockerfile

@@ -0,0 +1,40 @@
+FROM python:3.11-slim AS builder
+
+# Install Node.js for frontend build
+RUN apt-get update && apt-get install -y --no-install-recommends curl && \
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+    apt-get install -y --no-install-recommends nodejs && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app/frontend
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm ci --production=false
+COPY frontend/ ./
+RUN VITE_API_URL="" npm run build
+
+# ── Production stage ──
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgomp1 ca-certificates curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY config.py .
+COPY src/ src/
+COPY models/ models/
+COPY --from=builder /app/frontend/dist frontend/dist
+
+RUN adduser --disabled-password --gecos '' appuser && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=10s --retries=5 --start-period=60s \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+CMD ["uvicorn", "src.api:app", "--host", "0.0.0.0", "--port", "7860"]

config.py

@@ -0,0 +1,181 @@
+"""
+Climate Risk Index Engine — Configuration
+
+Extreme heat parametric insurance for East African cities.
+Zones are real neighborhoods with outdoor worker populations
+vulnerable to heat stress.
+"""
+
+from dataclasses import dataclass, field
+
+REGION_NAME = "East Africa"
+TIMEZONE = "Africa/Nairobi"
+LOCALE = "en-KE"
+CURRENCY = "USD"
+CURRENCY_SYMBOL = "$"
+
+# Data source configuration
+NASA_POWER_URL = "https://power.larc.nasa.gov/api/temporal/daily/point"
+OVERPASS_URL = "https://overpass-api.de/api/interpreter"
+
+# Heat thresholds for parametric triggers
+HEAT_THRESHOLDS = {
+    "critical": {"temp_c": 37, "wbgt_c": 32, "consecutive_days": 3},
+    "warning": {"temp_c": 35, "wbgt_c": 30, "consecutive_days": 2},
+    "watch": {"temp_c": 33, "wbgt_c": 28, "consecutive_days": 1},
+}
+
+# Payout per event per worker (USD)
+PAYOUT_PER_EVENT_USD = {
+    "critical": 15,
+    "warning": 10,
+    "watch": 5,
+}
+
+
+@dataclass
+class UrbanZone:
+    zone_id: str
+    name: str
+    city: str
+    country: str
+    latitude: float
+    longitude: float
+    elevation_m: float
+    area_km2: float
+    population_est: int
+    settlement_type: str  # formal, informal, mixed, commercial
+    worker_population_est: int  # estimated informal/outdoor workers
+    outdoor_exposure_pct: float  # % of workers with outdoor exposure
+    heat_vulnerability: str  # high, moderate, low
+    hot_months: list = field(default_factory=list)  # months of peak heat
+    notes: str = ""
+
+
+# Real urban zones in East Africa — same 20 zones, now with heat context
+# Dar es Salaam: hottest + most humid (coastal, sea level, WBGT danger)
+# Kampala: moderate heat (equatorial but 1140-1260m elevation, Lake Victoria moderates)
+# Nairobi: cooler (1620-1780m highland elevation)
+# Kigali: moderate (1420-1580m, "city of eternal spring")
+ZONES: list[UrbanZone] = [
+    # -- Nairobi, Kenya (elevation 1620-1780m, relatively cool) --
+    UrbanZone("NBO-KIB", "Kibera", "Nairobi", "Kenya",
+              -1.3133, 36.7876, 1720, 2.5, 250000, "informal",
+              45000, 0.72, "moderate",
+              [1, 2, 3, 10, 12], "Largest informal settlement. Tin roofs amplify heat. Many outdoor traders."),
+    UrbanZone("NBO-EAS", "Eastleigh", "Nairobi", "Kenya",
+              -1.2750, 36.8500, 1660, 3.2, 180000, "mixed",
+              22000, 0.55, "moderate",
+              [1, 2, 3, 10, 12], "Dense commercial area. Street vendors and market porters exposed."),
+    UrbanZone("NBO-MAT", "Mathare", "Nairobi", "Kenya",
+              -1.2583, 36.8583, 1620, 1.8, 200000, "informal",
+              38000, 0.70, "moderate",
+              [1, 2, 3, 10, 12], "Valley settlement. Poor ventilation in densely packed structures."),
+    UrbanZone("NBO-SBC", "South B/C", "Nairobi", "Kenya",
+              -1.3100, 36.8350, 1680, 4.5, 120000, "formal",
+              8000, 0.30, "low",
+              [1, 2, 3, 10, 12], "Formal residential area. Mostly indoor workers."),
+    UrbanZone("NBO-WES", "Westlands", "Nairobi", "Kenya",
+              -1.2667, 36.8100, 1740, 5.0, 90000, "commercial",
+              5000, 0.20, "low",
+              [1, 2, 3, 10, 12], "Commercial district. Air-conditioned offices predominate."),
+    UrbanZone("NBO-KAN", "Kangemi", "Nairobi", "Kenya",
+              -1.2600, 36.7450, 1780, 3.0, 150000, "mixed",
+              18000, 0.58, "moderate",
+              [1, 2, 3, 10, 12], "Peri-urban. Construction workers and jua kali artisans."),
+
+    # -- Dar es Salaam, Tanzania (sea level, hottest + most humid) --
+    UrbanZone("DAR-JAN", "Jangwani", "Dar es Salaam", "Tanzania",
+              -6.8000, 39.2700, 12, 2.0, 80000, "informal",
+              25000, 0.82, "high",
+              [1, 2, 3, 10, 11, 12], "Low-lying informal area. Tin roofs, no shade, extreme UHI. Outdoor labor dominant."),
+    UrbanZone("DAR-MSA", "Msasani", "Dar es Salaam", "Tanzania",
+              -6.7600, 39.2650, 18, 4.0, 95000, "mixed",
+              15000, 0.55, "high",
+              [1, 2, 3, 10, 11, 12], "Coastal mixed area. Fish market workers, beach traders exposed."),
+    UrbanZone("DAR-KIN", "Kinondoni", "Dar es Salaam", "Tanzania",
+              -6.7700, 39.2400, 35, 6.5, 200000, "formal",
+              18000, 0.45, "moderate",
+              [1, 2, 3, 10, 11, 12], "Mixed residential. Some tree cover but humidity remains high."),
+    UrbanZone("DAR-TEM", "Temeke", "Dar es Salaam", "Tanzania",
+              -6.8600, 39.2800, 22, 5.5, 170000, "mixed",
+              30000, 0.75, "high",
+              [1, 2, 3, 10, 11, 12], "Industrial zone. Port workers, construction crews, outdoor factories."),
+    UrbanZone("DAR-KIG", "Kigamboni", "Dar es Salaam", "Tanzania",
+              -6.8700, 39.3200, 8, 7.0, 110000, "mixed",
+              20000, 0.70, "high",
+              [1, 2, 3, 10, 11, 12], "Coastal peninsula. Fishing, salt panning, construction — all outdoor."),
+
+    # -- Kampala, Uganda (1140-1260m, Lake Victoria moderates) --
+    UrbanZone("KLA-BWA", "Bwaise", "Kampala", "Uganda",
+              0.3500, 32.5650, 1140, 1.5, 120000, "informal",
+              22000, 0.75, "moderate",
+              [1, 2, 3, 12], "Wetland settlement. High humidity from swamp. Outdoor traders predominate."),
+    UrbanZone("KLA-NAT", "Natete", "Kampala", "Uganda",
+              0.3050, 32.5550, 1150, 2.0, 85000, "mixed",
+              12000, 0.60, "moderate",
+              [1, 2, 3, 12], "Market area. Porters, boda-boda riders, street vendors."),
+    UrbanZone("KLA-NAK", "Nakivubo", "Kampala", "Uganda",
+              0.3100, 32.5850, 1160, 1.8, 70000, "mixed",
+              10000, 0.65, "moderate",
+              [1, 2, 3, 12], "Commercial corridor. Taxi park workers, hawkers exposed to heat."),
+    UrbanZone("KLA-LUB", "Lubaga", "Kampala", "Uganda",
+              0.3000, 32.5600, 1220, 3.5, 100000, "formal",
+              7000, 0.35, "low",
+              [1, 2, 3, 12], "Hillside residential. Some elevation relief from heat."),
+    UrbanZone("KLA-MAK", "Makindye", "Kampala", "Uganda",
+              0.2900, 32.5950, 1260, 4.0, 95000, "formal",
+              5500, 0.25, "low",
+              [1, 2, 3, 12], "Elevated residential. Better ventilation, more tree cover."),
+
+    # -- Kigali, Rwanda (1420-1580m, moderate) --
+    UrbanZone("KGL-NYA", "Nyabugogo", "Kigali", "Rwanda",
+              -1.9400, 30.0550, 1420, 1.2, 45000, "mixed",
+              8000, 0.68, "moderate",
+              [1, 2, 8, 9], "Valley area. Bus terminal workers, market traders. Valley traps heat."),
+    UrbanZone("KGL-KIC", "Kicukiro", "Kigali", "Rwanda",
+              -1.9800, 30.0700, 1520, 4.0, 120000, "formal",
+              6000, 0.30, "low",
+              [1, 2, 8, 9], "Residential district. Mostly indoor employment."),
+    UrbanZone("KGL-GAS", "Gasabo", "Kigali", "Rwanda",
+              -1.9300, 30.0900, 1580, 5.0, 150000, "formal",
+              5000, 0.22, "low",
+              [1, 2, 8, 9], "Administrative district on higher ground. Cooler, shaded."),
+    UrbanZone("KGL-NYM", "Nyamirambo", "Kigali", "Rwanda",
+              -1.9700, 30.0400, 1480, 2.5, 80000, "mixed",
+              9000, 0.60, "moderate",
+              [1, 2, 8, 9], "Dense residential. Hillside construction workers, market sellers."),
+]
+
+ZONE_MAP: dict[str, UrbanZone] = {z.zone_id: z for z in ZONES}
+
+# Cities for grouping
+CITIES = ["Nairobi", "Dar es Salaam", "Kampala", "Kigali"]
+
+# Hot season definitions (month numbers)
+HOT_SEASONS = {
+    "Nairobi": {"dry_hot": [1, 2, 3], "secondary_hot": [10, 12]},
+    "Dar es Salaam": {"hot_humid": [1, 2, 3, 10, 11, 12]},
+    "Kampala": {"hot_dry": [1, 2, 3, 12]},
+    "Kigali": {"hot_dry": [1, 2, 8, 9]},
+}
+
+# NASA POWER parameters to fetch
+NASA_POWER_PARAMS = [
+    "T2M",            # Temperature at 2m (C)
+    "T2M_MAX",        # Max temperature (C)
+    "T2M_MIN",        # Min temperature (C)
+    "RH2M",           # Relative humidity (%)
+    "WS2M",           # Wind speed at 2m (m/s)
+    "ALLSKY_SFC_SW_DWN",  # Solar radiation (for heat load)
+]
+
+# Pipeline step names
+PIPELINE_STEPS = [
+    "ingest",
+    "heal",
+    "index",
+    "calibrate",
+    "explain",
+    "notify",
+]

frontend/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Climate Risk Index Engine</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700;1,9..40,400&family=Source+Serif+4:opsz,wght@8..60,400;8..60,600;8..60,700&display=swap" rel="stylesheet" />
+  </head>
+  <body class="bg-cream font-sans text-gray-800 antialiased">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "climate-risk-engine",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.62.0",
+    "lucide-react": "^0.468.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-joyride": "^2.9.3",
+    "react-router-dom": "^7.1.1",
+    "recharts": "^2.15.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@vitejs/plugin-react": "^4.3.4",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "typescript": "~5.6.2",
+    "vite": "^6.0.5"
+  }
+}

frontend/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

frontend/src/App.tsx

@@ -0,0 +1,143 @@
+import { useCallback, useEffect, useState } from 'react'
+import { Routes, Route, useNavigate, useSearchParams } from 'react-router-dom'
+import Joyride, { type CallBackProps, STATUS, EVENTS, ACTIONS } from 'react-joyride'
+import { Thermometer } from 'lucide-react'
+import Sidebar from './components/Sidebar'
+import Dashboard from './pages/Dashboard'
+import Zones from './pages/Zones'
+import HeatMonitor from './pages/HeatMonitor'
+import ProgramDesigner from './pages/ProgramDesigner'
+import Notifications from './pages/Notifications'
+import Pipeline from './pages/Pipeline'
+import { tourSteps, tourStyles } from './lib/tour'
+
+// Map tour step indices to routes for page navigation
+const stepRoutes: Record<number, string> = {
+  0: '/',              // hero
+  1: '/',              // stage cards
+  2: '/',              // metrics
+  3: '/',              // nav-zones link
+  4: '/zones',         // zones metrics
+  5: '/zones',         // nav-heat-monitor link
+  6: '/heat-monitor',  // heat monitor metrics
+  7: '/heat-monitor',  // heat monitor tabs
+  8: '/heat-monitor',  // nav-calibrate link
+  9: '/calibrate',     // calibrate controls
+  10: '/calibrate',    // calibrate results
+  11: '/calibrate',    // nav-alerts link
+  12: '/alerts',       // alerts feed
+  13: '/',             // final — nav-home
+}
+
+export default function App() {
+  const [searchParams] = useSearchParams()
+  const [runTour, setRunTour] = useState(false)
+  const [stepIndex, setStepIndex] = useState(0)
+  const navigate = useNavigate()
+
+  useEffect(() => {
+    const forced = searchParams.get('tour') === 'true'
+    const seen = localStorage.getItem('heat_tour_v2') === '1'
+    if (forced || !seen) {
+      const timer = setTimeout(() => {
+        setRunTour(true)
+        setStepIndex(0)
+        localStorage.setItem('heat_tour_v2', '1')
+      }, 1500)
+      return () => clearTimeout(timer)
+    }
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Relaunch from tour button
+  useEffect(() => {
+    function handleRelaunch() {
+      navigate('/')
+      setTimeout(() => {
+        setStepIndex(0)
+        setRunTour(true)
+      }, 400)
+    }
+    window.addEventListener('relaunch-tour', handleRelaunch)
+    return () => window.removeEventListener('relaunch-tour', handleRelaunch)
+  }, [navigate])
+
+  const handleJoyrideCallback = useCallback(
+    (data: CallBackProps) => {
+      const { status, action, index, type } = data
+
+      if (status === STATUS.FINISHED || status === STATUS.SKIPPED || action === ACTIONS.CLOSE) {
+        setRunTour(false)
+        setStepIndex(0)
+        return
+      }
+
+      if (type === EVENTS.STEP_AFTER) {
+        const nextIndex = action === ACTIONS.PREV ? index - 1 : index + 1
+        const nextRoute = stepRoutes[nextIndex]
+
+        if (nextRoute !== undefined) {
+          const currentRoute = stepRoutes[index]
+          if (nextRoute !== currentRoute) {
+            navigate(nextRoute)
+            // Give the page time to render before advancing
+            setTimeout(() => setStepIndex(nextIndex), 400)
+            return
+          }
+        }
+        setStepIndex(nextIndex)
+      }
+    },
+    [navigate]
+  )
+
+  return (
+    <div className="flex min-h-screen">
+      <Sidebar />
+
+      <main className="flex-1 ml-56">
+        <div className="flex items-center justify-end h-12 px-8">
+          <button
+            onClick={() => window.dispatchEvent(new Event('relaunch-tour'))}
+            className="flex items-center gap-1.5 px-3 py-1.5 rounded-lg text-xs font-sans font-medium text-warm-muted hover:text-[#1a1a1a] hover:bg-warm-header-bg transition-colors"
+            title="Take the guided tour"
+          >
+            <Thermometer size={14} />
+            Tour
+          </button>
+        </div>
+        <div className="px-8 pb-8">
+        <Routes>
+          <Route path="/" element={<Dashboard />} />
+          <Route path="/zones" element={<Zones />} />
+          <Route path="/heat-monitor" element={<HeatMonitor />} />
+          <Route path="/calibrate" element={<ProgramDesigner />} />
+          <Route path="/alerts" element={<Notifications />} />
+          <Route path="/pipeline" element={<Pipeline />} />
+        </Routes>
+        </div>
+      </main>
+
+      <Joyride
+        steps={tourSteps}
+        run={runTour}
+        stepIndex={stepIndex}
+        continuous
+        showSkipButton
+        showProgress
+        scrollToFirstStep
+        disableOverlayClose
+        spotlightClicks={false}
+        callback={handleJoyrideCallback}
+        styles={tourStyles}
+        floaterProps={{ disableAnimation: true }}
+        locale={{
+          back: 'Back',
+          close: 'Close',
+          last: 'Finish',
+          next: 'Next',
+          skip: 'Skip tour',
+        }}
+      />
+    </div>
+  )
+}

frontend/src/components/Layout.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react'
+import Sidebar from './Sidebar'
+
+interface Props {
+  children: ReactNode
+}
+
+export default function Layout({ children }: Props) {
+  return (
+    <div className="flex min-h-screen bg-cream">
+      <Sidebar />
+      <main className="flex-1 ml-56 p-8">
+        {children}
+      </main>
+    </div>
+  )
+}

frontend/src/components/LoadingState.tsx

@@ -0,0 +1,33 @@
+interface LoadingProps {
+  message?: string
+}
+
+export function LoadingSpinner({ message = 'Loading...' }: LoadingProps) {
+  return (
+    <div className="flex flex-col items-center justify-center py-16">
+      <div className="w-8 h-8 border-2 border-warm-border border-t-gold rounded-full animate-spin" />
+      <p className="mt-4 text-sm text-warm-muted font-sans">{message}</p>
+    </div>
+  )
+}
+
+interface ErrorProps {
+  message?: string
+  onRetry?: () => void
+}
+
+export function ErrorState({ message = 'Failed to load data', onRetry }: ErrorProps) {
+  return (
+    <div className="flex flex-col items-center justify-center py-16">
+      <div className="w-12 h-12 rounded-full bg-red-50 flex items-center justify-center mb-3">
+        <span className="text-error text-xl font-bold">!</span>
+      </div>
+      <p className="text-sm text-warm-body font-sans mb-3">{message}</p>
+      {onRetry && (
+        <button onClick={onRetry} className="btn-secondary text-xs">
+          Retry
+        </button>
+      )}
+    </div>
+  )
+}

frontend/src/components/MetricCard.tsx

@@ -0,0 +1,77 @@
+import { useEffect, useRef, useState } from 'react'
+
+interface Props {
+  label: string
+  value: string | number | undefined | null
+  subtitle?: string
+  className?: string
+}
+
+function useCountUp(target: string | number | undefined | null, duration = 600) {
+  const [display, setDisplay] = useState<string>('--')
+  const hasAnimated = useRef(false)
+
+  useEffect(() => {
+    if (target === null || target === undefined) {
+      setDisplay('--')
+      return
+    }
+
+    const str = String(target)
+
+    if (hasAnimated.current) {
+      setDisplay(str)
+      return
+    }
+
+    const match = str.match(/(\d+)/)
+    if (!match) {
+      setDisplay(str)
+      hasAnimated.current = true
+      return
+    }
+
+    const num = parseInt(match[1], 10)
+    if (num === 0) {
+      setDisplay(str)
+      hasAnimated.current = true
+      return
+    }
+
+    const prefix = str.slice(0, match.index)
+    const suffix = str.slice((match.index ?? 0) + match[1].length)
+    const start = performance.now()
+
+    function tick(now: number) {
+      const elapsed = now - start
+      const progress = Math.min(elapsed / duration, 1)
+      const eased = 1 - Math.pow(1 - progress, 3)
+      const current = Math.round(num * eased)
+      setDisplay(`${prefix}${current}${suffix}`)
+
+      if (progress < 1) {
+        requestAnimationFrame(tick)
+      } else {
+        hasAnimated.current = true
+      }
+    }
+
+    requestAnimationFrame(tick)
+  }, [target, duration])
+
+  return display
+}
+
+export default function MetricCard({ label, value, subtitle, className = '' }: Props) {
+  const display = useCountUp(value)
+
+  return (
+    <div className={`metric-card ${className}`}>
+      <div className="metric-label">{label}</div>
+      <div className="metric-value">{display}</div>
+      {subtitle && (
+        <p className="text-xs text-warm-muted mt-1">{subtitle}</p>
+      )}
+    </div>
+  )
+}

frontend/src/components/Sidebar.tsx

@@ -0,0 +1,73 @@
+import { NavLink } from 'react-router-dom'
+import {
+  Home,
+  MapPin,
+  Thermometer,
+  SlidersHorizontal,
+  Bell,
+  Settings,
+} from 'lucide-react'
+
+const NAV_ITEMS = [
+  { to: '/', label: 'Home', icon: Home, tourId: 'nav-home' },
+  { to: '/zones', label: 'Zones', icon: MapPin, tourId: 'nav-zones' },
+  { to: '/heat-monitor', label: 'Heat Monitor', icon: Thermometer, tourId: 'nav-heat-monitor' },
+  { to: '/calibrate', label: 'Program Design', icon: SlidersHorizontal, tourId: 'nav-calibrate' },
+  { to: '/alerts', label: 'Alerts', icon: Bell, tourId: 'nav-alerts' },
+  { to: '/pipeline', label: 'Pipeline', icon: Settings, tourId: 'nav-pipeline' },
+]
+
+export default function Sidebar() {
+  return (
+    <aside
+      className="fixed top-0 left-0 z-50 h-full w-56 flex flex-col"
+      style={{ background: 'linear-gradient(180deg, #1a1a1a 0%, #222018 100%)' }}
+    >
+      {/* Brand */}
+      <div className="flex items-center h-16 px-5 border-b border-white/10">
+        <NavLink to="/" className="flex items-center gap-2.5 no-underline">
+          <div className="w-8 h-8 rounded-lg bg-gold flex items-center justify-center">
+            <Thermometer size={18} className="text-white" />
+          </div>
+          <div>
+            <h1 className="text-sm font-bold text-white leading-tight font-serif m-0">
+              Heat Risk
+            </h1>
+            <p className="text-[10px] text-[#e0dcd5] font-sans font-medium uppercase tracking-wider m-0">
+              Index Engine
+            </p>
+          </div>
+        </NavLink>
+      </div>
+
+      {/* Navigation */}
+      <nav className="flex-1 px-3 py-4 space-y-0.5 overflow-y-auto">
+        {NAV_ITEMS.map(({ to, label, icon: Icon, tourId }) => (
+          <NavLink
+            key={to}
+            to={to}
+            end={to === '/'}
+            data-tour={tourId}
+            className={({ isActive }) =>
+              `flex items-center gap-3 px-3 py-2.5 rounded-lg text-sm font-sans font-medium transition-colors duration-100 ${
+                isActive
+                  ? 'bg-gold/15 text-gold'
+                  : 'text-[#e0dcd5] hover:bg-white/5 hover:text-white'
+              }`
+            }
+          >
+            <Icon size={18} />
+            {label}
+          </NavLink>
+        ))}
+      </nav>
+
+      {/* Footer */}
+      <div className="px-5 py-3 border-t border-white/10">
+        <p className="text-[10px] text-[#e0dcd5]/60 font-sans uppercase tracking-wider m-0">
+          East Africa Urban Heat
+        </p>
+      </div>
+    </aside>
+  )
+}

frontend/src/components/StatusBadge.tsx

@@ -0,0 +1,33 @@
+interface Props {
+  status: string
+  className?: string
+}
+
+const STATUS_MAP: Record<string, { className: string; label?: string }> = {
+  critical: { className: 'badge-red' },
+  warning: { className: 'badge-orange' },
+  watch: { className: 'badge-amber' },
+  normal: { className: 'badge-green' },
+  active: { className: 'badge-blue' },
+  sent: { className: 'badge-green' },
+  failed: { className: 'badge-red' },
+  ok: { className: 'badge-green' },
+  partial: { className: 'badge-amber' },
+  dry_run: { className: 'badge-slate', label: 'dry run' },
+  high: { className: 'badge-red' },
+  moderate: { className: 'badge-amber' },
+  low: { className: 'badge-green' },
+  poor: { className: 'badge-red' },
+  good: { className: 'badge-green' },
+}
+
+export default function StatusBadge({ status, className = '' }: Props) {
+  const config = STATUS_MAP[status] ?? { className: 'badge-slate' }
+  const label = config.label ?? status
+
+  return (
+    <span className={`${config.className} ${className}`}>
+      {label}
+    </span>
+  )
+}

frontend/src/index.css

@@ -0,0 +1,308 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  html {
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  body {
+    @apply min-h-screen bg-cream font-sans text-[#1a1a1a] antialiased;
+    margin: 0;
+  }
+
+  h1, h2, h3, h4, h5, h6 {
+    @apply font-serif font-semibold text-[#1a1a1a];
+  }
+
+  h1 { @apply font-bold; }
+
+  p, li, td, span, label {
+    color: #555;
+  }
+
+  /* Custom scrollbar — warm tones */
+  ::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+
+  ::-webkit-scrollbar-track {
+    @apply bg-transparent;
+  }
+
+  ::-webkit-scrollbar-thumb {
+    @apply rounded-full;
+    background: #d4cfc7;
+  }
+
+  ::-webkit-scrollbar-thumb:hover {
+    background: #b8b3a9;
+  }
+}
+
+@layer components {
+  /* ── Cards ── */
+  .card {
+    @apply bg-white rounded-[10px] border border-warm-border;
+    transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease;
+  }
+
+  .card:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.06);
+    border-color: #ccc8c0;
+  }
+
+  .card-body {
+    @apply p-5;
+  }
+
+  /* ── Metric cards ── */
+  .metric-card {
+    @apply bg-white rounded-[10px] border border-warm-border p-5;
+    transition: transform 0.2s ease, box-shadow 0.2s ease, border-color 0.2s ease;
+  }
+
+  .metric-card:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.06);
+    border-color: #ccc8c0;
+  }
+
+  .metric-card .metric-label {
+    @apply uppercase text-[0.72rem] font-sans font-medium text-warm-muted;
+    letter-spacing: 1.2px;
+  }
+
+  .metric-card .metric-value {
+    @apply font-serif font-bold text-[#1a1a1a] text-2xl mt-1;
+  }
+
+  /* ── Buttons ── */
+  .btn {
+    @apply inline-flex items-center justify-center gap-2 rounded-md px-4 py-2.5
+           font-sans font-semibold text-sm uppercase transition-all duration-150 ease-in-out
+           focus:outline-none focus:ring-2 focus:ring-offset-2
+           disabled:opacity-50 disabled:cursor-not-allowed;
+    letter-spacing: 0.5px;
+  }
+
+  .btn-primary {
+    @apply inline-flex items-center justify-center gap-2 rounded-md px-4 py-2.5
+           font-sans font-semibold text-sm uppercase transition-all duration-150 ease-in-out
+           focus:outline-none focus:ring-2 focus:ring-offset-2
+           disabled:opacity-50 disabled:cursor-not-allowed
+           bg-gold text-white hover:bg-gold-hover
+           focus:ring-gold active:bg-gold-hover;
+    letter-spacing: 0.5px;
+    box-shadow: 0 1px 2px rgba(0,0,0,0.06);
+  }
+
+  .btn-primary:hover {
+    transform: translateY(-1px);
+    box-shadow: 0 3px 8px rgba(212, 160, 25, 0.25);
+  }
+
+  .btn-secondary {
+    @apply inline-flex items-center justify-center gap-2 rounded-md px-4 py-2.5
+           font-sans font-semibold text-sm uppercase transition-all duration-150 ease-in-out
+           focus:outline-none focus:ring-2 focus:ring-offset-2
+           disabled:opacity-50 disabled:cursor-not-allowed
+           bg-white text-[#555] border border-warm-border
+           hover:bg-warm-header-bg focus:ring-warm-border active:bg-warm-header-bg;
+    letter-spacing: 0.5px;
+  }
+
+  /* ── Inputs ── */
+  .input {
+    @apply block w-full rounded-md border border-warm-border px-3.5 py-2.5
+           text-sm text-[#1a1a1a] font-sans placeholder-[#888]
+           focus:border-gold focus:ring-2 focus:ring-gold/20
+           focus:outline-none transition-colors duration-150;
+  }
+
+  /* ── Badges / pills ── */
+  .badge {
+    @apply inline-flex items-center rounded-full px-2.5 py-0.5
+           text-xs font-semibold font-sans;
+  }
+
+  .badge-green {
+    @apply inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold font-sans;
+    background: rgba(42, 157, 143, 0.18);
+    color: #2a9d8f;
+    border: 1px solid rgba(42, 157, 143, 0.44);
+  }
+
+  .badge-amber {
+    @apply inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold font-sans;
+    background: rgba(212, 160, 25, 0.18);
+    color: #d4a019;
+    border: 1px solid rgba(212, 160, 25, 0.44);
+  }
+
+  .badge-red {
+    @apply inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold font-sans;
+    background: rgba(230, 57, 70, 0.18);
+    color: #e63946;
+    border: 1px solid rgba(230, 57, 70, 0.44);
+  }
+
+  .badge-blue {
+    @apply inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold font-sans;
+    background: rgba(21, 101, 192, 0.18);
+    color: #1565C0;
+    border: 1px solid rgba(21, 101, 192, 0.44);
+  }
+
+  .badge-slate {
+    @apply inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold font-sans;
+    background: rgba(136, 136, 136, 0.18);
+    color: #888;
+    border: 1px solid rgba(136, 136, 136, 0.44);
+  }
+
+  .badge-orange {
+    @apply inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold font-sans;
+    background: rgba(230, 126, 34, 0.18);
+    color: #e67e22;
+    border: 1px solid rgba(230, 126, 34, 0.44);
+  }
+
+  /* ── Tables ── */
+  .table-container {
+    @apply overflow-x-auto rounded-[10px] border border-warm-border bg-white;
+  }
+
+  .table-container table {
+    @apply w-full text-sm text-left font-sans;
+  }
+
+  .table-container thead {
+    @apply border-b border-warm-border;
+    background: #f5f3ef;
+  }
+
+  .table-container th {
+    @apply px-4 py-3 font-semibold text-warm-muted text-xs uppercase;
+    letter-spacing: 1.2px;
+  }
+
+  .table-container td {
+    @apply px-4 py-3 border-b border-warm-border/50;
+    color: #555;
+  }
+
+  .table-container tbody tr:last-child td {
+    @apply border-b-0;
+  }
+
+  .table-container tbody tr:hover {
+    background: rgba(250, 248, 245, 0.6);
+  }
+
+  /* ── Tabs (bottom-border style) ── */
+  .page-title {
+    font-size: 2rem;
+    font-weight: 700;
+    font-family: 'Source Serif 4', serif;
+    color: #1a1a1a;
+    line-height: 1.2;
+    margin: 0;
+  }
+
+  .page-caption {
+    font-size: 0.88rem;
+    color: #888;
+    margin-top: 6px;
+  }
+
+  .tab-list {
+    @apply flex border-b border-warm-border gap-0;
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+    scrollbar-width: none;
+  }
+  .tab-list::-webkit-scrollbar { display: none; }
+
+  .tab-item {
+    @apply px-4 py-2.5 text-sm font-sans font-medium text-warm-body cursor-pointer
+           border-b-2 border-transparent transition-colors duration-150
+           hover:text-[#1a1a1a] hover:border-warm-border;
+    white-space: nowrap;
+    flex-shrink: 0;
+  }
+
+  .tab-item.active {
+    @apply text-gold border-gold font-semibold;
+  }
+
+  /* ── Stage cards (Dashboard) ── */
+  .stage-card {
+    @apply bg-white rounded-[14px] border border-warm-border relative overflow-hidden;
+    padding: 22px 20px 16px;
+    text-decoration: none;
+    color: inherit;
+    font-family: 'DM Sans', sans-serif;
+    transition: all 0.25s cubic-bezier(0.25, 0.46, 0.45, 0.94);
+  }
+
+  .stage-card:hover {
+    border-color: #ccc8c0;
+    box-shadow: 0 8px 28px rgba(0,0,0,0.06), 0 2px 8px rgba(0,0,0,0.03);
+    transform: translateY(-3px);
+  }
+
+  /* ── Section headers ── */
+  .section-header {
+    @apply uppercase text-[0.78rem] font-sans font-semibold text-warm-muted pb-2 mb-4;
+    letter-spacing: 1.5px;
+    border-bottom: 2px solid #d4a019;
+  }
+}
+
+@layer utilities {
+  .animate-fade-in {
+    animation: fadeIn 0.2s ease-out;
+  }
+
+  .animate-slide-up {
+    animation: slideUp 0.3s ease-out both;
+  }
+
+  .animate-stagger > * {
+    animation: slideUp 0.3s ease-out both;
+  }
+  .animate-stagger > *:nth-child(1) { animation-delay: 0ms; }
+  .animate-stagger > *:nth-child(2) { animation-delay: 50ms; }
+  .animate-stagger > *:nth-child(3) { animation-delay: 100ms; }
+  .animate-stagger > *:nth-child(4) { animation-delay: 150ms; }
+  .animate-stagger > *:nth-child(5) { animation-delay: 200ms; }
+  .animate-stagger > *:nth-child(6) { animation-delay: 250ms; }
+
+  .animate-tab-enter {
+    animation: tabEnter 0.15s ease-out both;
+  }
+
+  @keyframes fadeIn {
+    from { opacity: 0; transform: translateY(4px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+
+  @keyframes slideUp {
+    from { opacity: 0; transform: translateY(8px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+
+  @keyframes tabEnter {
+    from { opacity: 0; transform: translateY(4px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+}
+
+/* Joyride tooltip overrides */
+.__floater__body {
+  font-family: 'DM Sans', system-ui, sans-serif !important;
+}

frontend/src/lib/api.ts

@@ -0,0 +1,340 @@
+import { useQuery, keepPreviousData } from '@tanstack/react-query'
+
+const BASE_URL = import.meta.env.VITE_API_URL ?? ''
+
+async function fetchJson<T>(path: string): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`)
+  if (!res.ok) throw new Error(`API error: ${res.status} ${res.statusText}`)
+  return res.json() as Promise<T>
+}
+
+// ── Types (matched to actual API response field names) ──────────────────
+
+export interface Zone {
+  zone_id: string
+  name: string
+  city: string
+  country: string
+  latitude: number
+  longitude: number
+  elevation_m: number
+  settlement_type: string
+  worker_population_est: number
+  outdoor_exposure_pct: number
+  heat_vulnerability: string
+  risk_level: string
+  current_temp_c: number
+  current_wbgt_c: number
+  current_heat_index_c: number
+  max_temp_c: number
+  max_wbgt_c: number
+  consecutive_hot_days: number
+  total_days_above_33: number
+  heat_risk_score: number
+  grid_temp_c: number
+  uhi_delta_c: number
+  corrected_temp_c: number
+  trigger_probability_7d: number
+  prediction_confidence: number
+  model_tier: string
+  enrolled_workers: number
+  data_quality: number
+  last_updated: string
+}
+
+export interface ZonesResponse {
+  zones: Zone[]
+  total: number
+  cities: string[]
+}
+
+export interface DailyHeat {
+  date: string
+  temp_c: number
+  grid_temp_c: number
+  uhi_delta_c: number
+  humidity_pct: number
+  wbgt_c: number
+  heat_index_c: number
+}
+
+export interface IndexData {
+  zone_id: string
+  zone_name: string
+  city: string
+  temp_current: number
+  wbgt_current: number
+  heat_index_current: number
+  consecutive_hot_days: number
+  heat_risk_score: number
+  risk_level: string
+  grid_temp_c: number
+  uhi_delta_c: number
+  trigger_probability_7d: number
+  prediction_confidence: number
+  model_tier: string
+  daily_history: DailyHeat[]
+}
+
+export interface IndicesResponse {
+  indices: IndexData[]
+  total: number
+}
+
+export interface Trigger {
+  trigger_id: string
+  zone_id: string
+  zone_name: string
+  city: string
+  trigger_level: string
+  trigger_date: string
+  heat_risk_score: number
+  max_temp_c: number
+  max_wbgt_c: number
+  consecutive_days: number
+  total_days_above: number
+  settlement_type: string
+  payout_per_worker_usd: number
+  enrolled_workers: number
+  total_payout_usd: number
+  status: string
+}
+
+export interface TriggersResponse {
+  triggers: Trigger[]
+  total: number
+  active: number
+  by_level: Record<string, number>
+}
+
+export interface BasisRisk {
+  zone_id: string
+  zone_name: string
+  city: string
+  overall_score: number
+  false_positive_rate: number
+  false_negative_rate: number
+  correlation: number
+  settlement_type: string
+  heat_vulnerability: string
+  recommendation: string
+}
+
+export interface BasisRiskResponse {
+  assessments: BasisRisk[]
+  total: number
+  avg_score: number
+}
+
+export interface Notification {
+  id: string
+  zone_id: string
+  zone_name: string
+  city: string
+  trigger_level: string
+  channel: string
+  language: string
+  recipient_count: number
+  message_preview: string
+  status: string
+  delivered_at: string
+  cost_estimate: number
+}
+
+export interface NotificationsResponse {
+  notifications: Notification[]
+  total: number
+  by_language: Record<string, number>
+}
+
+export interface PipelineStep {
+  step: string
+  status: string
+  duration_s: number
+}
+
+export interface PipelineRun {
+  run_id: string
+  started_at: string
+  ended_at: string
+  status: string
+  duration_s: number
+  zones_processed: number
+  triggers_found: number
+  notifications_sent: number
+  total_cost_usd: number
+  steps: PipelineStep[]
+}
+
+export interface PipelineRunsResponse {
+  runs: PipelineRun[]
+  total: number
+}
+
+export interface PipelineStats {
+  total_runs: number
+  successful_runs: number
+  success_rate: number
+  zones_monitored: number
+  cities: number
+  active_triggers: number
+  total_enrolled: number
+  total_cost_usd: number
+  avg_cost_per_run_usd: number
+  last_run: string | null
+  data_sources: string[]
+}
+
+export interface EnrolledResponse {
+  by_zone: { zone_id: string; zone_name: string; city: string; enrolled: number }[]
+  total_enrolled: number
+}
+
+export interface CalibrateParams {
+  temp_threshold: number
+  consecutive_days: number
+  wbgt_threshold: number
+  payout_usd: number
+  budget_usd: number
+  worker_contribution_usd: number
+}
+
+export interface CalibrateZoneResult {
+  zone_id: string
+  zone_name: string
+  city: string
+  settlement_type: string
+  heat_vulnerability: string
+  enrolled_workers: number
+  days_above_temp: number
+  days_above_wbgt: number
+  consecutive_days_temp: number
+  consecutive_days_wbgt: number
+  trigger_events: number
+  events_per_year: number
+  annual_payout_per_worker: number
+  annual_payout_total: number
+  basis_risk_score: number
+  triggered: boolean
+  actuarial_cost_per_worker: number
+  cost_breakdown: Record<string, any>
+  allocated_budget: number
+  workers_covered: number
+  coverage_pct: number
+  priority_rank: number
+}
+
+export interface CalibrateSummary {
+  total_zones: number
+  zones_triggered: number
+  total_trigger_days: number
+  avg_events_per_year: number
+  total_annual_cost: number
+  avg_cost_per_worker: number
+  total_enrolled: number
+  avg_basis_risk: number
+}
+
+export interface CalibrateAllocation {
+  budget_usd: number
+  worker_contribution_usd: number
+  workers_covered: number
+  overall_coverage_pct: number
+  zones_fully_funded: number
+  zones_partially_funded: number
+  zones_unfunded: number
+  stretch_analysis: Record<string, any>
+}
+
+export interface CalibrateResponse {
+  zones: CalibrateZoneResult[]
+  summary: CalibrateSummary
+  allocation: CalibrateAllocation
+  thresholds: CalibrateParams
+}
+
+// ── Query hooks ──────────────────────────────────────────────────────────
+
+const STALE_5MIN = 5 * 60 * 1000
+
+export function useZones() {
+  return useQuery<ZonesResponse>({
+    queryKey: ['zones'],
+    queryFn: () => fetchJson('/api/zones'),
+    staleTime: STALE_5MIN,
+  })
+}
+
+export function useIndices() {
+  return useQuery<IndicesResponse>({
+    queryKey: ['indices'],
+    queryFn: () => fetchJson('/api/indices'),
+    staleTime: STALE_5MIN,
+  })
+}
+
+export function useTriggers() {
+  return useQuery<TriggersResponse>({
+    queryKey: ['triggers'],
+    queryFn: () => fetchJson('/api/triggers'),
+    staleTime: STALE_5MIN,
+  })
+}
+
+export function useBasisRisk() {
+  return useQuery<BasisRiskResponse>({
+    queryKey: ['basis-risk'],
+    queryFn: () => fetchJson('/api/basis-risk'),
+    staleTime: STALE_5MIN,
+  })
+}
+
+export function useNotifications() {
+  return useQuery<NotificationsResponse>({
+    queryKey: ['notifications'],
+    queryFn: () => fetchJson('/api/notifications'),
+    staleTime: STALE_5MIN,
+  })
+}
+
+export function usePipelineRuns() {
+  return useQuery<PipelineRunsResponse>({
+    queryKey: ['pipeline-runs'],
+    queryFn: () => fetchJson('/api/pipeline/runs'),
+    staleTime: STALE_5MIN,
+  })
+}
+
+export function usePipelineStats() {
+  return useQuery<PipelineStats>({
+    queryKey: ['pipeline-stats'],
+    queryFn: () => fetchJson('/api/pipeline/stats'),
+    staleTime: STALE_5MIN,
+  })
+}
+
+export function useEnrolled() {
+  return useQuery<EnrolledResponse>({
+    queryKey: ['enrolled'],
+    queryFn: () => fetchJson('/api/enrolled-workers'),
+    staleTime: STALE_5MIN,
+  })
+}
+
+export function useCalibrateQuery(params: CalibrateParams) {
+  const qs = new URLSearchParams({
+    temp_threshold: String(params.temp_threshold),
+    consecutive_days: String(params.consecutive_days),
+    wbgt_threshold: String(params.wbgt_threshold),
+    payout_usd: String(params.payout_usd),
+    budget_usd: String(params.budget_usd),
+    worker_contribution_usd: String(params.worker_contribution_usd),
+  })
+
+  return useQuery<CalibrateResponse>({
+    queryKey: ['calibrate', params.temp_threshold, params.consecutive_days, params.wbgt_threshold, params.payout_usd, params.budget_usd, params.worker_contribution_usd],
+    queryFn: () => fetchJson(`/api/calibrate?${qs.toString()}`),
+    staleTime: 60 * 1000,
+    placeholderData: keepPreviousData,
+  })
+}

frontend/src/lib/tour.ts

@@ -0,0 +1,198 @@
+import type { Step } from 'react-joyride'
+
+export const tourSteps: Step[] = [
+  // ── Dashboard ──
+  {
+    target: '[data-tour="hero"]',
+    title: 'Welcome to the Heat Risk Engine',
+    content:
+      'This dashboard monitors an extreme heat insurance pipeline for urban workers across East Africa. ' +
+      'It pulls real satellite temperature data from NASA, calculates heat stress indices like WBGT, ' +
+      'and triggers payout notifications to enrolled workers when dangerous heat thresholds are breached — ' +
+      'across 20 neighborhoods in Nairobi, Dar es Salaam, Kampala, and Kigali.',
+    placement: 'bottom',
+    disableBeacon: true,
+  },
+  {
+    target: '[data-tour="stage-cards"]',
+    title: 'Three-stage pipeline',
+    content:
+      'Climate temperature data flows through heat index calculation to trigger calibration. ' +
+      'Each stage runs automatically on a scheduled pipeline.',
+    placement: 'bottom',
+    disableBeacon: true,
+  },
+  {
+    target: '[data-tour="metrics"]',
+    title: 'Live metrics',
+    content:
+      'Active triggers, zones monitored, enrolled workers, and pipeline run counts ' +
+      'update after each pipeline execution.',
+    placement: 'top',
+    disableBeacon: true,
+  },
+  // ── Navigate to Zones ──
+  {
+    target: '[data-tour="nav-zones"]',
+    title: 'Zone coverage',
+    content: 'Next: the 20 urban zones across East African cities.',
+    placement: 'right',
+    disableBeacon: true,
+  },
+  {
+    target: '[data-tour="zones-metrics"]',
+    title: 'Heat-vulnerable zones',
+    content:
+      'Urban neighborhoods where outdoor workers face the highest heat exposure. ' +
+      'Each zone has its own heat vulnerability profile, worker population estimate, and enrollment count.',
+    placement: 'bottom',
+    disableBeacon: true,
+  },
+  // ── Navigate to Heat Monitor ──
+  {
+    target: '[data-tour="nav-heat-monitor"]',
+    title: 'Heat monitoring',
+    content: 'Next: real-time temperature, WBGT, and heat index tracking.',
+    placement: 'right',
+    disableBeacon: true,
+  },
+  {
+    target: '[data-tour="heat-monitor-metrics"]',
+    title: 'Heat index monitoring',
+    content:
+      'Temperature and WBGT values classify each zone from normal through caution, warning, to critical. ' +
+      'Consecutive hot days track sustained heat events that trigger payouts.',
+    placement: 'bottom',
+    disableBeacon: true,
+  },
+  {
+    target: '[data-tour="heat-monitor-tabs"]',
+    title: 'Temperature trends',
+    content:
+      'The trends tab shows 90-day temperature history for each zone, revealing heat wave patterns ' +
+      'and the buildup to trigger events.',
+    placement: 'top',
+    disableBeacon: true,
+  },
+  // ── Navigate to Program Designer ──
+  {
+    target: '[data-tour="nav-calibrate"]',
+    title: 'Program design',
+    content: 'Next: the program design tool with actuarial pricing and budget allocation.',
+    placement: 'right',
+    disableBeacon: true,
+  },
+  {
+    target: '[data-tour="program-controls"]',
+    title: 'Design the product',
+    content:
+      'Enter your total budget and payout amount. The model does the actuarial pricing \u2014 ' +
+      'calculating what it costs to cover each zone based on predicted trigger frequency, ' +
+      'basis risk, and worker exposure. Then it optimizes allocation: highest-impact zones get funded first.',
+    placement: 'bottom',
+    disableBeacon: true,
+  },
+  {
+    target: '[data-tour="program-results"]',
+    title: 'Allocation results',
+    content:
+      'Results update live as you move the sliders. Zones are ranked by priority, ' +
+      'with actuarial cost per worker, allocated budget, and coverage percentage for each zone.',
+    placement: 'top',
+    disableBeacon: true,
+  },
+  // ── Navigate to Alerts ──
+  {
+    target: '[data-tour="nav-alerts"]',
+    title: 'Worker heat alerts',
+    content: 'Next: how workers are notified of heat danger and payouts.',
+    placement: 'right',
+    disableBeacon: true,
+  },
+  {
+    target: '[data-tour="alerts-feed"]',
+    title: 'Multilingual alerts',
+    content:
+      'SMS and WhatsApp notifications are sent in English and Swahili. ' +
+      'Each message includes the temperature reading, heat danger level, and payout amount.',
+    placement: 'top',
+    disableBeacon: true,
+  },
+  // ── Final ──
+  {
+    target: '[data-tour="nav-home"]',
+    title: 'The hard problems remain',
+    content:
+      'The full chain from satellite temperature data to worker payout notification, automated. ' +
+      'The hard part is still human: enrolling informal workers who need coverage most, ' +
+      'building trust in a product that pays based on a weather station reading, ' +
+      'and making sure people actually rest when it\u2019s dangerous to work. ' +
+      'That\u2019s where the investment should go.',
+    placement: 'right',
+    disableBeacon: true,
+  },
+]
+
+export const tourStyles = {
+  options: {
+    zIndex: 10000,
+    arrowColor: '#1a1a1a',
+    backgroundColor: '#1a1a1a',
+    primaryColor: '#d4a019',
+    textColor: '#e0dcd5',
+    overlayColor: 'rgba(0, 0, 0, 0.45)',
+  },
+  tooltip: {
+    borderRadius: 10,
+    padding: '20px 22px',
+    maxWidth: 380,
+    fontFamily: '"DM Sans", system-ui, sans-serif',
+    fontSize: '0.88rem',
+    lineHeight: 1.6,
+  },
+  tooltipTitle: {
+    fontFamily: '"Source Serif 4", Georgia, serif',
+    fontWeight: 700,
+    fontSize: '1.05rem',
+    color: '#d4a019',
+    marginBottom: 8,
+  },
+  tooltipContent: {
+    padding: '8px 0 0',
+  },
+  buttonNext: {
+    backgroundColor: '#d4a019',
+    color: '#fff',
+    borderRadius: 6,
+    fontFamily: '"DM Sans", system-ui, sans-serif',
+    fontWeight: 600,
+    fontSize: '0.8rem',
+    letterSpacing: '0.5px',
+    textTransform: 'uppercase' as const,
+    padding: '8px 18px',
+  },
+  buttonBack: {
+    color: '#888',
+    fontFamily: '"DM Sans", system-ui, sans-serif',
+    fontWeight: 500,
+    fontSize: '0.8rem',
+    marginRight: 8,
+  },
+  buttonSkip: {
+    color: '#666',
+    fontFamily: '"DM Sans", system-ui, sans-serif',
+    fontSize: '0.75rem',
+  },
+  spotlight: {
+    borderRadius: 10,
+  },
+  beacon: {
+    display: 'none',
+  },
+  beaconInner: {
+    display: 'none',
+  },
+  beaconOuter: {
+    display: 'none',
+  },
+}

frontend/src/main.tsx

@@ -0,0 +1,25 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import App from './App'
+import './index.css'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60_000,
+      retry: 1,
+    },
+  },
+})
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <App />
+      </BrowserRouter>
+    </QueryClientProvider>
+  </React.StrictMode>
+)

frontend/src/pages/Dashboard.tsx

@@ -0,0 +1,168 @@
+import { useState } from 'react'
+import { Link } from 'react-router-dom'
+import { Satellite, Thermometer, SlidersHorizontal, ChevronDown, ChevronRight, ArrowRight } from 'lucide-react'
+import MetricCard from '../components/MetricCard'
+import StatusBadge from '../components/StatusBadge'
+import { LoadingSpinner, ErrorState } from '../components/LoadingState'
+import { usePipelineStats, usePipelineRuns } from '../lib/api'
+
+export default function Dashboard() {
+  const stats = usePipelineStats()
+  const runs = usePipelineRuns()
+  const [showRuns, setShowRuns] = useState(false)
+
+  if (stats.isLoading) return <LoadingSpinner />
+  if (stats.isError) return <ErrorState onRetry={() => stats.refetch()} />
+
+  const s = stats.data
+
+  return (
+    <div className="animate-slide-up">
+      {/* Hero */}
+      <div data-tour="hero" className="pt-2 pb-6">
+        <h1 className="page-title">Extreme Heat Risk Engine</h1>
+        <p className="page-caption">
+          Parametric insurance triggers for urban workers in East Africa
+        </p>
+      </div>
+
+      {/* Stage Cards */}
+      <div data-tour="stage-cards" className="mb-8">
+        <div className="section-header">Pipeline Stages</div>
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-4 items-center">
+          <Link to="/heat-monitor" className="stage-card no-underline">
+            <div className="flex items-center gap-3 mb-2">
+              <div className="w-9 h-9 rounded-lg bg-blue-50 flex items-center justify-center">
+                <Satellite size={18} className="text-info" />
+              </div>
+              <h3 className="text-sm font-semibold text-[#1a1a1a] font-sans m-0">Climate Data + UHI Correction</h3>
+            </div>
+            <p className="text-xs text-warm-body leading-relaxed m-0">
+              NASA POWER grid temperatures corrected with ML urban heat island model per zone
+            </p>
+            <div className="mt-3 flex items-center gap-1.5 text-[10px] text-warm-muted uppercase tracking-wider font-semibold">
+              {s?.data_sources?.join(' + ')} + UHI Model
+            </div>
+          </Link>
+
+          <div className="hidden md:flex items-center justify-center">
+            <ArrowRight size={20} className="text-warm-border" />
+          </div>
+
+          <Link to="/heat-monitor" className="stage-card no-underline">
+            <div className="flex items-center gap-3 mb-2">
+              <div className="w-9 h-9 rounded-lg bg-amber-50 flex items-center justify-center">
+                <Thermometer size={18} className="text-warning" />
+              </div>
+              <h3 className="text-sm font-semibold text-[#1a1a1a] font-sans m-0">Heat Wave Prediction</h3>
+            </div>
+            <p className="text-xs text-warm-body leading-relaxed m-0">
+              7-day trigger probability forecasts with model confidence scoring per zone
+            </p>
+            <div className="mt-3 flex items-center gap-1.5 text-[10px] text-warm-muted uppercase tracking-wider font-semibold">
+              Prediction + WBGT + Heat Index
+            </div>
+          </Link>
+
+          <div className="hidden md:flex items-center justify-center">
+            <ArrowRight size={20} className="text-warm-border" />
+          </div>
+
+          <Link to="/calibrate" className="stage-card no-underline">
+            <div className="flex items-center gap-3 mb-2">
+              <div className="w-9 h-9 rounded-lg bg-red-50 flex items-center justify-center">
+                <SlidersHorizontal size={18} className="text-error" />
+              </div>
+              <h3 className="text-sm font-semibold text-[#1a1a1a] font-sans m-0">Program Design</h3>
+            </div>
+            <p className="text-xs text-warm-body leading-relaxed m-0">
+              Actuarial pricing and budget allocation across zones with priority-ranked coverage
+            </p>
+            <div className="mt-3 flex items-center gap-1.5 text-[10px] text-warm-muted uppercase tracking-wider font-semibold">
+              Pricing + Budget + Allocation
+            </div>
+          </Link>
+        </div>
+      </div>
+
+      {/* Metrics */}
+      <div data-tour="metrics" className="mb-8">
+        <div className="section-header">Current Status</div>
+        <div className="grid grid-cols-2 md:grid-cols-4 gap-4 animate-stagger">
+          <MetricCard
+            label="Active Triggers"
+            value={s?.active_triggers}
+            subtitle="zones above threshold"
+          />
+          <MetricCard
+            label="Zones Monitored"
+            value={s?.zones_monitored}
+            subtitle={`${s?.cities} cities`}
+          />
+          <MetricCard
+            label="Workers Enrolled"
+            value={s?.total_enrolled?.toLocaleString()}
+            subtitle="across all zones"
+          />
+          <MetricCard
+            label="Pipeline Runs"
+            value={s?.total_runs}
+            subtitle={`${Math.round((s?.success_rate ?? 0) * 100)}% success`}
+          />
+        </div>
+      </div>
+
+      {/* Run History (collapsible) */}
+      <div className="mb-8">
+        <button
+          onClick={() => setShowRuns(!showRuns)}
+          className="flex items-center gap-2 section-header cursor-pointer w-full text-left border-b-0 pb-0 mb-0 bg-transparent border-none"
+          style={{ borderBottom: '2px solid #d4a019', paddingBottom: 8, marginBottom: 16 }}
+        >
+          {showRuns ? <ChevronDown size={14} /> : <ChevronRight size={14} />}
+          Run History
+        </button>
+        {showRuns && (
+          <div className="animate-tab-enter">
+            {runs.isLoading ? (
+              <LoadingSpinner message="Loading runs..." />
+            ) : runs.isError ? (
+              <ErrorState onRetry={() => runs.refetch()} />
+            ) : (
+              <div className="table-container">
+                <table>
+                  <thead>
+                    <tr>
+                      <th>Run ID</th>
+                      <th>Date</th>
+                      <th>Status</th>
+                      <th>Duration</th>
+                      <th>Zones</th>
+                      <th>Triggers</th>
+                      <th>Notifications</th>
+                      <th>Cost (USD)</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {runs.data?.runs.map((run) => (
+                      <tr key={run.run_id}>
+                        <td className="font-mono text-xs">{run.run_id}</td>
+                        <td>{new Date(run.started_at).toLocaleDateString()}</td>
+                        <td><StatusBadge status={run.status} /></td>
+                        <td>{run.duration_s.toFixed(0)}s</td>
+                        <td>{run.zones_processed}</td>
+                        <td>{run.triggers_found}</td>
+                        <td>{run.notifications_sent}</td>
+                        <td>${run.total_cost_usd.toFixed(4)}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/pages/HeatMonitor.tsx

@@ -0,0 +1,334 @@
+import { useState } from 'react'
+import {
+  LineChart,
+  Line,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  ReferenceLine,
+  ResponsiveContainer,
+} from 'recharts'
+import MetricCard from '../components/MetricCard'
+import StatusBadge from '../components/StatusBadge'
+import { LoadingSpinner, ErrorState } from '../components/LoadingState'
+import { useIndices } from '../lib/api'
+
+function tempColor(temp: number): string {
+  if (temp > 37) return '#e63946'
+  if (temp > 35) return '#d35400'
+  if (temp > 33) return '#e67e22'
+  if (temp > 30) return '#d4a019'
+  return '#2a9d8f'
+}
+
+function wbgtColor(wbgt: number): string {
+  if (wbgt > 32) return '#e63946'
+  if (wbgt > 30) return '#e67e22'
+  if (wbgt > 28) return '#d4a019'
+  return '#2a9d8f'
+}
+
+export default function HeatMonitor() {
+  const indices = useIndices()
+  const [activeTab, setActiveTab] = useState<'current' | 'trends'>('current')
+  const [selectedZone, setSelectedZone] = useState<string>('')
+
+  if (indices.isLoading) return <LoadingSpinner />
+  if (indices.isError) return <ErrorState onRetry={() => indices.refetch()} />
+
+  const data = indices.data?.indices ?? []
+  const criticalCount = data.filter((d) => d.risk_level === 'critical').length
+  const wbgtDanger = data.filter((d) => d.wbgt_current > 32).length
+  const avgTemp = data.length > 0
+    ? data.reduce((sum, d) => sum + d.temp_current, 0) / data.length
+    : 0
+
+  // Default to first zone for trends chart
+  const zoneId = selectedZone || (data.length > 0 ? data[0].zone_id : '')
+  const selectedData = data.find((d) => d.zone_id === zoneId)
+  const chartData = selectedData?.daily_history.map((d) => ({
+    date: new Date(d.date).toLocaleDateString('en', { month: 'short', day: 'numeric' }),
+    temp: d.temp_c,
+    gridTemp: d.grid_temp_c,
+    wbgt: d.wbgt_c,
+    humidity: d.humidity_pct,
+  })) ?? []
+
+  return (
+    <div className="animate-slide-up">
+      {/* Title */}
+      <div data-tour="heat-monitor-title" className="pt-2 pb-6">
+        <h1 className="page-title">Heat Monitor</h1>
+        <p className="page-caption">
+          Temperature, WBGT, and heat index tracking across all zones
+        </p>
+      </div>
+
+      {/* Metrics */}
+      <div data-tour="heat-monitor-metrics" className="mb-8">
+        <div className="grid grid-cols-2 md:grid-cols-4 gap-4 animate-stagger">
+          <MetricCard label="Zones Tracked" value={data.length} subtitle="across all cities" />
+          <MetricCard label="Critical Heat" value={criticalCount} subtitle="zones at critical risk" />
+          <MetricCard label="WBGT Danger" value={wbgtDanger} subtitle="WBGT > 32°C" />
+          <MetricCard label="Avg Temperature" value={`${avgTemp.toFixed(1)}°C`} subtitle="across all zones" />
+        </div>
+      </div>
+
+      {/* Tabs */}
+      <div data-tour="heat-monitor-tabs" className="mb-6">
+        <div className="tab-list">
+          <button
+            className={`tab-item ${activeTab === 'current' ? 'active' : ''}`}
+            onClick={() => setActiveTab('current')}
+          >
+            Current Heat
+          </button>
+          <button
+            className={`tab-item ${activeTab === 'trends' ? 'active' : ''}`}
+            onClick={() => setActiveTab('trends')}
+          >
+            Temperature Trends
+          </button>
+        </div>
+      </div>
+
+      {activeTab === 'current' && (
+        <div className="animate-tab-enter">
+          <div className="table-container">
+            <table>
+              <thead>
+                <tr>
+                  <th>Zone</th>
+                  <th>Temp (°C)</th>
+                  <th>WBGT (°C)</th>
+                  <th>Heat Index</th>
+                  <th>Consecutive Hot Days</th>
+                  <th>7-Day Trigger</th>
+                  <th>Confidence</th>
+                  <th>Model</th>
+                  <th>Risk Level</th>
+                </tr>
+              </thead>
+              <tbody>
+                {data.map((idx) => {
+                  const pct = (idx.trigger_probability_7d ?? 0) * 100
+                  const probColor = pct > 70 ? '#e63946' : pct > 50 ? '#e67e22' : pct > 20 ? '#d4a019' : '#2a9d8f'
+                  const tier = idx.model_tier ?? 'climatology'
+                  const tierColor = tier === 'full_model' ? '#2a9d8f' : tier === 'persistence' ? '#d4a019' : '#888'
+                  const tierLabel = tier === 'full_model' ? 'Full Model' : tier === 'persistence' ? 'Persistence' : 'Climatology'
+                  return (
+                    <tr key={idx.zone_id}>
+                      <td>
+                        <div className="font-medium text-[#1a1a1a]">{idx.zone_name}</div>
+                        <div className="text-[10px] text-warm-muted">{idx.city}</div>
+                      </td>
+                      <td>
+                        <span
+                          className="font-mono font-semibold text-sm"
+                          style={{ color: tempColor(idx.temp_current) }}
+                        >
+                          {idx.temp_current.toFixed(1)}
+                        </span>
+                      </td>
+                      <td>
+                        <span
+                          className="font-mono font-semibold text-sm"
+                          style={{ color: wbgtColor(idx.wbgt_current) }}
+                        >
+                          {idx.wbgt_current.toFixed(1)}
+                        </span>
+                      </td>
+                      <td className="font-mono text-sm">{idx.heat_index_current.toFixed(1)}</td>
+                      <td className="font-mono text-sm">{idx.consecutive_hot_days}</td>
+                      <td>
+                        <div className="flex items-center gap-2">
+                          <div className="w-16 h-2 rounded-full bg-warm-border overflow-hidden">
+                            <div className="h-full rounded-full" style={{ width: `${pct}%`, backgroundColor: probColor }} />
+                          </div>
+                          <span className="font-mono font-semibold text-sm" style={{ color: probColor }}>
+                            {pct?.toFixed(0)}%
+                          </span>
+                        </div>
+                      </td>
+                      <td className="font-mono text-sm">{((idx.prediction_confidence ?? 0) * 100).toFixed(0)}%</td>
+                      <td>
+                        <span
+                          className="inline-block px-2 py-0.5 rounded text-[10px] font-sans font-semibold uppercase tracking-wider"
+                          style={{ backgroundColor: `${tierColor}18`, color: tierColor, border: `1px solid ${tierColor}40` }}
+                        >
+                          {tierLabel}
+                        </span>
+                      </td>
+                      <td><StatusBadge status={idx.risk_level} /></td>
+                    </tr>
+                  )
+                })}
+              </tbody>
+            </table>
+          </div>
+
+          {/* Temperature color legend */}
+          <div className="mt-4 flex flex-wrap items-center gap-4 text-xs text-warm-muted font-sans">
+            <span className="font-semibold uppercase tracking-wider">Temp:</span>
+            {[
+              { label: '<30°C Safe', color: '#2a9d8f' },
+              { label: '30-33°C Caution', color: '#d4a019' },
+              { label: '33-35°C Warning', color: '#e67e22' },
+              { label: '35-37°C Danger', color: '#d35400' },
+              { label: '>37°C Extreme', color: '#e63946' },
+            ].map((item) => (
+              <span key={item.label} className="flex items-center gap-1.5">
+                <span
+                  className="w-3 h-3 rounded-sm inline-block"
+                  style={{ backgroundColor: item.color }}
+                />
+                {item.label}
+              </span>
+            ))}
+          </div>
+          <div className="mt-2 flex flex-wrap items-center gap-4 text-xs text-warm-muted font-sans">
+            <span className="font-semibold uppercase tracking-wider">WBGT:</span>
+            {[
+              { label: '<28°C Safe', color: '#2a9d8f' },
+              { label: '28-30°C Caution', color: '#d4a019' },
+              { label: '30-32°C Danger', color: '#e67e22' },
+              { label: '>32°C Extreme', color: '#e63946' },
+            ].map((item) => (
+              <span key={item.label} className="flex items-center gap-1.5">
+                <span
+                  className="w-3 h-3 rounded-sm inline-block"
+                  style={{ backgroundColor: item.color }}
+                />
+                {item.label}
+              </span>
+            ))}
+          </div>
+        </div>
+      )}
+
+      {activeTab === 'trends' && (
+        <div className="animate-tab-enter">
+          {/* Zone selector */}
+          <div className="mb-6 flex items-center gap-3">
+            <label className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider">
+              Zone
+            </label>
+            <select
+              value={zoneId}
+              onChange={(e) => setSelectedZone(e.target.value)}
+              className="input max-w-xs text-sm"
+            >
+              {data.map((d) => (
+                <option key={d.zone_id} value={d.zone_id}>
+                  {d.zone_name} ({d.city})
+                </option>
+              ))}
+            </select>
+            {selectedData && (
+              <span className="ml-2">
+                <StatusBadge status={selectedData.risk_level} />
+              </span>
+            )}
+          </div>
+
+          {/* Temperature Chart */}
+          <div className="card card-body">
+            <h3 className="text-sm font-semibold font-sans text-[#1a1a1a] mb-1">
+              90-Day Temperature History: {selectedData?.zone_name}
+            </h3>
+            <p className="text-xs text-warm-muted mb-4">
+              Current:{' '}
+              <span style={{ color: tempColor(selectedData?.temp_current ?? 0) }} className="font-semibold">
+                {selectedData?.temp_current.toFixed(1)}°C
+              </span>
+              {' / WBGT: '}
+              <span style={{ color: wbgtColor(selectedData?.wbgt_current ?? 0) }} className="font-semibold">
+                {selectedData?.wbgt_current.toFixed(1)}°C
+              </span>
+            </p>
+            <ResponsiveContainer width="100%" height={320}>
+              <LineChart data={chartData} margin={{ top: 10, right: 20, left: 0, bottom: 0 }}>
+                <CartesianGrid strokeDasharray="3 3" stroke="#e0dcd5" />
+                <XAxis
+                  dataKey="date"
+                  tick={{ fontSize: 11, fill: '#888' }}
+                  tickLine={false}
+                  axisLine={{ stroke: '#e0dcd5' }}
+                  interval={Math.max(0, Math.floor(chartData.length / 10) - 1)}
+                />
+                <YAxis
+                  tick={{ fontSize: 11, fill: '#888' }}
+                  tickLine={false}
+                  axisLine={{ stroke: '#e0dcd5' }}
+                  domain={['auto', 'auto']}
+                />
+                <Tooltip
+                  contentStyle={{
+                    backgroundColor: '#1a1a1a',
+                    border: 'none',
+                    borderRadius: 8,
+                    color: '#e0dcd5',
+                    fontFamily: 'DM Sans, system-ui, sans-serif',
+                    fontSize: '0.8rem',
+                  }}
+                  labelStyle={{ color: '#d4a019', fontWeight: 600 }}
+                  formatter={(value: number, name: string) => {
+                    const labels: Record<string, string> = { temp: 'Corrected Temp (°C)', gridTemp: 'Grid Temp (°C)', wbgt: 'WBGT (°C)', humidity: 'Humidity (%)' }
+                    return [typeof value === 'number' ? value.toFixed(1) : value, labels[name] ?? name]
+                  }}
+                />
+                <ReferenceLine y={35} stroke="#e63946" strokeDasharray="4 4" strokeOpacity={0.6} label={{ value: '35°C', fill: '#e63946', fontSize: 10 }} />
+                <ReferenceLine y={30} stroke="#d4a019" strokeDasharray="4 4" strokeOpacity={0.4} />
+                <Line
+                  type="monotone"
+                  dataKey="gridTemp"
+                  stroke="#888"
+                  strokeWidth={1.5}
+                  strokeDasharray="4 4"
+                  dot={false}
+                  activeDot={{ r: 3, stroke: '#888', strokeWidth: 2 }}
+                />
+                <Line
+                  type="monotone"
+                  dataKey="temp"
+                  stroke="#e63946"
+                  strokeWidth={2}
+                  dot={false}
+                  activeDot={{ r: 4, stroke: '#e63946', strokeWidth: 2 }}
+                />
+                <Line
+                  type="monotone"
+                  dataKey="wbgt"
+                  stroke="#1565C0"
+                  strokeWidth={1.5}
+                  strokeDasharray="4 4"
+                  dot={false}
+                  activeDot={{ r: 4, stroke: '#1565C0', strokeWidth: 2 }}
+                />
+              </LineChart>
+            </ResponsiveContainer>
+            <div className="mt-3 flex items-center gap-6 text-xs text-warm-muted font-sans">
+              <span className="flex items-center gap-1.5">
+                <span className="w-4 h-0.5 inline-block rounded" style={{ borderTop: '1.5px dashed #888', background: 'none' }} />
+                Grid Temp (°C)
+              </span>
+              <span className="flex items-center gap-1.5">
+                <span className="w-4 h-0.5 bg-[#e63946] inline-block rounded" />
+                UHI-Corrected Temp (°C)
+              </span>
+              <span className="flex items-center gap-1.5">
+                <span className="w-4 h-0.5 inline-block rounded" style={{ borderTop: '1.5px dashed #1565C0', background: 'none' }} />
+                WBGT (°C)
+              </span>
+              <span className="flex items-center gap-1.5">
+                <span className="w-4 h-0.5 inline-block rounded" style={{ borderTop: '1.5px dashed #e63946', background: 'none' }} />
+                35°C threshold
+              </span>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

frontend/src/pages/Notifications.tsx

@@ -0,0 +1,106 @@
+import MetricCard from '../components/MetricCard'
+import StatusBadge from '../components/StatusBadge'
+import { LoadingSpinner, ErrorState } from '../components/LoadingState'
+import { useNotifications } from '../lib/api'
+
+const LANG_LABELS: Record<string, string> = {
+  en: 'English',
+  sw: 'Swahili',
+}
+
+export default function Notifications() {
+  const notifications = useNotifications()
+
+  if (notifications.isLoading) return <LoadingSpinner />
+  if (notifications.isError) return <ErrorState onRetry={() => notifications.refetch()} />
+
+  const data = notifications.data?.notifications ?? []
+  const byLang = notifications.data?.by_language ?? {}
+  const sentCount = data.filter((n) => n.status === 'sent').length
+  const channels = [...new Set(data.map((n) => n.channel))]
+  const deliveryRate = data.length > 0 ? Math.round((sentCount / data.length) * 100) : 0
+  const languages = Object.keys(byLang)
+
+  return (
+    <div className="animate-slide-up">
+      {/* Title */}
+      <div data-tour="alerts-title" className="pt-2 pb-6">
+        <h1 className="page-title">Heat Alerts</h1>
+        <p className="page-caption">
+          Worker heat alerts sent via SMS and WhatsApp in English and Swahili
+        </p>
+      </div>
+
+      {/* Metrics */}
+      <div data-tour="alerts-metrics" className="mb-8">
+        <div className="grid grid-cols-2 md:grid-cols-4 gap-4 animate-stagger">
+          <MetricCard
+            label="Total Sent"
+            value={sentCount}
+            subtitle={`of ${data.length} total`}
+          />
+          <MetricCard
+            label="Languages"
+            value={languages.length}
+            subtitle={languages.map((l) => LANG_LABELS[l] ?? l).join(', ')}
+          />
+          <MetricCard
+            label="Channels"
+            value={channels.length}
+            subtitle={channels.join(', ')}
+          />
+          <MetricCard
+            label="Delivery Rate"
+            value={`${deliveryRate}%`}
+            subtitle="of notifications sent"
+          />
+        </div>
+      </div>
+
+      {/* Notification Feed */}
+      <div data-tour="alerts-feed">
+        <div className="section-header">Alert Feed</div>
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+          {data.map((n) => (
+            <div key={n.id} className="card card-body">
+              <div className="flex items-start justify-between mb-2">
+                <div>
+                  <h3 className="text-sm font-semibold font-sans text-[#1a1a1a] m-0">
+                    {n.zone_name}
+                  </h3>
+                  <p className="text-[10px] text-warm-muted m-0">{n.city}</p>
+                </div>
+                <div className="flex items-center gap-2">
+                  <StatusBadge status={n.trigger_level} />
+                  <span className="badge-blue">{LANG_LABELS[n.language] ?? n.language}</span>
+                </div>
+              </div>
+
+              <p className="text-xs text-warm-body leading-relaxed my-3 bg-warm-header-bg rounded-md p-3">
+                {n.message_preview}
+              </p>
+
+              <div className="flex items-center justify-between text-[10px] text-warm-muted">
+                <div className="flex items-center gap-3">
+                  <span className="uppercase tracking-wider font-semibold">
+                    {n.channel}
+                  </span>
+                  <span>{n.recipient_count.toLocaleString()} recipients</span>
+                </div>
+                <div className="flex items-center gap-2">
+                  <StatusBadge status={n.status} />
+                  <span>{new Date(n.delivered_at).toLocaleString()}</span>
+                </div>
+              </div>
+            </div>
+          ))}
+        </div>
+        {data.length === 0 && (
+          <div className="text-center py-12 text-warm-muted text-sm font-sans">
+            No heat alerts sent yet.
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/pages/Pipeline.tsx

@@ -0,0 +1,387 @@
+import { useState } from 'react'
+import { ChevronDown, ChevronRight } from 'lucide-react'
+import MetricCard from '../components/MetricCard'
+import StatusBadge from '../components/StatusBadge'
+import { LoadingSpinner, ErrorState } from '../components/LoadingState'
+import { usePipelineRuns, usePipelineStats } from '../lib/api'
+
+const STATUS_COLOR: Record<string, string> = {
+  ok: '#2a9d8f', success: '#2a9d8f', completed: '#2a9d8f',
+  partial: '#f4a261', running: '#1976D2',
+  failed: '#e63946', error: '#e63946',
+}
+
+const STEP_LABELS: Record<string, string> = {
+  ingest: 'Data Ingestion',
+  heal: 'Data Healing',
+  index: 'Heat Index Calculation',
+  calibrate: 'Trigger Calibration',
+  explain: 'Alert Generation',
+  notify: 'Worker Notification',
+}
+
+// ---------------------------------------------------------------------------
+// Architecture Diagram
+// ---------------------------------------------------------------------------
+
+const ARCH_STEPS = [
+  {
+    num: 1, name: 'Ingest', table: 'daily_readings', color: '#2E7D32',
+    desc: 'Fetch temperature and humidity from satellite sources',
+    options: [
+      { label: 'NASA POWER', note: 'T2M, T2M_MAX, RH2M — free, no auth', active: true },
+      { label: 'Custom Station Data', note: 'Your own weather stations or CSV files' },
+    ],
+  },
+  {
+    num: 2, name: 'Heal', table: 'healed_readings', color: '#1565C0',
+    desc: 'Validate and repair temperature anomalies',
+    options: [
+      { label: 'Claude AI Agent', note: '5 diagnostic tools, reasoning logged', active: true },
+      { label: 'Rule-Based', note: 'Zero-cost fallback, same output format' },
+    ],
+  },
+  {
+    num: 3, name: 'Index', table: 'heat_indices', color: '#7B1FA2',
+    desc: 'Calculate WBGT, Heat Index, consecutive day counts',
+    options: [
+      { label: 'WBGT (Liljegren)', note: 'Simplified outdoor wet bulb globe temperature', active: true },
+      { label: 'NWS Heat Index', note: 'Rothfusz regression, "feels like" temperature', active: true },
+      { label: 'Consecutive Days', note: 'Run-length above configurable threshold', active: true },
+    ],
+  },
+  {
+    num: 4, name: 'Calibrate', table: 'trigger_events', color: '#E65100',
+    desc: 'Detect trigger events and estimate basis risk',
+    options: [
+      { label: 'Composite Scoring', note: 'Temp 30% + WBGT 25% + Duration 20% + Vulnerability 15% + Exposure 10%', active: true },
+      { label: 'Basis Risk Model', note: 'Urban heat island, worker exposure simulation', active: true },
+    ],
+  },
+  {
+    num: 5, name: 'Explain', table: 'explanations', color: '#C62828',
+    desc: 'Generate plain-language heat alerts in English + Swahili',
+    options: [
+      { label: 'Claude + Knowledge Base', note: 'WHO/ILO heat guidance, zone-specific context', active: true },
+      { label: 'Template-Based', note: 'Zero-cost fallback with pre-written alerts' },
+    ],
+  },
+  {
+    num: 6, name: 'Notify', table: 'notifications', color: '#d4a019',
+    desc: 'Deliver alerts and payout notifications to enrolled workers',
+    options: [
+      { label: 'Console', note: 'Dry-run, always works', active: true },
+      { label: 'Twilio SMS', note: 'Live delivery to worker phones' },
+      { label: 'WhatsApp', note: 'Via Twilio Business API' },
+    ],
+  },
+]
+
+function ArchitectureDiagram() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '0', paddingLeft: '20px' }}>
+      {ARCH_STEPS.map((s, i) => (
+        <div key={s.num}>
+          <div style={{ display: 'flex', alignItems: 'flex-start', gap: '14px' }}>
+            <div style={{
+              width: '36px', height: '36px', borderRadius: '50%', background: s.color,
+              color: '#fff', display: 'flex', alignItems: 'center', justifyContent: 'center',
+              fontWeight: 700, fontSize: '0.85rem', flexShrink: 0, marginTop: '2px',
+            }}>
+              {s.num}
+            </div>
+            <div style={{
+              flex: 1, background: '#fff', border: '1px solid #e0dcd5', borderRadius: '8px',
+              padding: '14px 16px',
+            }}>
+              <div style={{ display: 'flex', alignItems: 'center', gap: '10px', flexWrap: 'wrap', marginBottom: '4px' }}>
+                <span style={{ fontWeight: 700, fontSize: '0.9rem', color: s.color }}>{s.name}</span>
+                <code style={{
+                  background: '#f0ede8', padding: '2px 8px', borderRadius: '4px',
+                  fontSize: '0.72rem', color: '#555',
+                }}>{s.table}</code>
+              </div>
+              <div style={{ fontSize: '0.8rem', color: '#666', marginBottom: '8px' }}>{s.desc}</div>
+              <div style={{ display: 'flex', flexWrap: 'wrap', gap: '6px' }}>
+                {s.options.map(opt => (
+                  <div key={opt.label} title={opt.note} style={{
+                    background: opt.active ? `${s.color}10` : '#faf8f5',
+                    border: `1px solid ${opt.active ? s.color + '40' : '#e0dcd5'}`,
+                    borderRadius: '6px', padding: '4px 10px',
+                    fontSize: '0.72rem', color: opt.active ? s.color : '#888',
+                    fontWeight: opt.active ? 600 : 400,
+                    cursor: 'default',
+                  }}>
+                    {opt.label}
+                    {opt.active && <span style={{ marginLeft: '4px', fontSize: '0.65rem' }}>{'\u2713'}</span>}
+                  </div>
+                ))}
+              </div>
+            </div>
+          </div>
+          {i < ARCH_STEPS.length - 1 && (
+            <div style={{
+              width: '2px', height: '14px', background: '#d4a019', marginLeft: '17px',
+            }} />
+          )}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Build Your Own Tab
+// ---------------------------------------------------------------------------
+
+function BuildYourOwnTab() {
+  return (
+    <div className="space-y-6">
+      <div className="card card-body">
+        <p style={{ fontSize: '0.9rem', color: '#555', lineHeight: 1.7, marginBottom: '16px' }}>
+          This pipeline is designed to be forked and adapted for any region. The architecture separates
+          globally portable components (NASA POWER ingestion, WBGT calculation, Claude healing, notification delivery)
+          from region-specific configuration (zone definitions, temperature thresholds, payout tiers, knowledge base).
+        </p>
+        <p style={{ fontSize: '0.85rem', color: '#888', lineHeight: 1.7 }}>
+          To adapt for a new region, you need to customize these files:
+        </p>
+      </div>
+
+      <div className="section-header">Region-Specific Files</div>
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+        {[
+          { file: 'config.py', desc: 'Zone definitions: GPS coordinates, worker populations, heat vulnerability, payout tiers' },
+          { file: 'src/healing/healer.py', desc: 'Historical temperature norms for your cities (monthly averages, standard deviations)' },
+          { file: 'src/explanation/knowledge_base.py', desc: 'Local heat safety guidance, emergency contacts, zone-specific context, language translations' },
+          { file: 'src/calibration/basis_risk.py', desc: 'Urban heat island estimates, worker exposure patterns for your settlement types' },
+        ].map(item => (
+          <div key={item.file} style={{
+            background: '#fff', border: '1px solid #e0dcd5', borderRadius: '8px',
+            padding: '14px 16px',
+          }}>
+            <code style={{
+              background: '#f0ede8', padding: '2px 8px', borderRadius: '4px',
+              fontSize: '0.78rem', color: '#555', display: 'inline-block', marginBottom: '6px',
+            }}>{item.file}</code>
+            <p style={{ fontSize: '0.82rem', color: '#666', lineHeight: 1.5, margin: 0 }}>{item.desc}</p>
+          </div>
+        ))}
+      </div>
+
+      <div className="section-header">Globally Portable (No Changes Needed)</div>
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
+        {[
+          { file: 'src/ingestion/nasa_power.py', desc: 'Works anywhere on earth — just provide lat/lon coordinates' },
+          { file: 'src/indexing/heat_index.py', desc: 'WBGT and Heat Index calculations are physics-based, universally applicable' },
+          { file: 'src/indexing/heat_risk.py', desc: 'Composite scoring with parameterizable thresholds — configure via config.py' },
+          { file: 'src/notification/sender.py', desc: 'Console, SMS, or WhatsApp — plug in Twilio credentials' },
+        ].map(item => (
+          <div key={item.file} style={{
+            background: '#fff', border: '1px solid #e0dcd5', borderRadius: '8px',
+            padding: '14px 16px',
+          }}>
+            <code style={{
+              background: '#f0ede8', padding: '2px 8px', borderRadius: '4px',
+              fontSize: '0.78rem', color: '#2a9d8f', display: 'inline-block', marginBottom: '6px',
+            }}>{item.file}</code>
+            <p style={{ fontSize: '0.82rem', color: '#666', lineHeight: 1.5, margin: 0 }}>{item.desc}</p>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Main Component
+// ---------------------------------------------------------------------------
+
+export default function Pipeline() {
+  const runs = usePipelineRuns()
+  const stats = usePipelineStats()
+  const [activeTab, setActiveTab] = useState<'architecture' | 'runs' | 'build'>('architecture')
+  const [expandedRun, setExpandedRun] = useState<string | null>(null)
+
+  if (runs.isLoading || stats.isLoading) return <LoadingSpinner />
+  if (runs.isError) return <ErrorState onRetry={() => runs.refetch()} />
+  if (stats.isError) return <ErrorState onRetry={() => stats.refetch()} />
+
+  const runsData = runs.data?.runs ?? []
+  const s = stats.data
+
+  const TABS = ['Architecture', 'Pipeline Runs', 'Build Your Own']
+
+  return (
+    <div data-tour="pipeline-title" className="animate-slide-up">
+      <div className="pt-2 pb-6">
+        <h1 className="page-title">Pipeline</h1>
+        <p className="page-caption">
+          6-step automated pipeline: ingest, heal, index, calibrate, explain, notify
+        </p>
+      </div>
+
+      {/* Stats */}
+      <div className="mb-8">
+        <div className="grid grid-cols-2 md:grid-cols-4 gap-4 animate-stagger">
+          <MetricCard
+            label="Total Runs"
+            value={s?.total_runs}
+            subtitle={`${s?.successful_runs} successful`}
+          />
+          <MetricCard
+            label="Success Rate"
+            value={`${Math.round((s?.success_rate ?? 0) * 100)}%`}
+            subtitle="pipeline completions"
+          />
+          <MetricCard
+            label="Total Cost"
+            value={`$${s?.total_cost_usd?.toFixed(2)}`}
+            subtitle={`$${s?.avg_cost_per_run_usd?.toFixed(4)} avg/run`}
+          />
+          <MetricCard
+            label="Data Sources"
+            value={s?.data_sources?.length}
+            subtitle={s?.data_sources?.join(', ')}
+          />
+        </div>
+      </div>
+
+      {/* Tabs */}
+      <div className="tab-list mb-6">
+        {TABS.map((tab, i) => (
+          <button
+            key={tab}
+            className={`tab-item ${activeTab === (['architecture', 'runs', 'build'] as const)[i] ? 'active' : ''}`}
+            onClick={() => setActiveTab((['architecture', 'runs', 'build'] as const)[i])}
+          >
+            {tab}
+          </button>
+        ))}
+      </div>
+
+      {/* Architecture Tab */}
+      {activeTab === 'architecture' && (
+        <div className="animate-tab-enter">
+          <ArchitectureDiagram />
+        </div>
+      )}
+
+      {/* Pipeline Runs Tab */}
+      {activeTab === 'runs' && (
+        <div className="animate-tab-enter space-y-6">
+          {/* Cost Summary */}
+          <div className="card card-body">
+            <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+              <div>
+                <p className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider mb-1">
+                  Total Pipeline Cost
+                </p>
+                <p className="text-lg font-serif font-bold text-[#1a1a1a]">
+                  ${s?.total_cost_usd?.toFixed(2)}
+                </p>
+              </div>
+              <div>
+                <p className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider mb-1">
+                  Average per Run
+                </p>
+                <p className="text-lg font-serif font-bold text-[#1a1a1a]">
+                  ${s?.avg_cost_per_run_usd?.toFixed(4)}
+                </p>
+              </div>
+              <div>
+                <p className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider mb-1">
+                  Last Run
+                </p>
+                <p className="text-lg font-serif font-bold text-[#1a1a1a]">
+                  {s?.last_run ? new Date(s.last_run).toLocaleDateString() : '--'}
+                </p>
+              </div>
+            </div>
+          </div>
+
+          {/* Run History */}
+          <div className="section-header">Run History</div>
+          <div className="table-container">
+            <table>
+              <thead>
+                <tr>
+                  <th className="w-8"></th>
+                  <th>Run ID</th>
+                  <th>Date</th>
+                  <th>Status</th>
+                  <th>Duration</th>
+                  <th>Zones</th>
+                  <th>Triggers</th>
+                  <th>Notifications</th>
+                  <th>Cost (USD)</th>
+                </tr>
+              </thead>
+              {runsData.map((run) => (
+                <tbody key={run.run_id}>
+                  <tr
+                    className="cursor-pointer"
+                    onClick={() => setExpandedRun(expandedRun === run.run_id ? null : run.run_id)}
+                  >
+                    <td>
+                      {expandedRun === run.run_id ? (
+                        <ChevronDown size={14} className="text-warm-muted" />
+                      ) : (
+                        <ChevronRight size={14} className="text-warm-muted" />
+                      )}
+                    </td>
+                    <td className="font-mono text-xs">{run.run_id}</td>
+                    <td>{new Date(run.started_at).toLocaleDateString()}</td>
+                    <td><StatusBadge status={run.status} /></td>
+                    <td>{run.duration_s.toFixed(0)}s</td>
+                    <td>{run.zones_processed}</td>
+                    <td>{run.triggers_found}</td>
+                    <td>{run.notifications_sent}</td>
+                    <td>${run.total_cost_usd.toFixed(4)}</td>
+                  </tr>
+                  {expandedRun === run.run_id && (
+                    <tr>
+                      <td colSpan={9} className="bg-warm-header-bg !py-0 !px-0">
+                        <div className="px-6 py-4">
+                          <p className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider mb-3">
+                            Pipeline Steps
+                          </p>
+                          <div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-6 gap-3">
+                            {run.steps.map((step, i) => (
+                              <div
+                                key={step.step}
+                                className="bg-white rounded-lg border border-warm-border p-3 text-center"
+                              >
+                                <div className="text-[10px] text-warm-muted uppercase tracking-wider font-semibold mb-1">
+                                  Step {i + 1}
+                                </div>
+                                <div className="text-xs font-medium text-[#1a1a1a] mb-1">
+                                  {STEP_LABELS[step.step] ?? step.step}
+                                </div>
+                                <StatusBadge status={step.status} />
+                                <div className="text-[10px] text-warm-muted mt-1">
+                                  {step.duration_s.toFixed(1)}s
+                                </div>
+                              </div>
+                            ))}
+                          </div>
+                        </div>
+                      </td>
+                    </tr>
+                  )}
+                </tbody>
+              ))}
+            </table>
+          </div>
+        </div>
+      )}
+
+      {/* Build Your Own Tab */}
+      {activeTab === 'build' && (
+        <div className="animate-tab-enter">
+          <BuildYourOwnTab />
+        </div>
+      )}
+    </div>
+  )
+}

frontend/src/pages/ProgramDesigner.tsx

@@ -0,0 +1,296 @@
+import { useState, useEffect, useRef } from 'react'
+import MetricCard from '../components/MetricCard'
+import { LoadingSpinner, ErrorState } from '../components/LoadingState'
+import { useCalibrateQuery } from '../lib/api'
+import type { CalibrateParams } from '../lib/api'
+
+function formatUsd(n: number | undefined): string {
+  if (n == null) return '--'
+  return '$' + n.toLocaleString(undefined, { maximumFractionDigits: 0 })
+}
+
+function rankColor(rank: number): string {
+  if (rank <= 5) return '#2a9d8f'
+  if (rank <= 10) return '#d4a019'
+  return '#888'
+}
+
+export default function ProgramDesigner() {
+  const [params, setParams] = useState<CalibrateParams>({
+    temp_threshold: 35,
+    consecutive_days: 2,
+    wbgt_threshold: 30,
+    payout_usd: 10,
+    budget_usd: 500000,
+    worker_contribution_usd: 0,
+  })
+
+  // Debounced params for API calls
+  const [debouncedParams, setDebouncedParams] = useState<CalibrateParams>(params)
+  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(() => {
+    if (debounceTimer.current) clearTimeout(debounceTimer.current)
+    debounceTimer.current = setTimeout(() => {
+      setDebouncedParams(params)
+    }, 300)
+    return () => {
+      if (debounceTimer.current) clearTimeout(debounceTimer.current)
+    }
+  }, [params])
+
+  const calibrate = useCalibrateQuery(debouncedParams)
+
+  const updateParam = <K extends keyof CalibrateParams>(key: K, value: CalibrateParams[K]) => {
+    setParams((prev) => ({ ...prev, [key]: value }))
+  }
+
+  const summary = calibrate.data?.summary
+  const allocation = calibrate.data?.allocation
+  const zones = calibrate.data?.zones ?? []
+  const sortedZones = [...zones].sort((a, b) => (a.priority_rank ?? 99) - (b.priority_rank ?? 99))
+
+  return (
+    <div className="animate-slide-up">
+      {/* Title */}
+      <div className="pt-2 pb-6">
+        <h1 className="page-title">Program Design</h1>
+        <p className="page-caption">
+          Set budget, payout, and thresholds. The model prices each zone actuarially and allocates budget by priority.
+        </p>
+      </div>
+
+      {/* Controls */}
+      <div data-tour="program-controls" className="card card-body mb-6">
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-5 gap-6">
+          {/* Budget */}
+          <div>
+            <div className="flex items-center justify-between mb-1.5">
+              <label className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider">
+                Total Budget
+              </label>
+              <span className="font-mono font-semibold text-sm text-[#1a1a1a]">
+                {formatUsd(params.budget_usd)}
+              </span>
+            </div>
+            <input
+              type="range"
+              min={100000}
+              max={5000000}
+              step={50000}
+              value={params.budget_usd}
+              onChange={(e) => updateParam('budget_usd', Number(e.target.value))}
+              className="w-full h-1.5 bg-warm-border rounded-lg appearance-none cursor-pointer accent-gold"
+            />
+            <div className="flex justify-between text-[10px] text-warm-muted mt-1">
+              <span>$100K</span>
+              <span>$5M</span>
+            </div>
+          </div>
+
+          {/* Payout per event */}
+          <div>
+            <div className="flex items-center justify-between mb-1.5">
+              <label className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider">
+                Payout / Event
+              </label>
+              <span className="font-mono font-semibold text-sm text-[#1a1a1a]">
+                ${params.payout_usd}
+              </span>
+            </div>
+            <input
+              type="range"
+              min={1}
+              max={50}
+              step={1}
+              value={params.payout_usd}
+              onChange={(e) => updateParam('payout_usd', Number(e.target.value))}
+              className="w-full h-1.5 bg-warm-border rounded-lg appearance-none cursor-pointer accent-gold"
+            />
+            <div className="flex justify-between text-[10px] text-warm-muted mt-1">
+              <span>$1</span>
+              <span>$50</span>
+            </div>
+          </div>
+
+          {/* Worker contribution */}
+          <div>
+            <div className="flex items-center justify-between mb-1.5">
+              <label className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider">
+                Worker Contrib.
+              </label>
+              <span className="font-mono font-semibold text-sm text-[#1a1a1a]">
+                ${params.worker_contribution_usd}
+              </span>
+            </div>
+            <input
+              type="range"
+              min={0}
+              max={20}
+              step={1}
+              value={params.worker_contribution_usd}
+              onChange={(e) => updateParam('worker_contribution_usd', Number(e.target.value))}
+              className="w-full h-1.5 bg-warm-border rounded-lg appearance-none cursor-pointer accent-gold"
+            />
+            <div className="flex justify-between text-[10px] text-warm-muted mt-1">
+              <span>$0</span>
+              <span>$20</span>
+            </div>
+          </div>
+
+          {/* Temperature threshold */}
+          <div>
+            <div className="flex items-center justify-between mb-1.5">
+              <label className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider">
+                Temp Threshold
+              </label>
+              <span className="font-mono font-semibold text-sm text-[#1a1a1a]">
+                {params.temp_threshold}°C
+              </span>
+            </div>
+            <input
+              type="range"
+              min={30}
+              max={45}
+              step={1}
+              value={params.temp_threshold}
+              onChange={(e) => updateParam('temp_threshold', Number(e.target.value))}
+              className="w-full h-1.5 bg-warm-border rounded-lg appearance-none cursor-pointer accent-gold"
+            />
+            <div className="flex justify-between text-[10px] text-warm-muted mt-1">
+              <span>30°C</span>
+              <span>45°C</span>
+            </div>
+          </div>
+
+          {/* Consecutive days */}
+          <div>
+            <div className="flex items-center justify-between mb-1.5">
+              <label className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider">
+                Consec. Days
+              </label>
+              <span className="font-mono font-semibold text-sm text-[#1a1a1a]">
+                {params.consecutive_days}
+              </span>
+            </div>
+            <input
+              type="range"
+              min={1}
+              max={7}
+              step={1}
+              value={params.consecutive_days}
+              onChange={(e) => updateParam('consecutive_days', Number(e.target.value))}
+              className="w-full h-1.5 bg-warm-border rounded-lg appearance-none cursor-pointer accent-gold"
+            />
+            <div className="flex justify-between text-[10px] text-warm-muted mt-1">
+              <span>1 day</span>
+              <span>7 days</span>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Results */}
+      <div data-tour="program-results">
+        {calibrate.isLoading ? (
+          <LoadingSpinner message="Running actuarial model..." />
+        ) : calibrate.isError ? (
+          <ErrorState onRetry={() => calibrate.refetch()} />
+        ) : (
+          <>
+            {/* Allocation Summary */}
+            <div className="grid grid-cols-2 md:grid-cols-4 gap-4 mb-6 animate-stagger">
+              <MetricCard
+                label="Workers Covered"
+                value={allocation?.workers_covered?.toLocaleString() ?? '--'}
+                subtitle={`of ${summary?.total_enrolled?.toLocaleString() ?? '--'} enrolled`}
+              />
+              <MetricCard
+                label="Coverage"
+                value={`${allocation?.overall_coverage_pct?.toFixed(1) ?? '--'}%`}
+                subtitle="of enrolled workers"
+              />
+              <MetricCard
+                label="Zones Funded"
+                value={`${(allocation?.zones_fully_funded ?? 0) + (allocation?.zones_partially_funded ?? 0)}`}
+                subtitle={`${allocation?.zones_fully_funded ?? 0} full + ${allocation?.zones_partially_funded ?? 0} partial`}
+              />
+              <MetricCard
+                label="Avg Cost / Worker"
+                value={`$${summary?.avg_cost_per_worker?.toFixed(2) ?? '--'}`}
+                subtitle="annual actuarial"
+              />
+            </div>
+
+            {/* Zone Allocation Table */}
+            <div className="table-container">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Rank</th>
+                    <th>Zone</th>
+                    <th>City</th>
+                    <th>Actuarial Cost/Worker</th>
+                    <th>Allocated Budget</th>
+                    <th>Workers Covered</th>
+                    <th>Coverage %</th>
+                    <th>Events/Year</th>
+                    <th>Basis Risk</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {sortedZones.map((z) => {
+                    const unfunded = (z.allocated_budget ?? 0) === 0
+                    return (
+                      <tr key={z.zone_id} style={unfunded ? { opacity: 0.45 } : undefined}>
+                        <td>
+                          <span
+                            className="inline-flex items-center justify-center w-6 h-6 rounded-full text-[11px] font-mono font-bold text-white"
+                            style={{ backgroundColor: rankColor(z.priority_rank ?? 99) }}
+                          >
+                            {z.priority_rank ?? '--'}
+                          </span>
+                        </td>
+                        <td className="font-medium text-[#1a1a1a]">{z.zone_name}</td>
+                        <td>{z.city}</td>
+                        <td className="font-mono text-sm">${z.actuarial_cost_per_worker?.toFixed(2) ?? '--'}</td>
+                        <td className="font-mono text-sm font-semibold">{formatUsd(z.allocated_budget)}</td>
+                        <td className="font-mono text-sm">{z.workers_covered?.toLocaleString() ?? '0'}</td>
+                        <td>
+                          <span
+                            className="font-mono font-semibold text-sm"
+                            style={{
+                              color: (z.coverage_pct ?? 0) >= 80 ? '#2a9d8f' : (z.coverage_pct ?? 0) >= 40 ? '#d4a019' : '#e63946',
+                            }}
+                          >
+                            {z.coverage_pct?.toFixed(1) ?? '0'}%
+                          </span>
+                        </td>
+                        <td className="font-mono text-sm">{z.events_per_year?.toFixed(1)}</td>
+                        <td>
+                          <span
+                            className="font-mono font-semibold text-sm"
+                            style={{
+                              color: z.basis_risk_score > 0.3 ? '#e63946' : z.basis_risk_score > 0.2 ? '#e67e22' : '#2a9d8f',
+                            }}
+                          >
+                            {z.basis_risk_score?.toFixed(3)}
+                          </span>
+                        </td>
+                      </tr>
+                    )
+                  })}
+                </tbody>
+              </table>
+            </div>
+            {sortedZones.length === 0 && (
+              <div className="text-center py-12 text-warm-muted text-sm font-sans">
+                No zones triggered at current thresholds. Try lowering the temperature threshold.
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  )
+}

frontend/src/pages/Zones.tsx

@@ -0,0 +1,244 @@
+import { useState } from 'react'
+import MetricCard from '../components/MetricCard'
+import StatusBadge from '../components/StatusBadge'
+import { LoadingSpinner, ErrorState } from '../components/LoadingState'
+import { useZones, useEnrolled } from '../lib/api'
+
+function tempColor(temp: number): string {
+  if (temp > 37) return '#e63946'
+  if (temp > 35) return '#d35400'
+  if (temp > 33) return '#e67e22'
+  if (temp > 30) return '#d4a019'
+  return '#2a9d8f'
+}
+
+function wbgtColor(wbgt: number): string {
+  if (wbgt > 32) return '#e63946'
+  if (wbgt > 30) return '#e67e22'
+  if (wbgt > 28) return '#d4a019'
+  return '#2a9d8f'
+}
+
+export default function Zones() {
+  const zones = useZones()
+  const enrolled = useEnrolled()
+  const [cityFilter, setCityFilter] = useState<string>('all')
+  const [activeTab, setActiveTab] = useState<'zones' | 'exposure'>('zones')
+
+  if (zones.isLoading) return <LoadingSpinner />
+  if (zones.isError) return <ErrorState onRetry={() => zones.refetch()} />
+
+  const cities = zones.data?.cities ?? []
+  const allZones = zones.data?.zones ?? []
+  const filtered = cityFilter === 'all' ? allZones : allZones.filter((z) => z.city === cityFilter)
+  const totalWorkers = allZones.reduce((sum, z) => sum + z.worker_population_est, 0)
+
+  const enrolledByZone = enrolled.data?.by_zone ?? []
+
+  return (
+    <div className="animate-slide-up">
+      {/* Title */}
+      <div data-tour="zones-title" className="pt-2 pb-6">
+        <h1 className="page-title">Zones</h1>
+        <p className="page-caption">
+          20 heat-vulnerable urban zones across East African cities
+        </p>
+      </div>
+
+      {/* Metrics */}
+      <div data-tour="zones-metrics" className="mb-8">
+        <div className="grid grid-cols-2 md:grid-cols-4 gap-4 animate-stagger">
+          <MetricCard
+            label="Zones Monitored"
+            value={allZones.length}
+            subtitle={`${cities.length} cities`}
+          />
+          <MetricCard
+            label="Total Workers"
+            value={totalWorkers.toLocaleString()}
+            subtitle="estimated outdoor workers"
+          />
+          <MetricCard
+            label="High Vulnerability"
+            value={allZones.filter((z) => z.heat_vulnerability === 'high' || z.heat_vulnerability === 'critical').length}
+            subtitle="zones at elevated risk"
+          />
+          <MetricCard
+            label="Workers Enrolled"
+            value={enrolled.data?.total_enrolled?.toLocaleString() ?? '--'}
+            subtitle="across all zones"
+          />
+        </div>
+      </div>
+
+      {/* Tabs */}
+      <div className="mb-6">
+        <div className="tab-list">
+          <button
+            className={`tab-item ${activeTab === 'zones' ? 'active' : ''}`}
+            onClick={() => setActiveTab('zones')}
+          >
+            Zone Overview
+          </button>
+          <button
+            className={`tab-item ${activeTab === 'exposure' ? 'active' : ''}`}
+            onClick={() => setActiveTab('exposure')}
+          >
+            Worker Exposure
+          </button>
+        </div>
+      </div>
+
+      {activeTab === 'zones' && (
+        <div className="animate-tab-enter">
+          {/* City filter */}
+          <div className="mb-4 flex items-center gap-3">
+            <label className="text-xs text-warm-muted font-sans font-medium uppercase tracking-wider">
+              Filter by city
+            </label>
+            <select
+              value={cityFilter}
+              onChange={(e) => setCityFilter(e.target.value)}
+              className="input max-w-xs text-sm"
+            >
+              <option value="all">All Cities ({allZones.length})</option>
+              {cities.map((c) => (
+                <option key={c} value={c}>
+                  {c} ({allZones.filter((z) => z.city === c).length})
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {/* Zone table */}
+          <div className="table-container">
+            <table>
+              <thead>
+                <tr>
+                  <th>Zone</th>
+                  <th>City</th>
+                  <th>Settlement</th>
+                  <th>Heat Vulnerability</th>
+                  <th>Workers</th>
+                  <th>Grid Temp</th>
+                  <th>UHI</th>
+                  <th>Corrected</th>
+                  <th>WBGT (°C)</th>
+                  <th>7d Trigger</th>
+                  <th>Risk Level</th>
+                </tr>
+              </thead>
+              <tbody>
+                {filtered.map((z) => (
+                  <tr key={z.zone_id}>
+                    <td className="font-medium text-[#1a1a1a]">{z.name}</td>
+                    <td>{z.city}</td>
+                    <td className="capitalize">{z.settlement_type}</td>
+                    <td><StatusBadge status={z.heat_vulnerability} /></td>
+                    <td>{z.worker_population_est.toLocaleString()}</td>
+                    <td>
+                      <span className="font-mono text-sm text-warm-muted">
+                        {z.grid_temp_c?.toFixed(1)}°C
+                      </span>
+                    </td>
+                    <td>
+                      <span
+                        className="font-mono font-semibold text-sm"
+                        style={{ color: (z.uhi_delta_c ?? 0) > 4 ? '#e63946' : (z.uhi_delta_c ?? 0) > 2 ? '#e67e22' : '#d4a019' }}
+                      >
+                        +{z.uhi_delta_c?.toFixed(1)}°C
+                      </span>
+                    </td>
+                    <td>
+                      <span
+                        className="font-mono font-semibold text-sm"
+                        style={{ color: tempColor(z.corrected_temp_c ?? 0) }}
+                      >
+                        {z.corrected_temp_c?.toFixed(1)}°C
+                      </span>
+                    </td>
+                    <td>
+                      <span
+                        className="font-mono font-semibold text-sm"
+                        style={{ color: wbgtColor(z.current_wbgt_c) }}
+                      >
+                        {z.current_wbgt_c.toFixed(1)}
+                      </span>
+                    </td>
+                    <td>
+                      {(() => {
+                        const pct = (z.trigger_probability_7d ?? 0) * 100
+                        const color = pct > 70 ? '#e63946' : pct > 50 ? '#e67e22' : pct > 20 ? '#d4a019' : '#2a9d8f'
+                        return (
+                          <div className="flex items-center gap-2">
+                            <div className="w-16 h-2 rounded-full bg-warm-border overflow-hidden">
+                              <div className="h-full rounded-full" style={{ width: `${pct}%`, backgroundColor: color }} />
+                            </div>
+                            <span className="font-mono font-semibold text-sm" style={{ color }}>
+                              {pct?.toFixed(0)}%
+                            </span>
+                          </div>
+                        )
+                      })()}
+                    </td>
+                    <td><StatusBadge status={z.risk_level} /></td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </div>
+      )}
+
+      {activeTab === 'exposure' && (
+        <div className="animate-tab-enter">
+          {enrolled.isLoading ? (
+            <LoadingSpinner message="Loading enrollment data..." />
+          ) : enrolled.isError ? (
+            <ErrorState onRetry={() => enrolled.refetch()} />
+          ) : (
+            <div className="table-container">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Zone</th>
+                    <th>City</th>
+                    <th>Worker Population</th>
+                    <th>Outdoor Exposure</th>
+                    <th>Heat Vulnerability</th>
+                    <th>Enrolled Workers</th>
+                    <th>Enrollment Rate</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {allZones.map((z) => {
+                    const enrolledZone = enrolledByZone.find((e) => e.zone_id === z.zone_id)
+                    const enrolledCount = enrolledZone?.enrolled ?? 0
+                    const enrollmentRate = z.worker_population_est > 0
+                      ? Math.round((enrolledCount / z.worker_population_est) * 100)
+                      : 0
+                    return (
+                      <tr key={z.zone_id}>
+                        <td className="font-medium text-[#1a1a1a]">{z.name}</td>
+                        <td>{z.city}</td>
+                        <td>{z.worker_population_est.toLocaleString()}</td>
+                        <td>{z.outdoor_exposure_pct}%</td>
+                        <td><StatusBadge status={z.heat_vulnerability} /></td>
+                        <td>{enrolledCount.toLocaleString()}</td>
+                        <td>
+                          <span className={`font-mono text-sm font-semibold ${enrollmentRate < 20 ? 'text-[#e63946]' : enrollmentRate < 50 ? 'text-[#e67e22]' : 'text-[#2a9d8f]'}`}>
+                            {enrollmentRate}%
+                          </span>
+                        </td>
+                      </tr>
+                    )
+                  })}
+                </tbody>
+              </table>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

frontend/src/vite-env.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

frontend/tailwind.config.js

@@ -0,0 +1,50 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        cream: '#faf8f5',
+        gold: {
+          DEFAULT: '#d4a019',
+          hover: '#b8880f',
+          light: '#f0d97a',
+          dark: '#a67c10',
+        },
+        warm: {
+          border: '#e0dcd5',
+          muted: '#888888',
+          'muted-light': '#999999',
+          body: '#555555',
+          'body-light': '#666666',
+          'header-bg': '#f5f3ef',
+        },
+        sidebar: {
+          DEFAULT: '#1a1a1a',
+          end: '#222018',
+          hover: '#2a2a3e',
+        },
+        success: '#2a9d8f',
+        warning: '#d4a019',
+        error: '#e63946',
+        info: '#1565C0',
+      },
+      fontFamily: {
+        serif: ['"Source Serif 4"', 'Georgia', 'serif'],
+        sans: ['"DM Sans"', 'system-ui', '-apple-system', 'BlinkMacSystemFont', 'Segoe UI', 'Roboto', 'sans-serif'],
+      },
+      borderRadius: {
+        DEFAULT: '10px',
+      },
+      letterSpacing: {
+        'section': '1.5px',
+        'label': '1.2px',
+        'btn': '0.5px',
+      },
+    },
+  },
+  plugins: [],
+}

frontend/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true
+  },
+  "include": ["src"]
+}

frontend/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/App.tsx","./src/main.tsx","./src/vite-env.d.ts","./src/components/Layout.tsx","./src/components/LoadingState.tsx","./src/components/MetricCard.tsx","./src/components/Sidebar.tsx","./src/components/StatusBadge.tsx","./src/lib/api.ts","./src/lib/tour.ts","./src/pages/Dashboard.tsx","./src/pages/HeatMonitor.tsx","./src/pages/Notifications.tsx","./src/pages/Pipeline.tsx","./src/pages/ProgramDesigner.tsx","./src/pages/Zones.tsx"],"version":"5.6.3"}

frontend/vercel.json

@@ -0,0 +1,8 @@
+{
+  "buildCommand": "npm run build",
+  "outputDirectory": "dist",
+  "framework": "vite",
+  "rewrites": [
+    { "source": "/((?!api/).*)", "destination": "/index.html" }
+  ]
+}

frontend/vite.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:7860',
+        changeOrigin: true,
+      },
+      '/health': {
+        target: 'http://localhost:7860',
+        changeOrigin: true,
+      },
+    },
+  },
+})

requirements.txt

@@ -0,0 +1,9 @@
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+httpx>=0.27.0
+anthropic>=0.40.0
+scipy>=1.12.0
+numpy>=1.26.0
+xgboost>=2.0.0
+asyncpg>=0.30.0
+aiofiles>=24.1.0

run_pipeline.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""
+Climate Risk Index Engine — CLI Runner
+
+Usage:
+    python run_pipeline.py                      # Full pipeline, console delivery
+    python run_pipeline.py --days 30            # Last 30 days only
+    python run_pipeline.py --no-claude          # Rule-based healing, template explanations
+    python run_pipeline.py --channel sms        # SMS delivery via Twilio
+"""
+
+import argparse
+import asyncio
+import logging
+import json
+import sys
+from datetime import datetime
+
+from src.pipeline import FloodRiskPipeline
+from src.store import store
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    datefmt="%H:%M:%S",
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Climate Risk Index Engine")
+    parser.add_argument("--days", type=int, default=90, help="Days of data to fetch (default: 90)")
+    parser.add_argument("--no-claude", action="store_true", help="Use rule-based healing and template explanations")
+    parser.add_argument("--channel", default="console", choices=["console", "sms", "whatsapp"], help="Delivery channel")
+    parser.add_argument("--json", action="store_true", help="Output results as JSON")
+    args = parser.parse_args()
+
+    pipeline = FloodRiskPipeline(
+        days_back=args.days,
+        use_claude_healer=not args.no_claude,
+        use_claude_explainer=not args.no_claude,
+        delivery_channel=args.channel,
+    )
+
+    result = asyncio.run(pipeline.run())
+
+    # Populate the shared store so the API can serve real data
+    store.update_from_pipeline(pipeline, run_result=result)
+
+    if args.json:
+        print(json.dumps({
+            "run_id": result.run_id,
+            "status": result.status,
+            "started_at": result.started_at,
+            "ended_at": result.ended_at,
+            "duration_s": result.duration_s,
+            "zones_processed": result.zones_processed,
+            "triggers_found": result.triggers_found,
+            "notifications_sent": result.notifications_sent,
+            "total_cost_usd": result.total_cost_usd,
+            "steps": [
+                {
+                    "step": s.step,
+                    "status": s.status,
+                    "duration_s": round(s.duration_s, 2),
+                    "records": s.records_processed,
+                    "errors": s.errors,
+                }
+                for s in result.steps
+            ],
+        }, indent=2))
+    else:
+        print(f"\n{'='*60}")
+        print(f"Pipeline Run: {result.run_id}")
+        print(f"Status: {result.status.upper()}")
+        print(f"Duration: {result.duration_s:.1f}s")
+        print(f"Zones: {result.zones_processed}")
+        print(f"Triggers: {result.triggers_found}")
+        print(f"Notifications: {result.notifications_sent}")
+        print(f"Cost: ${result.total_cost_usd:.4f}")
+        print(f"{'='*60}")
+        for s in result.steps:
+            icon = "✓" if s.status == "ok" else "⚠" if s.status == "partial" else "○" if s.status == "skipped" else "✗"
+            print(f"  {icon} {s.step:<12} {s.status:<8} {s.duration_s:>6.1f}s  ({s.records_processed} records)")
+            if s.errors:
+                for e in s.errors[:3]:
+                    print(f"    └─ {e[:80]}")
+        print()
+
+
+if __name__ == "__main__":
+    main()

src/api.py

@@ -0,0 +1,591 @@
+"""
+Extreme Heat Risk Engine — FastAPI Application
+
+Serves synthetic demo data for the dashboard.
+When the real pipeline has been run, serves pipeline results instead.
+"""
+
+import logging
+import random
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+
+from config import ZONES, ZONE_MAP, CITIES, HEAT_THRESHOLDS, PAYOUT_PER_EVENT_USD
+from src.indexing.heat_index import calculate_wbgt, calculate_heat_index, count_consecutive_days, count_trigger_days
+from src.downscaling.uhi_model import UHICorrector
+from src.prediction.heat_forecast import HeatWavePredictor
+from src.pricing.actuarial import ActuarialPricer
+from src.pricing.budget_optimizer import BudgetOptimizer
+
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="Extreme Heat Risk Engine", version="1.0.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+SEED = 42
+
+
+def _generate_demo_data():
+    """Deterministic synthetic data for the dashboard demo, using real ML models."""
+    rng = random.Random(SEED)
+    now = datetime(2026, 3, 29, 10, 0, 0)
+
+    # Initialize ML models
+    uhi_corrector = UHICorrector()
+    predictor = HeatWavePredictor()
+    pricer = ActuarialPricer()
+
+    # City base temperatures (ERA5-Land grid-level — before UHI correction)
+    city_climate = {
+        "Dar es Salaam": {"base_temp": 31, "temp_var": 2.5, "base_hum": 78, "hum_var": 8},
+        "Kampala": {"base_temp": 28, "temp_var": 2.5, "base_hum": 68, "hum_var": 10},
+        "Nairobi": {"base_temp": 25, "temp_var": 2.5, "base_hum": 55, "hum_var": 12},
+        "Kigali": {"base_temp": 25, "temp_var": 2, "base_hum": 60, "hum_var": 10},
+    }
+
+    # Generate 90 days of daily data per zone
+    zones = []
+    indices = []
+    all_triggers = []
+    tid = 1
+
+    for z in ZONES:
+        clim = city_climate[z.city]
+
+        daily_grid_temps = []
+        daily_temps = []
+        daily_humidity = []
+        daily_dates = []
+        daily_wbgt = []
+        daily_hi = []
+        daily_uhi_deltas = []
+
+        for d in range(90):
+            date = now - timedelta(days=89 - d)
+            month = date.month
+            seasonal = 1.5 if month in z.hot_months else -0.5
+            # Grid-level temperature (ERA5-Land equivalent — before UHI)
+            grid_temp = clim["base_temp"] + seasonal + rng.gauss(0, clim["temp_var"] * 0.4)
+            grid_temp = round(max(18, min(42, grid_temp)), 1)
+            hum = clim["base_hum"] + rng.gauss(0, clim["hum_var"] * 0.3)
+            hum = round(max(30, min(95, hum)), 1)
+            # ML UHI correction
+            corrected, uhi_delta, _ = uhi_corrector.correct_temperature(z, grid_temp, hour=14, month=month)
+            temp = round(corrected, 1)
+            daily_grid_temps.append(grid_temp)
+            wbgt = calculate_wbgt(temp, hum)
+            hi = calculate_heat_index(temp, hum)
+
+            daily_temps.append(temp)
+            daily_humidity.append(hum)
+            daily_dates.append(date.strftime("%Y-%m-%d"))
+            daily_wbgt.append(wbgt)
+            daily_hi.append(hi)
+            daily_uhi_deltas.append(round(uhi_delta, 1))
+
+        # ML heat wave prediction (pass last 30 days for proper anomaly features)
+        pred_prob, pred_conf, pred_tier = predictor.predict(
+            z, daily_temps[-30:], daily_humidity[-30:], daily_wbgt[-30:],
+        )
+
+        max_temp = max(daily_temps)
+        max_wbgt = max(daily_wbgt)
+        recent_temps = daily_temps[-7:]
+        recent_wbgt = daily_wbgt[-7:]
+        current_temp = daily_temps[-1]
+        current_wbgt = daily_wbgt[-1]
+        current_hi = daily_hi[-1]
+        watch_temp = HEAT_THRESHOLDS["watch"]["temp_c"]
+        consec = count_consecutive_days(recent_temps, watch_temp)
+        total_above = count_trigger_days(daily_temps, watch_temp)
+
+        # Risk level from config thresholds
+        recent_max = max(recent_temps)
+        risk_level = "normal"
+        for level in ("critical", "warning", "watch"):
+            ht = HEAT_THRESHOLDS[level]
+            if recent_max >= ht["temp_c"] and consec >= ht["consecutive_days"]:
+                risk_level = level
+                break
+
+        # Composite score
+        temp_score = min(100, max(0, (max_temp - 28) * 10))
+        wbgt_score = min(100, max(0, (max_wbgt - 25) * 12))
+        vuln_score = {"high": 85, "moderate": 50, "low": 20}[z.heat_vulnerability]
+        exposure_score = z.outdoor_exposure_pct * 100
+        composite = round(temp_score * 0.3 + wbgt_score * 0.25 + consec * 10 * 0.2 + vuln_score * 0.15 + exposure_score * 0.1, 1)
+        composite = min(100, max(0, composite))
+
+        enrolled = int(z.worker_population_est * rng.uniform(0.15, 0.45))
+
+        zone_data = {
+            "zone_id": z.zone_id,
+            "name": z.name,
+            "city": z.city,
+            "country": z.country,
+            "latitude": z.latitude,
+            "longitude": z.longitude,
+            "elevation_m": z.elevation_m,
+            "settlement_type": z.settlement_type,
+            "worker_population_est": z.worker_population_est,
+            "outdoor_exposure_pct": z.outdoor_exposure_pct,
+            "heat_vulnerability": z.heat_vulnerability,
+            "risk_level": risk_level,
+            "current_temp_c": current_temp,
+            "current_wbgt_c": current_wbgt,
+            "current_heat_index_c": current_hi,
+            "max_temp_c": round(max_temp, 1),
+            "max_wbgt_c": round(max_wbgt, 1),
+            "consecutive_hot_days": consec,
+            "total_days_above_33": total_above,
+            "heat_risk_score": composite,
+            "grid_temp_c": daily_grid_temps[-1],
+            "uhi_delta_c": daily_uhi_deltas[-1],
+            "corrected_temp_c": temp,
+            "trigger_probability_7d": round(pred_prob, 2),
+            "prediction_confidence": round(pred_conf, 2),
+            "model_tier": pred_tier,
+            "enrolled_workers": enrolled,
+            "data_quality": round(rng.uniform(0.80, 0.98), 2),
+            "last_updated": now.isoformat(),
+        }
+        zones.append(zone_data)
+
+        # Index data with daily history
+        indices.append({
+            "zone_id": z.zone_id,
+            "zone_name": z.name,
+            "city": z.city,
+            "risk_level": risk_level,
+            "temp_current": current_temp,
+            "wbgt_current": current_wbgt,
+            "heat_index_current": current_hi,
+            "consecutive_hot_days": consec,
+            "heat_risk_score": composite,
+            "grid_temp_c": daily_grid_temps[-1],
+            "uhi_delta_c": daily_uhi_deltas[-1],
+            "trigger_probability_7d": round(pred_prob, 2),
+            "prediction_confidence": round(pred_conf, 2),
+            "model_tier": pred_tier,
+            "daily_history": [
+                {"date": daily_dates[i], "temp_c": daily_temps[i], "grid_temp_c": daily_grid_temps[i], "uhi_delta_c": daily_uhi_deltas[i], "humidity_pct": daily_humidity[i], "wbgt_c": daily_wbgt[i], "heat_index_c": daily_hi[i]}
+                for i in range(90)
+            ],
+        })
+
+        # Triggers
+        if risk_level != "normal":
+            payout = PAYOUT_PER_EVENT_USD.get(risk_level, 5)
+            all_triggers.append({
+                "trigger_id": f"TRG-{tid:04d}",
+                "zone_id": z.zone_id,
+                "zone_name": z.name,
+                "city": z.city,
+                "trigger_level": risk_level,
+                "trigger_date": (now - timedelta(hours=rng.randint(2, 48))).isoformat(),
+                "heat_risk_score": composite,
+                "max_temp_c": round(max_temp, 1),
+                "max_wbgt_c": round(max_wbgt, 1),
+                "consecutive_days": consec,
+                "total_days_above": total_above,
+                "settlement_type": z.settlement_type,
+                "payout_per_worker_usd": payout,
+                "enrolled_workers": enrolled,
+                "total_payout_usd": payout * enrolled,
+                "status": "active",
+            })
+            tid += 1
+
+    # Basis risk
+    basis_risk = []
+    for z_data in zones:
+        zone_obj = ZONE_MAP[z_data["zone_id"]]
+        if zone_obj.heat_vulnerability == "high" and zone_obj.settlement_type == "informal":
+            score = rng.uniform(0.25, 0.40)
+        elif zone_obj.heat_vulnerability == "high":
+            score = rng.uniform(0.18, 0.32)
+        elif zone_obj.heat_vulnerability == "moderate":
+            score = rng.uniform(0.10, 0.22)
+        else:
+            score = rng.uniform(0.05, 0.15)
+        basis_risk.append({
+            "zone_id": z_data["zone_id"],
+            "zone_name": z_data["name"],
+            "city": z_data["city"],
+            "overall_score": round(score, 3),
+            "false_positive_rate": round(score * rng.uniform(0.4, 0.7), 3),
+            "false_negative_rate": round(score * rng.uniform(0.3, 0.6), 3),
+            "correlation": round(1 - score * rng.uniform(0.8, 1.1), 3),
+            "settlement_type": z_data["settlement_type"],
+            "heat_vulnerability": z_data["heat_vulnerability"],
+            "recommendation": (
+                "Urban heat island effect significant — consider localized temperature sensors"
+                if zone_obj.settlement_type == "informal"
+                else "Station temperature may underestimate worker-experienced heat by 2-3°C"
+                if score > 0.2
+                else "Current calibration adequate for this zone"
+            ),
+        })
+
+    # Notifications
+    notifications = []
+    nid = 1
+    for trigger in all_triggers:
+        if trigger["trigger_level"] in ("critical", "warning"):
+            notifications.append({
+                "id": f"NOT-{nid:04d}",
+                "zone_id": trigger["zone_id"],
+                "zone_name": trigger["zone_name"],
+                "city": trigger["city"],
+                "trigger_level": trigger["trigger_level"],
+                "channel": rng.choice(["sms", "whatsapp"]),
+                "language": rng.choice(["en", "sw"]),
+                "recipient_count": trigger["enrolled_workers"],
+                "message_preview": (
+                    f"HEAT ALERT [{trigger['trigger_level'].upper()}]: "
+                    f"{trigger['zone_name']}, {trigger['city']}. "
+                    f"Temperature {trigger['max_temp_c']}°C (WBGT {trigger['max_wbgt_c']}°C). "
+                    f"Payout: ${trigger['payout_per_worker_usd']}."
+                ),
+                "status": "sent",
+                "delivered_at": trigger["trigger_date"],
+                "cost_estimate": round(trigger["enrolled_workers"] * 0.0075, 2),
+            })
+            nid += 1
+            notifications.append({
+                "id": f"NOT-{nid:04d}",
+                "zone_id": trigger["zone_id"],
+                "zone_name": trigger["zone_name"],
+                "city": trigger["city"],
+                "trigger_level": trigger["trigger_level"],
+                "channel": "sms",
+                "language": "sw",
+                "recipient_count": trigger["enrolled_workers"],
+                "message_preview": (
+                    f"TAHADHARI YA JOTO [{trigger['trigger_level'].upper()}]: "
+                    f"{trigger['zone_name']}, {trigger['city']}. "
+                    f"Joto {trigger['max_temp_c']}°C. "
+                    f"Malipo: ${trigger['payout_per_worker_usd']}."
+                ),
+                "status": "sent",
+                "delivered_at": trigger["trigger_date"],
+                "cost_estimate": round(trigger["enrolled_workers"] * 0.0075, 2),
+            })
+            nid += 1
+
+    # Pipeline runs
+    pipeline_runs = []
+    for i in range(15):
+        run_date = now - timedelta(days=i * 2)
+        duration = rng.uniform(30, 120)
+        cost = rng.uniform(0.06, 0.18)
+        status = "ok" if rng.random() > 0.15 else "partial"
+        pipeline_runs.append({
+            "run_id": f"run-{1000 + i}",
+            "started_at": run_date.isoformat(),
+            "ended_at": (run_date + timedelta(seconds=duration)).isoformat(),
+            "status": status,
+            "duration_s": round(duration, 1),
+            "zones_processed": 20,
+            "triggers_found": rng.randint(0, 8),
+            "notifications_sent": rng.randint(0, 16),
+            "total_cost_usd": round(cost, 4),
+            "steps": [
+                {"step": s, "status": "ok", "duration_s": round(duration / 6, 1)}
+                for s in ["ingest", "heal", "index", "calibrate", "explain", "notify"]
+            ],
+        })
+
+    stats = {
+        "total_runs": len(pipeline_runs),
+        "successful_runs": sum(1 for r in pipeline_runs if r["status"] == "ok"),
+        "success_rate": round(sum(1 for r in pipeline_runs if r["status"] == "ok") / len(pipeline_runs), 2),
+        "zones_monitored": len(ZONES),
+        "cities": len(CITIES),
+        "active_triggers": len(all_triggers),
+        "total_enrolled": sum(z["enrolled_workers"] for z in zones),
+        "total_cost_usd": round(sum(r["total_cost_usd"] for r in pipeline_runs), 2),
+        "avg_cost_per_run_usd": round(sum(r["total_cost_usd"] for r in pipeline_runs) / len(pipeline_runs), 4),
+        "last_run": pipeline_runs[0]["started_at"],
+        "data_sources": ["NASA POWER"],
+    }
+
+    return {
+        "zones": zones,
+        "indices": indices,
+        "triggers": all_triggers,
+        "basis_risk": basis_risk,
+        "notifications": notifications,
+        "pipeline_runs": pipeline_runs,
+        "stats": stats,
+    }
+
+
+_demo = _generate_demo_data()
+
+# Singletons for calibrate endpoint (avoid re-instantiation per request)
+_actuarial_pricer = ActuarialPricer()
+_budget_optimizer = BudgetOptimizer()
+
+
+# ── API Endpoints ──────────────────────────────────────────────────────────
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "extreme-heat-risk-engine", "version": "1.0.0"}
+
+
+@app.get("/api/zones")
+def get_zones():
+    return {"zones": _demo["zones"], "total": len(_demo["zones"]), "cities": CITIES}
+
+
+@app.get("/api/indices")
+def get_indices():
+    return {"indices": _demo["indices"], "total": len(_demo["indices"])}
+
+
+@app.get("/api/triggers")
+def get_triggers():
+    triggers = _demo["triggers"]
+    return {
+        "triggers": triggers,
+        "total": len(triggers),
+        "active": sum(1 for t in triggers if t["status"] == "active"),
+        "by_level": {
+            level: sum(1 for t in triggers if t["trigger_level"] == level)
+            for level in ["critical", "warning", "watch"]
+        },
+    }
+
+
+@app.get("/api/basis-risk")
+def get_basis_risk():
+    br = _demo["basis_risk"]
+    return {
+        "assessments": br,
+        "total": len(br),
+        "avg_score": round(sum(b["overall_score"] for b in br) / max(1, len(br)), 3),
+    }
+
+
+@app.get("/api/notifications")
+def get_notifications():
+    notifs = _demo["notifications"]
+    return {
+        "notifications": notifs,
+        "total": len(notifs),
+        "by_language": {
+            lang: sum(1 for n in notifs if n["language"] == lang)
+            for lang in ["en", "sw"]
+        },
+    }
+
+
+@app.get("/api/enrolled-workers")
+def get_enrolled():
+    by_zone = [
+        {"zone_id": z["zone_id"], "zone_name": z["name"], "city": z["city"], "enrolled": z["enrolled_workers"]}
+        for z in _demo["zones"]
+    ]
+    return {"by_zone": by_zone, "total_enrolled": sum(z["enrolled_workers"] for z in _demo["zones"])}
+
+
+@app.get("/api/pipeline/runs")
+def get_pipeline_runs():
+    return {"runs": _demo["pipeline_runs"], "total": len(_demo["pipeline_runs"])}
+
+
+@app.get("/api/pipeline/stats")
+def get_pipeline_stats():
+    return _demo["stats"]
+
+
+@app.get("/api/calibrate")
+def calibrate(
+    temp_threshold: float = 35.0,
+    consecutive_days: int = 2,
+    wbgt_threshold: float = 30.0,
+    payout_usd: float = 10.0,
+    budget_usd: float = 500000.0,
+    worker_contribution_usd: float = 0.0,
+):
+    """Interactive calibration endpoint.
+
+    Run heat risk scoring with custom thresholds against all zones.
+    Returns per-zone trigger analysis and program cost estimates.
+    """
+    rng = random.Random(SEED)
+    results = []
+    total_trigger_days = 0
+    total_annual_cost = 0.0
+    zones_triggered = 0
+
+    zones_by_id = {z["zone_id"]: z for z in _demo["zones"]}
+    basis_by_id = {b["zone_id"]: b for b in _demo["basis_risk"]}
+
+    for idx_data in _demo["indices"]:
+        zone_id = idx_data["zone_id"]
+        zone = ZONE_MAP.get(zone_id)
+        if not zone:
+            continue
+
+        # Extract daily temps and humidity from history
+        history = idx_data.get("daily_history", [])
+        temps = [d["temp_c"] for d in history]
+        humidity = [d["humidity_pct"] for d in history]
+        wbgts = [d["wbgt_c"] for d in history]
+
+        # Apply custom thresholds
+        days_above_temp = count_trigger_days(temps, temp_threshold)
+        days_above_wbgt = count_trigger_days(wbgts, wbgt_threshold)
+        consec_temp = count_consecutive_days(temps, temp_threshold)
+        consec_wbgt = count_consecutive_days(wbgts, wbgt_threshold)
+
+        # Count trigger events (consecutive runs above threshold)
+        trigger_events = 0
+        run_length = 0
+        for t in temps:
+            if t > temp_threshold:
+                run_length += 1
+            else:
+                if run_length >= consecutive_days:
+                    trigger_events += 1
+                run_length = 0
+        if run_length >= consecutive_days:
+            trigger_events += 1
+
+        # Annualize (90 days of data → multiply by 4)
+        events_per_year = round(trigger_events * (365 / max(len(temps), 1)), 1)
+
+        zone_demo = zones_by_id.get(zone_id, {})
+        enrolled = zone_demo.get("enrolled_workers", 0)
+
+        annual_payout = round(events_per_year * payout_usd * enrolled, 2)
+        annual_per_worker = round(events_per_year * payout_usd, 2)
+
+        br = basis_by_id.get(zone_id, {})
+        basis_score = br.get("overall_score", 0.15)
+
+        triggered = trigger_events > 0
+        if triggered:
+            zones_triggered += 1
+        total_trigger_days += days_above_temp
+        total_annual_cost += annual_payout
+
+        results.append({
+            "zone_id": zone_id,
+            "zone_name": zone.name,
+            "city": zone.city,
+            "settlement_type": zone.settlement_type,
+            "heat_vulnerability": zone.heat_vulnerability,
+            "enrolled_workers": enrolled,
+            "days_above_temp": days_above_temp,
+            "days_above_wbgt": days_above_wbgt,
+            "consecutive_days_temp": consec_temp,
+            "consecutive_days_wbgt": consec_wbgt,
+            "trigger_events": trigger_events,
+            "events_per_year": events_per_year,
+            "annual_payout_per_worker": annual_per_worker,
+            "annual_payout_total": annual_payout,
+            "basis_risk_score": basis_score,
+            "triggered": triggered,
+        })
+
+    total_enrolled = sum(r["enrolled_workers"] for r in results)
+
+    # Actuarial pricing per zone
+    actuarial_results = []
+    for r in results:
+        zone = ZONE_MAP.get(r["zone_id"])
+        if not zone:
+            continue
+        ar = _actuarial_pricer.price_zone(
+            zone=zone,
+            predicted_frequency=r["events_per_year"],
+            basis_risk_score=r["basis_risk_score"],
+            payout_per_event=payout_usd,
+            enrolled=r["enrolled_workers"],
+        )
+        r["actuarial_cost_per_worker"] = round(ar.cost_per_worker_year, 2)
+        r["cost_breakdown"] = ar.cost_breakdown
+        actuarial_results.append(ar)
+
+    # Budget allocation
+    allocation = _budget_optimizer.optimize(
+        budget_usd=budget_usd,
+        actuarial_results=actuarial_results,
+        payout_per_event=payout_usd,
+        worker_contribution=worker_contribution_usd,
+    )
+
+    # Merge allocation into zone results
+    alloc_map = {a.zone_id: a for a in allocation.allocations}
+    for r in results:
+        a = alloc_map.get(r["zone_id"])
+        if a:
+            r["allocated_budget"] = round(a.allocated_budget, 2)
+            r["workers_covered"] = a.workers_covered
+            r["coverage_pct"] = round(a.coverage_pct, 1)
+            r["priority_rank"] = a.priority_rank
+        else:
+            r["allocated_budget"] = 0
+            r["workers_covered"] = 0
+            r["coverage_pct"] = 0
+            r["priority_rank"] = 99
+
+    return {
+        "zones": sorted(results, key=lambda r: r.get("priority_rank", 99)),
+        "summary": {
+            "total_zones": len(results),
+            "zones_triggered": zones_triggered,
+            "total_trigger_days": total_trigger_days,
+            "avg_events_per_year": round(sum(r["events_per_year"] for r in results) / max(1, len(results)), 1),
+            "total_annual_cost": round(total_annual_cost, 2),
+            "avg_cost_per_worker": round(total_annual_cost / max(1, total_enrolled), 2),
+            "total_enrolled": total_enrolled,
+            "avg_basis_risk": round(sum(r["basis_risk_score"] for r in results) / max(1, len(results)), 3),
+        },
+        "allocation": {
+            "budget_usd": budget_usd,
+            "worker_contribution_usd": worker_contribution_usd,
+            "workers_covered": allocation.total_workers_covered,
+            "overall_coverage_pct": round(allocation.overall_coverage_pct, 1),
+            "zones_fully_funded": allocation.zones_fully_funded,
+            "zones_partially_funded": allocation.zones_partially_funded,
+            "zones_unfunded": allocation.zones_unfunded,
+            "stretch_analysis": allocation.stretch_analysis,
+        },
+        "thresholds": {
+            "temp_threshold": temp_threshold,
+            "consecutive_days": consecutive_days,
+            "wbgt_threshold": wbgt_threshold,
+            "payout_usd": payout_usd,
+        },
+    }
+
+
+# ── Static file serving ───────────────────────────────────────────────────
+
+dist_path = Path(__file__).parent.parent / "frontend" / "dist"
+if dist_path.exists():
+    app.mount("/assets", StaticFiles(directory=str(dist_path / "assets")), name="static")
+
+    @app.get("/{path:path}")
+    async def serve_spa(path: str):
+        file_path = dist_path / path
+        if file_path.exists() and file_path.is_file():
+            return FileResponse(str(file_path))
+        return FileResponse(str(dist_path / "index.html"))

src/calibration/basis_risk.py

@@ -0,0 +1,386 @@
+"""
+Basis risk estimation for parametric heat insurance.
+
+Basis risk is the mismatch between what the temperature index says happened
+and what outdoor workers actually experienced.  In parametric heat insurance
+the key sources of basis risk are:
+
+  1. Urban heat island effect — informal settlements with tin roofs are
+     significantly hotter than the station/satellite reading
+  2. Time-of-day exposure — workers are outside during 10am-4pm peak,
+     but daily-max temperature may occur at a different time
+  3. Indoor/outdoor split — the index triggers for the whole zone but
+     only outdoor workers are affected
+  4. Microclimate variation — shade, wind, surface type differ block to block
+
+Realistic basis risk ranges:
+  - Informal high-vulnerability zones:  0.25 - 0.40
+  - Mixed/moderate zones:               0.15 - 0.28
+  - Formal low-vulnerability zones:     0.08 - 0.18
+
+Each zone gets a BasisRiskReport with false-positive/negative rates,
+index-damage correlation, and threshold adjustment recommendations.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import math
+import random
+from dataclasses import dataclass, field
+from typing import Optional
+
+from config import HEAT_THRESHOLDS, PAYOUT_PER_EVENT_USD, ZONE_MAP, ZONES, UrbanZone
+
+log = logging.getLogger(__name__)
+
+
+# -- Data containers --------------------------------------------------------
+
+@dataclass
+class SimulatedEvent:
+    """One historical event: what the index said vs. what workers experienced."""
+    zone_id: str
+    date: str
+    index_triggered: bool
+    trigger_level: str  # critical, warning, watch, none
+    actual_heat_stress: bool
+    actual_severity: float  # 0.0-1.0
+    index_severity: float  # 0.0-1.0
+    notes: str = ""
+
+
+@dataclass
+class BasisRiskReport:
+    """Basis risk assessment for a single zone."""
+    zone_id: str
+    zone_name: str
+    city: str
+    settlement_type: str
+    heat_vulnerability: str
+
+    # Core metrics
+    overall_score: float  # 0-1, lower is better
+    false_positive_rate: float  # index fired but no heat stress
+    false_negative_rate: float  # heat stress occurred but index missed
+    correlation: float  # Pearson r between index and actual severity
+    mae: float  # mean absolute error
+
+    # Trigger accuracy
+    total_events: int
+    true_positives: int
+    true_negatives: int
+    false_positives: int
+    false_negatives: int
+    trigger_accuracy: float
+
+    # Basis risk components
+    uhi_adjustment: float  # urban heat island temperature delta (C)
+    time_of_day_factor: float  # mismatch from peak-hour vs daily-max
+    indoor_outdoor_split: float  # fraction of workers truly exposed
+
+    # Recommendations
+    recommendations: list[str] = field(default_factory=list)
+    confidence_interval: tuple[float, float] = (0.0, 1.0)
+    tier_accuracy: dict[str, float] = field(default_factory=dict)
+
+
+# -- Simulation parameters --------------------------------------------------
+
+# Basis risk ranges by (settlement_type, heat_vulnerability)
+_RISK_RANGES: dict[tuple[str, str], tuple[float, float]] = {
+    ("informal", "high"):     (0.30, 0.40),
+    ("informal", "moderate"): (0.25, 0.35),
+    ("informal", "low"):      (0.20, 0.30),
+    ("mixed", "high"):        (0.22, 0.32),
+    ("mixed", "moderate"):    (0.18, 0.28),
+    ("mixed", "low"):         (0.15, 0.22),
+    ("formal", "high"):       (0.14, 0.22),
+    ("formal", "moderate"):   (0.10, 0.18),
+    ("formal", "low"):        (0.08, 0.15),
+    ("commercial", "high"):   (0.12, 0.20),
+    ("commercial", "moderate"): (0.10, 0.16),
+    ("commercial", "low"):    (0.08, 0.14),
+}
+
+# Urban heat island temperature deltas (C above station reading)
+_UHI_DELTA = {
+    "informal": 3.5,   # tin roofs, no shade, concrete/dirt heat absorption
+    "mixed": 2.0,
+    "formal": 1.0,
+    "commercial": 1.5,  # concrete + AC exhaust
+}
+
+# Time-of-day exposure factor (how much 10am-4pm temps exceed daily max)
+_TIME_OF_DAY = {
+    "high": 0.15,      # workers out all day, actual exposure often higher
+    "moderate": 0.10,
+    "low": 0.05,
+}
+
+_SIM_EVENTS = 60  # ~5 years of hot-season events
+
+
+def _zone_seed(zone_id: str) -> int:
+    """Deterministic seed per zone."""
+    return int(hashlib.sha256(zone_id.encode()).hexdigest()[:8], 16)
+
+
+# -- Simulation engine -------------------------------------------------------
+
+def _simulate_events(zone: UrbanZone, n: int = _SIM_EVENTS) -> list[SimulatedEvent]:
+    """Generate a plausible history of heat trigger events vs actual impacts."""
+    rng = random.Random(_zone_seed(zone.zone_id))
+
+    risk_range = _RISK_RANGES.get(
+        (zone.settlement_type, zone.heat_vulnerability),
+        (0.18, 0.28),
+    )
+    base_risk = rng.uniform(*risk_range)
+
+    # UHI increases false negatives (station reads cooler than reality)
+    uhi = _UHI_DELTA.get(zone.settlement_type, 1.5)
+    base_risk += uhi * 0.015  # each degree of UHI adds ~1.5% basis risk
+    base_risk = max(0.05, min(0.55, base_risk))
+
+    trigger_prob = 0.30 if zone.heat_vulnerability == "high" else (
+        0.20 if zone.heat_vulnerability == "moderate" else 0.12
+    )
+    stress_base_prob = trigger_prob * (1.0 + 0.10 * (1 if zone.outdoor_exposure_pct > 0.6 else 0))
+
+    events: list[SimulatedEvent] = []
+    for i in range(n):
+        month = rng.choice(zone.hot_months) if zone.hot_months else rng.choice([1, 2, 3])
+        year = 2019 + (i // 12)
+        day = rng.randint(1, 28)
+        date = f"{year}-{month:02d}-{day:02d}"
+
+        index_triggered = rng.random() < trigger_prob
+        if index_triggered:
+            level_roll = rng.random()
+            trigger_level = (
+                "critical" if level_roll < 0.12 else
+                "warning" if level_roll < 0.45 else
+                "watch"
+            )
+            index_severity = (
+                rng.uniform(0.7, 1.0) if trigger_level == "critical" else
+                rng.uniform(0.4, 0.7) if trigger_level == "warning" else
+                rng.uniform(0.1, 0.4)
+            )
+        else:
+            trigger_level = "none"
+            index_severity = rng.uniform(0.0, 0.15)
+
+        if index_triggered:
+            actual_heat_stress = rng.random() < (1.0 - base_risk * 0.55)
+        else:
+            # False negative: UHI makes ground truth hotter than station
+            actual_heat_stress = rng.random() < (base_risk * 0.45)
+
+        if actual_heat_stress:
+            noise = rng.gauss(0, base_risk * 0.4)
+            actual_severity = max(0.0, min(1.0, index_severity + noise + uhi * 0.03))
+            if not index_triggered:
+                actual_severity = rng.uniform(0.15, 0.50)
+        else:
+            actual_severity = 0.0
+
+        notes = ""
+        if index_triggered and not actual_heat_stress:
+            notes = "False alarm: index triggered but workers did not report heat stress"
+        elif not index_triggered and actual_heat_stress:
+            notes = "Missed event: workers experienced heat stress but station temp was below threshold (likely UHI gap)"
+
+        events.append(SimulatedEvent(
+            zone_id=zone.zone_id,
+            date=date,
+            index_triggered=index_triggered,
+            trigger_level=trigger_level,
+            actual_heat_stress=actual_heat_stress,
+            actual_severity=actual_severity,
+            index_severity=index_severity,
+            notes=notes,
+        ))
+
+    return events
+
+
+# -- Metrics computation -----------------------------------------------------
+
+def _pearson_r(xs: list[float], ys: list[float]) -> float:
+    """Pearson correlation coefficient. Returns 0.0 if degenerate."""
+    n = len(xs)
+    if n < 3:
+        return 0.0
+    mean_x = sum(xs) / n
+    mean_y = sum(ys) / n
+    cov = sum((x - mean_x) * (y - mean_y) for x, y in zip(xs, ys))
+    std_x = math.sqrt(sum((x - mean_x) ** 2 for x in xs))
+    std_y = math.sqrt(sum((y - mean_y) ** 2 for y in ys))
+    if std_x < 1e-9 or std_y < 1e-9:
+        return 0.0
+    return cov / (std_x * std_y)
+
+
+def _compute_report(zone: UrbanZone, events: list[SimulatedEvent]) -> BasisRiskReport:
+    """Compute basis risk metrics from simulated events."""
+    tp = sum(1 for e in events if e.index_triggered and e.actual_heat_stress)
+    tn = sum(1 for e in events if not e.index_triggered and not e.actual_heat_stress)
+    fp = sum(1 for e in events if e.index_triggered and not e.actual_heat_stress)
+    fn = sum(1 for e in events if not e.index_triggered and e.actual_heat_stress)
+    total = len(events)
+
+    fpr = fp / max(1, fp + tp)
+    fnr = fn / max(1, fn + tn)
+    accuracy = (tp + tn) / max(1, total)
+
+    idx_sev = [e.index_severity for e in events]
+    act_sev = [e.actual_severity for e in events]
+    corr = _pearson_r(idx_sev, act_sev)
+    mae = sum(abs(i - a) for i, a in zip(idx_sev, act_sev)) / max(1, total)
+
+    overall = 0.30 * fpr + 0.30 * fnr + 0.20 * mae + 0.20 * (1.0 - max(0, corr))
+    overall = max(0.0, min(1.0, overall))
+
+    # UHI and time-of-day factors
+    uhi = _UHI_DELTA.get(zone.settlement_type, 1.5)
+    tod = _TIME_OF_DAY.get(zone.heat_vulnerability, 0.10)
+
+    # Per-tier accuracy
+    tier_acc: dict[str, float] = {}
+    for level in ("critical", "warning", "watch"):
+        tier_events = [e for e in events if e.trigger_level == level]
+        if tier_events:
+            tier_correct = sum(1 for e in tier_events if e.actual_heat_stress)
+            tier_acc[level] = tier_correct / len(tier_events)
+        else:
+            tier_acc[level] = 0.0
+
+    # Recommendations
+    recs: list[str] = []
+    if uhi >= 3.0:
+        recs.append(
+            f"Urban heat island effect adds ~{uhi:.1f}C in {zone.name}. "
+            f"Consider lowering trigger threshold by {uhi * 0.5:.1f}C for this zone."
+        )
+    if fnr > 0.20:
+        recs.append(
+            f"Missed event rate ({fnr:.0%}) is high. Station temperature "
+            f"underestimates ground-level heat in {zone.settlement_type} areas. "
+            f"Consider adding community-reported heat stress data."
+        )
+    if fpr > 0.25:
+        recs.append(
+            f"False positive rate ({fpr:.0%}). Consider raising threshold "
+            f"or adding WBGT as a secondary trigger condition."
+        )
+    if zone.outdoor_exposure_pct > 0.7:
+        recs.append(
+            f"High outdoor exposure ({zone.outdoor_exposure_pct:.0%}). "
+            f"Prioritize this zone for shade structures and rest-break interventions."
+        )
+    if zone.settlement_type == "informal":
+        recs.append(
+            "Informal settlement — tin roof temperatures can exceed ambient by 10-15C. "
+            "Ground-truth heat monitoring (e.g., community thermometers) would "
+            "significantly reduce basis risk."
+        )
+    if not recs:
+        recs.append(
+            "Basis risk is within acceptable range. Continue monitoring "
+            "and recalibrate with seasonal ground-truth data."
+        )
+
+    se = math.sqrt(overall * (1 - overall) / max(1, total))
+    ci_low = max(0.0, overall - 1.96 * se)
+    ci_high = min(1.0, overall + 1.96 * se)
+
+    return BasisRiskReport(
+        zone_id=zone.zone_id,
+        zone_name=zone.name,
+        city=zone.city,
+        settlement_type=zone.settlement_type,
+        heat_vulnerability=zone.heat_vulnerability,
+        overall_score=round(overall, 3),
+        false_positive_rate=round(fpr, 3),
+        false_negative_rate=round(fnr, 3),
+        correlation=round(corr, 3),
+        mae=round(mae, 3),
+        total_events=total,
+        true_positives=tp,
+        true_negatives=tn,
+        false_positives=fp,
+        false_negatives=fn,
+        trigger_accuracy=round(accuracy, 3),
+        uhi_adjustment=uhi,
+        time_of_day_factor=tod,
+        indoor_outdoor_split=zone.outdoor_exposure_pct,
+        recommendations=recs,
+        confidence_interval=(round(ci_low, 3), round(ci_high, 3)),
+        tier_accuracy={k: round(v, 3) for k, v in tier_acc.items()},
+    )
+
+
+# -- Public API ---------------------------------------------------------------
+
+def assess_zone(zone_id: str) -> BasisRiskReport:
+    """Run basis risk assessment for a single zone."""
+    zone = ZONE_MAP.get(zone_id)
+    if zone is None:
+        raise ValueError(f"Unknown zone: {zone_id}")
+    events = _simulate_events(zone)
+    report = _compute_report(zone, events)
+    log.info(
+        "Basis risk for %s (%s): %.3f [FPR=%.2f, FNR=%.2f, r=%.2f, UHI=+%.1fC]",
+        zone.name, zone.zone_id, report.overall_score,
+        report.false_positive_rate, report.false_negative_rate,
+        report.correlation, report.uhi_adjustment,
+    )
+    return report
+
+
+def assess_all_zones() -> dict[str, BasisRiskReport]:
+    """Run basis risk assessment across every configured zone."""
+    reports: dict[str, BasisRiskReport] = {}
+    for zone_id in ZONE_MAP:
+        reports[zone_id] = assess_zone(zone_id)
+    return reports
+
+
+def recommended_threshold_adjustment(
+    report: BasisRiskReport,
+) -> Optional[dict[str, dict[str, float]]]:
+    """Suggest adjusted trigger thresholds based on basis risk analysis.
+
+    Returns a dict like HEAT_THRESHOLDS but with modified values,
+    or None if no adjustment is needed.
+    """
+    if report.overall_score < 0.20:
+        return None
+
+    adjusted = {}
+    for level in ("critical", "warning", "watch"):
+        base = HEAT_THRESHOLDS[level].copy()
+        if report.false_negative_rate > 0.20:
+            # Missing too many events: lower temperature thresholds
+            # Account for UHI by reducing threshold
+            uhi_adj = report.uhi_adjustment * 0.4
+            adjusted[level] = {
+                "temp_c": round(base["temp_c"] - uhi_adj, 1),
+                "wbgt_c": round(base["wbgt_c"] - uhi_adj * 0.6, 1),
+                "consecutive_days": base["consecutive_days"],
+            }
+        elif report.false_positive_rate > 0.25:
+            # Too many false alarms: raise thresholds
+            factor = 1.0 + (report.false_positive_rate - 0.25) * 0.3
+            adjusted[level] = {
+                "temp_c": round(base["temp_c"] * factor, 1),
+                "wbgt_c": round(base["wbgt_c"] * factor, 1),
+                "consecutive_days": base["consecutive_days"],
+            }
+        else:
+            adjusted[level] = base
+
+    return adjusted

src/database/crud.py

@@ -0,0 +1,651 @@
+"""
+Database CRUD operations for the Climate Risk Index Engine.
+
+Uses asyncpg for PostgreSQL when DATABASE_URL is set, with an in-memory
+fallback for demo/testing.  Pattern follows Weather AI 2's PgConnection.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import uuid
+from collections import defaultdict
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Sequence
+
+from src.database.schema import get_full_ddl, get_table_names
+
+log = logging.getLogger(__name__)
+
+
+# ── Connection wrapper ───────────────────────────────────────────────────
+
+class PgConnection:
+    """
+    Async PostgreSQL connection manager.
+
+    If DATABASE_URL is not set, transparently switches to InMemoryStore
+    so the pipeline can run in demo mode without a database.
+    """
+
+    def __init__(self, database_url: Optional[str] = None):
+        self.database_url = database_url or os.environ.get("DATABASE_URL", "")
+        self._pool = None
+        self._memory: Optional[InMemoryStore] = None
+
+    @property
+    def is_postgres(self) -> bool:
+        return bool(self.database_url)
+
+    async def connect(self) -> None:
+        """Establish the connection pool or init in-memory store."""
+        if self.database_url:
+            try:
+                import asyncpg
+                self._pool = await asyncpg.create_pool(
+                    self.database_url,
+                    min_size=2,
+                    max_size=10,
+                    command_timeout=30,
+                )
+                log.info("Connected to PostgreSQL")
+            except Exception as exc:
+                log.warning("PostgreSQL unavailable (%s), using in-memory store", exc)
+                self._memory = InMemoryStore()
+        else:
+            log.info("No DATABASE_URL set, using in-memory store")
+            self._memory = InMemoryStore()
+
+    async def close(self) -> None:
+        """Close the connection pool."""
+        if self._pool:
+            await self._pool.close()
+            self._pool = None
+        self._memory = None
+
+    async def init_schema(self) -> None:
+        """Create all tables if they don't exist."""
+        if self._pool:
+            async with self._pool.acquire() as conn:
+                await conn.execute(get_full_ddl())
+            log.info("Schema initialized (%d tables)", len(get_table_names()))
+        else:
+            log.info("In-memory store: schema init is a no-op")
+
+    async def execute(self, query: str, *args) -> str:
+        """Execute a query, return status string."""
+        if self._pool:
+            async with self._pool.acquire() as conn:
+                return await conn.execute(query, *args)
+        return "OK (in-memory)"
+
+    async def fetch(self, query: str, *args) -> list[dict]:
+        """Fetch rows as list of dicts."""
+        if self._pool:
+            async with self._pool.acquire() as conn:
+                rows = await conn.fetch(query, *args)
+                return [dict(r) for r in rows]
+        return []
+
+    async def fetchrow(self, query: str, *args) -> Optional[dict]:
+        """Fetch a single row as dict."""
+        if self._pool:
+            async with self._pool.acquire() as conn:
+                row = await conn.fetchrow(query, *args)
+                return dict(row) if row else None
+        return None
+
+    async def fetchval(self, query: str, *args) -> Any:
+        """Fetch a single value."""
+        if self._pool:
+            async with self._pool.acquire() as conn:
+                return await conn.fetchval(query, *args)
+        return None
+
+
+# ── In-memory fallback ───────────────────────────────────────────────────
+
+class InMemoryStore:
+    """
+    Simple in-memory storage for demo mode.
+    Stores rows as dicts keyed by table name.
+    """
+
+    def __init__(self):
+        self.tables: Dict[str, list[dict]] = defaultdict(list)
+        self._id_counters: Dict[str, int] = defaultdict(int)
+
+    def insert(self, table: str, row: dict) -> int:
+        """Insert a row, returning a synthetic ID."""
+        self._id_counters[table] += 1
+        row_copy = dict(row)
+        row_copy["id"] = self._id_counters[table]
+        if "created_at" not in row_copy:
+            row_copy["created_at"] = datetime.now(timezone.utc).isoformat()
+        self.tables[table].append(row_copy)
+        return row_copy["id"]
+
+    def query(
+        self, table: str, filters: Optional[Dict[str, Any]] = None, limit: int = 100
+    ) -> list[dict]:
+        """Query rows with optional simple equality filters."""
+        rows = self.tables.get(table, [])
+        if filters:
+            rows = [
+                r for r in rows
+                if all(r.get(k) == v for k, v in filters.items())
+            ]
+        return rows[:limit]
+
+    def count(self, table: str) -> int:
+        return len(self.tables.get(table, []))
+
+
+# ── CRUD functions ───────────────────────────────────────────────────────
+
+# --- Zones ---
+
+async def upsert_zone(db: PgConnection, zone_data: dict) -> None:
+    """Insert or update a zone."""
+    if db._pool:
+        await db.execute(
+            """
+            INSERT INTO zones (zone_id, name, city, country, latitude, longitude,
+                               elevation_m, area_km2, population_est, settlement_type,
+                               flood_susceptibility, drainage_quality, primary_flood_type,
+                               rainy_seasons, notes)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15)
+            ON CONFLICT (zone_id) DO UPDATE SET
+                name = EXCLUDED.name,
+                population_est = EXCLUDED.population_est,
+                notes = EXCLUDED.notes
+            """,
+            zone_data["zone_id"], zone_data["name"], zone_data["city"],
+            zone_data["country"], zone_data["latitude"], zone_data["longitude"],
+            zone_data.get("elevation_m"), zone_data.get("area_km2"),
+            zone_data.get("population_est"), zone_data["settlement_type"],
+            zone_data["flood_susceptibility"], zone_data["drainage_quality"],
+            zone_data.get("primary_flood_type"), zone_data.get("rainy_seasons"),
+            zone_data.get("notes", ""),
+        )
+    elif db._memory:
+        # Simple overwrite in memory
+        existing = [
+            r for r in db._memory.tables["zones"]
+            if r["zone_id"] == zone_data["zone_id"]
+        ]
+        if existing:
+            existing[0].update(zone_data)
+        else:
+            db._memory.insert("zones", zone_data)
+
+
+async def get_zone(db: PgConnection, zone_id: str) -> Optional[dict]:
+    """Fetch a single zone."""
+    if db._pool:
+        return await db.fetchrow("SELECT * FROM zones WHERE zone_id = $1", zone_id)
+    elif db._memory:
+        rows = db._memory.query("zones", {"zone_id": zone_id}, limit=1)
+        return rows[0] if rows else None
+    return None
+
+
+async def get_all_zones(db: PgConnection) -> list[dict]:
+    """Fetch all zones."""
+    if db._pool:
+        return await db.fetch("SELECT * FROM zones ORDER BY city, name")
+    elif db._memory:
+        return db._memory.query("zones", limit=1000)
+    return []
+
+
+# --- Daily readings ---
+
+async def insert_daily_reading(db: PgConnection, reading: dict) -> Optional[int]:
+    """Insert a daily reading. Returns the row ID."""
+    if db._pool:
+        return await db.fetchval(
+            """
+            INSERT INTO daily_readings (zone_id, date, precip_mm, precip_nasa_mm,
+                precip_chirps_mm, temp_mean_c, temp_max_c, temp_min_c,
+                humidity_pct, wind_speed_ms, source, source_agreement, data_quality)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+            ON CONFLICT (zone_id, date) DO UPDATE SET
+                precip_mm = EXCLUDED.precip_mm,
+                data_quality = EXCLUDED.data_quality
+            RETURNING id
+            """,
+            reading["zone_id"], reading["date"],
+            reading.get("precip_mm"), reading.get("precip_nasa_mm"),
+            reading.get("precip_chirps_mm"), reading.get("temp_mean_c"),
+            reading.get("temp_max_c"), reading.get("temp_min_c"),
+            reading.get("humidity_pct"), reading.get("wind_speed_ms"),
+            reading.get("source", "unknown"), reading.get("source_agreement"),
+            reading.get("data_quality", 0.0),
+        )
+    elif db._memory:
+        return db._memory.insert("daily_readings", reading)
+    return None
+
+
+async def get_daily_readings(
+    db: PgConnection, zone_id: str, limit: int = 90
+) -> list[dict]:
+    """Fetch recent daily readings for a zone."""
+    if db._pool:
+        return await db.fetch(
+            "SELECT * FROM daily_readings WHERE zone_id = $1 ORDER BY date DESC LIMIT $2",
+            zone_id, limit,
+        )
+    elif db._memory:
+        rows = db._memory.query("daily_readings", {"zone_id": zone_id}, limit=limit)
+        return sorted(rows, key=lambda r: r.get("date", ""), reverse=True)
+    return []
+
+
+# --- Healed readings ---
+
+async def insert_healed_reading(db: PgConnection, reading: dict) -> Optional[int]:
+    """Insert a healed reading."""
+    if db._pool:
+        return await db.fetchval(
+            """
+            INSERT INTO healed_readings (zone_id, date, raw_reading_id,
+                precip_mm, temp_mean_c, temp_max_c, temp_min_c,
+                humidity_pct, wind_speed_ms, quality_score, heal_action, fields_corrected)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)
+            ON CONFLICT (zone_id, date) DO UPDATE SET
+                quality_score = EXCLUDED.quality_score,
+                heal_action = EXCLUDED.heal_action
+            RETURNING id
+            """,
+            reading["zone_id"], reading["date"], reading.get("raw_reading_id"),
+            reading.get("precip_mm"), reading.get("temp_mean_c"),
+            reading.get("temp_max_c"), reading.get("temp_min_c"),
+            reading.get("humidity_pct"), reading.get("wind_speed_ms"),
+            reading.get("quality_score", 0.0),
+            reading.get("heal_action", "passthrough"),
+            reading.get("fields_corrected", []),
+        )
+    elif db._memory:
+        return db._memory.insert("healed_readings", reading)
+    return None
+
+
+# --- Healing log ---
+
+async def insert_healing_log(db: PgConnection, entry: dict) -> Optional[int]:
+    """Insert a healing log entry."""
+    if db._pool:
+        return await db.fetchval(
+            """
+            INSERT INTO healing_log (zone_id, date, healed_reading_id,
+                agent_type, reasoning, corrections, tools_used,
+                confidence, tokens_used, latency_ms)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+            RETURNING id
+            """,
+            entry["zone_id"], entry["date"], entry.get("healed_reading_id"),
+            entry.get("agent_type", "rule_based"), entry.get("reasoning"),
+            json.dumps(entry.get("corrections", {})),
+            entry.get("tools_used", []),
+            entry.get("confidence"), entry.get("tokens_used", 0),
+            entry.get("latency_ms", 0),
+        )
+    elif db._memory:
+        return db._memory.insert("healing_log", entry)
+    return None
+
+
+# --- Monthly indices ---
+
+async def upsert_monthly_index(db: PgConnection, index_data: dict) -> None:
+    """Insert or update a monthly index record."""
+    if db._pool:
+        await db.execute(
+            """
+            INSERT INTO monthly_indices (zone_id, year, month, spi_1, spi_3, spi_6,
+                total_precip_mm, mean_precip_mm, precip_days, precip_anomaly_pct)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+            ON CONFLICT (zone_id, year, month) DO UPDATE SET
+                spi_1 = EXCLUDED.spi_1,
+                spi_3 = EXCLUDED.spi_3,
+                spi_6 = EXCLUDED.spi_6,
+                total_precip_mm = EXCLUDED.total_precip_mm,
+                computed_at = NOW()
+            """,
+            index_data["zone_id"], index_data["year"], index_data["month"],
+            index_data.get("spi_1"), index_data.get("spi_3"), index_data.get("spi_6"),
+            index_data.get("total_precip_mm"), index_data.get("mean_precip_mm"),
+            index_data.get("precip_days"), index_data.get("precip_anomaly_pct"),
+        )
+    elif db._memory:
+        db._memory.insert("monthly_indices", index_data)
+
+
+async def get_monthly_indices(
+    db: PgConnection, zone_id: str, limit: int = 24
+) -> list[dict]:
+    """Fetch recent monthly indices for a zone."""
+    if db._pool:
+        return await db.fetch(
+            """
+            SELECT * FROM monthly_indices
+            WHERE zone_id = $1
+            ORDER BY year DESC, month DESC
+            LIMIT $2
+            """,
+            zone_id, limit,
+        )
+    elif db._memory:
+        return db._memory.query("monthly_indices", {"zone_id": zone_id}, limit=limit)
+    return []
+
+
+# --- Flood risk scores ---
+
+async def insert_flood_risk_score(db: PgConnection, score: dict) -> Optional[int]:
+    """Insert a daily flood risk score."""
+    if db._pool:
+        return await db.fetchval(
+            """
+            INSERT INTO flood_risk_scores (zone_id, date, composite_score,
+                precip_score, api_5day_score, spi_score, drainage_factor,
+                settlement_factor, risk_level, contributing_factors)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+            ON CONFLICT (zone_id, date) DO UPDATE SET
+                composite_score = EXCLUDED.composite_score,
+                risk_level = EXCLUDED.risk_level
+            RETURNING id
+            """,
+            score["zone_id"], score["date"], score["composite_score"],
+            score.get("precip_score"), score.get("api_5day_score"),
+            score.get("spi_score"), score.get("drainage_factor"),
+            score.get("settlement_factor"), score.get("risk_level"),
+            score.get("contributing_factors", []),
+        )
+    elif db._memory:
+        return db._memory.insert("flood_risk_scores", score)
+    return None
+
+
+# --- Trigger events ---
+
+async def insert_trigger_event(db: PgConnection, event: dict) -> Optional[int]:
+    """Insert a trigger event."""
+    if db._pool:
+        return await db.fetchval(
+            """
+            INSERT INTO trigger_events (zone_id, trigger_level, triggered_at,
+                daily_precip_mm, api_5day_mm, spi_1month, composite_score,
+                contributing_factors, risk_score_id)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+            RETURNING id
+            """,
+            event["zone_id"], event["trigger_level"], event["triggered_at"],
+            event.get("daily_precip_mm"), event.get("api_5day_mm"),
+            event.get("spi_1month"), event.get("composite_score"),
+            event.get("contributing_factors", []), event.get("risk_score_id"),
+        )
+    elif db._memory:
+        return db._memory.insert("trigger_events", event)
+    return None
+
+
+async def get_trigger_events(
+    db: PgConnection, zone_id: Optional[str] = None, limit: int = 50
+) -> list[dict]:
+    """Fetch trigger events, optionally filtered by zone."""
+    if db._pool:
+        if zone_id:
+            return await db.fetch(
+                "SELECT * FROM trigger_events WHERE zone_id = $1 ORDER BY triggered_at DESC LIMIT $2",
+                zone_id, limit,
+            )
+        return await db.fetch(
+            "SELECT * FROM trigger_events ORDER BY triggered_at DESC LIMIT $1",
+            limit,
+        )
+    elif db._memory:
+        filters = {"zone_id": zone_id} if zone_id else None
+        return db._memory.query("trigger_events", filters, limit=limit)
+    return []
+
+
+# --- Basis risk ---
+
+async def insert_basis_risk(db: PgConnection, report: dict) -> Optional[int]:
+    """Insert a basis risk assessment."""
+    if db._pool:
+        return await db.fetchval(
+            """
+            INSERT INTO basis_risk (zone_id, overall_score, false_positive_rate,
+                false_negative_rate, correlation, mae, total_events,
+                true_positives, true_negatives, false_positives, false_negatives,
+                trigger_accuracy, tier_accuracy, recommendations,
+                confidence_low, confidence_high)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
+            RETURNING id
+            """,
+            report["zone_id"], report["overall_score"],
+            report.get("false_positive_rate"), report.get("false_negative_rate"),
+            report.get("correlation"), report.get("mae"),
+            report.get("total_events"), report.get("true_positives"),
+            report.get("true_negatives"), report.get("false_positives"),
+            report.get("false_negatives"), report.get("trigger_accuracy"),
+            json.dumps(report.get("tier_accuracy", {})),
+            report.get("recommendations", []),
+            report.get("confidence_low"), report.get("confidence_high"),
+        )
+    elif db._memory:
+        return db._memory.insert("basis_risk", report)
+    return None
+
+
+# --- Explanations ---
+
+async def insert_explanation(db: PgConnection, explanation: dict) -> Optional[int]:
+    """Insert a generated explanation."""
+    if db._pool:
+        return await db.fetchval(
+            """
+            INSERT INTO explanations (trigger_event_id, zone_id, trigger_level,
+                english_text, swahili_text, payout_amount, payout_currency,
+                settlement_type, protective_actions, provider)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+            RETURNING id
+            """,
+            explanation.get("trigger_event_id"), explanation["zone_id"],
+            explanation["trigger_level"], explanation["english_text"],
+            explanation["swahili_text"], explanation.get("payout_amount"),
+            explanation.get("payout_currency", "KES"),
+            explanation.get("settlement_type"),
+            explanation.get("protective_actions", []),
+            explanation.get("provider", "template"),
+        )
+    elif db._memory:
+        return db._memory.insert("explanations", explanation)
+    return None
+
+
+async def get_explanations(
+    db: PgConnection, zone_id: Optional[str] = None, limit: int = 20
+) -> list[dict]:
+    """Fetch explanations, optionally by zone."""
+    if db._pool:
+        if zone_id:
+            return await db.fetch(
+                "SELECT * FROM explanations WHERE zone_id = $1 ORDER BY generated_at DESC LIMIT $2",
+                zone_id, limit,
+            )
+        return await db.fetch(
+            "SELECT * FROM explanations ORDER BY generated_at DESC LIMIT $1",
+            limit,
+        )
+    elif db._memory:
+        filters = {"zone_id": zone_id} if zone_id else None
+        return db._memory.query("explanations", filters, limit=limit)
+    return []
+
+
+# --- Notifications ---
+
+async def insert_notification(db: PgConnection, notif: dict) -> Optional[int]:
+    """Insert a notification delivery record."""
+    if db._pool:
+        return await db.fetchval(
+            """
+            INSERT INTO notifications (explanation_id, zone_id, recipient, channel,
+                status, message_preview, message_sid, cost_estimate, error)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+            RETURNING id
+            """,
+            notif.get("explanation_id"), notif["zone_id"],
+            notif["recipient"], notif["channel"],
+            notif["status"], notif.get("message_preview"),
+            notif.get("message_sid"), notif.get("cost_estimate", 0.0),
+            notif.get("error"),
+        )
+    elif db._memory:
+        return db._memory.insert("notifications", notif)
+    return None
+
+
+async def get_notifications(
+    db: PgConnection, zone_id: Optional[str] = None, limit: int = 50
+) -> list[dict]:
+    """Fetch notification records."""
+    if db._pool:
+        if zone_id:
+            return await db.fetch(
+                "SELECT * FROM notifications WHERE zone_id = $1 ORDER BY sent_at DESC LIMIT $2",
+                zone_id, limit,
+            )
+        return await db.fetch(
+            "SELECT * FROM notifications ORDER BY sent_at DESC LIMIT $1",
+            limit,
+        )
+    elif db._memory:
+        filters = {"zone_id": zone_id} if zone_id else None
+        return db._memory.query("notifications", filters, limit=limit)
+    return []
+
+
+# --- Enrolled policies ---
+
+async def insert_policy(db: PgConnection, policy: dict) -> Optional[int]:
+    """Insert an insurance policy."""
+    if db._pool:
+        return await db.fetchval(
+            """
+            INSERT INTO enrolled_policies (policy_number, zone_id, holder_name,
+                holder_phone, holder_email, settlement_type, premium_kes,
+                coverage_start, coverage_end, payment_method)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+            ON CONFLICT (policy_number) DO NOTHING
+            RETURNING id
+            """,
+            policy.get("policy_number", f"POL-{uuid.uuid4().hex[:8].upper()}"),
+            policy["zone_id"], policy["holder_name"],
+            policy.get("holder_phone"), policy.get("holder_email"),
+            policy["settlement_type"], policy.get("premium_kes"),
+            policy["coverage_start"], policy["coverage_end"],
+            policy.get("payment_method", "mpesa"),
+        )
+    elif db._memory:
+        return db._memory.insert("enrolled_policies", policy)
+    return None
+
+
+async def get_policies_by_zone(db: PgConnection, zone_id: str) -> list[dict]:
+    """Fetch active policies for a zone."""
+    if db._pool:
+        return await db.fetch(
+            """
+            SELECT * FROM enrolled_policies
+            WHERE zone_id = $1 AND is_active = TRUE
+            ORDER BY holder_name
+            """,
+            zone_id,
+        )
+    elif db._memory:
+        return [
+            r for r in db._memory.query("enrolled_policies", {"zone_id": zone_id}, limit=1000)
+            if r.get("is_active", True)
+        ]
+    return []
+
+
+# --- Pipeline runs ---
+
+async def start_pipeline_run(db: PgConnection, run_id: Optional[str] = None) -> str:
+    """Record the start of a pipeline run. Returns run_id."""
+    rid = run_id or f"run-{uuid.uuid4().hex[:12]}"
+    now = datetime.now(timezone.utc).isoformat()
+
+    if db._pool:
+        await db.execute(
+            """
+            INSERT INTO pipeline_runs (run_id, started_at, status)
+            VALUES ($1, $2, 'running')
+            """,
+            rid, now,
+        )
+    elif db._memory:
+        db._memory.insert("pipeline_runs", {
+            "run_id": rid, "started_at": now, "status": "running",
+        })
+    return rid
+
+
+async def finish_pipeline_run(
+    db: PgConnection,
+    run_id: str,
+    status: str = "completed",
+    steps_completed: Optional[list[str]] = None,
+    step_status: Optional[dict] = None,
+    error: Optional[str] = None,
+    zones_processed: int = 0,
+) -> None:
+    """Record the completion of a pipeline run."""
+    now = datetime.now(timezone.utc).isoformat()
+
+    if db._pool:
+        await db.execute(
+            """
+            UPDATE pipeline_runs
+            SET finished_at = $2, status = $3, steps_completed = $4,
+                step_status = $5, error = $6, zones_processed = $7
+            WHERE run_id = $1
+            """,
+            run_id, now, status,
+            steps_completed or [],
+            json.dumps(step_status or {}),
+            error, zones_processed,
+        )
+    elif db._memory:
+        for row in db._memory.tables.get("pipeline_runs", []):
+            if row.get("run_id") == run_id:
+                row["finished_at"] = now
+                row["status"] = status
+                row["steps_completed"] = steps_completed or []
+                row["step_status"] = step_status or {}
+                row["error"] = error
+                row["zones_processed"] = zones_processed
+                break
+
+
+async def get_recent_runs(db: PgConnection, limit: int = 10) -> list[dict]:
+    """Fetch recent pipeline runs."""
+    if db._pool:
+        return await db.fetch(
+            "SELECT * FROM pipeline_runs ORDER BY started_at DESC LIMIT $1",
+            limit,
+        )
+    elif db._memory:
+        rows = db._memory.query("pipeline_runs", limit=limit)
+        return sorted(rows, key=lambda r: r.get("started_at", ""), reverse=True)
+    return []

src/database/schema.py

@@ -0,0 +1,319 @@
+"""
+PostgreSQL schema for the Climate Risk Index Engine.
+
+All table definitions as SQL strings with proper types, foreign keys,
+indexes, and constraints.  Tables are designed to be created in order
+(referenced tables first).
+"""
+
+from __future__ import annotations
+
+
+# ── Table creation order (respects foreign keys) ─────────────────────────
+
+TABLES_ORDERED: list[str] = [
+    "zones",
+    "daily_readings",
+    "healed_readings",
+    "healing_log",
+    "monthly_indices",
+    "flood_risk_scores",
+    "enrolled_policies",
+    "trigger_events",
+    "basis_risk",
+    "explanations",
+    "notifications",
+    "pipeline_runs",
+]
+
+
+# ── DDL statements ───────────────────────────────────────────────────────
+
+CREATE_ZONES = """
+CREATE TABLE IF NOT EXISTS zones (
+    zone_id         TEXT PRIMARY KEY,
+    name            TEXT NOT NULL,
+    city            TEXT NOT NULL,
+    country         TEXT NOT NULL,
+    latitude        DOUBLE PRECISION NOT NULL,
+    longitude       DOUBLE PRECISION NOT NULL,
+    elevation_m     DOUBLE PRECISION,
+    area_km2        DOUBLE PRECISION,
+    population_est  INTEGER,
+    settlement_type TEXT NOT NULL CHECK (settlement_type IN ('formal', 'informal', 'mixed', 'commercial')),
+    flood_susceptibility TEXT NOT NULL CHECK (flood_susceptibility IN ('high', 'moderate', 'low')),
+    drainage_quality TEXT NOT NULL CHECK (drainage_quality IN ('poor', 'moderate', 'good')),
+    primary_flood_type TEXT,
+    rainy_seasons   INTEGER[],
+    notes           TEXT DEFAULT '',
+    created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_zones_city ON zones (city);
+CREATE INDEX IF NOT EXISTS idx_zones_settlement ON zones (settlement_type);
+"""
+
+CREATE_DAILY_READINGS = """
+CREATE TABLE IF NOT EXISTS daily_readings (
+    id              BIGSERIAL PRIMARY KEY,
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    date            DATE NOT NULL,
+    precip_mm       DOUBLE PRECISION,
+    precip_nasa_mm  DOUBLE PRECISION,
+    precip_chirps_mm DOUBLE PRECISION,
+    temp_mean_c     DOUBLE PRECISION,
+    temp_max_c      DOUBLE PRECISION,
+    temp_min_c      DOUBLE PRECISION,
+    humidity_pct    DOUBLE PRECISION,
+    wind_speed_ms   DOUBLE PRECISION,
+    source          TEXT DEFAULT 'unknown',
+    source_agreement DOUBLE PRECISION,
+    data_quality    DOUBLE PRECISION DEFAULT 0.0,
+    ingested_at     TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE (zone_id, date)
+);
+
+CREATE INDEX IF NOT EXISTS idx_daily_readings_zone_date ON daily_readings (zone_id, date DESC);
+CREATE INDEX IF NOT EXISTS idx_daily_readings_date ON daily_readings (date DESC);
+"""
+
+CREATE_HEALED_READINGS = """
+CREATE TABLE IF NOT EXISTS healed_readings (
+    id              BIGSERIAL PRIMARY KEY,
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    date            DATE NOT NULL,
+    raw_reading_id  BIGINT REFERENCES daily_readings(id),
+    precip_mm       DOUBLE PRECISION,
+    temp_mean_c     DOUBLE PRECISION,
+    temp_max_c      DOUBLE PRECISION,
+    temp_min_c      DOUBLE PRECISION,
+    humidity_pct    DOUBLE PRECISION,
+    wind_speed_ms   DOUBLE PRECISION,
+    quality_score   DOUBLE PRECISION DEFAULT 0.0,
+    heal_action     TEXT DEFAULT 'passthrough',
+    fields_corrected TEXT[] DEFAULT '{}',
+    healed_at       TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE (zone_id, date)
+);
+
+CREATE INDEX IF NOT EXISTS idx_healed_readings_zone_date ON healed_readings (zone_id, date DESC);
+CREATE INDEX IF NOT EXISTS idx_healed_readings_quality ON healed_readings (quality_score);
+"""
+
+CREATE_HEALING_LOG = """
+CREATE TABLE IF NOT EXISTS healing_log (
+    id              BIGSERIAL PRIMARY KEY,
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    date            DATE NOT NULL,
+    healed_reading_id BIGINT REFERENCES healed_readings(id),
+    agent_type      TEXT DEFAULT 'rule_based',
+    reasoning       TEXT,
+    corrections     JSONB DEFAULT '{}',
+    tools_used      TEXT[] DEFAULT '{}',
+    confidence      DOUBLE PRECISION,
+    tokens_used     INTEGER DEFAULT 0,
+    latency_ms      INTEGER DEFAULT 0,
+    created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_healing_log_zone ON healing_log (zone_id, date DESC);
+"""
+
+CREATE_MONTHLY_INDICES = """
+CREATE TABLE IF NOT EXISTS monthly_indices (
+    id              BIGSERIAL PRIMARY KEY,
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    year            INTEGER NOT NULL,
+    month           INTEGER NOT NULL CHECK (month BETWEEN 1 AND 12),
+    spi_1           DOUBLE PRECISION,
+    spi_3           DOUBLE PRECISION,
+    spi_6           DOUBLE PRECISION,
+    total_precip_mm DOUBLE PRECISION,
+    mean_precip_mm  DOUBLE PRECISION,
+    precip_days     INTEGER,
+    precip_anomaly_pct DOUBLE PRECISION,
+    computed_at     TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE (zone_id, year, month)
+);
+
+CREATE INDEX IF NOT EXISTS idx_monthly_indices_zone_ym ON monthly_indices (zone_id, year DESC, month DESC);
+"""
+
+CREATE_FLOOD_RISK_SCORES = """
+CREATE TABLE IF NOT EXISTS flood_risk_scores (
+    id              BIGSERIAL PRIMARY KEY,
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    date            DATE NOT NULL,
+    composite_score DOUBLE PRECISION NOT NULL CHECK (composite_score BETWEEN 0 AND 1),
+    precip_score    DOUBLE PRECISION,
+    api_5day_score  DOUBLE PRECISION,
+    spi_score       DOUBLE PRECISION,
+    drainage_factor DOUBLE PRECISION,
+    settlement_factor DOUBLE PRECISION,
+    risk_level      TEXT CHECK (risk_level IN ('low', 'moderate', 'high', 'critical')),
+    contributing_factors TEXT[] DEFAULT '{}',
+    computed_at     TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE (zone_id, date)
+);
+
+CREATE INDEX IF NOT EXISTS idx_flood_risk_zone_date ON flood_risk_scores (zone_id, date DESC);
+CREATE INDEX IF NOT EXISTS idx_flood_risk_level ON flood_risk_scores (risk_level);
+"""
+
+CREATE_ENROLLED_POLICIES = """
+CREATE TABLE IF NOT EXISTS enrolled_policies (
+    id              BIGSERIAL PRIMARY KEY,
+    policy_number   TEXT UNIQUE NOT NULL,
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    holder_name     TEXT NOT NULL,
+    holder_phone    TEXT,
+    holder_email    TEXT,
+    settlement_type TEXT NOT NULL CHECK (settlement_type IN ('formal', 'informal', 'mixed', 'commercial', 'residential')),
+    premium_kes     DOUBLE PRECISION,
+    coverage_start  DATE NOT NULL,
+    coverage_end    DATE NOT NULL,
+    payment_method  TEXT DEFAULT 'mpesa' CHECK (payment_method IN ('mpesa', 'bank', 'cash')),
+    is_active       BOOLEAN DEFAULT TRUE,
+    created_at      TIMESTAMPTZ DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_policies_zone ON enrolled_policies (zone_id);
+CREATE INDEX IF NOT EXISTS idx_policies_active ON enrolled_policies (is_active) WHERE is_active = TRUE;
+CREATE INDEX IF NOT EXISTS idx_policies_phone ON enrolled_policies (holder_phone);
+"""
+
+CREATE_TRIGGER_EVENTS = """
+CREATE TABLE IF NOT EXISTS trigger_events (
+    id              BIGSERIAL PRIMARY KEY,
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    trigger_level   TEXT NOT NULL CHECK (trigger_level IN ('critical', 'warning', 'watch')),
+    triggered_at    TIMESTAMPTZ NOT NULL,
+    daily_precip_mm DOUBLE PRECISION,
+    api_5day_mm     DOUBLE PRECISION,
+    spi_1month      DOUBLE PRECISION,
+    composite_score DOUBLE PRECISION,
+    contributing_factors TEXT[] DEFAULT '{}',
+    risk_score_id   BIGINT REFERENCES flood_risk_scores(id),
+    resolved_at     TIMESTAMPTZ,
+    resolution_notes TEXT,
+    created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_trigger_events_zone ON trigger_events (zone_id, triggered_at DESC);
+CREATE INDEX IF NOT EXISTS idx_trigger_events_level ON trigger_events (trigger_level);
+CREATE INDEX IF NOT EXISTS idx_trigger_events_unresolved ON trigger_events (zone_id) WHERE resolved_at IS NULL;
+"""
+
+CREATE_BASIS_RISK = """
+CREATE TABLE IF NOT EXISTS basis_risk (
+    id              BIGSERIAL PRIMARY KEY,
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    assessed_at     TIMESTAMPTZ DEFAULT NOW(),
+    overall_score   DOUBLE PRECISION NOT NULL CHECK (overall_score BETWEEN 0 AND 1),
+    false_positive_rate DOUBLE PRECISION,
+    false_negative_rate DOUBLE PRECISION,
+    correlation     DOUBLE PRECISION,
+    mae             DOUBLE PRECISION,
+    total_events    INTEGER,
+    true_positives  INTEGER,
+    true_negatives  INTEGER,
+    false_positives INTEGER,
+    false_negatives INTEGER,
+    trigger_accuracy DOUBLE PRECISION,
+    tier_accuracy   JSONB DEFAULT '{}',
+    recommendations TEXT[] DEFAULT '{}',
+    confidence_low  DOUBLE PRECISION,
+    confidence_high DOUBLE PRECISION
+);
+
+CREATE INDEX IF NOT EXISTS idx_basis_risk_zone ON basis_risk (zone_id, assessed_at DESC);
+"""
+
+CREATE_EXPLANATIONS = """
+CREATE TABLE IF NOT EXISTS explanations (
+    id              BIGSERIAL PRIMARY KEY,
+    trigger_event_id BIGINT REFERENCES trigger_events(id),
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    trigger_level   TEXT NOT NULL,
+    english_text    TEXT NOT NULL,
+    swahili_text    TEXT NOT NULL,
+    payout_amount   DOUBLE PRECISION,
+    payout_currency TEXT DEFAULT 'KES',
+    settlement_type TEXT,
+    protective_actions TEXT[] DEFAULT '{}',
+    provider        TEXT DEFAULT 'template',
+    generated_at    TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_explanations_trigger ON explanations (trigger_event_id);
+CREATE INDEX IF NOT EXISTS idx_explanations_zone ON explanations (zone_id, generated_at DESC);
+"""
+
+CREATE_NOTIFICATIONS = """
+CREATE TABLE IF NOT EXISTS notifications (
+    id              BIGSERIAL PRIMARY KEY,
+    explanation_id  BIGINT REFERENCES explanations(id),
+    zone_id         TEXT NOT NULL REFERENCES zones(zone_id),
+    recipient       TEXT NOT NULL,
+    channel         TEXT NOT NULL CHECK (channel IN ('console', 'sms', 'whatsapp')),
+    status          TEXT NOT NULL CHECK (status IN ('sent', 'failed', 'dry_run', 'pending')),
+    message_preview TEXT,
+    message_sid     TEXT,
+    cost_estimate   DOUBLE PRECISION DEFAULT 0.0,
+    error           TEXT,
+    sent_at         TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_notifications_zone ON notifications (zone_id, sent_at DESC);
+CREATE INDEX IF NOT EXISTS idx_notifications_status ON notifications (status);
+CREATE INDEX IF NOT EXISTS idx_notifications_recipient ON notifications (recipient);
+"""
+
+CREATE_PIPELINE_RUNS = """
+CREATE TABLE IF NOT EXISTS pipeline_runs (
+    id              BIGSERIAL PRIMARY KEY,
+    run_id          TEXT UNIQUE NOT NULL,
+    started_at      TIMESTAMPTZ NOT NULL,
+    finished_at     TIMESTAMPTZ,
+    status          TEXT DEFAULT 'running' CHECK (status IN ('running', 'completed', 'failed', 'partial')),
+    zones_processed INTEGER DEFAULT 0,
+    steps_completed TEXT[] DEFAULT '{}',
+    step_status     JSONB DEFAULT '{}',
+    error           TEXT,
+    duration_s      DOUBLE PRECISION,
+    config_snapshot JSONB DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS idx_pipeline_runs_status ON pipeline_runs (status);
+CREATE INDEX IF NOT EXISTS idx_pipeline_runs_started ON pipeline_runs (started_at DESC);
+"""
+
+
+# ── Aggregate DDL ────────────────────────────────────────────────────────
+
+ALL_DDL: dict[str, str] = {
+    "zones": CREATE_ZONES,
+    "daily_readings": CREATE_DAILY_READINGS,
+    "healed_readings": CREATE_HEALED_READINGS,
+    "healing_log": CREATE_HEALING_LOG,
+    "monthly_indices": CREATE_MONTHLY_INDICES,
+    "flood_risk_scores": CREATE_FLOOD_RISK_SCORES,
+    "enrolled_policies": CREATE_ENROLLED_POLICIES,
+    "trigger_events": CREATE_TRIGGER_EVENTS,
+    "basis_risk": CREATE_BASIS_RISK,
+    "explanations": CREATE_EXPLANATIONS,
+    "notifications": CREATE_NOTIFICATIONS,
+    "pipeline_runs": CREATE_PIPELINE_RUNS,
+}
+
+
+def get_full_ddl() -> str:
+    """Return the complete DDL script to create all tables in order."""
+    parts = [f"-- Table: {name}\n{ddl}" for name, ddl in ALL_DDL.items()]
+    return "\n\n".join(parts)
+
+
+def get_table_names() -> list[str]:
+    """Return table names in creation order."""
+    return list(TABLES_ORDERED)

src/downscaling/uhi_model.py

@@ -0,0 +1,274 @@
+"""
+Urban Heat Island (UHI) ML correction model.
+
+Adjusts ERA5-Land grid-cell temperature to neighborhood-level using
+zone characteristics (settlement type, outdoor exposure, elevation)
+and temporal features (hour, month).
+
+Calibrated to published UHI literature for tropical African cities:
+  - Informal settlements (tin roofs, no shade): +3 to +6 C
+  - Mixed zones: +1 to +3 C
+  - Formal residential: +0.5 to +1.5 C
+  - Commercial districts: +1 to +2 C
+
+References:
+  - Oke et al. (2017) Urban Climates, Cambridge University Press
+  - Scott et al. (2017) UHI in African cities, Urban Climate
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+try:
+    import xgboost as xgb
+except ImportError:
+    xgb = None
+
+# Settlement type encoding order (for one-hot)
+SETTLEMENT_TYPES = ["informal", "mixed", "formal", "commercial"]
+
+# UHI delta ranges by settlement type (daytime peak, deg C)
+UHI_RANGES = {
+    "informal": (3.0, 6.0),
+    "mixed": (1.0, 3.0),
+    "formal": (0.5, 1.5),
+    "commercial": (1.0, 2.0),
+}
+
+# Vulnerability multipliers
+VULNERABILITY_MULT = {"high": 1.15, "moderate": 1.0, "low": 0.85}
+
+
+def _resolve_model_path(model_path: str) -> Path:
+    """Resolve model path relative to the project root."""
+    p = Path(model_path)
+    if not p.is_absolute():
+        p = Path(__file__).resolve().parents[2] / model_path
+    return p
+
+
+class UHICorrector:
+    """XGBoost model: zone characteristics -> temperature delta from grid."""
+
+    def __init__(self, model_path: str = "models/uhi_xgb.json"):
+        if xgb is None:
+            raise ImportError(
+                "xgboost is required. Install with: pip install 'xgboost>=2.0.0'"
+            )
+        self.model_path = _resolve_model_path(model_path)
+        self.model: xgb.XGBRegressor | None = None
+        self._load_or_train()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def correct_temperature(
+        self,
+        zone,
+        grid_temp_c: float,
+        hour: int = 12,
+        month: int = 3,
+    ) -> tuple[float, float, float]:
+        """Return (corrected_temp, uhi_delta, confidence).
+
+        Args:
+            zone: An UrbanZone instance (from config.ZONES).
+            grid_temp_c: ERA5-Land grid temperature in deg C.
+            hour: Local hour (0-23).
+            month: Month (1-12).
+
+        Returns:
+            Tuple of (corrected temperature, UHI delta, confidence 0-1).
+        """
+        features = self._build_features(zone, hour, month)
+        delta = float(self.model.predict(features)[0])
+
+        # Confidence based on how well the zone matches training regime
+        confidence = self._estimate_confidence(zone, hour, month)
+
+        return round(grid_temp_c + delta, 2), round(delta, 2), round(confidence, 3)
+
+    # ------------------------------------------------------------------
+    # Training
+    # ------------------------------------------------------------------
+
+    def train(self, n_samples: int = 5000, seed: int = 42) -> None:
+        """Generate synthetic training data and train the XGBoost model.
+
+        Creates samples from the 20 configured zones across varying
+        hours (0-23) and months (1-12), with UHI deltas drawn from
+        literature-calibrated distributions.
+        """
+        rng = np.random.default_rng(seed)
+
+        # Import zones lazily to avoid circular imports at module level
+        from config import ZONES  # noqa: WPS433
+
+        X_rows = []
+        y_rows = []
+
+        samples_per_zone = n_samples // len(ZONES)
+        extra = n_samples - samples_per_zone * len(ZONES)
+
+        for idx, zone in enumerate(ZONES):
+            n = samples_per_zone + (1 if idx < extra else 0)
+            hours = rng.integers(0, 24, size=n)
+            months = rng.integers(1, 13, size=n)
+
+            for h, m in zip(hours, months):
+                feat = self._build_features(zone, int(h), int(m))
+                X_rows.append(feat[0])
+
+                delta = self._synthetic_delta(zone, int(h), int(m), rng)
+                y_rows.append(delta)
+
+        X = np.array(X_rows, dtype=np.float32)
+        y = np.array(y_rows, dtype=np.float32)
+
+        self.model = xgb.XGBRegressor(
+            n_estimators=100,
+            max_depth=4,
+            learning_rate=0.1,
+            random_state=seed,
+        )
+        self.model.fit(X, y)
+        self._save_model()
+
+    # ------------------------------------------------------------------
+    # Feature engineering
+    # ------------------------------------------------------------------
+
+    def _build_features(self, zone, hour: int, month: int) -> np.ndarray:
+        """Construct feature vector from zone + time.
+
+        Features (12 total):
+            0-3: settlement_type one-hot (informal, mixed, formal, commercial)
+            4:   outdoor_exposure_pct
+            5:   elevation_m (scaled /1000)
+            6:   heat_vulnerability encoded (high=1, moderate=0.5, low=0)
+            7-8: hour_sin, hour_cos
+            9-10: month_sin, month_cos
+            11:  outdoor_exposure * vulnerability interaction
+        """
+        # Settlement one-hot
+        onehot = [0.0] * len(SETTLEMENT_TYPES)
+        if zone.settlement_type in SETTLEMENT_TYPES:
+            onehot[SETTLEMENT_TYPES.index(zone.settlement_type)] = 1.0
+
+        # Vulnerability numeric
+        vuln_map = {"high": 1.0, "moderate": 0.5, "low": 0.0}
+        vuln = vuln_map.get(zone.heat_vulnerability, 0.5)
+
+        # Cyclic time encoding
+        hour_sin = np.sin(2 * np.pi * hour / 24.0)
+        hour_cos = np.cos(2 * np.pi * hour / 24.0)
+        month_sin = np.sin(2 * np.pi * (month - 1) / 12.0)
+        month_cos = np.cos(2 * np.pi * (month - 1) / 12.0)
+
+        # Interaction term
+        interaction = zone.outdoor_exposure_pct * vuln
+
+        features = np.array(
+            onehot
+            + [
+                zone.outdoor_exposure_pct,
+                zone.elevation_m / 1000.0,
+                vuln,
+                hour_sin,
+                hour_cos,
+                month_sin,
+                month_cos,
+                interaction,
+            ],
+            dtype=np.float32,
+        ).reshape(1, -1)
+
+        return features
+
+    # ------------------------------------------------------------------
+    # Synthetic data generation
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _synthetic_delta(zone, hour: int, month: int, rng) -> float:
+        """Generate a single UHI delta calibrated to literature.
+
+        Key drivers:
+        1. Settlement type (biggest factor) — sets the base range.
+        2. Time of day — UHI peaks at night (urban surfaces release
+           stored heat), smaller during daytime due to rural insolation.
+        3. Season — hot dry months amplify UHI; cool/wet months dampen.
+        4. Elevation — higher elevation slightly reduces UHI.
+        """
+        lo, hi = UHI_RANGES.get(zone.settlement_type, (1.0, 3.0))
+        base = rng.uniform(lo, hi)
+
+        # Nocturnal amplification: UHI peaks around 22:00-04:00
+        # Minimum around 10:00-14:00 (rural catches up via insolation)
+        hour_factor = 1.0 + 0.35 * np.cos(2 * np.pi * (hour - 1) / 24.0)
+
+        # Seasonal modulation: hot months get +10-15%, cool months -10%
+        is_hot_month = month in getattr(zone, "hot_months", [])
+        season_factor = 1.12 if is_hot_month else 0.90
+
+        # Elevation damping: higher = slightly less UHI
+        elev_factor = max(0.7, 1.0 - zone.elevation_m / 5000.0)
+
+        # Vulnerability/exposure boost
+        vuln_mult = VULNERABILITY_MULT.get(zone.heat_vulnerability, 1.0)
+
+        delta = base * hour_factor * season_factor * elev_factor * vuln_mult
+        # Add noise
+        delta += rng.normal(0, 0.3)
+
+        return float(max(0.0, delta))
+
+    # ------------------------------------------------------------------
+    # Confidence estimation
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _estimate_confidence(zone, hour: int, month: int) -> float:
+        """Heuristic confidence score (0-1).
+
+        Higher confidence for:
+        - Informal/mixed settlements (most UHI literature covers these)
+        - Daytime hours (better-studied regime)
+        - Hot-season months (more extreme, easier to model)
+        """
+        conf = 0.75  # baseline
+
+        # Settlement coverage
+        if zone.settlement_type in ("informal", "mixed"):
+            conf += 0.10
+        elif zone.settlement_type == "commercial":
+            conf += 0.05
+
+        # Daytime boost
+        if 6 <= hour <= 18:
+            conf += 0.05
+
+        # Hot season
+        if month in getattr(zone, "hot_months", []):
+            conf += 0.05
+
+        return min(conf, 0.95)
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    def _save_model(self) -> None:
+        self.model_path.parent.mkdir(parents=True, exist_ok=True)
+        self.model.save_model(str(self.model_path))
+
+    def _load_or_train(self) -> None:
+        if self.model_path.exists():
+            self.model = xgb.XGBRegressor()
+            self.model.load_model(str(self.model_path))
+        else:
+            self.train()

src/explanation/explainer.py

@@ -0,0 +1,363 @@
+"""
+Claude-powered heat alert explanation generator.
+
+When a heat risk trigger fires, enrolled workers need a plain-language
+explanation of WHY, what it means for their payout, and what protective
+actions to take. This module generates bilingual (English + Swahili)
+explanations using Claude with RAG context, with a template-based
+fallback if Claude is unavailable.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from config import HEAT_THRESHOLDS, PAYOUT_PER_EVENT_USD, ZONE_MAP, UrbanZone
+from src.explanation.knowledge_base import (
+    INSURANCE_PRODUCT_INFO,
+    SWAHILI_TERMS,
+    get_emergency_contacts,
+    get_protective_actions,
+    get_zone_context,
+)
+
+log = logging.getLogger(__name__)
+
+
+# -- Data containers -------------------------------------------------------
+
+@dataclass
+class TriggerEvent:
+    """A triggered insurance event to be explained."""
+    zone_id: str
+    trigger_level: str  # critical, warning, watch
+    triggered_at: str  # ISO timestamp
+    max_temp_c: float = 0.0
+    max_wbgt_c: float = 0.0
+    consecutive_days: int = 0
+    heat_risk_score: float = 0.0
+    contributing_factors: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ExplanationResult:
+    """Generated explanation for a trigger event."""
+    zone_id: str
+    trigger_level: str
+    english_text: str
+    swahili_text: str
+    payout_estimate: Dict[str, Any]
+    protective_actions: list[str]
+    emergency_contacts: Dict[str, str]
+    generated_at: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat()
+    )
+    provider: str = "template"  # claude or template
+    zone_name: str = ""
+    city: str = ""
+    zone_context: str = ""
+    tokens_used: int = 0
+
+
+# -- Claude-based explainer ------------------------------------------------
+
+class TriggerExplainer:
+    """Generates bilingual heat alert explanations using Claude with RAG."""
+
+    def __init__(self, api_key: Optional[str] = None, model: str = "claude-sonnet-4-20250514"):
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+        self.model = model
+        self._client = None
+
+    def _get_client(self):
+        if self._client is None:
+            try:
+                import anthropic
+                self._client = anthropic.AsyncAnthropic(api_key=self.api_key)
+            except Exception as exc:
+                log.warning("Could not init Anthropic client: %s", exc)
+        return self._client
+
+    async def explain(self, event, zone=None, basis_risk=None) -> ExplanationResult:
+        """Generate a full explanation for a heat trigger event."""
+        # Support both TriggerEvent and HeatTriggerEvent dataclass inputs
+        zone_id = getattr(event, 'zone_id', '')
+        trigger_level = getattr(event, 'trigger_level', 'watch')
+
+        zone_obj = zone or ZONE_MAP.get(zone_id)
+        if zone_obj is None:
+            raise ValueError(f"Unknown zone: {zone_id}")
+
+        payout = _compute_payout(event, zone_obj)
+        actions = get_protective_actions(trigger_level)
+        contacts = get_emergency_contacts(zone_obj.city)
+
+        if self.api_key:
+            try:
+                english, swahili = await self._generate_claude(event, zone_obj, payout)
+                return ExplanationResult(
+                    zone_id=zone_id,
+                    trigger_level=trigger_level,
+                    english_text=english,
+                    swahili_text=swahili,
+                    payout_estimate=payout,
+                    protective_actions=actions,
+                    emergency_contacts=contacts,
+                    provider="claude",
+                    zone_name=zone_obj.name,
+                    city=zone_obj.city,
+                    zone_context=get_zone_context(zone_id),
+                )
+            except Exception as exc:
+                log.warning("Claude explanation failed, using template: %s", exc)
+
+        english = _template_english(event, zone_obj, payout)
+        swahili = _template_swahili(event, zone_obj, payout)
+        return ExplanationResult(
+            zone_id=zone_id,
+            trigger_level=trigger_level,
+            english_text=english,
+            swahili_text=swahili,
+            payout_estimate=payout,
+            protective_actions=actions,
+            emergency_contacts=contacts,
+            provider="template",
+            zone_name=zone_obj.name,
+            city=zone_obj.city,
+            zone_context=get_zone_context(zone_id),
+        )
+
+    async def _generate_claude(
+        self, event, zone: UrbanZone, payout: Dict[str, Any]
+    ) -> tuple[str, str]:
+        context = get_zone_context(event.zone_id)
+
+        system = (
+            "You are a heat safety notification system for outdoor workers in East Africa. "
+            "Your audience is workers in markets, construction sites, and informal "
+            "settlements — many with limited formal education. Write clearly, simply, "
+            "and with empathy. Do not use jargon or technical abbreviations. "
+            "Explain what happened, what their payout is, and what they should do to "
+            "stay safe. Keep the explanation to 4-6 sentences."
+        )
+
+        max_temp = getattr(event, 'max_temp_c', 0)
+        max_wbgt = getattr(event, 'max_wbgt_c', 0)
+        consec = getattr(event, 'consecutive_days', getattr(event, 'consecutive_days_above', 0))
+        thresholds = HEAT_THRESHOLDS.get(event.trigger_level, {})
+
+        user = (
+            f"A {event.trigger_level.upper()} heat alert has been triggered for "
+            f"outdoor workers in {zone.name}, {zone.city}.\n\n"
+            f"What happened:\n"
+            f"- Maximum temperature: {max_temp:.1f}C "
+            f"(threshold: {thresholds.get('temp_c', 'N/A')}C)\n"
+            f"- Maximum WBGT (feels-like for workers): {max_wbgt:.1f}C "
+            f"(threshold: {thresholds.get('wbgt_c', 'N/A')}C)\n"
+            f"- Consecutive days above threshold: {consec} "
+            f"(required: {thresholds.get('consecutive_days', 'N/A')})\n"
+            f"- Settlement type: {zone.settlement_type}\n"
+            f"- Outdoor worker exposure: {zone.outdoor_exposure_pct:.0%}\n"
+            f"- Estimated workers affected: {zone.worker_population_est:,}\n\n"
+            f"Payout: {payout['currency_symbol']}{payout['amount']} per worker\n\n"
+            f"Knowledge base:\n{context}\n\n"
+            f"Write a 4-6 sentence explanation for the worker. Tell them what is "
+            f"happening with the heat, their payout amount, and the most important "
+            f"thing they should do right now to stay safe."
+        )
+
+        client = self._get_client()
+        if client is None:
+            raise RuntimeError("Anthropic client not available")
+
+        msg = await client.messages.create(
+            model=self.model,
+            max_tokens=500,
+            system=system,
+            messages=[{"role": "user", "content": user}],
+        )
+        english = msg.content[0].text.strip()
+        swahili = await self._translate_to_swahili(english, zone.name)
+        return english, swahili
+
+    async def _translate_to_swahili(self, english_text: str, zone_name: str) -> str:
+        system = (
+            "You are a professional translator specializing in Swahili (Kiswahili). "
+            "Translate the given English heat safety notification to simple, clear "
+            "Swahili that a non-technical person can understand. Keep numbers, "
+            "currency amounts, and proper nouns unchanged. Return only the translated text."
+        )
+        user = (
+            f"Translate this heat alert notification for workers in {zone_name} "
+            f"to Swahili:\n\n{english_text}"
+        )
+
+        client = self._get_client()
+        if client is None:
+            raise RuntimeError("Anthropic client not available")
+
+        msg = await client.messages.create(
+            model=self.model,
+            max_tokens=600,
+            system=system,
+            messages=[{"role": "user", "content": user}],
+        )
+        return msg.content[0].text.strip()
+
+
+# -- Template-based fallback explainer (same interface) --------------------
+
+class TemplateExplainer:
+    """Template-based fallback when Claude is unavailable."""
+
+    async def explain(self, event, zone=None, basis_risk=None) -> ExplanationResult:
+        zone_id = getattr(event, 'zone_id', '')
+        trigger_level = getattr(event, 'trigger_level', 'watch')
+        zone_obj = zone or ZONE_MAP.get(zone_id)
+        if zone_obj is None:
+            raise ValueError(f"Unknown zone: {zone_id}")
+
+        payout = _compute_payout(event, zone_obj)
+        actions = get_protective_actions(trigger_level)
+        contacts = get_emergency_contacts(zone_obj.city)
+
+        english = _template_english(event, zone_obj, payout)
+        swahili = _template_swahili(event, zone_obj, payout)
+
+        return ExplanationResult(
+            zone_id=zone_id,
+            trigger_level=trigger_level,
+            english_text=english,
+            swahili_text=swahili,
+            payout_estimate=payout,
+            protective_actions=actions,
+            emergency_contacts=contacts,
+            provider="template",
+            zone_name=zone_obj.name,
+            city=zone_obj.city,
+            zone_context=get_zone_context(zone_id),
+        )
+
+
+# -- Payout computation ---------------------------------------------------
+
+def _compute_payout(event, zone: UrbanZone) -> Dict[str, Any]:
+    trigger_level = getattr(event, 'trigger_level', 'watch')
+    amount = PAYOUT_PER_EVENT_USD.get(trigger_level, 0)
+
+    return {
+        "amount": amount,
+        "currency": "USD",
+        "currency_symbol": "$",
+        "settlement_type": zone.settlement_type,
+        "trigger_level": trigger_level,
+        "delivery_method": "M-Pesa" if zone.settlement_type in ("informal", "mixed") else "Mobile money",
+        "expected_delivery": "Within 48 hours of trigger verification",
+        "is_payout": amount > 0,
+        "workers_covered": zone.worker_population_est,
+        "total_payout": amount * zone.worker_population_est,
+    }
+
+
+# -- Template-based fallback explanations ----------------------------------
+
+_LEVEL_DESCRIPTIONS = {
+    "critical": (
+        "A CRITICAL heat alert has been triggered",
+        "Onyo la HATARI la joto kali limetolewa",
+    ),
+    "warning": (
+        "A WARNING heat alert has been issued",
+        "Onyo la joto limetolewa",
+    ),
+    "watch": (
+        "A WATCH heat advisory has been issued",
+        "Tahadhari ya joto imetolewa",
+    ),
+}
+
+
+def _template_english(event, zone: UrbanZone, payout: Dict[str, Any]) -> str:
+    trigger_level = getattr(event, 'trigger_level', 'watch')
+    level_en, _ = _LEVEL_DESCRIPTIONS.get(trigger_level, ("A heat alert has been issued", ""))
+
+    max_temp = getattr(event, 'max_temp_c', 0)
+    max_wbgt = getattr(event, 'max_wbgt_c', 0)
+    consec = getattr(event, 'consecutive_days', getattr(event, 'consecutive_days_above', 0))
+
+    lines = [f"{level_en} for outdoor workers in {zone.name}, {zone.city}."]
+
+    thresholds = HEAT_THRESHOLDS.get(trigger_level, {})
+    reasons: list[str] = []
+    if max_temp >= thresholds.get("temp_c", 999):
+        reasons.append(
+            f"temperatures reached {max_temp:.0f}C, above the "
+            f"{thresholds['temp_c']}C safety threshold"
+        )
+    if max_wbgt >= thresholds.get("wbgt_c", 999):
+        reasons.append(
+            f"the heat-humidity index (WBGT) reached {max_wbgt:.0f}C, "
+            f"above the {thresholds['wbgt_c']}C danger level"
+        )
+    if consec >= thresholds.get("consecutive_days", 999):
+        reasons.append(
+            f"these dangerous conditions lasted {consec} consecutive days"
+        )
+
+    if reasons:
+        lines.append("This was triggered because " + " and ".join(reasons) + ".")
+    else:
+        lines.append("Heat conditions have exceeded the safety threshold for your area.")
+
+    if payout["is_payout"]:
+        lines.append(
+            f"Your payout is {payout['currency_symbol']}{payout['amount']} per worker, "
+            f"which will be sent via {payout['delivery_method']} within 48 hours."
+        )
+
+    actions = get_protective_actions(trigger_level)
+    if actions:
+        lines.append(f"Most important: {actions[0]}")
+
+    return " ".join(lines)
+
+
+def _template_swahili(event, zone: UrbanZone, payout: Dict[str, Any]) -> str:
+    trigger_level = getattr(event, 'trigger_level', 'watch')
+    _, level_sw = _LEVEL_DESCRIPTIONS.get(trigger_level, ("", "Onyo la joto limetolewa"))
+
+    max_temp = getattr(event, 'max_temp_c', 0)
+    consec = getattr(event, 'consecutive_days', getattr(event, 'consecutive_days_above', 0))
+
+    lines = [f"{level_sw} kwa wafanyakazi wa nje katika {zone.name}, {zone.city}."]
+
+    lines.append(
+        f"Joto limefika {max_temp:.0f}C kwa siku {consec} mfululizo."
+    )
+
+    if payout["is_payout"]:
+        lines.append(
+            f"Malipo yako ni {payout['currency_symbol']}{payout['amount']} kwa kila mfanyakazi. "
+            f"Utapokea kupitia {payout['delivery_method']} ndani ya masaa 48."
+        )
+
+    if trigger_level == "critical":
+        lines.append(
+            "Acha kazi za nje sasa hivi. Nenda kivulini au ndani ya nyumba. "
+            "Kunywa maji mengi."
+        )
+    elif trigger_level == "warning":
+        lines.append(
+            "Punguza kazi za nje. Fanya kazi nzito asubuhi mapema au jioni. "
+            "Pumzika kivulini kila saa."
+        )
+    else:
+        lines.append(
+            "Kuwa makini. Kunywa maji zaidi. Panga kazi nzito kwa masaa ya baridi."
+        )
+
+    return " ".join(lines)

src/explanation/knowledge_base.py

@@ -0,0 +1,340 @@
+"""
+Curated knowledge base for the heat alert explanation RAG system.
+
+Contains real guidance from WHO, ILO, and East African occupational
+health authorities, adapted for extreme heat contexts in Nairobi,
+Dar es Salaam, Kampala, and Kigali.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+
+# -- WHO/ILO heat stress guidance for outdoor workers ----------------------
+
+HEAT_SAFETY_GUIDANCE: list[str] = [
+    # Hydration
+    "Drink water every 15-20 minutes even if you are not thirsty. "
+    "Do not wait until you feel thirsty — by then you are already dehydrated.",
+
+    "Carry at least 1 litre of clean water for every 2 hours of outdoor work. "
+    "Avoid alcohol, strong tea, and sugary drinks which increase dehydration.",
+
+    "Add a pinch of salt and sugar to drinking water to replace minerals "
+    "lost through sweating (oral rehydration solution).",
+
+    # Rest breaks
+    "Take a 10-minute rest break in shade every 45 minutes when temperature "
+    "exceeds 35C. In extreme heat above 37C, rest 15 minutes every 30 minutes.",
+
+    "Schedule heavy physical work (carrying, digging, construction) for early "
+    "morning (before 10am) or late afternoon (after 4pm). Avoid peak heat hours.",
+
+    "If possible, rotate between outdoor and indoor tasks throughout the day "
+    "to reduce cumulative heat exposure.",
+
+    # Shade and clothing
+    "Wear loose, light-colored clothing that covers the skin. A wide-brimmed "
+    "hat or head covering protects against direct sun and reduces heat stroke risk.",
+
+    "Work in shade whenever possible. If shade is not available, create "
+    "temporary shade using tarps, umbrellas, or fabric canopies.",
+
+    # Emergency signs (heat stroke)
+    "DANGER SIGNS — seek medical help immediately if someone shows: confusion "
+    "or strange behavior, inability to sweat despite heat, hot dry red skin, "
+    "seizures, unconsciousness, or body temperature above 40C.",
+
+    "If a co-worker collapses from heat: move them to shade immediately, pour "
+    "cool water over their body, fan them, and call for emergency help. Do not "
+    "give water to an unconscious person.",
+
+    # Adjusted work hours
+    "Employers should implement a heat action plan: shift start times earlier, "
+    "provide free drinking water stations, and designate shaded rest areas.",
+
+    "New workers and those returning after absence are at higher risk during "
+    "the first 1-2 weeks. Gradually increase workload over 7-14 days "
+    "(heat acclimatization).",
+]
+
+
+# -- Zone-specific heat context -------------------------------------------
+
+ZONE_HEAT_CONTEXT: Dict[str, str] = {
+    # Nairobi
+    "NBO-KIB": (
+        "Kibera's informal structures have corrugated tin roofs that absorb and "
+        "re-radiate solar heat, creating indoor temperatures 10-15C above ambient. "
+        "Most workers are outdoor traders, jua kali artisans, and transport workers. "
+        "The zone's elevation (1720m) keeps ambient temperatures moderate, but the "
+        "urban heat island effect is significant in the densely packed settlement."
+    ),
+    "NBO-EAS": (
+        "Eastleigh is a busy commercial district with thousands of street vendors "
+        "and market porters working outdoors on concrete and asphalt surfaces. "
+        "Heat radiating from buildings and pavement raises effective temperature. "
+        "Nairobi's highland climate provides some relief, but midday temperatures "
+        "during the dry season (Jan-Mar) can reach 28-30C."
+    ),
+    "NBO-MAT": (
+        "Mathare valley traps heat due to its low-lying topography and dense "
+        "settlement. Air circulation is poor between tightly packed structures. "
+        "Many residents work as construction laborers, scrap collectors, and "
+        "informal transport operators — all with high outdoor exposure."
+    ),
+    "NBO-SBC": (
+        "South B/C is a formal residential area where most workers commute to "
+        "indoor offices. Heat risk is lower but still affects outdoor guards, "
+        "gardeners, and maintenance workers during peak afternoon hours."
+    ),
+    "NBO-WES": (
+        "Westlands commercial district has air-conditioned offices and shopping "
+        "centers. Heat risk is minimal for most workers but affects outdoor "
+        "security guards, construction crews, and delivery riders."
+    ),
+    "NBO-KAN": (
+        "Kangemi has a large population of jua kali (literally 'fierce sun') "
+        "artisans — welders, carpenters, and mechanics who work outdoors with "
+        "heat-generating equipment. Combined with ambient heat, occupational "
+        "heat exposure can be significant."
+    ),
+
+    # Dar es Salaam
+    "DAR-JAN": (
+        "Jangwani is Dar es Salaam's most heat-vulnerable zone. Located at sea "
+        "level in an informal settlement with minimal shade and tin roofing, "
+        "ground-level temperatures regularly exceed 40C during hot months. "
+        "Humidity of 75-85% pushes WBGT into dangerous territory. Most workers "
+        "are outdoor laborers, market vendors, and waste collectors."
+    ),
+    "DAR-MSA": (
+        "Msasani has a large fish market and coastal trading area where workers "
+        "are exposed to direct sun reflected off the ocean surface. Coastal "
+        "humidity compounds heat stress. Salt processing and fish drying are "
+        "outdoor occupations with extended sun exposure."
+    ),
+    "DAR-KIN": (
+        "Kinondoni is more mixed with some tree cover, but humidity remains "
+        "consistently high (75-85%). Street vendors and bodaboda riders face "
+        "extended outdoor exposure. The concrete urban surface amplifies heat."
+    ),
+    "DAR-TEM": (
+        "Temeke is Dar es Salaam's industrial zone. Port workers, construction "
+        "crews, and factory workers in poorly ventilated structures face extreme "
+        "heat exposure. Heavy physical labor combined with high humidity creates "
+        "the city's highest occupational heat stress."
+    ),
+    "DAR-KIG": (
+        "Kigamboni peninsula has fishing, salt panning, and coastal construction "
+        "as primary outdoor occupations. Workers face combined heat from direct "
+        "sun, sea surface reflection, and high humidity. Limited shade on the "
+        "exposed peninsula."
+    ),
+
+    # Kampala
+    "KLA-BWA": (
+        "Bwaise is built on former wetland, creating humid conditions even by "
+        "Kampala standards. The low-lying settlement traps heat, and the high "
+        "water table increases humidity. Market traders and small manufacturers "
+        "work outdoors in congested conditions with poor air circulation."
+    ),
+    "KLA-NAT": (
+        "Natete market area has high concentrations of outdoor workers — porters, "
+        "vendors, and boda-boda riders. Concrete market surfaces store and "
+        "re-radiate heat. Lake Victoria moderates temperatures but also "
+        "maintains high humidity."
+    ),
+    "KLA-NAK": (
+        "Nakivubo commercial corridor includes the main taxi park where drivers "
+        "and conductors wait outdoors for extended periods. The concrete channel "
+        "and surrounding paved areas create a heat sink."
+    ),
+    "KLA-LUB": (
+        "Lubaga is on higher ground with some hilltop breezes that provide relief. "
+        "Heat risk is moderate, mainly affecting construction workers and "
+        "outdoor service providers."
+    ),
+    "KLA-MAK": (
+        "Makindye is elevated and has better tree cover than lower-lying areas. "
+        "Heat risk is lower, but outdoor security guards and gardeners in the "
+        "residential area still face extended exposure."
+    ),
+
+    # Kigali
+    "KGL-NYA": (
+        "Nyabugogo valley traps heat despite Kigali's highland elevation. The bus "
+        "terminal and surrounding market create a hot, congested environment. "
+        "Workers loading and unloading vehicles face combined heat stress from "
+        "sun exposure and vehicle exhaust."
+    ),
+    "KGL-KIC": (
+        "Kicukiro is a growing residential area with moderate heat exposure. "
+        "Construction workers on new building sites are the primary at-risk group. "
+        "Kigali's elevation (1520m) keeps temperatures manageable most of the year."
+    ),
+    "KGL-GAS": (
+        "Gasabo is the administrative district on higher ground. Air-conditioned "
+        "offices keep most workers comfortable. Outdoor workers (guards, cleaners, "
+        "construction) face moderate heat during dry season peaks."
+    ),
+    "KGL-NYM": (
+        "Nyamirambo is a dense residential hillside neighborhood. Market traders "
+        "and informal workers face heat stress during the dry season, particularly "
+        "in the lower, more sheltered areas where air circulation is limited."
+    ),
+}
+
+
+# -- Insurance product description ----------------------------------------
+
+INSURANCE_PRODUCT_INFO: str = (
+    "This is a parametric heat insurance product for outdoor workers in East Africa. "
+    "Unlike traditional insurance, payouts are triggered automatically when heat "
+    "conditions exceed pre-defined thresholds — there is no need to file a claim.\n\n"
+    "How it works:\n"
+    "1. We continuously monitor temperature and humidity for your work zone.\n"
+    "2. When heat conditions exceed the trigger threshold for the required number "
+    "of consecutive days, a payout is initiated automatically.\n"
+    "3. Payouts arrive via M-Pesa or mobile money within 48 hours of the trigger.\n\n"
+    "Trigger levels:\n"
+    "- WATCH: Temperature above 33C or WBGT above 28C for 1+ day. "
+    "Payout: $5 per worker. Take precautions.\n"
+    "- WARNING: Temperature above 35C or WBGT above 30C for 2+ consecutive days. "
+    "Payout: $10 per worker. Reduce outdoor work.\n"
+    "- CRITICAL: Temperature above 37C or WBGT above 32C for 3+ consecutive days. "
+    "Payout: $15 per worker. Stop outdoor work during peak hours.\n\n"
+    "Important: Parametric insurance pays based on the weather index, not on whether "
+    "you personally experienced heat illness. This means you may receive a payout "
+    "even if you felt fine (because conditions were dangerous), or you may not receive "
+    "a payout even if you felt unwell (if the index did not reach the threshold). "
+    "This gap is called 'basis risk' and we work continuously to minimize it."
+)
+
+
+# -- Emergency contacts by city -------------------------------------------
+
+EMERGENCY_CONTACTS: Dict[str, Dict[str, str]] = {
+    "Nairobi": {
+        "National Emergency": "999 or 112",
+        "Kenya Red Cross": "1199",
+        "Kenyatta National Hospital": "+254 20 272 6300",
+        "Kenya Meteorological Department": "+254 20 386 7880",
+        "Ambulance (St John)": "+254 20 221 0000",
+        "Police Emergency": "999",
+    },
+    "Dar es Salaam": {
+        "Tanzania Emergency": "112 or 114",
+        "Tanzania Red Cross": "+255 22 215 0330",
+        "Muhimbili National Hospital": "+255 22 215 1599",
+        "Tanzania Meteorological Authority": "+255 22 246 0706",
+        "Ambulance": "114",
+    },
+    "Kampala": {
+        "Uganda Emergency": "999 or 112",
+        "Uganda Red Cross": "+256 31 225 8701",
+        "Mulago National Hospital": "+256 41 425 4106",
+        "Uganda National Meteorological Authority": "+256 41 425 1798",
+        "Ambulance": "911",
+    },
+    "Kigali": {
+        "Rwanda Emergency": "112",
+        "Rwanda Red Cross": "+250 78 830 0086",
+        "CHUK Hospital": "+250 78 830 1001",
+        "Rwanda Meteorology Agency": "+250 78 218 5230",
+        "Ambulance (SAMU)": "912",
+    },
+}
+
+
+# -- Swahili translations of key heat and insurance terms ----------------
+
+SWAHILI_TERMS: Dict[str, str] = {
+    "heat": "joto",
+    "extreme heat": "joto kali",
+    "heat stroke": "kiharusi cha joto",
+    "heat stress": "msongo wa joto",
+    "temperature": "joto la hewa",
+    "humidity": "unyevunyevu",
+    "warning": "onyo",
+    "critical": "hali ya hatari",
+    "watch": "tahadhari",
+    "payout": "malipo",
+    "insurance": "bima",
+    "trigger": "kiwango cha hatari",
+    "shade": "kivuli",
+    "water": "maji",
+    "rest break": "mapumziko",
+    "dehydration": "upungufu wa maji mwilini",
+    "outdoor worker": "mfanyakazi wa nje",
+    "sun protection": "kinga ya jua",
+    "emergency": "dharura",
+    "ambulance": "gari la wagonjwa",
+    "M-Pesa": "M-Pesa",
+    "Red Cross": "Msalaba Mwekundu",
+}
+
+
+# -- Protective actions by trigger level ----------------------------------
+
+PROTECTIVE_ACTIONS: Dict[str, list[str]] = {
+    "critical": [
+        "STOP all outdoor work during peak heat hours (10am-4pm).",
+        "Move to shade or indoors immediately. Do not continue working in direct sun.",
+        "Drink water constantly — at least 250ml every 15 minutes.",
+        "Watch for danger signs: confusion, no sweating, hot dry skin, dizziness.",
+        "If someone collapses: move to shade, pour water on them, fan, call ambulance.",
+        "Your payout of $15 will arrive via mobile money within 48 hours.",
+        "Do not return to outdoor work until the heat alert is downgraded.",
+    ],
+    "warning": [
+        "Reduce outdoor work to early morning (before 10am) and late afternoon (after 4pm).",
+        "Take 15-minute shade breaks every hour during outdoor work.",
+        "Drink at least 1 cup of water every 20 minutes.",
+        "Wear loose, light-colored clothing and a hat.",
+        "Your payout of $10 will arrive via mobile money within 48 hours.",
+        "Watch for heat illness signs in yourself and co-workers.",
+        "Set up shade structures if working outdoors is unavoidable.",
+    ],
+    "watch": [
+        "Stay alert — heat conditions are developing.",
+        "Increase water intake beyond normal levels.",
+        "Plan your heavy work for cooler hours of the day.",
+        "Ensure shade and water are available at your work site.",
+        "Your payout of $5 will arrive via mobile money within 48 hours.",
+    ],
+}
+
+
+# -- Retrieval function ---------------------------------------------------
+
+def get_zone_context(zone_id: str) -> str:
+    """Assemble full knowledge base context for a zone.
+
+    Returns a single text block suitable for injection into a Claude prompt.
+    """
+    parts: list[str] = []
+
+    # Zone heat context
+    context = ZONE_HEAT_CONTEXT.get(zone_id, "No heat vulnerability data available for this zone.")
+    parts.append(f"ZONE HEAT VULNERABILITY:\n{context}")
+
+    # Product info
+    parts.append(f"INSURANCE PRODUCT:\n{INSURANCE_PRODUCT_INFO}")
+
+    # Heat safety (first 8 most relevant)
+    safety_text = "\n".join(f"- {s}" for s in HEAT_SAFETY_GUIDANCE[:8])
+    parts.append(f"HEAT SAFETY GUIDANCE (WHO/ILO):\n{safety_text}")
+
+    return "\n\n---\n\n".join(parts)
+
+
+def get_emergency_contacts(city: str) -> Dict[str, str]:
+    """Get emergency contacts for a city."""
+    return EMERGENCY_CONTACTS.get(city, EMERGENCY_CONTACTS.get("Nairobi", {}))
+
+
+def get_protective_actions(trigger_level: str) -> list[str]:
+    """Get recommended protective actions for a trigger level."""
+    return PROTECTIVE_ACTIONS.get(trigger_level, PROTECTIVE_ACTIONS["watch"])

src/healing/healer.py

@@ -0,0 +1,953 @@
+"""
+Claude-powered AI healing agent + rule-based fallback for climate data.
+
+HealingAgent: uses Claude Sonnet with 5 investigation tools to assess and
+heal daily precipitation/temperature readings for East African urban zones.
+Cross-validates CHIRPS vs NASA POWER, checks against climatological normals,
+and compares neighboring zones.
+
+RuleBasedFallback: deterministic anomaly detection and correction.
+Used when the Anthropic API is unavailable.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+import anthropic
+
+from config import ZONE_MAP, ZONES, RAINY_SEASONS
+
+log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HealingAssessment:
+    zone_id: str
+    date: str
+    assessment: str  # good, corrected, filled, flagged
+    original_precip: float | None
+    healed_precip: float | None
+    original_temp: float | None
+    healed_temp: float | None
+    reasoning: str
+    tools_used: list[str]
+    tokens_used: int
+    latency_ms: float
+
+
+@dataclass
+class HealedReading:
+    zone_id: str
+    date: str
+    precip_mm: float | None
+    temp_mean_c: float | None
+    temp_max_c: float | None
+    temp_min_c: float | None
+    humidity_pct: float | None
+    wind_speed_ms: float | None
+    heal_action: str
+    quality_score: float
+
+
+@dataclass
+class HealedData:
+    zone_id: str
+    readings: list[HealedReading]
+    quality_score: float  # 0-1
+    assessments: list[HealingAssessment]
+    healer_used: str  # "claude" or "rule_based"
+
+
+# ---------------------------------------------------------------------------
+# Climatological normals — real data for East African cities
+# Monthly mean precipitation (mm), std dev (mm), typical daily range (mm)
+# Sources: Kenya Met Department, Tanzania Met Agency, UNMA, Rwanda Meteorology
+# ---------------------------------------------------------------------------
+
+CLIMATOLOGICAL_NORMALS: dict[tuple[str, int], dict[str, Any]] = {
+    # ── Nairobi (bimodal: long rains MAM, short rains ON) ──
+    ("Nairobi", 1):  {"mean_precip_mm": 58, "std_dev_mm": 35, "daily_range": (0, 15), "mean_temp_c": 19.0, "temp_range": (12, 26)},
+    ("Nairobi", 2):  {"mean_precip_mm": 52, "std_dev_mm": 40, "daily_range": (0, 18), "mean_temp_c": 19.5, "temp_range": (12, 27)},
+    ("Nairobi", 3):  {"mean_precip_mm": 95, "std_dev_mm": 50, "daily_range": (0, 30), "mean_temp_c": 20.0, "temp_range": (14, 26)},
+    ("Nairobi", 4):  {"mean_precip_mm": 210, "std_dev_mm": 70, "daily_range": (0, 50), "mean_temp_c": 19.5, "temp_range": (14, 25)},
+    ("Nairobi", 5):  {"mean_precip_mm": 165, "std_dev_mm": 60, "daily_range": (0, 40), "mean_temp_c": 18.5, "temp_range": (13, 24)},
+    ("Nairobi", 6):  {"mean_precip_mm": 35, "std_dev_mm": 25, "daily_range": (0, 10), "mean_temp_c": 16.5, "temp_range": (11, 22)},
+    ("Nairobi", 7):  {"mean_precip_mm": 18, "std_dev_mm": 15, "daily_range": (0, 5),  "mean_temp_c": 15.5, "temp_range": (10, 21)},
+    ("Nairobi", 8):  {"mean_precip_mm": 22, "std_dev_mm": 18, "daily_range": (0, 8),  "mean_temp_c": 16.0, "temp_range": (10, 22)},
+    ("Nairobi", 9):  {"mean_precip_mm": 28, "std_dev_mm": 20, "daily_range": (0, 10), "mean_temp_c": 17.5, "temp_range": (11, 24)},
+    ("Nairobi", 10): {"mean_precip_mm": 60, "std_dev_mm": 40, "daily_range": (0, 25), "mean_temp_c": 19.0, "temp_range": (13, 25)},
+    ("Nairobi", 11): {"mean_precip_mm": 150, "std_dev_mm": 65, "daily_range": (0, 45), "mean_temp_c": 18.5, "temp_range": (13, 24)},
+    ("Nairobi", 12): {"mean_precip_mm": 90, "std_dev_mm": 50, "daily_range": (0, 25), "mean_temp_c": 18.5, "temp_range": (13, 25)},
+
+    # ── Dar es Salaam (bimodal: masika MAM, vuli ND) ──
+    ("Dar es Salaam", 1):  {"mean_precip_mm": 70, "std_dev_mm": 50, "daily_range": (0, 20), "mean_temp_c": 28.0, "temp_range": (24, 32)},
+    ("Dar es Salaam", 2):  {"mean_precip_mm": 55, "std_dev_mm": 45, "daily_range": (0, 18), "mean_temp_c": 28.5, "temp_range": (24, 33)},
+    ("Dar es Salaam", 3):  {"mean_precip_mm": 130, "std_dev_mm": 65, "daily_range": (0, 40), "mean_temp_c": 28.0, "temp_range": (24, 32)},
+    ("Dar es Salaam", 4):  {"mean_precip_mm": 280, "std_dev_mm": 90, "daily_range": (0, 60), "mean_temp_c": 27.0, "temp_range": (23, 31)},
+    ("Dar es Salaam", 5):  {"mean_precip_mm": 180, "std_dev_mm": 75, "daily_range": (0, 45), "mean_temp_c": 26.0, "temp_range": (22, 30)},
+    ("Dar es Salaam", 6):  {"mean_precip_mm": 40, "std_dev_mm": 30, "daily_range": (0, 12), "mean_temp_c": 24.5, "temp_range": (20, 29)},
+    ("Dar es Salaam", 7):  {"mean_precip_mm": 30, "std_dev_mm": 22, "daily_range": (0, 8),  "mean_temp_c": 24.0, "temp_range": (19, 29)},
+    ("Dar es Salaam", 8):  {"mean_precip_mm": 25, "std_dev_mm": 18, "daily_range": (0, 8),  "mean_temp_c": 24.0, "temp_range": (19, 29)},
+    ("Dar es Salaam", 9):  {"mean_precip_mm": 25, "std_dev_mm": 18, "daily_range": (0, 8),  "mean_temp_c": 25.0, "temp_range": (20, 30)},
+    ("Dar es Salaam", 10): {"mean_precip_mm": 55, "std_dev_mm": 40, "daily_range": (0, 18), "mean_temp_c": 26.5, "temp_range": (22, 31)},
+    ("Dar es Salaam", 11): {"mean_precip_mm": 120, "std_dev_mm": 60, "daily_range": (0, 35), "mean_temp_c": 27.5, "temp_range": (23, 32)},
+    ("Dar es Salaam", 12): {"mean_precip_mm": 130, "std_dev_mm": 65, "daily_range": (0, 35), "mean_temp_c": 28.0, "temp_range": (24, 32)},
+
+    # ── Kampala (bimodal: first rains MAM, second rains SON) ──
+    ("Kampala", 1):  {"mean_precip_mm": 50, "std_dev_mm": 35, "daily_range": (0, 15), "mean_temp_c": 22.0, "temp_range": (17, 28)},
+    ("Kampala", 2):  {"mean_precip_mm": 60, "std_dev_mm": 40, "daily_range": (0, 18), "mean_temp_c": 22.5, "temp_range": (17, 29)},
+    ("Kampala", 3):  {"mean_precip_mm": 130, "std_dev_mm": 55, "daily_range": (0, 35), "mean_temp_c": 22.0, "temp_range": (17, 27)},
+    ("Kampala", 4):  {"mean_precip_mm": 175, "std_dev_mm": 65, "daily_range": (0, 50), "mean_temp_c": 21.5, "temp_range": (17, 26)},
+    ("Kampala", 5):  {"mean_precip_mm": 145, "std_dev_mm": 55, "daily_range": (0, 40), "mean_temp_c": 21.5, "temp_range": (17, 26)},
+    ("Kampala", 6):  {"mean_precip_mm": 65, "std_dev_mm": 35, "daily_range": (0, 15), "mean_temp_c": 21.0, "temp_range": (16, 26)},
+    ("Kampala", 7):  {"mean_precip_mm": 55, "std_dev_mm": 30, "daily_range": (0, 12), "mean_temp_c": 20.5, "temp_range": (16, 25)},
+    ("Kampala", 8):  {"mean_precip_mm": 75, "std_dev_mm": 40, "daily_range": (0, 20), "mean_temp_c": 21.0, "temp_range": (16, 26)},
+    ("Kampala", 9):  {"mean_precip_mm": 90, "std_dev_mm": 45, "daily_range": (0, 25), "mean_temp_c": 21.5, "temp_range": (17, 27)},
+    ("Kampala", 10): {"mean_precip_mm": 120, "std_dev_mm": 55, "daily_range": (0, 35), "mean_temp_c": 21.5, "temp_range": (17, 27)},
+    ("Kampala", 11): {"mean_precip_mm": 140, "std_dev_mm": 60, "daily_range": (0, 40), "mean_temp_c": 21.5, "temp_range": (17, 26)},
+    ("Kampala", 12): {"mean_precip_mm": 80, "std_dev_mm": 45, "daily_range": (0, 22), "mean_temp_c": 21.5, "temp_range": (17, 27)},
+
+    # ── Kigali (bimodal: long rains MAM, short rains ON) ──
+    ("Kigali", 1):  {"mean_precip_mm": 75, "std_dev_mm": 40, "daily_range": (0, 20), "mean_temp_c": 21.0, "temp_range": (15, 27)},
+    ("Kigali", 2):  {"mean_precip_mm": 90, "std_dev_mm": 45, "daily_range": (0, 25), "mean_temp_c": 21.0, "temp_range": (15, 27)},
+    ("Kigali", 3):  {"mean_precip_mm": 115, "std_dev_mm": 50, "daily_range": (0, 35), "mean_temp_c": 21.0, "temp_range": (15, 27)},
+    ("Kigali", 4):  {"mean_precip_mm": 155, "std_dev_mm": 60, "daily_range": (0, 45), "mean_temp_c": 21.0, "temp_range": (15, 26)},
+    ("Kigali", 5):  {"mean_precip_mm": 100, "std_dev_mm": 50, "daily_range": (0, 30), "mean_temp_c": 21.0, "temp_range": (15, 27)},
+    ("Kigali", 6):  {"mean_precip_mm": 20, "std_dev_mm": 15, "daily_range": (0, 5),  "mean_temp_c": 21.0, "temp_range": (15, 28)},
+    ("Kigali", 7):  {"mean_precip_mm": 10, "std_dev_mm": 10, "daily_range": (0, 3),  "mean_temp_c": 21.5, "temp_range": (14, 28)},
+    ("Kigali", 8):  {"mean_precip_mm": 30, "std_dev_mm": 22, "daily_range": (0, 10), "mean_temp_c": 22.0, "temp_range": (15, 29)},
+    ("Kigali", 9):  {"mean_precip_mm": 75, "std_dev_mm": 40, "daily_range": (0, 20), "mean_temp_c": 21.5, "temp_range": (15, 28)},
+    ("Kigali", 10): {"mean_precip_mm": 105, "std_dev_mm": 50, "daily_range": (0, 30), "mean_temp_c": 21.0, "temp_range": (15, 27)},
+    ("Kigali", 11): {"mean_precip_mm": 105, "std_dev_mm": 50, "daily_range": (0, 30), "mean_temp_c": 20.5, "temp_range": (15, 26)},
+    ("Kigali", 12): {"mean_precip_mm": 70, "std_dev_mm": 40, "daily_range": (0, 20), "mean_temp_c": 20.5, "temp_range": (15, 26)},
+}
+
+
+# ---------------------------------------------------------------------------
+# Tool definitions (JSON Schema format for Claude tool-use API)
+# ---------------------------------------------------------------------------
+
+HEALING_TOOLS = [
+    {
+        "name": "zone_metadata",
+        "description": (
+            "Get metadata for an urban zone: name, city, country, settlement type, "
+            "elevation, flood susceptibility, drainage quality, primary flood type. "
+            "Use this to understand a zone's geography and vulnerability context."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "zone_id": {
+                    "type": "string",
+                    "description": "Zone ID, e.g. 'NBO-KIB' for Kibera or 'DAR-JAN' for Jangwani",
+                },
+            },
+            "required": ["zone_id"],
+        },
+    },
+    {
+        "name": "historical_norms",
+        "description": (
+            "Get climatological normals for a zone's city in a given month. Returns "
+            "mean monthly precipitation, standard deviation, typical daily range, "
+            "mean temperature, and temperature range. Based on long-term observational "
+            "records. Use this to check whether a reading is within normal bounds."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "zone_id": {"type": "string", "description": "Zone ID"},
+                "month": {"type": "integer", "description": "Calendar month (1-12)"},
+            },
+            "required": ["zone_id", "month"],
+        },
+    },
+    {
+        "name": "cross_source_check",
+        "description": (
+            "Compare CHIRPS and NASA POWER precipitation values for the same zone "
+            "and date. Returns both source values, the absolute difference, and an "
+            "agreement score. Use this when you need to assess which source is more "
+            "reliable for a given reading or when values look suspicious."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "zone_id": {"type": "string", "description": "Zone ID"},
+                "date": {"type": "string", "description": "Date in YYYY-MM-DD format"},
+            },
+            "required": ["zone_id", "date"],
+        },
+    },
+    {
+        "name": "neighbor_comparison",
+        "description": (
+            "Compare a zone's readings against other zones in the same city. Returns "
+            "neighboring zone values with distances. Use this to detect spatial "
+            "outliers — if one zone in Nairobi reads 200mm while all others read <20mm, "
+            "that's suspicious."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "zone_id": {"type": "string", "description": "Zone ID to compare"},
+                "date": {"type": "string", "description": "Date in YYYY-MM-DD format"},
+            },
+            "required": ["zone_id", "date"],
+        },
+    },
+    {
+        "name": "seasonal_context",
+        "description": (
+            "Get seasonal rainfall context for a zone: whether the date falls in a "
+            "rainy season, what the season is called locally, and expected rainfall "
+            "patterns. Use this to judge whether extreme values are seasonally normal."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "zone_id": {"type": "string", "description": "Zone ID"},
+                "month": {"type": "integer", "description": "Calendar month (1-12)"},
+            },
+            "required": ["zone_id", "month"],
+        },
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# System prompt for the healing agent
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT_TEMPLATE = """You are a climate data quality agent for an urban flood parametric insurance system covering {n_zones} zones across Nairobi, Dar es Salaam, Kampala, and Kigali.
+
+## Data Sources You're Working With
+
+Each zone has daily readings from two independent satellite/reanalysis sources:
+1. **CHIRPS** (Climate Hazards Group InfraRed Precipitation with Station data) — 0.05° resolution precipitation estimates combining satellite imagery with station data
+2. **NASA POWER** — 0.5° resolution reanalysis providing precipitation, temperature, humidity, and wind speed
+
+Your job is Step 2 of a 6-step parametric insurance pipeline: heal and quality-score daily readings BEFORE they feed into SPI calculation and flood risk indexing (Step 3), which ultimately triggers insurance payouts.
+
+## What You're Checking
+
+For each zone's daily reading:
+- **Impossible values**: negative precipitation, precipitation >500mm/day, temperatures outside -5 to 55°C
+- **Statistical outliers**: daily precip more than 3 standard deviations above the monthly mean for that city
+- **Source disagreements**: CHIRPS and NASA POWER differing by more than 20mm on the same day
+- **Missing data**: NULL precipitation or temperature values that need filling
+- **Spatial inconsistency**: one zone in a city reading wildly differently from its neighbors
+
+## Your Task
+
+You receive a batch of {n_zones} daily readings. For each reading:
+1. Assess data quality — check for impossible values, outliers, source disagreements, missing data
+2. Use your tools selectively to investigate suspicious readings
+3. Produce a structured assessment for EVERY reading
+
+## East African Climate Context
+
+These are tropical cities at varying elevations with distinct rainy seasons:
+- **Nairobi** (1620-1780m): Bimodal — long rains MAM (heavy: 95-210mm/month), short rains ON (60-150mm/month). Highland climate, cooler than expected for equator.
+- **Dar es Salaam** (8-35m): Bimodal — masika MAM (130-280mm/month), vuli ND (120-130mm/month). Hot coastal, consistent high humidity.
+- **Kampala** (1140-1260m): Bimodal with less pronounced dry season. Peak rains MAM and SON (90-175mm/month).
+- **Kigali** (1420-1580m): Bimodal — long rains MAM, short rains ON. Pronounced dry JJ (10-20mm/month). "Land of a thousand hills" — elevation matters.
+
+Daily rainfall of 50-80mm during peak rainy season is heavy but not impossible. 100mm+ in a single day is extreme and warrants investigation. >200mm/day is very rare outside tropical cyclone influence.
+
+## Key Rules
+- NEVER fabricate data. If you can't confidently correct a value, flag it.
+- For missing precipitation: use the other source (CHIRPS or NASA POWER) if available; if both missing, use neighbor average.
+- For missing temperature: use NASA POWER value (CHIRPS is precip-only).
+- When CHIRPS and NASA POWER agree within 10mm, use CHIRPS as primary (higher resolution). When they disagree >20mm, investigate.
+- Quality score: 0.95+ for dual-source agreement, 0.7-0.9 for corrected, 0.5-0.7 for single-source filled, <0.5 for flagged.
+
+## Efficiency — IMPORTANT
+Be selective with tools:
+- For readings with dual-source agreement and reasonable values: mark as "good" without tool calls.
+- Only call `historical_norms` or `neighbor_comparison` when a value looks suspicious.
+- Only call `seasonal_context` when you need to judge whether an extreme value is normal for the season.
+- Batch tool calls in a single turn when possible.
+- Do NOT investigate a reading more than 2 rounds.
+
+## Output Format
+
+Return your final assessment as a JSON array wrapped in ```json fences. Each object must have:
+- zone_id (string)
+- date (string): YYYY-MM-DD
+- assessment (string): "good" | "corrected" | "filled" | "flagged"
+- original_precip (number or null)
+- healed_precip (number or null)
+- original_temp (number or null)
+- healed_temp (number or null)
+- reasoning (string): 1-2 sentences
+- tools_used (array of strings)"""
+
+
+# ---------------------------------------------------------------------------
+# Tool implementations
+# ---------------------------------------------------------------------------
+
+def _haversine_km(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Great-circle distance between two points in km."""
+    import math
+    R = 6371.0
+    dlat = math.radians(lat2 - lat1)
+    dlon = math.radians(lon2 - lon1)
+    a = (math.sin(dlat / 2) ** 2 +
+         math.cos(math.radians(lat1)) * math.cos(math.radians(lat2)) *
+         math.sin(dlon / 2) ** 2)
+    return R * 2 * math.asin(math.sqrt(a))
+
+
+def _tool_zone_metadata(zone_id: str) -> dict[str, Any]:
+    zone = ZONE_MAP.get(zone_id)
+    if zone is None:
+        return {"error": f"Unknown zone_id: {zone_id}"}
+    return {
+        "zone_id": zone.zone_id,
+        "name": zone.name,
+        "city": zone.city,
+        "country": zone.country,
+        "latitude": zone.latitude,
+        "longitude": zone.longitude,
+        "elevation_m": zone.elevation_m,
+        "settlement_type": zone.settlement_type,
+        "flood_susceptibility": zone.flood_susceptibility,
+        "drainage_quality": zone.drainage_quality,
+        "primary_flood_type": zone.primary_flood_type,
+        "notes": zone.notes,
+    }
+
+
+def _tool_historical_norms(zone_id: str, month: int) -> dict[str, Any]:
+    zone = ZONE_MAP.get(zone_id)
+    if zone is None:
+        return {"error": f"Unknown zone_id: {zone_id}"}
+
+    key = (zone.city, month)
+    norms = CLIMATOLOGICAL_NORMALS.get(key)
+    if norms is None:
+        return {"error": f"No climatological normals for city={zone.city}, month={month}"}
+
+    return {
+        "zone_id": zone_id,
+        "city": zone.city,
+        "month": month,
+        **norms,
+    }
+
+
+def _tool_cross_source_check(zone_id: str, date: str,
+                              batch_readings: list[dict]) -> dict[str, Any]:
+    zone = ZONE_MAP.get(zone_id)
+    if zone is None:
+        return {"error": f"Unknown zone_id: {zone_id}"}
+
+    # Find this zone's reading in the batch
+    reading = None
+    for r in batch_readings:
+        if r.get("zone_id") == zone_id and r.get("date") == date:
+            reading = r
+            break
+
+    if reading is None:
+        return {"error": f"No reading found for zone {zone_id} on {date}"}
+
+    chirps = reading.get("precip_chirps_mm")
+    nasa = reading.get("precip_nasa_mm")
+
+    result: dict[str, Any] = {
+        "zone_id": zone_id,
+        "date": date,
+        "chirps_precip_mm": chirps,
+        "nasa_precip_mm": nasa,
+    }
+
+    if chirps is not None and nasa is not None:
+        diff = abs(chirps - nasa)
+        agreement = max(0.0, 1.0 - diff / 50.0)  # 0mm diff = 1.0, 50mm diff = 0.0
+        result["difference_mm"] = round(diff, 1)
+        result["agreement_score"] = round(agreement, 2)
+        result["recommendation"] = (
+            "Sources agree well" if diff < 10 else
+            "Moderate disagreement — investigate" if diff < 20 else
+            "Significant disagreement — check neighbors and norms"
+        )
+    else:
+        available = "CHIRPS" if chirps is not None else "NASA POWER" if nasa is not None else "neither"
+        result["note"] = f"Only {available} available for cross-check"
+
+    return result
+
+
+def _tool_neighbor_comparison(zone_id: str, date: str,
+                               batch_readings: list[dict]) -> dict[str, Any]:
+    zone = ZONE_MAP.get(zone_id)
+    if zone is None:
+        return {"error": f"Unknown zone_id: {zone_id}"}
+
+    # Build lookup from batch readings for this date
+    readings_by_zone = {}
+    for r in batch_readings:
+        if r.get("date") == date:
+            readings_by_zone[r["zone_id"]] = r
+
+    # Find zones in the same city
+    neighbors = []
+    for z in ZONES:
+        if z.zone_id == zone_id or z.city != zone.city:
+            continue
+        dist = _haversine_km(zone.latitude, zone.longitude, z.latitude, z.longitude)
+        reading = readings_by_zone.get(z.zone_id, {})
+        neighbors.append({
+            "zone_id": z.zone_id,
+            "name": z.name,
+            "distance_km": round(dist, 1),
+            "precip_mm": reading.get("precip_mm"),
+            "precip_chirps_mm": reading.get("precip_chirps_mm"),
+            "precip_nasa_mm": reading.get("precip_nasa_mm"),
+            "temp_mean_c": reading.get("temp_mean_c"),
+            "settlement_type": z.settlement_type,
+        })
+
+    neighbors.sort(key=lambda x: x["distance_km"])
+
+    # Compute city average for context
+    precip_vals = [n["precip_mm"] for n in neighbors if n.get("precip_mm") is not None]
+    city_avg = round(sum(precip_vals) / len(precip_vals), 1) if precip_vals else None
+
+    return {
+        "zone_id": zone_id,
+        "city": zone.city,
+        "date": date,
+        "neighbors_found": len(neighbors),
+        "city_avg_precip_mm": city_avg,
+        "neighbors": neighbors,
+    }
+
+
+def _tool_seasonal_context(zone_id: str, month: int) -> dict[str, Any]:
+    zone = ZONE_MAP.get(zone_id)
+    if zone is None:
+        return {"error": f"Unknown zone_id: {zone_id}"}
+
+    city = zone.city
+    seasons = RAINY_SEASONS.get(city, {})
+
+    in_rainy_season = False
+    season_name = "dry season"
+    for name, months in seasons.items():
+        if month in months:
+            in_rainy_season = True
+            season_name = name
+            break
+
+    norms = CLIMATOLOGICAL_NORMALS.get((city, month), {})
+
+    return {
+        "zone_id": zone_id,
+        "city": city,
+        "month": month,
+        "in_rainy_season": in_rainy_season,
+        "season_name": season_name,
+        "rainy_months": zone.rainy_seasons,
+        "expected_monthly_precip_mm": norms.get("mean_precip_mm"),
+        "expected_daily_max_mm": norms.get("daily_range", (0, 0))[1],
+        "expected_temp_range": norms.get("temp_range"),
+        "context": (
+            f"{'Peak' if month in zone.rainy_seasons else 'Off-season'} for {city}. "
+            f"Zone {zone.name} is a {zone.settlement_type} settlement with "
+            f"{zone.flood_susceptibility} flood susceptibility and "
+            f"{zone.drainage_quality} drainage."
+        ),
+    }
+
+
+# ---------------------------------------------------------------------------
+# HealingAgent — Claude-powered agentic healer
+# ---------------------------------------------------------------------------
+
+class HealingAgent:
+    """Uses Claude Sonnet with 5 investigation tools to assess and heal
+    a batch of daily climate readings for East African urban zones."""
+
+    MAX_TOOL_ROUNDS = 8
+
+    def __init__(self, api_key: str, model: str = "claude-sonnet-4-6"):
+        self.api_key = api_key
+        self.model = model
+        self._client: anthropic.Anthropic | None = None
+
+    def _get_client(self) -> anthropic.Anthropic:
+        if self._client is None:
+            self._client = anthropic.Anthropic(api_key=self.api_key)
+        return self._client
+
+    def _execute_tool(self, name: str, tool_input: dict[str, Any],
+                      context: dict[str, Any]) -> str:
+        """Dispatch a tool call. Returns JSON string."""
+        try:
+            if name == "zone_metadata":
+                result = _tool_zone_metadata(tool_input["zone_id"])
+            elif name == "historical_norms":
+                result = _tool_historical_norms(
+                    tool_input["zone_id"], tool_input["month"])
+            elif name == "cross_source_check":
+                result = _tool_cross_source_check(
+                    tool_input["zone_id"], tool_input["date"],
+                    context["batch_readings"])
+            elif name == "neighbor_comparison":
+                result = _tool_neighbor_comparison(
+                    tool_input["zone_id"], tool_input["date"],
+                    context["batch_readings"])
+            elif name == "seasonal_context":
+                result = _tool_seasonal_context(
+                    tool_input["zone_id"], tool_input["month"])
+            else:
+                result = {"error": f"Unknown tool: {name}"}
+        except Exception as exc:
+            result = {"error": f"Tool execution failed: {exc}"}
+
+        return json.dumps(result, default=str)
+
+    def _build_system_prompt(self, n_zones: int) -> str:
+        return SYSTEM_PROMPT_TEMPLATE.format(n_zones=n_zones)
+
+    def _parse_assessments(self, text: str) -> list[dict[str, Any]]:
+        """Extract JSON assessment array from Claude's response."""
+        match = re.search(r'```json\s*([\s\S]*?)```', text)
+        if match:
+            return json.loads(match.group(1))
+
+        match = re.search(r'\[[\s\S]*\]', text)
+        if match:
+            return json.loads(match.group(0))
+
+        raise ValueError("Could not find JSON assessment array in response")
+
+    BATCH_SIZE = 10
+
+    def heal(self, readings: list[dict[str, Any]]) -> HealedData:
+        """Main entry point: assess and heal a batch of daily readings.
+
+        Args:
+            readings: list of dicts with keys matching DailyReading fields:
+                zone_id, date, precip_mm, precip_chirps_mm, precip_nasa_mm,
+                temp_mean_c, temp_max_c, temp_min_c, humidity_pct, wind_speed_ms,
+                source, source_agreement, data_quality
+
+        Returns:
+            HealedData with healed readings, quality score, and assessments.
+        """
+        t0 = time.time()
+
+        # Split into sub-batches
+        batches = [readings[i:i + self.BATCH_SIZE]
+                   for i in range(0, len(readings), self.BATCH_SIZE)]
+
+        all_healed: list[HealedReading] = []
+        all_assessments: list[HealingAssessment] = []
+        total_tokens = 0
+        fallback_used = False
+
+        for batch_num, batch in enumerate(batches):
+            log.info("AI healing batch %d/%d (%d readings)",
+                     batch_num + 1, len(batches), len(batch))
+            try:
+                result = self._heal_sub_batch(batch, readings)
+                all_healed.extend(result["healed"])
+                all_assessments.extend(result["assessments"])
+                total_tokens += result["tokens"]
+            except Exception as exc:
+                log.warning("AI healing batch %d failed: %s — using rule-based fallback",
+                            batch_num + 1, exc)
+                fallback_used = True
+                fb = RuleBasedFallback()
+                for r in batch:
+                    healed, assessment = fb.heal_reading(r)
+                    all_healed.append(healed)
+                    all_assessments.append(assessment)
+
+        # Compute overall quality score
+        quality_scores = [h.quality_score for h in all_healed]
+        avg_quality = sum(quality_scores) / len(quality_scores) if quality_scores else 0.0
+
+        zone_id = readings[0]["zone_id"] if readings else "unknown"
+        latency = (time.time() - t0) * 1000
+
+        return HealedData(
+            zone_id=zone_id,
+            readings=all_healed,
+            quality_score=round(avg_quality, 3),
+            assessments=all_assessments,
+            healer_used="rule_based" if fallback_used else "claude",
+        )
+
+    def _heal_sub_batch(self, batch: list[dict], all_readings: list[dict]) -> dict:
+        """Process a single sub-batch through Claude."""
+        t0 = time.time()
+        total_tokens_in = 0
+        total_tokens_out = 0
+
+        client = self._get_client()
+        context = {"batch_readings": all_readings}
+
+        # Build user message
+        readings_payload = []
+        for r in batch:
+            readings_payload.append({
+                "zone_id": r["zone_id"],
+                "date": r.get("date", ""),
+                "precip_mm": r.get("precip_mm"),
+                "precip_chirps_mm": r.get("precip_chirps_mm"),
+                "precip_nasa_mm": r.get("precip_nasa_mm"),
+                "temp_mean_c": r.get("temp_mean_c"),
+                "temp_max_c": r.get("temp_max_c"),
+                "temp_min_c": r.get("temp_min_c"),
+                "humidity_pct": r.get("humidity_pct"),
+                "wind_speed_ms": r.get("wind_speed_ms"),
+                "source": r.get("source", "unknown"),
+                "source_agreement": r.get("source_agreement"),
+            })
+
+        now = datetime.now(timezone.utc)
+        user_msg = (
+            f"Current date/time: {now.isoformat()} UTC (month={now.month})\n\n"
+            f"Here are {len(batch)} daily climate readings to assess and heal:\n\n"
+            f"```json\n{json.dumps(readings_payload, indent=2, default=str)}\n```\n\n"
+            "Investigate any suspicious readings using your tools, then return "
+            "your assessment for ALL readings."
+        )
+
+        messages: list[dict[str, Any]] = [{"role": "user", "content": user_msg}]
+        system_prompt = self._build_system_prompt(len(batch))
+
+        # Agentic tool-use loop
+        for round_num in range(self.MAX_TOOL_ROUNDS):
+            response = client.messages.create(
+                model=self.model,
+                max_tokens=8192,
+                system=system_prompt,
+                tools=HEALING_TOOLS,
+                messages=messages,
+            )
+
+            total_tokens_in += getattr(response.usage, "input_tokens", 0)
+            total_tokens_out += getattr(response.usage, "output_tokens", 0)
+
+            if response.stop_reason == "end_turn":
+                text_blocks = [b.text for b in response.content if hasattr(b, "text")]
+                full_text = "\n".join(text_blocks)
+
+                try:
+                    raw_assessments = self._parse_assessments(full_text)
+                except (ValueError, json.JSONDecodeError) as exc:
+                    log.warning("Failed to parse AI healing response: %s", exc)
+                    raise
+
+                latency_ms = (time.time() - t0) * 1000
+                total_tokens = total_tokens_in + total_tokens_out
+
+                healed_readings: list[HealedReading] = []
+                assessments: list[HealingAssessment] = []
+                readings_by_zone = {r["zone_id"]: r for r in batch}
+
+                for a in raw_assessments:
+                    zid = a.get("zone_id", "")
+                    original = readings_by_zone.get(zid)
+                    if original is None:
+                        continue
+
+                    assessment = HealingAssessment(
+                        zone_id=zid,
+                        date=a.get("date", original.get("date", "")),
+                        assessment=a.get("assessment", "flagged"),
+                        original_precip=original.get("precip_mm"),
+                        healed_precip=a.get("healed_precip"),
+                        original_temp=original.get("temp_mean_c"),
+                        healed_temp=a.get("healed_temp"),
+                        reasoning=a.get("reasoning", ""),
+                        tools_used=a.get("tools_used", []),
+                        tokens_used=total_tokens,
+                        latency_ms=latency_ms,
+                    )
+                    assessments.append(assessment)
+
+                    # Determine healed values
+                    healed_precip = a.get("healed_precip", original.get("precip_mm"))
+                    healed_temp = a.get("healed_temp", original.get("temp_mean_c"))
+
+                    heal_action = f"ai_{a.get('assessment', 'flagged')}"
+                    quality = {
+                        "good": 0.95,
+                        "corrected": 0.8,
+                        "filled": 0.6,
+                        "flagged": 0.3,
+                    }.get(a.get("assessment", "flagged"), 0.5)
+
+                    healed_readings.append(HealedReading(
+                        zone_id=zid,
+                        date=a.get("date", original.get("date", "")),
+                        precip_mm=healed_precip,
+                        temp_mean_c=healed_temp,
+                        temp_max_c=original.get("temp_max_c"),
+                        temp_min_c=original.get("temp_min_c"),
+                        humidity_pct=original.get("humidity_pct"),
+                        wind_speed_ms=original.get("wind_speed_ms"),
+                        heal_action=heal_action,
+                        quality_score=quality,
+                    ))
+
+                return {
+                    "healed": healed_readings,
+                    "assessments": assessments,
+                    "tokens": total_tokens,
+                }
+
+            elif response.stop_reason == "tool_use":
+                messages.append({"role": "assistant", "content": response.content})
+                tool_results = []
+                for block in response.content:
+                    if block.type == "tool_use":
+                        result_str = self._execute_tool(block.name, block.input, context)
+                        tool_results.append({
+                            "type": "tool_result",
+                            "tool_use_id": block.id,
+                            "content": result_str,
+                        })
+                messages.append({"role": "user", "content": tool_results})
+            else:
+                log.warning("Unexpected stop_reason: %s", response.stop_reason)
+                break
+
+        raise RuntimeError(
+            f"AI healing exhausted {self.MAX_TOOL_ROUNDS} tool rounds without completing"
+        )
+
+
+# ---------------------------------------------------------------------------
+# RuleBasedFallback — deterministic healing when Claude is unavailable
+# ---------------------------------------------------------------------------
+
+class RuleBasedFallback:
+    """Deterministic anomaly detection, correction, and cross-validation.
+    Used when the Anthropic API is unavailable."""
+
+    # Physical limits
+    PRECIP_MIN = 0.0
+    PRECIP_MAX = 500.0  # mm/day — absolute physical maximum
+    TEMP_MIN = -5.0
+    TEMP_MAX = 55.0
+
+    # Cross-validation threshold
+    SOURCE_DISAGREE_MM = 20.0
+
+    def heal_reading(self, reading: dict[str, Any]) -> tuple[HealedReading, HealingAssessment]:
+        """Heal a single reading using deterministic rules.
+
+        Returns (HealedReading, HealingAssessment) tuple.
+        """
+        t0 = time.time()
+        zone_id = reading["zone_id"]
+        date = reading.get("date", "")
+        original_precip = reading.get("precip_mm")
+        original_temp = reading.get("temp_mean_c")
+
+        healed_precip = original_precip
+        healed_temp = original_temp
+        assessment_type = "good"
+        reasoning_parts: list[str] = []
+        tools_used: list[str] = []
+
+        # --- Check precipitation ---
+        chirps = reading.get("precip_chirps_mm")
+        nasa = reading.get("precip_nasa_mm")
+
+        if original_precip is not None:
+            # Impossible: negative
+            if original_precip < self.PRECIP_MIN:
+                healed_precip = 0.0
+                assessment_type = "corrected"
+                reasoning_parts.append(
+                    f"Negative precipitation ({original_precip}mm) corrected to 0."
+                )
+
+            # Impossible: >500mm/day
+            elif original_precip > self.PRECIP_MAX:
+                # Try to use the other source
+                if chirps is not None and 0 <= chirps <= self.PRECIP_MAX:
+                    healed_precip = chirps
+                elif nasa is not None and 0 <= nasa <= self.PRECIP_MAX:
+                    healed_precip = nasa
+                else:
+                    healed_precip = None  # can't salvage
+                assessment_type = "corrected"
+                reasoning_parts.append(
+                    f"Extreme precipitation ({original_precip}mm) exceeds 500mm/day physical limit."
+                )
+
+            # Check source disagreement
+            elif chirps is not None and nasa is not None:
+                diff = abs(chirps - nasa)
+                if diff > self.SOURCE_DISAGREE_MM:
+                    # Use CHIRPS as primary (higher resolution)
+                    healed_precip = chirps
+                    assessment_type = "corrected"
+                    reasoning_parts.append(
+                        f"Source disagreement: CHIRPS={chirps}mm vs NASA={nasa}mm "
+                        f"(diff={diff:.1f}mm). Using CHIRPS."
+                    )
+
+            # Check against climatological norms
+            zone = ZONE_MAP.get(zone_id)
+            if zone and healed_precip is not None and date:
+                try:
+                    month = int(date.split("-")[1])
+                    norms = CLIMATOLOGICAL_NORMALS.get((zone.city, month))
+                    if norms:
+                        daily_max = norms["daily_range"][1]
+                        std = norms["std_dev_mm"]
+                        # Flag if daily reading > 3x the monthly std dev
+                        if healed_precip > 3 * std and assessment_type == "good":
+                            assessment_type = "flagged"
+                            reasoning_parts.append(
+                                f"Daily precip ({healed_precip}mm) exceeds 3x monthly "
+                                f"std dev ({std}mm) for {zone.city} in month {month}."
+                            )
+                except (ValueError, IndexError):
+                    pass
+
+        elif original_precip is None:
+            # Missing precipitation — try to fill
+            if chirps is not None:
+                healed_precip = chirps
+                assessment_type = "filled"
+                reasoning_parts.append("Missing precipitation filled from CHIRPS.")
+            elif nasa is not None:
+                healed_precip = nasa
+                assessment_type = "filled"
+                reasoning_parts.append("Missing precipitation filled from NASA POWER.")
+            else:
+                assessment_type = "flagged"
+                reasoning_parts.append("Missing precipitation with no source available for fill.")
+
+        # --- Check temperature ---
+        if original_temp is not None:
+            if not (self.TEMP_MIN <= original_temp <= self.TEMP_MAX):
+                # Possible decimal typo (e.g., 325 -> 32.5)
+                if original_temp > 100:
+                    healed_temp = original_temp / 10.0
+                    if assessment_type == "good":
+                        assessment_type = "corrected"
+                    reasoning_parts.append(
+                        f"Temperature typo ({original_temp}°C) corrected to {healed_temp}°C."
+                    )
+                else:
+                    healed_temp = None
+                    if assessment_type == "good":
+                        assessment_type = "flagged"
+                    reasoning_parts.append(
+                        f"Temperature ({original_temp}°C) outside valid range."
+                    )
+        elif original_temp is None:
+            # NASA POWER provides temperature even when CHIRPS doesn't
+            nasa_temp = reading.get("temp_mean_c")  # already None
+            if nasa_temp is None:
+                # Try to use city norms
+                zone = ZONE_MAP.get(zone_id)
+                if zone and date:
+                    try:
+                        month = int(date.split("-")[1])
+                        norms = CLIMATOLOGICAL_NORMALS.get((zone.city, month))
+                        if norms:
+                            healed_temp = norms["mean_temp_c"]
+                            if assessment_type == "good":
+                                assessment_type = "filled"
+                            reasoning_parts.append(
+                                f"Missing temperature filled from climatological mean "
+                                f"({healed_temp}°C) for {zone.city}."
+                            )
+                    except (ValueError, IndexError):
+                        pass
+
+        # Determine quality score
+        quality_map = {"good": 0.95, "corrected": 0.75, "filled": 0.55, "flagged": 0.3}
+        quality = quality_map.get(assessment_type, 0.5)
+
+        if not reasoning_parts:
+            reasoning_parts.append("Values within expected ranges; dual-source agreement.")
+
+        latency_ms = (time.time() - t0) * 1000
+
+        healed = HealedReading(
+            zone_id=zone_id,
+            date=date,
+            precip_mm=healed_precip,
+            temp_mean_c=healed_temp,
+            temp_max_c=reading.get("temp_max_c"),
+            temp_min_c=reading.get("temp_min_c"),
+            humidity_pct=reading.get("humidity_pct"),
+            wind_speed_ms=reading.get("wind_speed_ms"),
+            heal_action=f"rule_{assessment_type}",
+            quality_score=quality,
+        )
+
+        assessment = HealingAssessment(
+            zone_id=zone_id,
+            date=date,
+            assessment=assessment_type,
+            original_precip=original_precip,
+            healed_precip=healed_precip,
+            original_temp=original_temp,
+            healed_temp=healed_temp,
+            reasoning=" ".join(reasoning_parts),
+            tools_used=tools_used,
+            tokens_used=0,
+            latency_ms=latency_ms,
+        )
+
+        return healed, assessment
+
+    def heal_batch(self, readings: list[dict[str, Any]]) -> HealedData:
+        """Heal a batch of readings using rule-based logic.
+
+        Args:
+            readings: list of dicts with DailyReading fields.
+
+        Returns:
+            HealedData with healed readings and assessments.
+        """
+        all_healed: list[HealedReading] = []
+        all_assessments: list[HealingAssessment] = []
+
+        for r in readings:
+            healed, assessment = self.heal_reading(r)
+            all_healed.append(healed)
+            all_assessments.append(assessment)
+
+        quality_scores = [h.quality_score for h in all_healed]
+        avg_quality = sum(quality_scores) / len(quality_scores) if quality_scores else 0.0
+
+        zone_id = readings[0]["zone_id"] if readings else "unknown"
+
+        return HealedData(
+            zone_id=zone_id,
+            readings=all_healed,
+            quality_score=round(avg_quality, 3),
+            assessments=all_assessments,
+            healer_used="rule_based",
+        )