🚦 LLM-Assisted Light (LA-Light)

Official implementation of LLM-Assisted Light: Augmenting Traffic Signal Control with Large Language Model in Complex Urban Scenarios.

📢 Latest News

• [May 2026] Introducing OmniTraffic Benchmark and Omnitraffic Dataset: A large-scale benchmark and dataset for evaluating multi-view spatiotemporal reasoning and BEV perception in multimodal large language models (MLLMs). The full dataset contains over 8M generated VQA samples, with a 3.2K human-validated benchmark for reliable evaluation.
• [June 2026] 🔧 Codebase refresh: dynamic special events (accidents, special vehicles, sensor failures) are now loaded from a YAML config (--event-config) instead of being hard-coded; the LLM agent no longer depends on LangChain (lightweight OpenAI-based ReAct); and static intersection info (layout, phase structure, available actions) is injected into the prompt once per episode, simplifying tool calls to dynamic state only.
• [September 2025] 🎉 VLMLight accepted at NeurIPS 2025! Congratulations! Our VLM-based traffic signal control paper has been accepted at NeurIPS 2025. Paper Link
• [July 2025] Introducing VLMLight: Our next-generation framework featuring image-based traffic signal control using Vision-Language Models (VLMs) for enhanced scene understanding and real-time decision-making.
• [August 2023] We have migrated the simulation platform used in this project from Aiolos to TransSimHub (TSHub). We would like to express our sincere gratitude to our colleagues at SenseTime, @KanYuheng (阚宇衡), @MaZian (马子安), and @XuChengcheng (徐承成) (in alphabetical order) for their valuable contributions. The development of TransSimHub (TSHub) is a continuation of the work done on Aiolos.

🧩 Core Framework of LLM-Assisted Light

Five-stage hybrid decision-making for human-AI collaborative traffic control:

1. Task Planning: LLM defines traffic management role
2. Tool Selection: Dynamically invokes perception & decision tools
3. Environment Interaction: Real-time traffic data collection
4. Data Analysis: Decision unit generates control strategies
5. Execution Feedback: Implements decisions with explainable justifications

🌐 Complex Urban Scenarios

LA-Light is built for dynamic special events in urban traffic:

• ACCIDENTS — a lane is blocked (simulated with a stopped vehicle)
• SPECIAL_VEHICLES — emergency vehicles need priority
• SENSOR_FAILURES — occupancy readings are masked

Left — Road blockage (ACCIDENTS)  ·  Right — Special vehicle (SPECIAL_VEHICLES)

Events are declared in YAML and injected via --event-config; see Event-Aware Evaluation.

🚀 Getting Started with LA-Light

The current lightweight validation code keeps the LA-Light tool-calling idea and runs on single-intersection TSHub/SUMO scenarios with configurable traffic events.

🛠️ Installation

Install TransSimHub:

git clone https://github.com/Traffic-Alpha/TransSimHub.git
cd TransSimHub
pip install -e ".[all]"

Copy and edit the local configuration file:

cp config.yaml.example config.yaml

Set OPENAI_API_KEY in config.yaml or via environment variable. The local config.yaml is ignored by git.

🤖 LLM-Assisted Traffic Signal Control

Run the LLM-based traffic signal controller:

python run_llm_tsc.py \
  --scenario 4way \
  --phase-num 4 \
  --event-config scenarios/4way/events/accident_set1.yaml \
  --decision-log /tmp/llm_decision.jsonl \
  --raw-response-log /tmp/llm_raw.jsonl

The current controller uses the LLM agent for every traffic-signal decision step. It queries tools for intersection layout, signal phases, current occupancy, traditional max-pressure recommendation, emergency vehicles, accident details, blocked movements, and sensor failures. --decision-log stores structured decision records. --raw-response-log stores raw LLM outputs separately for debugging.

📊 Max-Pressure Baseline

Run the max-pressure baseline on the same scenario and event configuration:

python run_maxpressure.py \
  --scenario 4way \
  --phase-num 4 \
  --event-config scenarios/4way/events/accident_set1.yaml \
  --decision-log /tmp/maxpressure_decision.jsonl

The baseline uses the environment's get_traditional_decision() recommendation, so it is aligned with the traditional-decision tool seen by the LLM agent.

🚑 Event-Aware Evaluation

The complex urban scenarios above are declared per scenario in:

scenarios/<scenario>/events/*.yaml

and injected at runtime via --event-config. The supported sections are ACCIDENTS, SPECIAL_VEHICLES, and SENSOR_FAILURES.

Compare tripinfo results, including both regular traffic and special-vehicle efficiency:

python analyze_tsc_results.py \
  llm:4way_llm_tsc.tripinfo.xml \
  maxpressure:4way_maxpressure.tripinfo.xml

The report separates:

• regular: ordinary traffic efficiency
• special: ambulance/rescue/police/fire vehicle completion rate, waiting time, and time loss
• all: aggregate metrics

See docs/event_config.md for event configuration details.

Notes on the Current Lightweight Code

The original project included RL training/evaluation and legacy launchers. The current runnable validation path is centered on:

• run_llm_tsc.py: event-aware LLM controller with local tool-calling agent
• run_maxpressure.py: aligned max-pressure baseline
• analyze_tsc_results.py: regular/special vehicle metric comparison

RL training and trained models are not included in this lightweight validation path. For single-intersection RL-based TSC code, see single-tsc-baselines.

🎥 LA-Light Joint Decision-Making Demo

The following video shows the original LA-Light decision-making process. Each decision involves multiple tool invocations and subsequent reasoning based on tool-returned observations, culminating in a final decision and explanation.

LLM_for_TSC_README.webm

Due to the video length limit, we only captured part of the first decision-making process, including:

• Action 1: Obtaining the intersection layout, the number of lanes, and lane functions (turn left, go straight, or turn right) for each edge.
• Action 3: Obtaining the occupancy of each edge. The -E3 straight line has a higher occupancy rate, corresponding to the simulation. At this point, LA-Light can use tools to obtain real-time road network information.
• Final Decision and Explanation: Based on a series of results, LA-Light provides the final decision and explanation.

🎥 Scenario Demos

scenario1.mp4

Examples of LA-Lights Utilizing Tools to Control Traffic Signals (Normal Scenario)

scenario_2.mp4

Examples of LA-Lights Utilizing Tools to Control Traffic Signals (Emergency Vehicle (EMV) Scenario)

📜 Citation

If you find our work useful in your research, we would be grateful if you could cite our papers:

@article{wang2024llm,
  title={LLM-Assisted Light: Leveraging Large Language Model Capabilities for Human-Mimetic Traffic Signal Control in Complex Urban Environments},
  author={Wang, Maonan and Pang, Aoyu and Kan, Yuheng and Pun, Man-On and Chen, Chung Shue and Huang, Bo},
  journal={arXiv preprint arXiv:2403.08337},
  year={2024}
}

@inproceedings{wang2025vlmlight,
 author = {Wang, Maonan and Chen, Yirong and Pang, Aoyu and Cai, Yuxin and Chen, Chung Shue and Kan, Yuheng and Pun, Man On},
 booktitle = {Advances in Neural Information Processing Systems},
 editor = {D. Belgrave and C. Zhang and H. Lin and R. Pascanu and P. Koniusz and M. Ghassemi and N. Chen},
 pages = {39590--39621},
 publisher = {Curran Associates, Inc.},
 title = {{VLMLight}: Safety-Critical Traffic Signal Control via Vision-Language Meta-Control and Dual-Branch Reasoning Architecture},
 url = {https://proceedings.neurips.cc/paper_files/paper/2025/file/3849b5861dcaeaf4758eef0979a98cc6-Paper-Conference.pdf},
 volume = {38},
 year = {2025}
}

@ARTICLE{pang2026illmtsc,
  author={Pang, Aoyu and Wang, Maonan and Pun, Man-On and Chen, Chung Shue and Xiong, Xi},
  journal={IEEE Transactions on Vehicular Technology}, 
  title={iLLM-TSC: Integration Reinforcement Learning and Large Language Model for Traffic Signal Control Policy Improvement}, 
  year={2026},
  volume={75},
  number={8},
  pages={15762-15776},
  doi={10.1109/TVT.2026.3674284}
}

You may also be interested in our earlier work on RL-based traffic signal control (TSC):

@ARTICLE{wang2024unitsa,
  author={Wang, Maonan and Xiong, Xi and Kan, Yuheng and Xu, Chengcheng and Pun, Man-On},
  journal={IEEE Transactions on Vehicular Technology}, 
  title={UniTSA: A Universal Reinforcement Learning Framework for V2X Traffic Signal Control}, 
  year={2024},
  volume={73},
  number={10},
  pages={14354-14369},
  doi={10.1109/TVT.2024.3403879}
}

@ARTICLE{wang2024ccda,
  author={Wang, Maonan and Chen, Yirong and Kan, Yuheng and Xu, Chengcheng and Lepech, Michael and Pun, Man-On and Xiong, Xi},
  journal={IEEE Transactions on Intelligent Transportation Systems}, 
  title={Traffic Signal Cycle Control With Centralized Critic and Decentralized Actors Under Varying Intervention Frequencies}, 
  year={2024},
  volume={25},
  number={12},
  pages={20085-20104},
  doi={10.1109/TITS.2024.3462153}
}

@ARTICLE{pang2024delaytsc,
  author={Pang, Aoyu and Wang, Maonan and Chen, Yirong and Pun, Man-On and Lepech, Michael},
  journal={IEEE Open Journal of Vehicular Technology}, 
  title={Scalable Reinforcement Learning Framework for Traffic Signal Control Under Communication Delays}, 
  year={2024},
  volume={5},
  pages={330-343},
  doi={10.1109/OJVT.2024.3368693}
}

🤝 Open-Source Foundations

This project stands on the shoulders of these open-source giants:

• TransSimHub
• LangChain
• stable-baselines3

📮 Contact

If you have any questions, please report issues on GitHub.