🌡️ Thermal Sentinel

Heat-risk monitoring agent powered by the FortyGuard Temperature API. Detects heat waves and temperature anomalies, generates alerts with urban-planning recommendations, and exposes an MCP tool interface. Built for the FortyGuard Hackathon'26 (Agentic AI track).

Live demo: https://thermal-sentinel-agent.vercel.app · GitHub: 0xConsole/thermal-sentinel-agent

What It Does

Thermal Sentinel is an AI agent that:

1. Queries the FortyGuard Temperature API for real-time urban temperature data
2. Detects heat waves and anomalies using Sentinel-style multi-signal anomaly detection (WHO heat bands + z-score + sustained-heat + rate-of-change)
3. Generates heat-risk alerts with actionable urban-planning recommendations
4. Exposes 11 tools via the MCP (Model Context Protocol) — any AI agent can call them
5. Displays a live dashboard with city grid, alerts, charts, and one-click demo

Quick Start

# Clone
git clone https://github.com/0xConsole/thermal-sentinel-agent.git
cd thermal-sentinel-agent

# Install deps
pip install -r requirements.txt

# Run locally (no API key needed — mock data works out of the box)
uvicorn app.main:app --reload --port 8000

# Open dashboard
open http://localhost:8000

With Real FortyGuard API

export FORTYGUARD_API_KEY="your-api-key"
export FORTYGUARD_API_BASE="https://api.fortyguard.com"  # default
uvicorn app.main:app --reload --port 8000

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Dashboard UI (static)                 │
│              REST API  +  MCP Tool Interface              │
├─────────────────────────────────────────────────────────┤
│                     FastAPI (app/main.py)                │
│         /api/* routes  +  /mcp/tools  /mcp/call          │
├─────────────────────────────────────────────────────────┤
│                    Agent (app/agent.py)                   │
│     scan_cities → monitor_city → heat_risk_report        │
├──────────────┬───────────────────┬──────────────────────┤
│ FortyGuard   │  Anomaly Detector │     Store (SQLite)    │
│  Client      │  (Sentinel-style) │   /tmp persistence    │
│ Real or mock │  4 signals + score │  readings + alerts   │
└──────────────┴───────────────────┴──────────────────────┘

MCP Tools (11)

Tool	Endpoint	Description
scan_cities	POST /mcp/call	Scan multiple cities for heat risk
get_temperature	POST /mcp/call	Current temperature for a city
get_temperature_history	POST /mcp/call	Hourly temperature history
detect_heat_anomaly	POST /mcp/call	Run anomaly detection
monitor_city	POST /mcp/call	Deep single-city monitoring
get_heat_risk_report	POST /mcp/call	Consolidated risk report
get_alerts	POST /mcp/call	Active alerts from log
acknowledge_alert	POST /mcp/call	Dismiss an alert
list_monitored_cities	POST /mcp/call	List monitorable cities
get_monitoring_stats	POST /mcp/call	Monitoring statistics
run_demo	POST /mcp/call	One-click demo scan

List tools: GET /mcp/tools Call tool: POST /mcp/call with {"name": "scan_cities", "arguments": {"cities": ["Dubai", "Phoenix"]}}

REST API

Method	Path	Description
GET	/	Dashboard UI
GET	/health	Health check (shows live/mock mode)
POST	/api/scan	Scan cities
GET	/api/temperature/{city}	Current temperature
GET	/api/history/{city}?hours=24	Temperature history
GET	/api/monitor/{city}?hours=24	Deep city monitoring
GET	/api/report?city=...	Heat-risk report
GET	/api/alerts?city=...&limit=50	Active alerts
POST	/api/alerts/{id}/ack	Acknowledge alert
GET	/api/stats	Monitoring stats
GET	/api/cities	List cities
POST	/api/demo	One-click demo

Anomaly Detection

Multi-signal, composite 0-100 risk score:

Signal	Max Points	Catches
WHO heat-risk band	40	Absolute heat level
Z-score (vs 24h baseline)	25	Statistical outlier
Sustained heat-wave (consecutive ≥38°C)	20	Heat wave declaration
Rate-of-change (≥5°C/hr)	15	Rapid shifts

Severity: info → low → medium → high → critical

Project Structure

thermal-sentinel-agent/
├── api/
│   └── index.py              # Vercel entry
├── app/
│   ├── __init__.py
│   ├── main.py               # FastAPI app + routes
│   ├── fortyguard_client.py  # API client + mock transport
│   ├── anomaly_detector.py   # Sentinel-style detection
│   ├── agent.py              # Orchestration
│   ├── mcp_server.py         # MCP tool registry
│   └── store.py              # SQLite persistence
├── static/
│   └── index.html            # Dashboard UI
├── CONCEPT.md
├── README.md
├── vercel.json
├── requirements.txt
└── .gitignore

What's Real vs Mocked

• ✅ Real: FortyGuard API integration (when FORTYGUARD_API_KEY set), anomaly detection engine, MCP tool protocol, alert generation, dashboard UI, Vercel deployment
• 🔶 Mock (fallback): When no API key, temperature data is generated from per-city climate baselines with realistic diurnal variation and anomaly injection — for zero-credential demos

Deploy

# Vercel (auto-creates project on first deploy)
vercel --prod --yes --token "$VERCEL_TOKEN"

# Or set env var on Vercel
vercel env add FORTYGUARD_API_KEY production

License

MIT

Built For

FortyGuard Hackathon'26 — Agentic AI track

• Prize: $6K + NVIDIA Jetson
• Judging: Impact (40%), Technical Execution (35%), Innovation (15%), Communication (10%)
• See CONCEPT.md for full concept and judging-criteria alignment