Official implementation of LLM-Assisted Light: Augmenting Traffic Signal Control with Large Language Model in Complex Urban Scenarios.
- [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.
Five-stage hybrid decision-making for human-AI collaborative traffic control:
- Task Planning: LLM defines traffic management role
- Tool Selection: Dynamically invokes perception & decision tools
- Environment Interaction: Real-time traffic data collection
- Data Analysis: Decision unit generates control strategies
- Execution Feedback: Implements decisions with explainable justifications
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 prioritySENSOR_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.
The current lightweight validation code keeps the LA-Light tool-calling idea and runs on single-intersection TSHub/SUMO scenarios with configurable traffic events.
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.yamlSet OPENAI_API_KEY in config.yaml or via environment variable. The local config.yaml is ignored by git.
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.jsonlThe 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.
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.jsonlThe baseline uses the environment's get_traditional_decision() recommendation, so it is aligned with the traditional-decision tool seen by the LLM agent.
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.xmlThe report separates:
regular: ordinary traffic efficiencyspecial: ambulance/rescue/police/fire vehicle completion rate, waiting time, and time lossall: aggregate metrics
See docs/event_config.md for event configuration details.
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 agentrun_maxpressure.py: aligned max-pressure baselineanalyze_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.
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.
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)
If you find this work useful, please 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{pang2026illm,
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={},
number={},
pages={1-14},
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}
}This project stands on the shoulders of these open-source giants:
If you have any questions, please report issues on GitHub.