HeatShield Labs

Inspiration

Heat days and smoke days are now a normal part of the school year. District teams juggle weather alerts, air-quality dashboards, spreadsheets, and last-minute emails just to decide recess and athletics. We built HeatShield Labs to make that a 1-click, explainable workflow with clear language and provenance.

What It Does

Turns live ERA5 meteorology (ASDI S3) and OpenAQ PM2.5 into per-campus, bilingual safety plans.
Surfaces the "principal view": peak WBGT, orange/red hours, smoke alerts, hottest hour, and a clear plan.
Ships a one-click Communications Kit (SMS, email, PA) and a Copilot that answers natural-language questions.
Provides a district map with actionable filters (tier chips, smoke alerts, dynamic marker sizes).
Adds a Scenario Simulator to test hydration cadence, schedule shifts, and supports—and diff those into the plan.
Proves provenance with a Judge Dashboard and public FastAPI docs.

How We Built It

Backend: FastAPI on Render. We fetch ERA5 from NOAA's ASDI S3 via s3fs/xarray, compute WBGT using a Liljegren-style method, fuse hourly PM2.5 (OpenAQ S3/REST), and summarize risk.

Frontend: Streamlit (glassy UI), Pydeck map, SF Pro typography, skeletons/toasts, accessibility landmarks, and robust state handling.

AI: OpenAI (gpt-4o-mini) powers the Copilot, the Communications Kit drafts, and CSV QA summaries. Safety rails and bilingual output are enforced in prompts. If a key isn't present, we fall back to deterministic text.

DevEx: GitHub Actions (Black + Ruff + pytest), containerized with Docker, and a controlled demo mode that's instant with realistic seasonal profiles.

Data & Provenance

ERA5: Anonymous reads from nsf-ncar-era5 on ASDI (S3), streaming tiles with s3fs.

OpenAQ: Nearest-site lookup via v3, S3 archive for records; REST fallback if needed.

We attribute sources per school (met_source, aq_source) and log fallbacks so judges can see exactly what drove each plan.

Why It's Robust and Explainable

We surface both metrics and rationale: orange/red hours, hottest hour, PM peaks—and "Why this action?" logic in the rule planner.
The Copilot is grounded on the latest summary and refuses medical/legal guidance; it suggests only K-12-appropriate actions.

The AI Components, Clearly

Copilot: "Given this summary, answer questions in {language}…" with rails.

Comms Kit: "Return JSON with sms/email/pa that fits constraints; bilingual tone; only add masks/HEPA if PM warrants."

QA: "Summarize CSV issues and fixes in ≤80 words."

We intentionally keep AI in the loop but not in charge so districts get speed, clarity, and traceable guardrails.

Challenges We Solved

S3 streaming of large geophysical tiles with minimal latency and zero creds (ASDI).
OpenAQ API changes (410/422) → resilient v3 + archive fallback, with transparent logs.
Streamlit UX under long-running calls: skeletons, toasts, retry buttons, and layout preservation.
Seasonal demo realism: winter == cool, summer == hot; judges see sensible WBGT in any month.

What We Learned

"Ops-ready" matters more than "model-fancy" for real institutions: provenance, comms, and a playbook beat raw predictions.
Small touches—bilingual copy, one-click PDFs, webhook buttons which dramatically reduce decision time.

What's Next (Post-judging)

Multi-campus playbook builder with asset assignment (shade, HEPA, staffing).
Historical backtesting against district actions to quantify time saved and risk reduced.
Simple rule editor for conditional automations ("If PM>55 + athletics scheduled → mask advisory").

Methods (lightweight)

We compute an hourly WBGT from near-surface ERA5 fields and shortwave flux, then assign tiers:

$$ \mathrm{WBGT} = f\,(T_{2m},\; RH,\; SW\downarrow,\; u_{10}) \quad\Rightarrow\quad \text{tier}_t \in {\text{green},\;\text{yellow},\;\text{orange},\;\text{red}} $$

The per-campus "worst tier" is the maximum tier with any hours that day, used for the district map and comms thresholding.