feat(space): add gradio app and configure huggingface space runtime

README.md

@@ -1,135 +1,40 @@
 ---
-language: en
-tags:
-- reinforcement-learning
-- dqn
-- traffic-control
-- pytorch
-license: mit
-library_name: pytorch
-pipeline_tag: reinforcement-learning
+title: RL Traffic Intelligence
+emoji: ??
+colorFrom: blue
+colorTo: green
+sdk: gradio
+sdk_version: 5.29.0
+app_file: app.py
+pinned: false
 ---
 
 # RL-Based Adaptive Traffic Intelligence System
 
-A modular, production-style Reinforcement Learning project for adaptive traffic signal control.
+A modular reinforcement learning project for adaptive traffic signal control.
 
-## Problem Statement
-Traffic control is treated as a sequential decision-making problem. An agent selects signal actions each step to:
-- minimize waiting time
-- minimize queue length
-- maximize throughput
-- prioritize emergency vehicles
-
-## Hugging Face Model Artifacts
-- `artifacts/dqn_state_dict.pt` (trained DQN weights)
-- `artifacts/model_config.json` (environment/training config snapshot)
-- `artifacts/model_metrics.json` (evaluation snapshot)
-
-## Highlights
-- OpenEnv-style deterministic environment (`TrafficEnv`)
-- Dense multi-component reward (no sparse-only objective)
-- Fixed-time baseline controller for mandatory comparison
-- Lightweight PyTorch DQN (replay buffer, epsilon-greedy, target network)
-- Realistic traffic dynamics (stochastic arrivals, lane imbalance, peak/off-peak)
-- Emergency vehicle priority handling
-- Bonus multi-intersection decentralized simulator
-- Visualization + end-to-end demo pipeline
-- Skill-style modular wrappers for orchestration
-
-## Architecture
-- `traffic_rl/env`: core environment + multi-intersection extension
-- `traffic_rl/reward`: reward engineering logic
-- `traffic_rl/baseline`: fixed-time control baseline
-- `traffic_rl/agent`: DQN and replay buffer
-- `traffic_rl/training`: training loop
-- `traffic_rl/evaluation`: metrics + policy comparison
-- `traffic_rl/visualization`: dashboard plots
-- `traffic_rl/demo`: demo pipeline runner
-- `traffic_rl/skills`: modular reusable wrappers
-
-## State, Action, Reward
-### State
-`[Q1,Q2,Q3,Q4,W1,W2,W3,W4,phase,ambulance_flag]`
-
-### Action Space
-- `0`: hold current phase
-- `1`: switch/set NS green phase
-- `2`: switch/set EW green phase
-
-### Reward
-`R_total = R_base + flow_bonus - congestion_penalty + emergency_bonus - switch_penalty`
-
-Where:
-- `R_base = - (queue_length + waiting_time)`
-- `flow_bonus` rewards throughput
-- `congestion_penalty` penalizes overloaded states
-- `emergency_bonus` rewards ambulance clearance and penalizes ambulance delay
-- `switch_penalty` discourages unstable phase flapping
-
-## Quick Start
-Use the project-local virtual environment.
+## What this Space does
+- Runs a fixed-time baseline traffic controller
+- Trains a lightweight DQN agent
+- Compares baseline vs RL on:
+  - waiting time
+  - queue length
+  - throughput
+  - emergency handling
+- Produces visual plots for training trends and policy comparison
 
+## Local run
 ```powershell
-# run tests
 .\.venv\Scripts\python.exe -m pytest
-
-# run demo pipeline
 .\.venv\Scripts\python.exe run_demo.py --episodes 70 --eval-episodes 20 --output-dir outputs
 ```
 
-## Load Saved Weights
-```python
-import torch
-from traffic_rl.agent.dqn_agent import DQNAgent
-
-agent = DQNAgent(state_dim=10, action_dim=3)
-state_dict = torch.load("artifacts/dqn_state_dict.pt", map_location="cpu")
-agent.q_network.load_state_dict(state_dict)
-agent.sync_target()
-```
-
-## Demo Pipeline
-The demo performs:
-1. fixed baseline simulation
-2. RL training
-3. RL evaluation
-4. emergency-priority scenario
-5. metrics + plots export
-
-Artifacts are saved to `outputs/`:
-- `metrics_summary.json`
-- `training_history.png`
-- `policy_comparison.png`
-- `fixed_trajectory.png`
-- `rl_trajectory.png`
-
-## Measured Results (Demo Run)
-From `outputs/metrics_summary.json`:
-
-### Baseline vs RL
-- Waiting time improvement: **9.82%**
-- Queue length improvement: **1.64%**
-- Throughput gain: **7.62%**
-
-### Emergency Scenario
-- Baseline ambulance clearances: **1.0**
-- RL ambulance clearances: **2.0**
-
-## Skill-Modular Components
-Reusable orchestration wrappers:
-- `env_builder_skill.py`
-- `reward_engineering_skill.py`
-- `baseline_skill.py`
-- `dqn_training_skill.py`
-- `evaluation_skill.py`
-- `visualization_skill.py`
-
-## Test Coverage
-TDD tests include:
-- Environment reset/step contracts, deterministic behavior, non-negative state
-- Reward monotonicity and penalty/bonus triggers
-- Baseline phase alternation logic
-- DQN action validity and Q-value output shape
-- Training/evaluation smoke tests
-- Multi-intersection step contract
+## Project modules
+- `traffic_rl/env` � environment and traffic dynamics
+- `traffic_rl/reward` � reward engineering
+- `traffic_rl/baseline` � fixed-time baseline
+- `traffic_rl/agent` � DQN + replay buffer
+- `traffic_rl/training` � training loop
+- `traffic_rl/evaluation` � metric comparison
+- `traffic_rl/visualization` � plotting dashboard
+- `traffic_rl/skills` � modular wrappers

app.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+import gradio as gr
+
+from traffic_rl.env.traffic_env import TrafficEnv
+from traffic_rl.evaluation.evaluator import (
+    compare_policies,
+    evaluate_agent,
+    evaluate_fixed_controller,
+)
+from traffic_rl.training.trainer import TrainingConfig, train_dqn
+from traffic_rl.visualization.dashboard import plot_comparison, plot_training_history
+
+
+def _default_env_config(ambulance_prob: float, seed: int) -> dict:
+    return {
+        "max_steps": 120,
+        "arrival_mode": "stochastic",
+        "lane_bias": (1.6, 0.8, 1.4, 0.6),
+        "peak_rates": (3.8, 2.2, 3.4, 1.5),
+        "offpeak_rates": (1.4, 0.9, 1.2, 0.7),
+        "peak_duration": 35,
+        "cycle_duration": 60,
+        "service_rate": 2,
+        "ambulance_spawn_prob": ambulance_prob,
+        "seed": seed,
+    }
+
+
+def run_experiment(train_episodes: int, eval_episodes: int, ambulance_prob: float, seed: int):
+    env_config = _default_env_config(ambulance_prob=ambulance_prob, seed=seed)
+
+    baseline_metrics = evaluate_fixed_controller(
+        env_config=env_config,
+        episodes=eval_episodes,
+        switch_interval=5,
+    )
+
+    train_env = TrafficEnv(config=env_config)
+    cfg = TrainingConfig(
+        episodes=train_episodes,
+        max_steps=env_config["max_steps"],
+        batch_size=64,
+        target_sync_interval=10,
+        epsilon_decay=0.97,
+        seed=seed,
+    )
+
+    agent, history = train_dqn(env=train_env, config=cfg)
+    rl_metrics = evaluate_agent(agent=agent, env_config=env_config, episodes=eval_episodes)
+    improvement = compare_policies(baseline_metrics, rl_metrics)
+
+    run_dir = Path("outputs") / "space_runs" / datetime.now().strftime("%Y%m%d_%H%M%S")
+    run_dir.mkdir(parents=True, exist_ok=True)
+
+    train_plot = plot_training_history(history, output_dir=run_dir)["training_history"]
+    compare_plot = plot_comparison(baseline_metrics, rl_metrics, output_dir=run_dir)["policy_comparison"]
+
+    result = {
+        "baseline": baseline_metrics,
+        "rl": rl_metrics,
+        "improvement": improvement,
+        "config": {
+            "train_episodes": train_episodes,
+            "eval_episodes": eval_episodes,
+            "ambulance_prob": ambulance_prob,
+            "seed": seed,
+        },
+    }
+
+    summary_md = (
+        "## Run Summary\n"
+        f"- Waiting time improvement: **{improvement['waiting_time_improvement_pct']:.2f}%**\n"
+        f"- Queue length improvement: **{improvement['queue_length_improvement_pct']:.2f}%**\n"
+        f"- Throughput gain: **{improvement['throughput_gain_pct']:.2f}%**\n"
+        f"- Ambulance clearance gain: **{improvement['ambulance_clearance_gain_pct']:.2f}%**"
+    )
+
+    return result, summary_md, train_plot, compare_plot
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(title="RL-Based Adaptive Traffic Intelligence") as demo:
+        gr.Markdown(
+            """
+# ?? RL-Based Adaptive Traffic Intelligence System
+Train and compare a DQN traffic controller against a fixed-time baseline.
+This demo optimizes waiting time, queue length, throughput, and emergency handling.
+            """
+        )
+
+        with gr.Row():
+            train_episodes = gr.Slider(20, 200, value=70, step=10, label="Training Episodes")
+            eval_episodes = gr.Slider(5, 50, value=20, step=5, label="Evaluation Episodes")
+        with gr.Row():
+            ambulance_prob = gr.Slider(0.0, 0.4, value=0.08, step=0.01, label="Ambulance Spawn Probability")
+            seed = gr.Number(value=42, precision=0, label="Random Seed")
+
+        run_btn = gr.Button("Run RL vs Baseline", variant="primary")
+
+        metrics_json = gr.JSON(label="Metrics")
+        summary = gr.Markdown()
+        train_img = gr.Image(label="Training Trends")
+        compare_img = gr.Image(label="Policy Comparison")
+
+        run_btn.click(
+            fn=run_experiment,
+            inputs=[train_episodes, eval_episodes, ambulance_prob, seed],
+            outputs=[metrics_json, summary, train_img, compare_img],
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    app = build_app()
+    app.launch()

requirements.txt

@@ -2,3 +2,4 @@ pytest
 numpy
 matplotlib
 torch
+gradio