feat(model): add huggingface-ready model artifacts and card metadata

README.md

@@ -1,3 +1,15 @@
+---
+language: en
+tags:
+- reinforcement-learning
+- dqn
+- traffic-control
+- pytorch
+license: mit
+library_name: pytorch
+pipeline_tag: reinforcement-learning
+---
+
 # RL-Based Adaptive Traffic Intelligence System
 
 A modular, production-style Reinforcement Learning project for adaptive traffic signal control.
@@ -9,6 +21,11 @@ Traffic control is treated as a sequential decision-making problem. An agent sel
 - 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)
@@ -61,6 +78,17 @@ Use the project-local virtual environment.
 .\.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
@@ -76,7 +104,7 @@ Artifacts are saved to `outputs/`:
 - `fixed_trajectory.png`
 - `rl_trajectory.png`
 
-## Measured Results (Latest Run)
+## Measured Results (Demo Run)
 From `outputs/metrics_summary.json`:
 
 ### Baseline vs RL

artifacts/dqn_state_dict.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f720b22d1790faa32f0a80cbc6da7a1f67898ae81b9dca0d0e4864a20386c2c6
+size 23401

artifacts/export_model.py

@@ -0,0 +1,34 @@
+import json
+from pathlib import Path
+
+import torch
+
+from traffic_rl.env.traffic_env import TrafficEnv
+from traffic_rl.training.trainer import TrainingConfig, train_dqn
+from traffic_rl.evaluation.evaluator import evaluate_agent
+
+env_config = {
+    "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": 0.08,
+    "seed": 42,
+}
+
+cfg = TrainingConfig(episodes=80, max_steps=120, batch_size=64, target_sync_interval=10, epsilon_decay=0.97)
+env = TrafficEnv(config=env_config)
+agent, history = train_dqn(env, cfg)
+
+metrics = evaluate_agent(agent=agent, env_config=env_config, episodes=20)
+
+artifacts = Path("artifacts")
+artifacts.mkdir(exist_ok=True)
+torch.save(agent.q_network.state_dict(), artifacts / "dqn_state_dict.pt")
+(artifacts / "model_metrics.json").write_text(json.dumps(metrics, indent=2), encoding="utf-8")
+(artifacts / "model_config.json").write_text(json.dumps(env_config, indent=2), encoding="utf-8")
+print(json.dumps({"metrics": metrics, "artifact_dir": str(artifacts)}, indent=2))

artifacts/model_config.json

@@ -0,0 +1,27 @@
+{
+  "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": 0.08,
+  "seed": 42
+}

artifacts/model_metrics.json

@@ -0,0 +1,7 @@
+{
+  "reward": -1061689.7,
+  "avg_queue_length": 534.1583333333333,
+  "avg_waiting_time": 22575.933333333334,
+  "throughput": 240.0,
+  "ambulance_clearances": 0.0
+}