# 🛡️ Edge-Cloud AIoT Sentinel (`aiot-mcp-agent`)

**Author:** **Benalia Meriem** (<mi.benalia@gmail.com>)  
**Specialization:** Edge AI, IoT Systems, and Large Language Models  
**Academic Report:** [`report/aiot_sentinel_report.tex`](./report/aiot_sentinel_report.tex) | [📄 Download Compiled PDF](./report/aiot_sentinel_report.pdf)

> **Hierarchical Edge-Cloud AIoT Architecture with FastMCP, Multi-Modal Telemetry Ingestion, and Gated SLM Reasoning.**  
> Built as a thesis-grade and portfolio-grade engineering project demonstrating modern AIoT, edge computing trade-offs, and deterministic agent safety.

---

## 📌 Executive Summary & Research Questions

Deploying Large Language Models directly on raw IoT sensor streams creates two catastrophic engineering failures:
1. **Network & Token Flooding:** Streaming high-frequency sensor floats (temperature, humidity, CO2, dB) consumes massive bandwidth and cloud token budgets on static, nominal data.
2. **Hallucinatory Actuator Hazards:** Unchecked LLMs can dispatch dangerous commands to physical hardware (e.g., shutting down HVAC during thermal runaway, or disabling ventilation during chemical gas leaks).

### 🎯 Primary Research Questions (RQs)
- **RQ1 (Data Efficiency & Telemetry Gating):** *To what degree can on-device event-triggered deadband and rate-of-rise gradient filtering suppress redundant high-frequency IoT telemetry and LLM token overhead without attenuating critical transient anomaly transitions?*
- **RQ2 (Deterministic Actuation Safety):** *Can a standardized protocol gateway (Model Context Protocol) enforcing pre-actuation deterministic interlocks eliminate safety invariant violations when probabilistic language models control physical actuators?*
- **RQ3 (Latency & Multi-Modal Reasoning Trade-off):** *How does a tiered architecture combining edge event filtering with compact local Small Language Models (SLMs) perform relative to static heuristic baselines and monolithic cloud streaming in decision latency, cross-sensor false alarm rejection, and resource efficiency?*

**AIoT Sentinel** solves these challenges with a **three-tier hierarchical architecture**:
- **Tier 1 (Physical Edge / TinyML Gate):** Lightweight deadband & finite-difference rate-of-rise gradient filtering that eliminates **90.0% of redundant telemetry** while deterministically catching critical edge transitions.
- **Tier 2 (FastMCP Gateway & Safety Interlocks):** A Model Context Protocol (MCP) server providing typed tools, tamper-evident SHA-256 chained audit trails, and deterministic invariant checks (ISO-50001 building codes).
- **Tier 3 (Gated SLM Agent):** Correlates multi-modal sensor signals (thermal, acoustic, gas, optical, contact) to discern genuine threats from false alarms.

---

## 🏛️ System Architecture

![System Architecture](./report/figures/fig1_system_architecture.png)

```
[ ESP32 Sensor Fleet ] (DHT22, MQ-135, PIR, Acoustic, Reed Contact)
          │
          ▼  (Raw Telemetry Stream)
┌────────────────────────────────────────────────────────┐
│ Tier 1: TinyML Edge Filter                             │
│ • Deadband thresholding (&Delta;x &ge; &delta;)        │
│ • Rate-of-rise gradient detection (dx/dt &ge; &gamma;) │
│ • Periodic heartbeat synchronization                  │
│ ──> Discards 90.0% redundant nominal samples           │
└────────────────────────────────────────────────────────┘
          │ (Escalated Event Packets Only)
          ▼
┌────────────────────────────────────────────────────────┐
│ Tier 2: FastMCP Gateway (Model Context Protocol)       │
│ • get_room_state(room_id)                              │
│ • query_safety_policy(domain)                          │
│ • execute_actuator_action(...)                         │
│   ├──> [ Deterministic Safety Interlock Gate ]         │
│   └──> [ Tamper-evident SHA-256 Chained Audit Trail ]  │
└────────────────────────────────────────────────────────┘
          ▲
          │ Tool Calls & Safety Justifications
          ▼
┌────────────────────────────────────────────────────────┐
│ Tier 3: Multi-Modal SLM Reasoner (Qwen2.5 / Edge SLM)  │
│ • Cross-sensor consensus reasoning                     │
│ • False alarm rejection (e.g. transient solar heating) │
│ • Multi-stage disaster mitigation planning             │
└────────────────────────────────────────────────────────┘
```

---

## 📊 Empirical Head-to-Head Benchmark

Evaluated over **25 continuous temporal scenarios** (1,500 total ticks / 9,000 multi-sensor observations) including thermal runaway, chemical gas leaks, after-hours intrusion, HVAC energy waste, and transient solar glare:

| Architecture | Decision Accuracy | Safety Invariant Violations | Packets Transmitted | Bandwidth Saved | Avg Decision Latency | Total Tokens |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **Static Heuristics (Rule-based)** | 100.0% | 2 | 9,000 | 0.0% | **3.75 ms** | **0** |
| **Unfiltered Cloud LLM (Raw Stream)** | 92.0% | 1 | 9,000 | 0.0% | 485.00 ms | 63,000 |
| **Hierarchical AIoT Sentinel (Ours)** | **100.0%** | **0** | **900** | **90.0%** | **21.11 ms** | **680** |

### Key Empirical Findings:
- **Bandwidth & Token Efficiency:** The edge filtering layer reduces transmitted telemetry packets by **90.0%** and slashes token consumption by **92×** (from 63,000 down to 680 tokens) with **zero missed emergency anomalies**.
- **Deterministic Zero-Violation Safety:** While naive LLMs occasionally dispatch hazardous commands due to phrasing nuance, the FastMCP safety gate achieved **0 safety violations**.
- **Edge Latency:** Local SLM actuation completed in **21.11 ms**, approximately **23× faster** than round-trip cloud LLM streaming.

---

## 📈 Visual Benchmark Reports

### Multi-Modal Telemetry & Edge Detection
![Telemetry Stream](./report/figures/fig2_telemetry_stream.png)

### TinyML Bandwidth Reduction by Sensor Modality
![Compression Breakdown](./report/figures/fig3_edge_compression.png)

### Head-to-Head Metrics Comparison
![Benchmark Metrics](./report/figures/fig4_benchmark_metrics.png)

### Latency vs Token Cost Trade-off (Pareto Frontier)
![Pareto Frontier](./report/figures/fig5_pareto_frontier.png)

---

## 🛠️ Repository Layout

```
aiot-mcp-agent/
├── src/aiot/
│   ├── simulator/
│   │   └── virtual_fleet.py       # Multi-room ESP32 telemetry simulator & AR(1) drift
│   ├── edge_filter/
│   │   └── tiny_filter.py         # TinyML deadband filter & rate-of-rise gradient gate
│   ├── mcp/
│   │   └── server.py              # FastMCP Server + JSON-RPC 2.0 + SHA-256 audit log
│   ├── agent/
│   │   └── reasoner.py            # Multi-modal SLM correlation & decision agent
│   └── benchmark/
│       └── eval_harness.py        # 25-scenario continuous temporal evaluation suite
├── tests/                         # Full Pytest test suite (11/11 passing in 0.39s)
│   ├── test_simulator.py
│   ├── test_edge_filter.py
│   ├── test_mcp_server.py
│   ├── test_agent.py
│   └── test_benchmark.py
├── report/
│   ├── aiot_sentinel_report.tex   # Formal academic IEEE-style paper (Author: Benalia Meriem)
│   ├── aiot_sentinel_report.pdf   # Compiled publication-ready PDF report
│   └── figures/                   # High-res publication charts (300 DPI)
├── results/                       # Benchmark outputs (JSON and Markdown)
├── dashboard.py                   # Interactive Streamlit telemetry & live agent console
├── pyproject.toml
└── requirements.txt
```

---

## 🚀 Quickstart & Reproducibility

### 1. Installation
```bash
git clone https://github.com/Anish-Guntreddi/aiot-mcp-agent.git
cd aiot-mcp-agent
pip install -r requirements.txt
pip install -e .
```

### 2. Run Test Suite
```bash
pytest tests/ -v
```

### 3. Run Empirical Benchmark
```bash
python -m aiot.benchmark.eval_harness
```

### 4. Launch Live Streamlit Console
```bash
streamlit run dashboard.py
```

---

## 🔬 Hardware Deployment Guide (ESP32-S3 / MicroPython)

To bind this software gateway to physical hardware, flash the following snippet onto an **ESP32-S3** board with a DHT22 and MQ-135 sensor:

```python
# firmware/main.py (MicroPython for ESP32-S3)
import time, ujson, urequests
from machine import Pin, ADC

SERVER_URL = "http://<GATEWAY_IP>:8000/telemetry"
LAST_TEMP = 0.0

def read_and_filter():
    global LAST_TEMP
    # Read hardware sensor...
    current_temp = 22.4 
    if abs(current_temp - LAST_TEMP) >= 0.5 or current_temp > 40.0:
        payload = {"device_id": "esp32_01", "room_id": "server_room_a", "sensor": "temperature_c", "value": current_temp}
        urequests.post(SERVER_URL, json=payload)
        LAST_TEMP = current_temp

while True:
    read_and_filter()
    time.sleep(1)
```

---

## 📜 Citation & Academic Credit

If you use this work in academic research or engineering evaluations, please cite:

```bibtex
@article{benalia2026aiot,
  title={Hierarchical Edge-Cloud AIoT Architecture: Integrating TinyML Gating, Model Context Protocol (MCP), and Gated SLM Reasoning for Safety-Critical Facilities},
  author={Benalia, Meriem},
  journal={Department of Computer Science & Artificial Intelligence},
  year={2026}
}
```

---

## 📜 License
MIT License. Authored by **Benalia Meriem** (2026).