feat(api): compare endpoint carries supplementary blocks, national averages and benchmarks

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0146VHeLAWjDVE2B5uU67jCB

backend/app.py

@@ -25,6 +25,7 @@ import asyncio
 from .config import settings
 from .data_loader import (
     clear_cache,
+    compute_benchmarks,
     load_school_data,
     load_latest_school_data,
     geocode_single_postcode,
@@ -662,6 +663,34 @@ async def compare_schools(
     if comparison_data.empty:
         raise HTTPException(status_code=404, detail="No schools found")
 
+    # One session for all schools' supplementary blocks; failures degrade
+    # to empty blocks rather than failing a working comparison (mirrors
+    # the detail endpoint's defensive pattern).
+    from . import database
+
+    _EMPTY_SUPPLEMENTARY = {
+        "ofsted": None,
+        "census": None,
+        "admissions": None,
+        "admissions_history": [],
+        "deprivation": None,
+    }
+    supplementary_by_urn: dict = {}
+    db = None
+    try:
+        db = database.SessionLocal()
+        for urn in urn_list:
+            supp = get_supplementary_data(db, urn)
+            supplementary_by_urn[urn] = {
+                key: supp.get(key, default)
+                for key, default in _EMPTY_SUPPLEMENTARY.items()
+            }
+    except Exception:
+        supplementary_by_urn = {}
+    finally:
+        if db is not None:
+            db.close()
+
     result = {}
     for urn in urn_list:
         school_data = comparison_data[comparison_data["urn"] == urn].sort_values("year")
@@ -679,9 +708,16 @@ async def compare_schools(
                     "rwm_expected_pct": float(latest["rwm_expected_pct"]) if pd.notna(latest.get("rwm_expected_pct")) else None,
                 },
                 "yearly_data": clean_for_json(school_data),
+                **supplementary_by_urn.get(urn, dict(_EMPTY_SUPPLEMENTARY)),
             }
 
-    return {"comparison": result}
+    return {
+        "comparison": result,
+        # Official DfE anchors + computed state-school benchmarks so the
+        # compare UI can label provenance correctly (spec §8.6).
+        "national_averages": _national_averages_payload(df),
+        "benchmarks": compute_benchmarks(df),
+    }
 
 
 @app.get("/api/filters")
@@ -727,22 +763,17 @@ async def get_la_averages(request: Request):
     return {"year": latest_year, "secondary": {"attainment_8_by_la": la_avg}}
 
 
-@app.get("/api/national-averages")
-@limiter.limit(f"{settings.rate_limit_per_minute}/minute")
-async def get_national_averages(request: Request):
-    """
-    Compute national average for each metric from the latest data year.
-    Returns separate averages for primary (KS2) and secondary (KS4) schools.
-    Values are derived from the loaded DataFrame so they automatically
-    stay current when new data is loaded.
-    """
-    df = load_school_data()
+def _national_averages_payload(df: pd.DataFrame) -> dict:
+    """National-averages payload shared by /api/national-averages and
+    /api/compare. Official DfE KS2 figures come from the mart table;
+    KS4 figures are computed from our dataset (no DfE dataset yet)."""
     if df.empty:
         return {"primary": {}, "secondary": {}}
 
     ks2_metrics = [
         "rwm_expected_pct", "rwm_high_pct",
         "reading_expected_pct", "writing_expected_pct", "maths_expected_pct",
+        "gps_expected_pct", "gps_high_pct", "science_expected_pct",
         "reading_avg_score", "maths_avg_score", "gps_avg_score",
         "reading_progress", "writing_progress", "maths_progress",
         "overall_absence_pct", "persistent_absence_pct",
@@ -777,12 +808,13 @@ async def get_national_averages(request: Request):
 
     # Per-year KS2 primary averages: use official DfE figures from the mart table.
     # Per-year KS4 secondary averages: computed from our dataset (no DfE dataset yet).
-    from .database import SessionLocal
+    from . import database
     from .models import Ks2NationalAverage
 
     by_year = []
+    db = None
     try:
-        db = SessionLocal()
+        db = database.SessionLocal()
         nat_rows = db.query(Ks2NationalAverage).order_by(Ks2NationalAverage.year).all()
         # Build a lookup of computed secondary averages per year as fallback
         secondary_by_year = {}
@@ -810,7 +842,8 @@ async def get_national_averages(request: Request):
                 "secondary": secondary_by_year.get(yr, {}),
             })
     finally:
-        db.close()
+        if db is not None:
+            db.close()
 
     # Update latest_primary with official DfE figure for the latest year if available
     if by_year:
@@ -826,6 +859,17 @@ async def get_national_averages(request: Request):
     }
 
 
+@app.get("/api/national-averages")
+@limiter.limit(f"{settings.rate_limit_per_minute}/minute")
+async def get_national_averages(request: Request):
+    """
+    National averages: official DfE KS2 figures per year plus computed
+    KS4 averages, derived from the loaded DataFrame and the
+    fact_ks2_national_averages mart.
+    """
+    return _national_averages_payload(load_school_data())
+
+
 @app.get("/api/metrics")
 @limiter.limit(f"{settings.rate_limit_per_minute}/minute")
 async def get_available_metrics(request: Request):