- Python 87.6%
- HTML 12.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| dataset | ||
| experiments | ||
| LTFM-WaterNetwork | ||
| optimization_utils | ||
| paper | ||
| partition_utils | ||
| static | ||
| templates | ||
| .env.example | ||
| .gitignore | ||
| app.py | ||
| mm_wds_agent.py | ||
| README.md | ||
| requirements.txt | ||
| start.bat | ||
| start.sh | ||
| wds_leak_main.py | ||
| wds_optimization_main.py | ||
| wds_partition_main.py | ||
| wds_sensor_main.py | ||
LeakAgent: a multi-agent system for leak detection using multi-modal large language model coordination in water distribution network
An Intelligent System for Leak Detection and Regional Identification via Multi-Modal LLM Coordination
Guangzhou Institute of Industrial Intelligence
🔥 News
- [2026-08] The LeakAgent paper has been accepted in Communications AI & Computing (Nature Portfolio).
- [2026-06] v1.1.0 reproducibility release: the repository now ships a complete
experiments/tree that reproduces every quantitative figure and table of the paper, together with the published result files. - [2026-02] LeakAgent code released: leak detection module, sensor placement and boundary optimization.
📋 Introduction
LeakAgent is a multi-agent system for water distribution network (WDN) management. A multimodal-LLM coordinator translates natural-language requests into executable workflows and orchestrates four specialized agents that share a single hydraulic pressure-sensitivity field:
- 💧 HydroSim — hydraulic simulation and pressure-sensitivity analysis (WNTR / EPANET).
- 🧩 PartitionSim — division of the network into hydraulically coherent DMAs (FCM clustering).
- 📡 SensorPlacement — multi-objective sensor deployment (detectability, time-to-detection, coverage, failure resilience).
- 🔍 LeakDetection — the LTGFM dual-branch graph model for joint global (leak / no-leak) and regional (which DMA) detection.
- 📊 Interactive web interface — bilingual natural-language dialogue with embedded visualizations.
🏗️ Architecture
The LeakDetection agent: (a) training workflow; (b) Adaptor layer; (c) LTGFM layers; (d) inference.
🚀 Quick Start
Prerequisites
- OS: Windows 10/11, Linux, macOS
- Python: 3.10 (versions of all pinned packages follow the paper; see
requirements.txt) - Redis (for the web app's conversation memory)
- Hardware: NVIDIA GPU (8 GB+ VRAM) recommended for training experiments
Installation & Run
-
Clone the repository
git clone https://github.com/mutianwei521/leakagent.git cd leakagent -
Configure environment
cp .env.example .env # then fill in your API keysNo credentials are stored in the code; everything is read from
.env/ environment variables. -
Start the system
pip install -r requirements.txt python app.py # or ./start.sh (Linux/mac), start.bat (Windows)
📑 Reproducing the paper
All experiments behind the paper's figures and tables live under
experiments/, one self-contained harness per result:
| Paper result | Harness |
|---|---|
| Fig. 2, Figs. S2–S5, Tables S4–S23 (detection vs leak magnitude) | experiments/leak_magnitude/ |
| Fig. 3, Figs. S6–S10, Table S24 (noise robustness) | experiments/noise_robustness/ |
| Fig. 5, Tables S44–S45 (feature & architecture ablations) | experiments/ablation/ |
| Fig. 6, Figs. S39–S42, Table S46 (baseline comparison) | experiments/baselines/ |
| Figs. S37–S38, Table S43 (MLLM coordinator comparison) | experiments/mllm_coordinator/ |
| Tables S40–S42 (error correction and recovery) | experiments/error_correction/ |
| Publication box-plot figures from Source Data | experiments/figures/ |
The published per-repetition results are included as JSON, so every figure can
be regenerated without re-running the experiments. See
experiments/README.md for commands, runtimes and
data notes (the City H network model is proprietary and not distributed).
📂 Repository structure
leakagent/
├── app.py # web application (Flask)
├── mm_wds_agent.py # MLLM coordinator + agent tools
├── wds_*_main.py # pipeline entry points (partition / sensor / leak / optimization)
├── LTFM-WaterNetwork/ # LTGFM model package (training / inference)
├── optimization_utils/ # MOEA sensor placement, hydraulic objectives
├── partition_utils/ # FCM partitioning
├── dataset/ # public benchmark networks (EXA5, EXA7, KY3, KY5)
├── experiments/ # paper reproduction harnesses + published results
├── static/, templates/ # web UI
└── paper/ # figures used in this README
📖 Citation
If you use LeakAgent in your research, please cite the following paper:
@article{mu2026leakagent,
title = {LeakAgent: a multi-agent system for leak detection using multi-modal large language model coordination in water distribution network},
author = {Mu, Tianwei and Duan, Feiyu and Xue, Dan and Yuan, Mingzhe and Wang, Wenhong and Huang, Manhong and Yang, Hui and Li, Jun and Rezakazemi, Mashallah},
journal = {Communications AI & Computing},
year = {2026},
doi = {10.1038/s44488-026-00024-w},
url = {https://doi.org/10.1038/s44488-026-00024-w}
}
📄 License
MIT — see LICENSE.