README.md

metadata

title: Traffix Synapse Decision Explainer
emoji: 🚦
colorFrom: green
colorTo: indigo
sdk: gradio
sdk_version: 6.31.0
app_file: app.py
short_description: Multi-agent AI traffic signal explainability demo (Tunis)
python_version: '3.12'
startup_duration_timeout: 5m

🚦 Traffix · Synapse Decision Explainer

Multi-agent hierarchical traffic signal control · Tunis city centre (J1–J6)
ESPRIT 4DS capstone project · azizmessaoud/traffix

---

What this Space shows

This Space runs Synapse, the read-only explainability layer of the Traffix system. Given a recorded traffic-signal decision, Synapse answers natural-language questions about why the agent made that choice, citing the policy that grounds the answer.

⚠️ Simulation only. No traffic simulator (SUMO) is active. No real signals are actuated. The events shown are synthetic fixtures that match the real Traffix schema.

---

The Traffix system (overview)

Traffix is a hierarchical multi-agent system that controls traffic signals for six real OpenStreetMap junctions in central Tunis:

┌──────────────────────────────────────────────────────┐
│              traffix agent hierarchy                  │
│                                                       │
│   J1 ──── J2 ──── J3                                  │
│   │         │        │   ← 6 junctions, Tunis centre │
│   J4 ──── J5 ──── J6                                  │
│                                                       │
│  A1 controller per light (exclusive write)            │
│  A2–A5 advisers send messages; A1 decides & logs      │
└──────────────────────────────────────────────────────┘
          ↓ every decision → JSONL decision log
┌──────────────────────────────────────────────────────┐
│             Synapse (this Space)                      │
│  Read-only · Never actuates signals · Never runs SUMO │
│  Answers questions from the decision log              │
└──────────────────────────────────────────────────────┘

Agent roles

Agent	Role
A1 controller	Only agent that may change signal phases
A2 pedestrian adviser	Promotes pedestrian crossings near schools
A3 bus-priority adviser	Extends green for late buses with passengers
A4 emergency adviser	Triggers preemption when an ambulance is detected
A5 forecaster	Sends 15-minute traffic predictions

ML models trained

The full system trains 11 scikit-learn / XGBoost / LightGBM models: incident detection, sensor health, pedestrian prediction, ambulance ETA, bus ETA, bus lateness, edge travel time, predictive arrivals, rain speed, demand forecast, and notification routing — plus a reinforcement-learning traffic light agent (Fitted Q-Iteration with gradient-boosted trees).

Architecture rules (checked by scripts/check_architecture.py)

• ✅ Only one controller per traffic light — no race conditions
• ✅ Every decision logged with a reason code before it is applied
• ✅ Synapse is read-only — it never writes to the simulation
• ✅ Safety mask holds conflicting phases red during emergency preemption
• ✅ Fallback probe restores fixed cycle if A1 misses its heartbeat

Honesty flags

The project explicitly labels what its numbers mean:

• simulation is not deployment evidence — SUMO metrics ≠ real-world proof
• no lives saved — simulated emergency times only
• no measured air quality — HBEFA emission proxies only
• evidence events in this demo are synthetic fixtures

---

Running the full system locally (Windows + SUMO required)

# Windows only — SUMO 1.27.1 must be installed
git clone https://github.com/azizmessaoud/traffix
cd traffix
python -m venv .venv && .venv\Scripts\activate
pip install -e ".[dev]"
python scripts/train.py
python scripts/run_experiments.py --scenario morning_peak --seeds 1 2 3

---

MCP server

This Space also exposes its API as an MCP server (Gradio 5+ mcp_server=True). Tools: check_health, list_runs, list_events, ask_synapse, get_metrics.

---

Built by ESPRIT 4DS students, 2025–2026.