🌡️ HeatSafe AI — California Heat Intelligence Command Center
1-Hour Machine-Learning Temperature Forecast · NWS Heat Risk Scoring · Real-Time Live Weather Pipeline
Global AI Hackathon '26 Submission
🚀 Live Demo
👉 Open HeatSafe AI — Live Streamlit App
HeatSafe AI is a deployed end-to-end climate intelligence system for 1-hour-ahead temperature forecasting and heat-risk assessment across California.
🎯 What You Can Try
🌐 Live FortyGuard Mode — real-time weather and 1-hour ML forecast
🤖 AI Forecast — HistGradientBoosting temperature prediction
🚨 Heat Risk — NWS Rothfusz Heat Index and risk classification
🎛️ What-If Mode — interactively test temperature/humidity scenarios
📊 ERA5 2025 Backtest — replay historical observations and predictions
🛰️ FortyGuard API Inspection — verified asynchronous API request, Activity ID, and completed response
📋 Table of Contents
Project Overview
Problem Statement
System Architecture
Module Structure
ERA5 Climate Reanalysis Data
Feature Engineering
Machine Learning Model Methodology
Spatial Training Dataset
2025 Final Test Results
FortyGuard API Integration
Live Prediction Pipeline
Zero-Fabrication Policy
Heat Risk Engine
Streamlit Command Center
Historical Backtesting
Installation & Setup
Testing & Verification
Hackathon Demo Flow
Current Project Status
Known Limitations & System Boundaries
Data & Methodology Attribution
Author
Project Overview
HeatSafe AI is an end-to-end machine-learning and climate intelligence system for 1-hour-ahead temperature and heat-risk forecasting across California.
The platform integrates:
ERA5 Climate Reanalysis (Copernicus/ECMWF) for chronological model training and historical backtesting
HistGradientBoostingRegressor (scikit-learn) for 1-hour-ahead temperature forecasting
NWS Rothfusz Heat Index methodology for heat-risk scoring
FortyGuard Temperature & Heat Intelligence API for external heat-intelligence and microclimate analysis
Open-Meteo API as the supporting live hourly weather provider used to construct the model's historical context
Interactive Streamlit Command Center for live forecasting, historical replay, What-If analysis, and API inspection
Core Outputs
Predicted 1-hour temperature (°C / °F)
Forecast Heat Index (°C / °F)
Heat-risk category
Risk level
NWS-style health action guidance
FortyGuard Activity ID and completed API status for verified API requests
Problem Statement
Extreme heat creates significant risks for outdoor workers, urban populations, and vulnerable communities.
Existing public weather products may not provide the combination of:
Short-horizon localized temperature forecasting
Explicit heat-index interpretation
Interactive scenario analysis
Historical model validation
External heat-intelligence integration
HeatSafe AI addresses this by combining machine learning, climate reanalysis, live weather observations, heat-risk scoring, and FortyGuard heat intelligence into a single operational dashboard.
The system is designed around a strict zero-data-fabrication policy: if the historical observations required for the ML feature vector are unavailable, the system does not invent them.
System Architecture
┌──────────────────────────────────────────────────────────────────────────────┐ │ HeatSafe AI Architecture │ ├──────────────────────────────────────────────────────────────────────────────┤ │ │ │ [ Live Inference Mode ] [ Historical / Training Mode ] │ │ │ │ ┌──────────────────────┐ ┌──────────────────────────────┐ │ │ │ Open-Meteo API │ │ ECMWF CDS ERA5 │ │ │ │ Supporting Provider │ │ Climate Reanalysis │ │ │ └──────────┬───────────┘ └──────────────┬───────────────┘ │ │ │ Hourly history │ 2023–2025 │ │ ▼ ▼ │ │ ┌──────────────────────┐ ┌──────────────────────────────┐ │ │ │ Feature Engineering │ │ Feature Engineering │ │ │ │ 47 Features │ │ 47 Features │ │ │ └──────────┬───────────┘ └──────────────┬───────────────┘ │ │ │ │ │ │ └────────────────────┬───────────────────────┘ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │ │ HeatSafePredictor (sklearn Pipeline) │ │ │ │ StandardScaler + HistGradientBoostingRegressor │ │ │ └──────────────────────────────────┬─────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │ │ HeatRiskEngine (NWS Rothfusz HI) │ │ │ │ Categorizes: LOW (0), MODERATE (1), HIGH (2), EXTREME (3) │ │ │ └──────────────────────────────────┬─────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────────────┐ │ │ │ Streamlit Command Center (app/main.py) │ │ │ │ Live Forecast · 2025 ERA5 Backtest · Manual What-If · API Inspection│ │ │ └──────────────────────────────────┬─────────────────────────────────────┘ │ │ │ │ │ ┌──────────▼──────────┐ │ │ │ FortyGuard API │ │ │ │ Heat Intelligence │ │ │ │ / Activity Status │ │ │ └─────────────────────┘ │ └──────────────────────────────────────────────────────────────────────────────┘
Module Structure
Path
Purpose
src/models/predict.py
Model inference and 47-feature validation
src/models/heat_risk.py
NWS Rothfusz Heat Index and risk scoring
src/models/train.py
Chronological model training pipeline
src/features/engineering.py
Temporal, cyclical, lag, rolling and physics features
src/api/fortyguard.py
FortyGuard API client and asynchronous status polling
src/api/open_meteo.py
Supporting live hourly weather provider
src/pipeline/live_predict.py
End-to-end live prediction pipeline
src/visualization/spatial.py
California spatial risk visualization
app/main.py
Streamlit command center
scripts/test_fortyguard_real.py
FortyGuard API diagnostic
scripts/evaluate_model.py
2025 evaluation and feature importance
models/heatsafe_histgradientboosting.pkl
Trained production model
ERA5 Climate Reanalysis Data
HeatSafe AI uses ECMWF ERA5 climate reanalysis data retrieved through the Copernicus Climate Data Store (CDS).
Dataset Configuration
Region: California
Bounding Box: 32.5°N–42.0°N, 124.5°W–114.0°W
Spatial Resolution: 0.25° × 0.25°
Temporal Resolution: Hourly
Coverage: 2023–2025
Atmospheric Variables
Variable
Description
t2m
2-meter air temperature
d2m
2-meter dewpoint temperature
u10, v10
10-meter wind components
sp
Surface pressure
tcc
Total cloud cover
These variables are transformed into the physical units and derived quantities required by the feature-engineering pipeline.
Feature Engineering — 47 Features
The production model uses 47 deterministic input features constructed from atmospheric observations and past-only history.
No synthetic observations or fabricated lag values are inserted.
Feature Group
Count
Examples
Spatial
2
latitude, longitude
Observed Weather
4
temperature, dewpoint, pressure, cloud cover
Derived Physics
6
humidity, wind speed/direction, heat index
Temporal / Cyclical
11
hour, day, month, season, sine/cosine encodings
Lag Features
12
1h, 3h and 6h weather history
Rolling Statistics
12
3h, 6h and 12h means/std
Total
47
Feature Design
The feature vector combines:
Current atmospheric observations
Latitude and longitude
Cyclical time representations
Historical 1h / 3h / 6h lag values
3h / 6h / 12h rolling statistics
Derived humidity and wind characteristics
Heat-index-related physical information
This allows the model to learn both short-term atmospheric persistence and daily/seasonal patterns.
Machine Learning Model Methodology
Chronological Training Strategy
To prevent temporal leakage, the dataset is split strictly by calendar year:
Year
Role
Purpose
2023
Training
Model fitting
2024
Validation
Model selection / tuning
2025
Final Test
Unseen benchmark evaluation
The model is therefore evaluated on a future year that was not used for training.
Production Model
Algorithm: HistGradientBoostingRegressor
Library: scikit-learn
Preprocessing: StandardScaler
Input: 47 engineered features
Target: target_temp_c_1h
Forecast Horizon: t + 1 hour
Random State: 42
Hyperparameters
HistGradientBoostingRegressor( max_iter=200, max_depth=6, learning_rate=0.05, min_samples_leaf=20, random_state=42, )
Why HistGradientBoosting?
HistGradientBoosting provides a practical balance of:
Fast inference
Non-linear feature interactions
Strong performance on tabular weather data
Efficient training on a spatial California dataset
The model is designed for rapid short-horizon operational forecasting, not multi-day weather prediction.
Spatial Training Dataset
The production model uses a spatially distributed California dataset covering 40 representative locations.
Year
Role
Locations
2023
Training
40
2024
Validation
40
2025
Final Test
40
The spatial coverage includes different California climate environments:
Coastal regions
Inland areas
Central Valley
Desert environments
Mountain regions
Lag and rolling features are constructed from past observations. Initial warm-up rows without sufficient history are removed rather than filled with artificial values.
2025 Final Test Results
The final model was evaluated on the held-out 2025 spatial test partition.
Test observations: 350,360
Metric
Result
MAE
0.2403 °C
RMSE
0.3353 °C
R² Score
0.9883
Maximum Absolute Error
3.1526 °C
Mean Bias
+0.0063 °C
Interpretation
MAE = 0.2403 °C indicates a low average 1-hour temperature prediction error.
RMSE = 0.3353 °C captures the effect of larger prediction errors.
R² = 0.9883 indicates strong predictive performance on the held-out 2025 dataset.
Mean Bias = +0.0063 °C indicates very little systematic over- or under-prediction.
Top Permutation Features
The leading features identified during evaluation were:
temp_c
hour_sin
hour
temp_c_roll3h_mean
temp_c_lag1h
doy_cos
cloud_cover_pct
hour_cos
dewpoint_c_lag1h
wind_dir_cos
These results highlight the importance of current temperature, time-of-day patterns, and recent temperature history for short-horizon forecasting.
FortyGuard API Integration
HeatSafe AI integrates the FortyGuard Temperature & Heat Intelligence API as an external heat-intelligence and microclimate analysis service.
The client implementation is located at:
src/api/fortyguard.py
Verified API Workflow
User Coordinates │ ▼ POST /v1/heat_intelligence │ ▼ Activity ID │ ▼ GET /v1/status/{activity_id} │ ▼ Completed │ ▼ Heat Intelligence Result
Verified Capabilities
API-key authentication
Heat Intelligence submission
Asynchronous processing
Activity ID generation
Status polling
Completed API response
GeoJSON/report result handling
Downloadable report response
The application exposes this through the FortyGuard API Inspection Panel, where the Activity ID and completion status can be inspected.
Integration Boundary
FortyGuard is not used as the complete 47-feature historical input source for the ML model.
The ML model requires continuous historical context for:
Temperature lags
Dewpoint lags
Humidity lags
Wind history
Rolling temperature statistics
Rolling humidity statistics
The live ML pipeline therefore uses the supporting hourly weather provider to construct the complete 47-feature vector, while FortyGuard provides additional heat-intelligence functionality.
Live Prediction Pipeline
The live forecasting pipeline is implemented in:
src/pipeline/live_predict.py
The execution flow is:
California Location │ ▼ Live Hourly Weather Data │ ▼ Historical Context Window │ ▼ 47-Feature Engineering │ ▼ Feature Validation │ ▼ HeatSafePredictor │ ▼ +1 Hour Temperature │ ▼ HeatRiskEngine │ ▼ Heat Index + Risk Category
The predictor validates that all required model features exist before inference.
Zero-Fabrication Policy
HeatSafe AI follows a strict zero-data-fabrication policy.
If the live provider does not supply enough valid historical observations to construct the required feature vector, the system does not:
Fill missing history with zeros
Invent historical observations
Create artificial weather sequences
Pretend an incomplete vector is a valid ML input
Instead, the live pipeline returns a structured insufficient-history state:
status = "insufficient_history"
The dashboard can still communicate available observed conditions while clearly indicating that ML forecasting requires sufficient historical context.
Heat Risk Engine
After the model predicts the temperature one hour ahead, HeatSafe AI calculates the corresponding Heat Index and risk category.
Implementation:
src/models/heat_risk.py
NWS Rothfusz Heat Index
The system uses the NWS Rothfusz regression methodology, combining:
Air temperature
Relative humidity
The resulting Heat Index is displayed in both Celsius and Fahrenheit.
Risk Categories
Category
Level
Heat Index
🟢 LOW
0
< 80°F
🟡 MODERATE
1
80–90°F
🟠 HIGH
2
90–105°F
🔴 EXTREME
3
≥ 105°F
The dashboard presents the risk category together with the temperature forecast, Heat Index, and explanatory guidance.
Streamlit Command Center
The user-facing application is built with Streamlit.
Launch locally with:
streamlit run app/main.py
Dashboard Modes
🌐 Live FortyGuard Data
The live mode provides:
California location selection
Current weather conditions
1-hour ML temperature forecast
Heat Index
Heat-risk category
FortyGuard integration
API Activity ID inspection
🤖 ERA5 2025 Historical Backtest
The historical mode provides:
2025 observation selection
Actual historical temperature
Model prediction
Prediction error
Heat Index
Risk assessment
The model artifact validates the required 47 features before inference.
🎛️ Demo / What-If Mode
The What-If mode allows users to manually explore:
Temperature
Relative humidity
and immediately observe the corresponding heat-risk calculation.
Historical Backtesting
The deployed application includes the 2025 ERA5 feature dataset:
data/processed/features/california_2025.parquet
The trained model artifact is:
models/heatsafe_histgradientboosting.pkl
The backtest selects a historical observation and passes its feature vector through the same production predictor used by the application.
This provides a reproducible demonstration of the model operating on the held-out 2025 dataset.
FortyGuard API Inspection Panel
The Streamlit application includes a dedicated inspection panel for demonstrating the real FortyGuard integration.
A successful request displays:
Status: Completed Activity ID: GeoJSON Data: Received
The raw API response can also be expanded for technical inspection.
This demonstrates the complete asynchronous workflow:
Request → Activity ID → Polling → Completed Result
Installation & Setup
Prerequisites
Python 3.12+
Git
Internet connection for live API functionality
Virtual environment recommended
Clone the Repository
git clone https://github.com/Neopraveen234/HeatSafe-AI.git cd HeatSafe-AI
Create Virtual Environment
python -m venv .venv
Windows PowerShell
.venv\Scripts\Activate.ps1
macOS / Linux
source .venv/bin/activate
Install Dependencies
pip install -r requirements.txt
Configure Environment Variables
Create .env from the template:
copy .env.example .env
Configure:
FORTYGUARD_API_KEY=your_api_key_here FORTYGUARD_BASE_URL=https://api.fortyguard.com
Never commit the actual API key to GitHub.
Run the Application
streamlit run app/main.py
Testing & Verification
HeatSafe AI includes automated tests covering the major system components.
Verified Test Result
117 tests passed
The test suite covers:
Feature engineering
Model loading and prediction
47-feature validation
Heat-risk calculations
FortyGuard API client behavior
Open-Meteo integration
Live prediction pipeline
Data loading
Spatial processing
Syntax Verification
Key modules can be checked with:
python -m py_compile "app/main.py" python -m py_compile "src/models/train.py" python -m py_compile "src/api/fortyguard.py"
🏆 Hackathon Demo Flow
For a short live demonstration, use this sequence:
- Live Weather
Select a California location and show the current atmospheric conditions.
- AI Forecast
Show the model's +1 hour temperature prediction.
- Heat Risk
Show:
Heat Index
Risk category
Risk level
Health guidance
- What-If Scenario
Change temperature and relative humidity and demonstrate how the calculated risk changes.
- ERA5 Historical Validation
Switch to:
🤖 ERA5 2025 Historical Backtest
Move the observation slider and demonstrate that historical observations and predictions change.
- FortyGuard Verification
Open:
FortyGuard API Inspection Panel
Execute the Heat Intelligence request and show:
HTTP 200 Status: Completed Activity ID: ... GeoJSON Data: Received
The raw response can then be expanded if technical verification is requested.
Current Project Status
Component
Status
California spatial dataset
✅ Complete
47-feature engineering
✅ Complete
Chronological 2023/2024/2025 split
✅ Complete
HistGradientBoosting model
✅ Complete
2025 held-out evaluation
✅ Complete
1-hour live prediction
✅ Verified
Heat-risk engine
✅ Verified
What-If mode
✅ Verified
ERA5 2025 backtest
✅ Verified
FortyGuard API integration
✅ Verified
Activity ID generation
✅ Verified
FortyGuard Completed response
✅ Verified
GeoJSON response handling
✅ Verified
Streamlit application
✅ Deployed
Automated tests
✅ 117 passed
GitHub repository
✅ Updated
Live demo
✅ Available
Known Limitations & System Boundaries
Forecast Horizon
The production model is designed specifically for 1-hour-ahead temperature forecasting and is not intended to replace multi-day weather forecasts.
Historical Context
The live ML model requires sufficient historical weather observations to construct its lag and rolling features.
If the required history is unavailable, forecasting is disabled rather than fabricated.
Spatial Resolution
ERA5 operates at approximately 0.25° spatial resolution, so extremely localized microclimate effects may not be fully represented by the reanalysis data.
Heat Index Inputs
The forecast Heat Index calculation depends on the available relative-humidity information. Where a future RH forecast is unavailable, the system uses the appropriate available observed RH context rather than inventing a future humidity value.
FortyGuard Scope
FortyGuard provides additional heat intelligence and microclimate information but does not replace the complete historical feature-engineering pipeline required by the ML model.
Data & Methodology Attribution
ERA5: ECMWF / Copernicus Climate Change Service
Heat Index methodology: NOAA / National Weather Service
FortyGuard: Temperature & Heat Intelligence API
Open-Meteo: Supporting live weather data provider
Machine Learning: scikit-learn HistGradientBoostingRegressor
Application: Streamlit
👨💻 Author
Praveenkanth M
Machine Learning Enthusiast | Python Developer
GitHub: https://github.com/Neopraveen234
LinkedIn: https://www.linkedin.com/in/praveenkanth-m
Project: HeatSafe AI — California Heat Intelligence Command Center
Built for: Global AI Hackathon '26
HeatSafe AI combines machine learning, climate reanalysis, live weather data, heat-risk scoring, and external heat intelligence into an end-to-end system for 1-hour-ahead temperature forecasting and heat-risk intelligence across California.