Real-time mode + 7-day backtest tab + EIA API integration

README.md

@@ -14,21 +14,19 @@ short_description: Real-time day-ahead demand forecasting for ISO New England
 
 # ⚡ Multi-Modal Deep Learning for Energy Demand Forecasting
 
-Live demo of the trained **CNN-Transformer baseline** from CS-137 Assignment 3 (Tufts University, Spring 2026). The baseline reaches **5.24 % MAPE** on the 2022 self-evaluation slice (last 2 days of 2022) when given real HRRR weather inputs.
+Live demo of two models from our CS-137 final project (Tufts, Spring 2026):
 
-## What it does
+1. **Part 1 baseline** — CNN-Transformer (1.75 M params), reaches **5.24 % MAPE** with real HRRR weather on the 2022 self-eval slice.
+2. **Ensemble (Baseline ⊕ Chronos-Bolt-mini, zero-shot, per-zone α)** — adds the 21 M-param Amazon foundation model on demand history alone (no weather, no fine-tuning) and reaches **4.21 % MAPE** in offline evaluation.
 
-1. Pick a target datetime (UTC) — defaults to "now".
-2. The Space fetches the last 24 hours of ISO New England system demand from the public ISO Express data feed and splits it into the 8 load zones using a fixed proportion vector estimated from 2022 historical zonal reports. (If the live feed is unreachable, it falls back to a bundled 24-hour CSV from 2022.)
-3. Calendar features (hour-of-day, day-of-week, month, US-holiday flag) are computed for the past 24 h and the next 24 h.
-4. The trained baseline runs forward and produces a 24-hour per-zone demand forecast in MWh.
-5. You see two plots: an 8-panel per-zone history+forecast chart and a sorted bar of next-hour predicted demand.
+## What it does
 
-## ⚠ Demo limitation — synthetic weather inputs
+1. **Real-time tab**: every click pulls the most recent 24 h of ISO New England system demand from the [EIA Open Data API](https://www.eia.gov/opendata/) (`respondent=ISNE`, `type=D`), splits it into the 8 ISO-NE zones via fixed proportions, and runs the chosen model on it. The Space holds a personal `EIA_API_KEY` as a Secret; if EIA is unreachable we fall through to an ISO-NE legacy endpoint and finally to a bundled 2022 sample.
+2. **Backtest tab**: 7 pre-computed daily forecasts (Dec 25–31, 2022 at 00:00 UTC) with all three models side-by-side and a per-zone MAPE table. The baseline curves there were computed on the Tufts HPC cluster with **real HRRR weather**, so this tab reaches the headline accuracy that the live tab can't get without weather inputs.
 
-This Space substitutes **zeros** (training-mean weather in z-score space) for the model's weather raster channel. The cluster runs that hit **5.24 % MAPE** used real HRRR rasters. Calendar features and the recent demand pattern still drive the output, so the forecast shape is preserved, but absolute accuracy is degraded vs. the cluster.
+## ⚠ Demo limitation — synthetic weather inputs (live tab)
 
-The full real-weather pipeline (live HRRR fetch + per-zone real-time demand) is documented in the report and tracked as future work.
+The live tab substitutes **zeros** (training-mean weather in z-score space) for the baseline's weather raster channels because real-time HRRR isn't accessible from the Space. Calendar features (hour-of-day, day-of-week, month, holiday flag) and the recent demand pattern still drive the output, so the forecast shape is preserved, but absolute accuracy is lower than the cluster's 5.24 %. **Ensemble** mode largely closes the gap because Chronos-Bolt-mini doesn't need weather at all.
 
 ## Links
 
@@ -48,12 +46,19 @@ python app.py     # http://localhost:7860
 
 | File | Purpose |
 |---|---|
-| `app.py` | Gradio Blocks UI + request handler |
-| `iso_ne_fetch.py` | Live ISO-NE demand fetch (with CSV fallback) |
+| `app.py` | Gradio Blocks UI + Real-time / Backtest / About tabs |
+| `iso_ne_fetch.py` | Live demand fetch: EIA API → ISO-NE legacy → bundled CSV |
 | `calendar_features.py` | 44-d calendar one-hot encoder |
-| `model_utils.py` | Checkpoint loading + inference + denormalization |
+| `model_utils.py` | Baseline + Chronos-Bolt-mini loading, inference, per-zone ensemble |
 | `models/cnn_transformer_baseline.py` | Baseline architecture (1.75 M params) |
 | `checkpoints/best.pt` | Trained baseline weights (~20 MB) |
 | `checkpoints/norm_stats.pt` | z-score statistics for de-/normalization |
+| `assets/backtest_2022_last7d.json` | 7-day cached forecasts shown in the Backtest tab |
 | `assets/` | Figures shown in the *About* tab |
 | `about.md` | Demo explanation rendered in the UI |
+
+## Secrets
+
+| Name | Purpose |
+|---|---|
+| `EIA_API_KEY` | Personal EIA Open Data key for live ISO-NE demand. Free; register at https://www.eia.gov/opendata/register.php. Without this secret the Space still works — it just falls through to the ISO-NE legacy endpoint and (if that also fails) a bundled 2022 sample. |

about.md

@@ -5,7 +5,11 @@ This Space runs two models from our CS-137 final project on **live ISO New Engla
 1. **Baseline only** — the Part 1 CNN-Transformer (1.75 M params). Reaches **5.24 % MAPE** with real HRRR weather on the 2022 self-evaluation slice; in this Space the weather inputs are synthetic so accuracy is degraded.
 2. **Ensemble (Baseline + Chronos-Bolt-mini)** — late-fusion of the baseline with [Chronos-Bolt-mini](https://huggingface.co/amazon/chronos-bolt-mini) (Amazon, 21 M params, Apache-2.0), used **zero-shot on demand history only** — no weather, no fine-tuning. Reaches **4.21 % MAPE** on the same offline slice and is the recommended path for this demo.
 
-The Model selector at the top of the page switches between them.
+The Model selector at the top of the page switches between them. The Real-time tab always issues a forecast for *now*; the Backtest tab shows 7 pre-computed forecasts over the last week of 2022 with cluster-quality (real-HRRR) baselines so you can see the headline accuracy.
+
+### Real-time data path
+
+Each click on **Forecast next 24 h** pulls the most recent 24 hours of ISO-NE system demand from the [EIA Open Data API](https://www.eia.gov/opendata/) (`respondent=ISNE`, `type=D`). The Space holds my personal API key as a Secret named `EIA_API_KEY`; if EIA is unreachable we fall back to an ISO-NE legacy endpoint and finally to the bundled 2022 sample. The status line above the plots tells you which source served the request (`live (EIA)`, `live (ISO-NE)`, `cached`, or `sample-2022`).
 
 ### What's real vs. synthetic
 
@@ -21,9 +25,13 @@ In Baseline-only mode, the forecast is degraded vs. the cluster's **5.24 %** MAP
 
 In Ensemble mode, Chronos-Bolt-mini receives 720 hours (4 weeks) of recent per-zone demand and outputs a zero-shot 24-hour forecast for each zone. Per-zone weights $\alpha_z$ (shown beneath the chart) control the blend: $\alpha_z = 1$ keeps only the baseline; $\alpha_z = 0$ keeps only Chronos. The values come from a grid search on a 14-day validation window (2022-12-16 → 12-29) and are hard-coded in this Space — see Table 10 of the report for the underlying ablation.
 
+### Backtest tab
+
+The **Backtest** tab plays back 7 daily forecasts (Dec 25–31, 2022 at 00:00 UTC) from the `space/assets/backtest_2022_last7d.json` cache. The baseline curves there were computed on the Tufts HPC cluster with real HRRR weather inputs, so this tab demonstrates the headline accuracy that the live tab can't reach without weather. The Chronos and Ensemble curves are computed locally with the same code paths the live tab uses.
+
 ### Per-zone allocation
 
-ISO-NE's public data feed publishes *system-level* demand at 5-minute granularity. We split that total into 8 zones using fixed proportions estimated from 2022 historical zonal load reports. Per-zone real-time data requires an authenticated ISO Express account.
+ISO-NE's public data feed publishes *system-level* demand at hourly granularity. We split that total into 8 zones using fixed proportions estimated from 2022 historical zonal load reports. Per-zone real-time data requires an authenticated ISO Express account.
 
 ### What this is for
 

app.py

@@ -1,18 +1,34 @@
 """Gradio Space: Multi-Modal Deep Learning for Energy Demand Forecasting.
 
+Real-time mode (always-now, no user-supplied datetime):
+  - Pulls the most recent 24 h of ISO-NE system demand from the EIA Open
+    Data API (free key, exposed to this Space as the `EIA_API_KEY`
+    secret), splits it into the 8 ISO-NE zones via fixed proportions,
+    and runs the chosen model on it.
+  - Falls back to the bundled 2022 sample window when the live API is
+    unreachable.
+
 Two model modes:
-  - Baseline only:  Part 1 CNN-Transformer (1.75 M params) on synthetic weather
-                    + real demand history.
-  - Ensemble (Baseline + Chronos-Bolt-mini):  weather-aware baseline blended
-                    per-zone with the 21 M-parameter foundation model used
-                    zero-shot on demand history. Per Table 10 of the report,
-                    the mini variant of Chronos-Bolt gives the best per-zone
-                    ensemble (4.21 % test MAPE) and is small enough to run on
-                    the HF Spaces free CPU tier.
+  - Baseline only:  Part 1 CNN-Transformer (1.75 M params) on synthetic
+                    weather + real demand history.
+  - Ensemble (Baseline + Chronos-Bolt-mini): weather-aware baseline
+                    blended per-zone with the 21 M-param foundation
+                    model used zero-shot on demand history. Per Table 10
+                    of the report, mini gives the best per-zone ensemble
+                    (4.21 % test MAPE) and is small enough to run on the
+                    HF Spaces free CPU tier.
+
+Backtest tab:
+  - Pre-computed 7-day backtest (Dec 25-31, 2022) showing all three
+    models' forecasts vs. ground truth, with per-zone and overall MAPE.
+  - The baseline forecasts in this cache use REAL HRRR weather (computed
+    on the cluster), so this tab demonstrates the headline accuracy
+    that the live tab can't reach without weather inputs.
 """
 
 from __future__ import annotations
 
+import json
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
@@ -35,10 +51,13 @@ from model_utils import (
 ROOT = Path(__file__).parent
 ASSETS = ROOT / "assets"
 ABOUT = (ROOT / "about.md").read_text()
+BACKTEST_JSON = ASSETS / "backtest_2022_last7d.json"
 
 NAVY = "#1A3A5C"
 ACCENT = "#2E86DE"
 AMBER = "#C97B12"
+TEAL = "#16A085"
+GREY = "#7F8C8D"
 
 print("Loading baseline checkpoint...")
 MODEL, NORM_STATS = load_baseline(ROOT / "checkpoints" / "best.pt", device="cpu")
@@ -56,34 +75,27 @@ def _get_chronos():
     return _CHRONOS["pipeline"]
 
 
-def _parse_dt(text: str) -> datetime:
-    if not text or text.lower().startswith("(leave"):
-        dt = datetime.now(timezone.utc)
-    else:
-        try:
-            dt = datetime.fromisoformat(text.strip().replace("Z", "+00:00"))
-        except ValueError:
-            dt = datetime.now(timezone.utc)
-    if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=timezone.utc)
-    return dt.replace(minute=0, second=0, microsecond=0)
+def _now_utc_hour() -> datetime:
+    return datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0)
 
 
-def forecast(target_dt_text: str, model_choice: str):
-    target = _parse_dt(target_dt_text)
+# =====================================================================
+#  Real-time forecast
+# =====================================================================
+
+def forecast(model_choice: str):
+    """Always-now real-time forecast: pulls live demand, runs the chosen model."""
+    target = _now_utc_hour()
     hist_start = target - timedelta(hours=24)
 
-    # Always need 24 h history for the baseline.
     hist_demand, source = fetch_recent_demand_mwh(target)
     hist_cal = encode_range(hist_start, 24)
     fut_cal = encode_range(target, 24)
 
-    # Run baseline on synthetic weather.
     baseline_pred = run_forecast(MODEL, hist_demand, hist_cal, fut_cal,
                                   NORM_STATS, device="cpu")
 
     if model_choice == "Ensemble (Baseline + Chronos-Bolt-mini)":
-        # Need 720 h of demand history for Chronos.
         long_history, long_source = fetch_long_history_mwh(target, hours=720)
         pipeline = _get_chronos()
         chronos_pred = run_chronos_zeroshot(pipeline, long_history)
@@ -104,11 +116,11 @@ def forecast(target_dt_text: str, model_choice: str):
     bar = _bar_plot(target, pred_mwh[0])
     sys_total = pred_mwh.sum(axis=1)
     summary = (
-        f"{active_label} · "
-        f"Demand history: `{source}` · "
-        f"forecast: **{target.strftime('%Y-%m-%d %H:00')} UTC** "
-        f"to **{(target + timedelta(hours=24)).strftime('%Y-%m-%d %H:00')} UTC** · "
-        f"system-level peak in next 24 h: **{sys_total.max():,.0f} MW**."
+        f"{active_label}  \n"
+        f"Demand history source: `{source}`  ·  "
+        f"forecast issued at **{target.strftime('%Y-%m-%d %H:00')} UTC**  ·  "
+        f"covers next 24 h to **{(target + timedelta(hours=24)).strftime('%Y-%m-%d %H:00')} UTC**  ·  "
+        f"system-level peak: **{sys_total.max():,.0f} MW**."
     )
     return line, bar, summary
 
@@ -122,23 +134,20 @@ def _line_plot(target: datetime, hist: np.ndarray, pred: np.ndarray,
     hist_t = [target - timedelta(hours=24 - i) for i in range(24)]
     fut_t = [target + timedelta(hours=i + 1) for i in range(24)]
     overlay = overlay or {}
-    overlay_palette = ["#7F8C8D", "#16A085", AMBER]   # gray, teal, amber for overlays
+    overlay_palette = [GREY, TEAL, AMBER]
 
     for i, zone in enumerate(ZONE_COLS):
         r, c = i // 2 + 1, i % 2 + 1
-        # History (always solid navy)
         fig.add_trace(go.Scatter(
             x=hist_t, y=hist[:, i], mode="lines",
             line=dict(color=NAVY, width=2),
             name="history", showlegend=(i == 0),
         ), row=r, col=c)
-        # Active forecast (dashed accent blue, thicker)
         fig.add_trace(go.Scatter(
             x=fut_t, y=pred[:, i], mode="lines",
             line=dict(color=ACCENT, width=2.5, dash="dash"),
             name="forecast (active)", showlegend=(i == 0),
         ), row=r, col=c)
-        # Optional overlays (component models when in ensemble mode)
         for k, (label, arr) in enumerate(overlay.items()):
             colour = overlay_palette[k % len(overlay_palette)]
             fig.add_trace(go.Scatter(
@@ -178,43 +187,166 @@ def _bar_plot(target: datetime, next_hour_pred: np.ndarray):
 
 
 def _alpha_table_md() -> str:
-    """Markdown table of per-zone alpha values for the ensemble path."""
     rows = " | ".join(f"{z}: {ALPHA_PER_ZONE_MINI[z]:.2f}" for z in ZONE_COLS)
     return f"**Per-zone α (weight on Baseline; 1−α goes to Chronos):** {rows}"
 
 
+# =====================================================================
+#  Backtest tab (cached: 7 forecasts, Dec 25-31, 2022, real HRRR weather)
+# =====================================================================
+
+if BACKTEST_JSON.exists():
+    BACKTEST = json.loads(BACKTEST_JSON.read_text())
+else:
+    BACKTEST = None
+    print(f"WARNING: backtest cache not found at {BACKTEST_JSON}")
+
+
+def _backtest_overview_plot():
+    """One row per zone, showing 7-day truth vs. each model's forecast."""
+    if BACKTEST is None:
+        return go.Figure()
+    forecasts = BACKTEST["forecasts"]
+    fig = make_subplots(rows=4, cols=2, shared_xaxes=False,
+                        subplot_titles=ZONE_COLS,
+                        vertical_spacing=0.10, horizontal_spacing=0.07)
+    for i, zone in enumerate(ZONE_COLS):
+        r, c = i // 2 + 1, i % 2 + 1
+        for f in forecasts:
+            start = datetime.fromisoformat(f["start"]).replace(tzinfo=timezone.utc)
+            t = [start + timedelta(hours=h) for h in range(24)]
+            truth = np.asarray(f["truth_24h"])[:, i]
+            base = np.asarray(f["baseline"])[:, i]
+            chron = np.asarray(f["chronos"])[:, i]
+            ens = np.asarray(f["ensemble"])[:, i]
+            show = (i == 0 and f is forecasts[0])
+            fig.add_trace(go.Scatter(
+                x=t, y=truth, mode="lines",
+                line=dict(color=NAVY, width=2),
+                name="actual demand", showlegend=show,
+            ), row=r, col=c)
+            fig.add_trace(go.Scatter(
+                x=t, y=base, mode="lines",
+                line=dict(color=GREY, width=1, dash="dot"),
+                name="baseline (real HRRR)", showlegend=show,
+                opacity=0.85,
+            ), row=r, col=c)
+            fig.add_trace(go.Scatter(
+                x=t, y=chron, mode="lines",
+                line=dict(color=TEAL, width=1, dash="dot"),
+                name="chronos zero-shot", showlegend=show,
+                opacity=0.85,
+            ), row=r, col=c)
+            fig.add_trace(go.Scatter(
+                x=t, y=ens, mode="lines",
+                line=dict(color=ACCENT, width=2, dash="dash"),
+                name="ensemble", showlegend=show,
+            ), row=r, col=c)
+    fig.update_layout(
+        title="7-day backtest, Dec 25-31 2022 — actual demand vs. 3 model variants",
+        height=900, plot_bgcolor="white",
+        margin=dict(l=40, r=20, t=80, b=40),
+        legend=dict(orientation="h", yanchor="bottom", y=1.02,
+                    xanchor="right", x=1),
+    )
+    fig.update_yaxes(title_text="MW", title_standoff=4)
+    return fig
+
+
+def _backtest_summary_md() -> str:
+    if BACKTEST is None:
+        return "_Backtest cache missing — re-run `scripts/build_space_backtest.py`._"
+    s = BACKTEST["summary"]
+    rows = []
+    rows.append("| Model | " + " | ".join(ZONE_COLS) + " | **Overall** |")
+    rows.append("|---|" + "|".join(["---"] * (len(ZONE_COLS) + 1)) + "|")
+    for key, label in (("baseline", "Baseline (real HRRR)"),
+                       ("chronos",  "Chronos-Bolt-mini (zero-shot)"),
+                       ("ensemble", "Ensemble (per-zone α)")):
+        per_zone = " | ".join(f"{s[key]['per_zone'][z]:.2f}" for z in ZONE_COLS)
+        rows.append(f"| {label} | {per_zone} | **{s[key]['overall']:.2f}** |")
+    table = "\n".join(rows)
+    return (
+        f"### 7-day average MAPE (%) over {BACKTEST['n_forecasts']} forecasts (Dec 25–31, 2022)\n\n"
+        f"{table}\n\n"
+        f"_Each forecast is a 24-hour prediction starting at 00:00 UTC. The "
+        f"baseline numbers in this table use **real HRRR weather** (computed "
+        f"on the cluster), so they reflect the headline 5.24 % test MAPE setup. "
+        f"The live tab above uses synthetic weather, so its accuracy is lower; "
+        f"the **Ensemble** path closes most of that gap because Chronos-Bolt-mini "
+        f"doesn't need weather at all._"
+    )
+
+
+def _backtest_bars():
+    """Bar chart: overall MAPE per model (averaged over 7 forecasts)."""
+    if BACKTEST is None:
+        return go.Figure()
+    s = BACKTEST["summary"]
+    labels = ["Baseline\n(real HRRR)", "Chronos-Bolt-mini\n(zero-shot)", "Ensemble\n(per-zone α)"]
+    values = [s["baseline"]["overall"], s["chronos"]["overall"], s["ensemble"]["overall"]]
+    fig = go.Figure(go.Bar(
+        x=labels, y=values, marker_color=[GREY, TEAL, ACCENT],
+        text=[f"{v:.2f}%" for v in values], textposition="outside",
+    ))
+    fig.update_layout(
+        title="Overall MAPE on the 7-day backtest (lower is better)",
+        yaxis_title="MAPE (%)", height=350, plot_bgcolor="white",
+        margin=dict(l=60, r=40, t=60, b=60),
+    )
+    return fig
+
+
+# =====================================================================
+#  Gradio layout
+# =====================================================================
+
 with gr.Blocks(title="ISO-NE Energy Demand Forecast",
                theme=gr.themes.Default(primary_hue="blue")) as demo:
     gr.Markdown(
         "# ⚡ Multi-Modal Deep Learning for Energy Demand Forecasting\n"
         "**Author:** Pang Liu · Tufts CS-137 · "
         "[GitHub](https://github.com/jeffliulab/real-time-power-predict)\n\n"
-        "> ⚠ **Demo limitation:** weather inputs are synthetic (training-mean "
-        "zeros). The cluster runs reach **5.24 % MAPE** with real HRRR weather; "
-        "the **Ensemble** path adds Chronos-Bolt-mini (foundation model, "
-        "zero-shot on demand history) which does not need weather and reaches "
-        "**4.21 % MAPE** in our offline evaluation. See the *About* tab for details."
+        "> 🔴 **Real-time mode**: every click pulls the most recent ISO-NE system "
+        "demand from the EIA Open Data API and forecasts the next 24 h.\n"
+        "> ⚠ **Demo limitation**: weather inputs are synthetic (training-mean "
+        "zeros) since real-time HRRR rasters aren't available in this Space. "
+        "The cluster runs reach **5.24 % MAPE** with real HRRR weather; the "
+        "**Ensemble** path adds Chronos-Bolt-mini (zero-shot on demand history "
+        "only — no weather) and reaches **4.21 % MAPE** in our offline "
+        "evaluation. See the **Backtest** tab for a 7-day side-by-side "
+        "comparison and the **About** tab for full details."
     )
     with gr.Row():
-        dt_input = gr.Textbox(
-            label="Target datetime (UTC, ISO-8601 — e.g. 2022-12-30T18:00). Leave empty for now.",
-            value="",
-            placeholder="(leave empty for now)",
-        )
         model_choice = gr.Radio(
             choices=["Baseline only",
                      "Ensemble (Baseline + Chronos-Bolt-mini)"],
             value="Ensemble (Baseline + Chronos-Bolt-mini)",
             label="Model",
-            scale=1,
+            scale=2,
         )
-        run_btn = gr.Button("Run forecast", variant="primary", scale=0)
+        run_btn = gr.Button("Forecast next 24 h (now)",
+                             variant="primary", scale=1)
     summary_md = gr.Markdown()
     with gr.Tabs():
-        with gr.Tab("Forecast"):
+        with gr.Tab("Real-time forecast"):
             line_plot = gr.Plot(label="Per-zone history + forecast")
             bar_plot = gr.Plot(label="Predicted next-hour demand")
             gr.Markdown(_alpha_table_md())
+        with gr.Tab("Backtest (last 7 days of 2022)"):
+            gr.Markdown(
+                "These are 7 daily forecasts on the held-out 2022-12-25 → "
+                "12-31 window, each issued at 00:00 UTC for the next 24 h. "
+                "The **baseline** column uses real HRRR weather (computed "
+                "offline on the cluster); **Chronos-Bolt-mini** is zero-shot; "
+                "the **ensemble** is the per-zone weighted blend reported in "
+                "the paper."
+            )
+            backtest_plot = gr.Plot(value=_backtest_overview_plot(),
+                                     label="7-day per-zone comparison")
+            backtest_bars = gr.Plot(value=_backtest_bars(),
+                                     label="Overall MAPE")
+            gr.Markdown(_backtest_summary_md())
         with gr.Tab("About"):
             gr.Markdown(ABOUT)
             with gr.Row():
@@ -228,9 +360,9 @@ with gr.Blocks(title="ISO-NE Energy Demand Forecast",
                      label="Baseline CNN-Transformer architecture",
                      show_label=True)
 
-    run_btn.click(forecast, inputs=[dt_input, model_choice],
+    run_btn.click(forecast, inputs=[model_choice],
                   outputs=[line_plot, bar_plot, summary_md])
-    demo.load(forecast, inputs=[dt_input, model_choice],
+    demo.load(forecast, inputs=[model_choice],
               outputs=[line_plot, bar_plot, summary_md])
 
 

iso_ne_fetch.py

@@ -1,27 +1,33 @@
 """
 Fetch the past 24 hours of ISO-NE per-zone demand for the live demo.
 
-Two sources, in priority order:
-
-1. **Public genfuelmix API** at https://www.iso-ne.com/ws/wsclient
-   (returns system-level demand). We split the total into the 8
-   load zones using a fixed zonal-proportion vector estimated from
-   the 2022 historical zonal data.
-
-2. **Bundled CSV fallback** at `assets/sample_demand_2022.csv`.
-   Used when the API is unreachable (CORS, rate limit, HF networking
-   restrictions). Returns a representative 24-hour slice from
-   2022-12-30/31 (the same window we use for self-eval).
-
-Public API access for true per-zone real-time data requires an
-authenticated ISO-NE account. The proportional split is a reasonable
-approximation for a demo --- the model still sees real recent
-ISO-NE-wide demand patterns; only the per-zone allocation is fixed.
+Three sources, in priority order:
+
+1. **EIA Open Data API** at https://api.eia.gov/v2/electricity/rto/region-data
+   (system-level hourly demand, respondent=ISNE).  Free, requires a
+   personal API key registered via https://www.eia.gov/opendata/register.php
+   and exposed to the Space as the secret `EIA_API_KEY`.  We split the
+   system total into the 8 ISO-NE zones using a fixed proportion
+   vector estimated from 2022 zonal load reports.
+
+2. **ISO-NE legacy `wsclient` endpoint**.  Tried as a backup; in
+   practice it currently returns HTTP 500 from outside the IETF
+   network, so it almost always falls through.
+
+3. **Bundled CSV fallback** at `assets/sample_demand_2022.csv` (24 h)
+   and `assets/sample_demand_2022_long.csv` (720 h).  Used when both
+   live paths fail (no key configured, network down, rate-limited).
+
+True per-zone real-time data requires an authenticated ISO Express
+account. The proportional split is a reasonable demo approximation:
+the model sees real recent ISO-NE-wide demand patterns; only the
+per-zone allocation is fixed.
 """
 
 from __future__ import annotations
 
 import logging
+import os
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Optional
@@ -62,10 +68,68 @@ def _cache_key(end_dt: datetime) -> str:
     return end_dt.strftime("%Y-%m-%dT%H:00")
 
 
+EIA_API_URL = "https://api.eia.gov/v2/electricity/rto/region-data/data/"
+
+
+def _try_eia_api(end_dt: datetime, hours: int = 24) -> Optional[np.ndarray]:
+    """Fetch ISO-NE system demand from EIA Open Data.
+
+    Requires the env var ``EIA_API_KEY`` (registered free at
+    https://www.eia.gov/opendata/register.php and exposed to this
+    Space as a Secret).
+
+    Returns ``(hours, 8)`` MWh array on success, ``None`` on any failure
+    (no key, HTTP error, missing rows, parse error).
+    """
+    key = os.environ.get("EIA_API_KEY", "").strip()
+    if not key:
+        return None
+    try:
+        # EIA returns data on hour-ending convention; pull a generous
+        # window so we can clip the freshest `hours` hours.
+        start = (end_dt - timedelta(hours=hours + 6)).strftime("%Y-%m-%dT%H")
+        end = end_dt.strftime("%Y-%m-%dT%H")
+        params = {
+            "api_key": key,
+            "frequency": "hourly",
+            "data[0]": "value",
+            "facets[respondent][]": "ISNE",
+            "facets[type][]": "D",        # 'D' = demand
+            "start": start,
+            "end": end,
+            "sort[0][column]": "period",
+            "sort[0][direction]": "desc",
+            "length": hours + 24,
+        }
+        r = requests.get(EIA_API_URL, params=params, timeout=8)
+        if r.status_code != 200:
+            logger.info("EIA API HTTP %d: %s", r.status_code, r.text[:200])
+            return None
+        payload = r.json()
+        rows = payload.get("response", {}).get("data", [])
+        if not rows:
+            return None
+        df = pd.DataFrame(rows)
+        if "period" not in df.columns or "value" not in df.columns:
+            return None
+        df["ts"] = pd.to_datetime(df["period"], utc=True, errors="coerce")
+        df = df.dropna(subset=["ts"]).sort_values("ts")
+        df["value"] = pd.to_numeric(df["value"], errors="coerce")
+        df = df.dropna(subset=["value"])
+        if len(df) < hours:
+            return None
+        last = df.tail(hours)["value"].to_numpy(dtype=np.float32)
+        return _split_to_zones(last)
+    except Exception as e:  # noqa: BLE001
+        logger.info("EIA API fetch failed: %s", e)
+        return None
+
+
 def _try_iso_ne_api(end_dt: datetime) -> Optional[np.ndarray]:
-    """Attempt to fetch system demand from ISO-NE public endpoints.
+    """Backup: ISO-NE legacy wsclient endpoint.
 
-    Returns (24, 8) array in MWh on success, or None on any failure.
+    Frequently returns HTTP 500 from outside their network, so this
+    is mostly a fallback after EIA. Returns ``(24, 8)`` MWh or ``None``.
     """
     try:
         url = "https://www.iso-ne.com/ws/wsclient"
@@ -126,10 +190,15 @@ def fetch_recent_demand_mwh(end_dt: Optional[datetime] = None):
         if (datetime.now(timezone.utc) - ts).total_seconds() < _CACHE_TTL_SECONDS:
             return arr.copy(), "cached"
 
+    arr = _try_eia_api(end_dt, hours=24)
+    if arr is not None:
+        _CACHE[key] = (datetime.now(timezone.utc), arr)
+        return arr.copy(), "live (EIA)"
+
     arr = _try_iso_ne_api(end_dt)
     if arr is not None:
         _CACHE[key] = (datetime.now(timezone.utc), arr)
-        return arr.copy(), "live"
+        return arr.copy(), "live (ISO-NE)"
 
     arr = _load_sample_csv()
     return arr, "sample-2022"