# 🌡️ 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](https://www.fortyguard.com/hackathon26) (Agentic AI track).

**Live demo:** [https://thermal-sentinel-agent.vercel.app](https://thermal-sentinel-agent.vercel.app) · **GitHub:** [0xConsole/thermal-sentinel-agent](https://github.com/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

```bash
# 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

```bash
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

```bash
# 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](CONCEPT.md) for full concept and judging-criteria alignment