Add AI trigger explanations behind EXPLANATION_MODE flag

Wire TriggerExplainer into step_explain so explanation generation
can be switched from the default free template path to a Claude-
Haiku-4.5 path via EXPLANATION_MODE=ai. Default stays "template"
so nothing changes at runtime without an opt-in.

- config.py: read EXPLANATION_MODE env var (default "template")
- src/explanation/explainer.py: switch TriggerExplainer default
model from Sonnet to Haiku 4.5 (advisory rewriting is a
template-fill task, not reasoning)
- src/pipeline.py: dispatch Template vs Trigger in _step_explain
based on the flag; report mode and cost in StepResult details
- frontend/src/pages/Pipeline.tsx: add ScalingCostPanel showing
three tiers (current/pilot/state-wide) on the Architecture tab

The design point the panel makes: LLM cost is decoupled from
worker population because explanations fire at trigger events
(a handful per week), not per worker. Pilot at 106K workers
costs the same ~$0.05/wk as the demo; AI explanations on add
less than a dollar even at 10x coverage.

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

config.py

@@ -6,6 +6,7 @@ Zones are real neighborhoods with outdoor worker populations
 vulnerable to heat stress.
 """
 
+import os
 from dataclasses import dataclass, field
 
 REGION_NAME = "East Africa"
@@ -14,6 +15,12 @@ LOCALE = "en-KE"
 CURRENCY = "USD"
 CURRENCY_SYMBOL = "$"
 
+# Explanation mode for step 5 (EXPLAIN).
+#   "template" — free, instant, deterministic templates (default)
+#   "ai"       — Claude Haiku 4.5 generates bilingual explanations per trigger event
+# Scales with trigger events fired, not worker population.
+EXPLANATION_MODE = os.environ.get("EXPLANATION_MODE", "template").strip().lower()
+
 # Data source configuration
 NASA_POWER_URL = "https://power.larc.nasa.gov/api/temporal/daily/point"
 OVERPASS_URL = "https://overpass-api.de/api/interpreter"

frontend/src/pages/Pipeline.tsx

@@ -132,7 +132,75 @@ function ArchitectureDiagram() {
   )
 }
 
-// (Build Your Own content is now inline in the main component)
+// ---------------------------------------------------------------------------
+// Scaling Cost Panel
+// ---------------------------------------------------------------------------
+// Shows how LLM cost scales (or doesn't) with worker population. The design
+// point: per-user cost is decoupled from LLM cost because all AI work happens
+// at the zone and trigger-event level, not the worker level.
+
+function ScalingCostPanel() {
+  const TIERS = [
+    {
+      label: 'Current (live)',
+      scale: '15 zones · template explanations',
+      cost: '~$0.05 / week',
+      note: 'Rule-based alert messages. Zero LLM spend on explanations.',
+      color: '#2a9d8f',
+    },
+    {
+      label: 'Pilot (106K workers)',
+      scale: '15 zones · AI explanations on',
+      cost: '~$0.10 / week',
+      note: 'Claude Haiku writes bilingual alerts for every trigger event. Cost scales with events fired, not workers.',
+      color: '#1565C0',
+    },
+    {
+      label: 'State-wide (10× coverage)',
+      scale: '150 zones · AI explanations on',
+      cost: '< $1 / week',
+      note: 'Because alerts are per trigger event (not per worker), population scale barely moves the cost line.',
+      color: '#d4a019',
+    },
+  ]
+
+  return (
+    <div style={{ marginTop: '32px', paddingLeft: '20px' }}>
+      <div style={{
+        fontSize: '0.72rem', fontWeight: 600, color: '#888',
+        textTransform: 'uppercase', letterSpacing: '0.5px', marginBottom: '12px',
+      }}>
+        What it costs to run at scale
+      </div>
+      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(260px, 1fr))', gap: '12px' }}>
+        {TIERS.map(tier => (
+          <div key={tier.label} style={{
+            background: '#fff', border: '1px solid #e0dcd5', borderRadius: '8px',
+            padding: '16px 18px', borderLeft: `3px solid ${tier.color}`,
+          }}>
+            <div style={{ fontSize: '0.72rem', fontWeight: 600, color: tier.color, textTransform: 'uppercase', letterSpacing: '0.5px', marginBottom: '6px' }}>
+              {tier.label}
+            </div>
+            <div style={{ fontSize: '1.35rem', fontWeight: 700, color: '#1a1a1a', fontFamily: 'Source Serif 4, serif', marginBottom: '4px' }}>
+              {tier.cost}
+            </div>
+            <div style={{ fontSize: '0.78rem', color: '#666', marginBottom: '8px' }}>
+              {tier.scale}
+            </div>
+            <div style={{ fontSize: '0.72rem', color: '#888', lineHeight: 1.5 }}>
+              {tier.note}
+            </div>
+          </div>
+        ))}
+      </div>
+      <p style={{ fontSize: '0.72rem', color: '#888', marginTop: '12px', fontStyle: 'italic' }}>
+        AI explanations are off by default. Set{' '}
+        <code style={{ background: '#f0ede8', padding: '1px 6px', borderRadius: '3px', fontSize: '0.7rem' }}>EXPLANATION_MODE=ai</code>
+        {' '}to enable. The capability is wired end-to-end either way.
+      </p>
+    </div>
+  )
+}
 
 // ---------------------------------------------------------------------------
 // Main Component
@@ -289,6 +357,7 @@ export default function Pipeline() {
       {activeTab === 'architecture' && (
         <div className="animate-tab-enter">
           <ArchitectureDiagram />
+          <ScalingCostPanel />
         </div>
       )}
 

src/explanation/explainer.py

@@ -68,7 +68,7 @@ class ExplanationResult:
 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"):
+    def __init__(self, api_key: Optional[str] = None, model: str = "claude-haiku-4-5-20251001"):
         self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
         self.model = model
         self._client = None

src/pipeline.py

@@ -8,13 +8,14 @@ Each step has independent fallbacks — no cascading failures.
 
 import asyncio
 import logging
+import os
 import time
 import uuid
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
 from pathlib import Path
 
-from config import ZONES, ZONE_MAP
+from config import ZONES, ZONE_MAP, EXPLANATION_MODE
 
 # Pipeline runs only on Dar es Salaam zones (where the neural model is trained).
 # Other cities remain in config.py for the dashboard but don't run through the pipeline.
@@ -742,7 +743,17 @@ class HeatRiskPipeline:
             )
 
         try:
-            explainer = TemplateExplainer()  # Always use templates (free, instant)
+            # Dispatch on EXPLANATION_MODE config flag.
+            #   "template" — free, deterministic (default)
+            #   "ai"       — Claude Haiku 4.5 per trigger event. Scales with trigger
+            #                events fired, not worker population — ~$0.10/wk even at
+            #                100K+ workers.
+            if EXPLANATION_MODE == "ai" and os.environ.get("ANTHROPIC_API_KEY"):
+                explainer = TriggerExplainer()
+                mode_used = "ai"
+            else:
+                explainer = TemplateExplainer()
+                mode_used = "template"
 
             for trigger in self._triggers:
                 zone = ZONE_MAP.get(trigger.zone_id)
@@ -750,12 +761,12 @@ class HeatRiskPipeline:
                     continue
 
                 basis = self._basis_risk.get(trigger.zone_id, {})
-                # TemplateExplainer.explain is async — run it
                 explanation = asyncio.run(explainer.explain(trigger, zone, basis))
                 self._explanations.append(explanation)
                 total_tokens += getattr(explanation, "tokens_used", 0)
 
-            est_cost = total_tokens * 0.005 / 1000
+            # Haiku 4.5 pricing: $1/M input, $5/M output. Rough blended estimate.
+            est_cost = total_tokens * 3 / 1_000_000 if mode_used == "ai" else 0.0
 
             return StepResult(
                 step="explain", status="ok",
@@ -764,6 +775,7 @@ class HeatRiskPipeline:
                 details={
                     "explanations_generated": len(self._explanations),
                     "languages": ["en", "sw"],
+                    "mode": mode_used,
                     "total_tokens": total_tokens,
                     "cost_usd": est_cost,
                 },