docs: add CyclePlan model description, inference example, and performance metrics

README.md

@@ -11,36 +11,89 @@ tags:
 license: cc-by-nc-4.0
 ---
 
-# DeepSignal-4B-V1 (GGUF)
+# DeepSignal (GGUF)
 
-This repository provides a GGUF model file for local inference (e.g., `llama.cpp` / LM Studio). It is intended for traffic-signal-control analysis and related text-generation workflows.
+This repository provides GGUF model files for local inference (e.g., `llama.cpp` / LM Studio). It contains two models for traffic-signal-control tasks.
 For details, check our repository at [`AIMSLaboratory/DeepSignal`](https://github.com/AIMSLaboratory/DeepSignal).
 
+## Models
 
-## Files
+This repository contains two models:
 
-- `DeepSignal-4B_V1.F16.gguf`
-- `config.json`
+- **DeepSignal-Phase-4B-V1** — next signal-phase prediction (predicts which phase to activate next and for how long)
+- **DeepSignal-CyclePlan-4B-V1** — signal-cycle timing optimization (outputs green-time allocations for every phase in the upcoming cycle)
 
-## Quickstart (llama.cpp)
+## Model Files
+
+| Filename | Model | Quantization | Size | Description |
+|:---|:---:|:---:|:---:|:---|
+| `DeepSignal-Phase-4B_V1.F16.gguf` | Phase | F16 (full precision) | ~8 GB | Phase model, full precision |
+| `DeepSignal-CyclePlan-4B_V1.F16.gguf` | CyclePlan | F16 (full precision) | ~8 GB | CyclePlan model, full precision |
+| `DeepSignal-CyclePlan-4B_V1.Q4_K_M.gguf` | CyclePlan | Q4_K_M (4-bit quantized) | ~2.5 GB | CyclePlan model, quantized (recommended for local inference) |
+
+## DeepSignal-Phase-4B-V1
+
+DeepSignal-Phase-4B-V1 is designed for **next signal-phase prediction**. Given the current traffic scene and state at an intersection, it predicts which signal phase to activate next and for how long.
+
+**Quickstart (llama.cpp):**
 
 ```bash
-llama-cli -m DeepSignal-4B_V1.F16.gguf -p "You are a traffic management expert. You can use your traffic knowledge to solve the traffic signal control task.
-Based on the given traffic {scene} and {state}, predict the next signal phase and its duration.
+llama-cli -m DeepSignal-Phase-4B_V1.F16.gguf -p "You are a traffic management expert. You can use your traffic knowledge to solve the traffic signal control task.
+Based on the given traffic scene and state, predict the next signal phase and its duration.
 You must answer directly, the format must be: next signal phase: {number}, duration: {seconds} seconds
 where the number is the phase index (starting from 0) and the seconds is the duration (usually between 20-90 seconds)."
 ```
 
-*You need to input the {scene} (total number of phases, which phases controls which lanes/directions and current phase ID/number, etc) and {state} (number of queing vehicles per lane, throughout vehicles per lane during the current phase, etc)*
+*You need to input the scene (total number of phases, which phases control which lanes/directions, and current phase ID/number, etc.) and state (number of queuing vehicles per lane, throughput vehicles per lane during the current phase, etc.)*
+
+## DeepSignal-CyclePlan-4B-V1
+
+DeepSignal-CyclePlan-4B-V1 is designed for **signal-cycle timing optimization**. It takes predicted traffic state data for the upcoming cycle as input and outputs green-time allocations for every phase.
+
+**System Prompt:**
+
+```
+You are a traffic signal timing optimization expert.
+Please carefully analyze the predicted traffic states for each phase in the next cycle, provide the timing plan for the next cycle, and give your reasoning process.
+Place the reasoning process between <start_working_out> and <end_working_out>.
+Then, place your final plan between <SOLUTION> and </SOLUTION>.
+```
+
+**Quickstart (llama.cpp, Q4_K_M recommended for local inference):**
+
+```bash
+llama-cli -m DeepSignal-CyclePlan-4B_V1.Q4_K_M.gguf \
+  -p "You are a traffic signal timing optimization expert.
+Please carefully analyze the predicted traffic states for each phase in the next cycle, provide the timing plan for the next cycle, and give your reasoning process.
+Place the reasoning process between <start_working_out> and <end_working_out>.
+Then, place your final plan between <SOLUTION> and </SOLUTION>.
+
+【cycle_predict_input_json】{
+  \"prediction\": {
+    \"as_of\": \"2026-02-22T10:00:00\",
+    \"phase_waits\": [
+      {\"phase_id\": 0, \"pred_saturation\": 0.8, \"min_green\": 20, \"max_green\": 60, \"capacity\": 100},
+      {\"phase_id\": 1, \"pred_saturation\": 0.5, \"min_green\": 15, \"max_green\": 45, \"capacity\": 80}
+    ]
+  }
+}【/cycle_predict_input_json】
+
+Task (must complete):
+Mainly based on prediction.phase_waits pred_saturation (already calculated), output the final green light time for each phase in the next cycle (unit: seconds), while satisfying hard constraints."
+```
+
+**Input format**: JSON wrapped in `【cycle_predict_input_json】...【/cycle_predict_input_json】` tags, containing `prediction.phase_waits` — an array of per-phase objects with `phase_id`, `pred_saturation`, `min_green`, `max_green`, and `capacity`.
+
+**Output format**: A JSON array of objects `[{"phase_id": <int>, "final": <int>}, ...]`, where `final` is the allocated green time in integer seconds for each phase.
 
 ## Evaluation (Traffic Simulation)
 
-### Performance Metrics Comparison by Model *
+### Performance Metrics Comparison by Model (Phase) *
 
 | Model | Avg Saturation | Avg Cumulative Queue Length (veh⋅min) | Avg Throughput (veh/5min) | Avg Response Time (s) |
 |:---:|:---:|:---:|:---:|:---:|
 | [`GPT-OSS-20B (thinking)`](https://huggingface.co/openai/gpt-oss-20b) | 0.380 | 14.088 | 77.910 | 6.768 |
-| **DeepSignal-4B (Ours)** | 0.422 | 15.703 | **79.883** | 2.131 |
+| **DeepSignal-Phase-4B (Ours)** | 0.422 | 15.703 | **79.883** | 2.131 |
 | [`Qwen3-30B-A3B`](https://huggingface.co/Qwen/Qwen3-VL-30B-A3B-Instruct) | 0.431 | 17.046 | 79.059 | 2.727 |
 | [`Qwen3-4B`](https://huggingface.co/Qwen/Qwen3-4B-Instruct-2507) | 0.466 | 57.699 | 75.712 | 1.994 |
 | Max Pressure | 0.465 | 23.022 | 77.236 | ** |
@@ -50,7 +103,25 @@ where the number is the phase index (starting from 0) and the seconds is the dur
 `**`: Max Pressure is a fixed signal-timing optimization algorithm (not an LLM), so we omit its Avg Response Time; this metric is only defined for LLM-based signal-timing optimization.  
 `***`: For LightGPT-8B-Llama3, Avg Response Time is computed using only the successful responses.
 
-# License
+**Conclusion**: Thinking-enabled models (e.g., GPT-OSS-20B) can achieve better control performance, but typically incur higher response latency. Among **non-thinking** LLM baselines, **DeepSignal-Phase-4B** is the best-performing model in our evaluation.
+
+### Performance Metrics Comparison by Model (CyclePlan) *
+
+| Model | Format Success Rate (%) | Avg Queue Vehicles | Avg Delay per Vehicle (s) | Throughput (veh/min) |
+|:---:|:---:|:---:|:---:|:---:|
+| **DeepSignal-CyclePlan-4B-V1 F16 (Ours)** | **100.0** | **3.504** | **27.747** | **8.611** |
+| [`GLM-4.7-Flash`](https://huggingface.co/zai-org/glm-4.7-flash) | 100.0 | 7.323 | 29.422 | 8.567 |
+| DeepSignal-CyclePlan-4B-V1 Q4_K_M (Ours) | 98.1 | 4.783 | 29.891 | 7.722 |
+| [`Qwen3-30B-A3B`](https://huggingface.co/Qwen/Qwen3-30B-A3B-2507) | 97.1 | 6.938 | 31.135 | 7.578 |
+| [`LightGPT-8B-Llama3`](https://huggingface.co/lightgpt/LightGPT-8B-Llama3) | 68.0 | 5.026 | 31.266 | 7.380 |
+| [`GPT-OSS-20B`](https://huggingface.co/openai/gpt-oss-20b) | 65.4 | 6.289 | 31.947 | 7.247 |
+| [`Qwen3-4B (thinking)`](https://huggingface.co/Qwen/Qwen3-4B-Instruct-2507) | 54.1 | 10.060 | 48.895 | 7.096 |
+
+`*`: Each simulation scenario runs for 60 minutes. We discard the first **5 minutes** as warm-up, then compute metrics over the next **20 minutes** (minute 5 to 25). All evaluations are conducted on a **Mac Studio M3 Ultra**.
+
+**Conclusion**: DeepSignal-CyclePlan-4B-V1 (F16) achieves a 100% format success rate, the lowest average queue vehicles (3.504), and the highest throughput (8.611 veh/min) among all evaluated models. The Q4_K_M quantized version maintains strong performance with 98.1% format success rate while offering faster inference.
+
+## License
+
 This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).
 Commercial use is strictly prohibited.
-