Agentic SWMM Workflow

1# Agentic SWMM Workflow
2 
3<p align="center">
4  <img src="docs/figs/agentic_swmm_logo.png" alt="Agentic SWMM logo with agentic robot, stormwater system, and SWMM wordmark" width="900" />
5</p>
6 
7<p align="center">
8  <a href="https://aiswmm.com/demo/">
9    <img src="https://img.shields.io/badge/demo-live-1a7f37" alt="Demo Live: aiswmm.com/demo" />
10  </a>
11  <a href="https://github.com/Zhonghao1995/agentic-swmm-workflow/actions/workflows/ci.yml">
12    <img src="https://github.com/Zhonghao1995/agentic-swmm-workflow/actions/workflows/ci.yml/badge.svg" alt="CI status" />
13  </a>
14  <a href="https://pypi.org/project/aiswmm/">
15    <img src="https://img.shields.io/pypi/v/aiswmm?label=PyPI&color=3775A9&cacheSeconds=300" alt="PyPI version" />
16  </a>
17  <a href="https://codecov.io/gh/Zhonghao1995/agentic-swmm-workflow">
18    <img src="https://codecov.io/gh/Zhonghao1995/agentic-swmm-workflow/graph/badge.svg" alt="Codecov coverage" />
19  </a>
20  <a href="https://github.com/Zhonghao1995/agentic-swmm-workflow/pkgs/container/agentic-swmm-workflow">
21    <img src="https://img.shields.io/badge/docker-reproducible-2496ED" alt="Docker reproducible environment" />
22  </a>
23  <a href="LICENSE">
24    <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" />
25  </a>
26  <a href="https://zhonghaoz.ca">
27    <img src="https://img.shields.io/badge/built%20by-Zhonghao-7C3AED" alt="Built by Zhonghao" />
28  </a>
29  <a href="https://pepy.tech/project/aiswmm">
30    <img src="https://img.shields.io/pepy/dt/aiswmm?label=downloads&color=3775A9" alt="PyPI downloads (total)" />
31  </a>
32</p>
33 
34> **Pre-1.0** · stable **v0.8.0** · `pip install aiswmm==0.8.0` · [CHANGELOG](CHANGELOG.md)
35 
36> [!TIP]
37> **Headaches from tedious model setup?** Try our another project [**SWMMCanada**](https://github.com/Zhonghao1995/SWMMCanada), our automated model-building project: draw an area anywhere in Canada and get a ready-to-run SWMM model. Up and running now.
38 
39## Highlights
40 
41- **Agentic SWMM for reproducible stormwater modeling:** the [**aiswmm**](https://pypi.org/project/aiswmm/) runtime + Skills + MCP + SWMM, with a verification-first workflow and Obsidian-compatible audit trail.
42- **Five minutes, one command:** an Agentic SWMM workflow that is auditable, memory-informed, and agent-ready.
43- **Live demo (no install, offline case replay):** try it in the browser at [aiswmm.com](https://aiswmm.com/demo/).
44- **[SWMMCanada](https://github.com/Zhonghao1995/SWMMCanada) upstream, ready to use:** inside Canada, real municipal storm networks for 35 cities or synthesis anywhere else in the country, built from Canadian open data and fetched directly into aiswmm through the `fetch_swmm_from_canada` tool; outside Canada, [SWMManywhere](https://github.com/ImperialCollegeLondon/SWMManywhere)-based synthesis covers the rest of the globe. Two complementary upstream sources, and one goal can chain fetch, simulate, and audit into a single run folder.
45- **Bring the LLM you already pay for:** ten provider routes behind one detect-first `aiswmm setup` wizard (OpenAI, Anthropic, OpenRouter, DeepSeek, Groq, Gemini, local Ollama and LM Studio, OpenAI-compatible gateways, custom endpoints), with an optional local fallback chain that keeps sessions alive through outages and quota windows.
46- **Calibrate, then force:** `aiswmm climate` batches precipitation-scaled climate scenarios over a calibrated model and writes a per-scenario comparison of runoff, flooding, outflow, and peak flow.
47- **A domain-specific agent runtime, managed-agent style:** every session is self-describing (verbatim goal, auto-derived agent snapshot with tool/skill/prompt hashes, environment fingerprint, append-only event log, status lifecycle), and the orchestration plus verification rules are open source and auditable.
48- **Runtime-portable:** the Skills and MCP servers also work with [Codex](https://openai.com/codex/), [OpenClaw](https://github.com/openclaw/openclaw), and [Hermes Agent](https://github.com/NousResearch/hermes-agent).
49- **Published research:** our paper is published in *AI for Engineering* (MDPI), June 9, 2026: [read the paper](https://doi.org/10.3390/aieng1010005).
50 
51## Project Overview
52 
53Agentic SWMM is an open-source, verification-first framework for reproducible and extensible stormwater modelling, starting with EPA SWMM. It connects QGIS-based preprocessing, upstream model generation from [SWMMCanada](https://github.com/Zhonghao1995/SWMMCanada) inside Canada (real storm networks for 35 cities, synthesis anywhere else in the country) and SWMManywhere-based synthesis outside Canada, deterministic SWMM execution, QA checks, provenance tracking, calibration and climate-scenario support, documentation, and modelling memory, while keeping human modellers in control.
54 
55**The goal is not to replace SWMM or the modeller, but to build an agentic modelling layer that makes stormwater-modelling workflows easier to reproduce, audit, extend, remember, and trust.**  Agentic SWMM comes with aiswmm as its built-in runtime. Users can describe a modelling goal in natural language, while model execution remains deterministic, inspectable, and artifact-based. The repository's MCP servers and Skills can also be used with other agent runtimes, including Codex, Claude, OpenClaw, and Hermes.
56 
57This is not a simple chat-to-SWMM wrapper. The aiswmm runtime can help coordinate the workflow, but model files, SWMM runs, QA checks, plots, provenance records, audit notes, and modelling memory remain visible as reusable artifacts. Modelling memory can summarize repeated problems and propose Skill refinements, but accepted changes still require human review and benchmark verification.
58 
59Authors: **Zhonghao Zhang** & **Caterina Valeo**  
60License: **MIT**
61 
62<p>
63  <a href="https://aiswmm.com/"><img src="https://img.shields.io/badge/Video-introduction-EA4335" alt="Introduction video" /></a>
64  <a href="https://doi.org/10.3390/aieng1010005"><img src="https://img.shields.io/badge/Published-AI%20for%20Engineering-2DA44E" alt="Published in AI for Engineering" /></a>
65  <a href="https://doi.org/10.31223/X5F47G"><img src="https://img.shields.io/badge/Preprint-EarthArXiv-1F6FEB" alt="Preprint on EarthArXiv" /></a>
66  <a href="https://doi.org/10.5281/zenodo.20337281"><img src="https://img.shields.io/badge/Zenodo-DOI-1682D4" alt="Zenodo DOI" /></a>
67  <a href="https://github.com/Zhonghao1995/agentic-swmm-workflow/releases/latest"><img src="https://img.shields.io/badge/release-v0.8.0-1F6FEB" alt="latest release v0.8.0" /></a>
68</p>
69 
70 
71## Why this project exists
72 
73Stormwater modelling is rarely one command. A typical SWMM project can involve GIS preprocessing, rainfall formatting, parameter assignment, network assembly, INP construction, model execution, QA checks, plots, calibration, uncertainty analysis, and reporting.
74 
75Agentic SWMM provides a middle path: natural-language orchestration with deterministic SWMM execution, explicit provenance, project memory, and verification-first modelling.
76 
77## What makes it different
78 
79- **Quick onboarding:** start from one-line macOS/Linux or Windows installers, with Docker and Python package paths documented separately.
80- **Agent-guided, SWMM-grounded:** agents can coordinate tasks, while model execution stays deterministic, inspectable, and CLI-runnable.
81- **Modular skill layer:** GIS, climate, building, running, plotting, calibration, uncertainty, audit, and orchestration are separated into reusable modules with MCP interfaces where available.
82- **Verification-first provenance:** build, run, audit, and comparison stages emit traceable artifacts before outputs are treated as evidence.
83- **Supervised skill evolution:** audited runs can surface recurring workflow patterns and propose updates to existing skills or new skills, while staying coupled to the current skill-driven framework.
84 
85## Meet your agent in about five minutes
86 
87macOS and Linux:
88 
89```bash
90curl -fsSL https://aiswmm.com/install.sh | bash
91```
92 
93Windows PowerShell:
94 
95```powershell
96irm https://aiswmm.com/install.ps1 | iex
97```
98 
99Reproducible run (pinned Docker image, v0.8.0), no local install:
100 
101```bash
102docker run --rm -v "$PWD/runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.8.0 acceptance
103```
104 
105After installation, launch the runtime with `aiswmm`.
106 
107One-line installers run a remote script; review it first if you want to see what executes. The installer can set up your OpenAI API key, or you can configure one later via your shell; see [API key configuration](docs/api-key-configuration.md). Never paste API keys into the `aiswmm` conversation.
108 
109**Three ways in** (one-line installer, Docker, or `pip`), compared side by side (what you get, prerequisites, reproducibility, when to pick each): [choosing an install path](docs/runtime-install-options.md).
110 
111## Workflow
112 
113<p align="center">
114  <a href="docs/figs/modeling_memory_skill_evolution.png">
115    <img src="docs/figs/modeling_memory_skill_evolution.png" alt="Agentic SWMM modeling memory and controlled skill evolution loop" style="background:#ffffff; padding:12px; border-radius:8px;" width="900" />
116  </a>
117</p>
118 
119 
120The workflow has three connected layers: execution, modeling memory, and controlled skill evolution. Natural-language requests can trigger reproducible SWMM actions; audited artifacts update human-readable and machine-readable memory; repeated patterns can produce skill-refinement proposals that still require human review and benchmark verification.
121 
122## What a run can produce
123 
124- generated or supplied SWMM input files such as `model.inp`
125- SWMM report and binary outputs such as `.rpt` and `.out`
126- manifests, command traces, QA summaries, and parsed peak-flow metrics
127- rainfall-runoff figures, calibration summaries, and fuzzy uncertainty summaries
128- audit records: `experiment_provenance.json`, `comparison.json`, and `experiment_note.md`
129- Obsidian-ready modelling notes and modelling-memory summaries
130 
131<p align="center">
132  <a href="docs/figs/aiswmm_demo_greenwich.png">
133    <img src="docs/figs/aiswmm_demo_greenwich.png" alt="Agentic SWMM live demo (Greenwich Peninsula): synthesised network on a map, agent chat, artifacts (model.inp, model.rpt, subcatchments.geojson, graph.parquet, network_map.png), and a deterministic audit record" width="900" />
134  </a>
135</p>
136<p align="center"><sub><a href="https://aiswmm.com/demo/">▶ Try the live demo</a>: Greenwich Peninsula, <a href="https://github.com/ImperialCollegeLondon/SWMManywhere">SWMManywhere</a> synthesis → swmm5 run → audit → render, end to end in the browser.</sub></p>
137 
138## Validation snapshot
139 
140The repository includes runnable benchmarks and research previews with different evidence boundaries. The README keeps only the index; figures, commands, and boundary notes live in [Validation evidence](docs/validation-evidence.md).
141 
142| Path | What it shows | Evidence boundary |
143| --- | --- | --- |
144| [Information-loss-guided subcatchment partition](docs/validation-evidence.md#information-loss-guided-subcatchment-partition) | QGIS-to-Agentic SWMM preprocessing using entropy and fuzzy-similarity concepts from Zhang & Valeo's [Journal of Hydrology paper](https://doi.org/10.1016/j.jhydrol.2025.134447) | GIS preprocessing concept, not a calibrated SWMM performance claim |
145| [Raw GeoPackage-to-INP benchmark](docs/validation-evidence.md#raw-geopackage-to-inp-benchmark) | Public TUFLOW GeoPackage layers converted into SWMM-ready artifacts, QA, and audit | Structured raw GIS path, not arbitrary CAD/GIS recognition |
146| [Prepared-input SWMM benchmark](docs/validation-evidence.md#prepared-input-swmm-benchmark) | External 40-subcatchment Tecnopolo model execution, plotting, and direct `swmm5` comparison | Prepared INP validation path |
147| [Prior Monte Carlo uncertainty smoke](docs/validation-evidence.md#prior-monte-carlo-uncertainty-smoke) | Tecnopolo HORTON parameter perturbation and hydrograph envelope preview | Prior uncertainty smoke, not calibration |
148| [Optional INP-derived raw adapter benchmark](docs/validation-evidence.md#inp-derived-raw-adapter-benchmark) | Raw-like inputs extracted from a public SWMM fixture and rebuilt through the modular path | Adapter handoff check, not greenfield watershed generation |
149| [Cross-environment byte-identical reproducibility](docs/byte-identical-reproducibility.md) | A natural-language prompt (`Run the Tecnopolo (Rome 1994) demo`) drives the aiswmm chain (LLM agent → MCP → swmm-runner skill) to the same byte-identical `model.out` as bare `swmm5`, across macOS and Docker. **v0.7.1 re-verification**: the minimum natural-language prompt length for this chain is now **11 words**, and the `model.out` SHA256 remains identical across the v0.7.0 → v0.7.1 minor revision. | SWMM execution-layer reproducibility, not agentic workflow reproducibility |
150| [LLM-driven dispatch + data-scarce urban modeling (SWMManywhere)](docs/v0.7.1-swmmanywhere-nl-driven-evidence.md) | A single natural-language sentence referring only to a WGS84 bounding box drives the end-to-end SWMManywhere → SWMM → audit → network-map workflow on two independent regions (Greenwich Peninsula and NYC Midtown, ~1 km² each), with no shapefile, no DEM file, and no step-by-step tool instructions. Synthesis is the work of [SWMManywhere](https://github.com/ImperialCollegeLondon/SWMManywhere) (Imperial College London, BSD-3-Clause). | Agent-side plumbing for data-scarce baseline modeling; **not** a calibrated or validated network. Calibration is next-milestone scope. |
151| [Cross-session memory autonomous activation](docs/v0.7.1-cross-session-memory-evidence.md) | An 11-word user prompt drove a complete Tecnopolo run on 2026-05-28 during which the LLM autonomously queried `recall_session_history` and recovered two prior Tecnopolo sessions from 12 days earlier: the first user-observable activation of the memory layer on a real production run. | Memory layer fires correctly and shapes planner decisions; staleness weighting and negative-precedent handling are next-milestone scope. |
152 
153Examples: [TUFLOW](examples/tuflow-swmm-module03/README.md) and [Tecnopolo](examples/tecnopolo/README.md).
154 
155## Audit and research memory
156 
157The audit layer consolidates artifacts, QA checks, and metric provenance into an Obsidian-compatible experiment note. This example catches a recorded peak-flow value that does not match the value re-parsed from the SWMM report source section.
158 
159<p align="center">
160  <img src="docs/figs/audit_comparison_example_readme.png" alt="Experiment audit comparison showing a peak-flow provenance mismatch" width="900" />
161</p>
162 
163The downstream modelling-memory layer can summarize audited run histories into recurring failure patterns, assumptions, missing evidence, QA issues, lessons learned, and controlled proposals for updating existing skills or creating new skills. Because skills drive the workflow, these proposals stay coupled to the current Agentic SWMM framework and still require human review and benchmark verification before acceptance.
164 
165More details: [Experiment audit framework](docs/experiment-audit-framework.md) and [Modeling memory and skill evolution](docs/modeling-memory-and-skill-evolution.md).
166 
167## Learn more about the ecosystem
168 
169Agentic SWMM is the **SWMM engine** within a larger effort toward a *trustworthy, auditable, fully automated urban-hydrology modelling platform*: a top-level agentic runtime orchestrating engine-specific automation on top of a shared data-to-model front end.
170 
171| Project | Role in the ecosystem | Status |
172| --- | --- | --- |
173| [agentic-hydrology-platform](https://github.com/Zhonghao1995/agentic-hydrology-platform) | **Orchestration layer:** top-level agentic runtime that governs data, model selection, runs, and audit across the engine branches | LSTM catchment-modelling pipeline live; cross-engine (SWMM / MIKE+) orchestration in progress |
174| [SWMMCanada](https://github.com/Zhonghao1995/SWMMCanada) | **Data & model-building layer:** ingests and cleans GIS / open data and synthesises reliable model files; the shared front end for the engines. Agentic SWMM consumes it as an upstream INP source via `fetch_swmm_from_canada` (real municipal pipes for 8 Canadian cities) | SWMM today; extending to MIKE+ and InfoWorks ICM |
175| **Agentic SWMM** *(this repository)* | **SWMM engine:** verification-first EPA SWMM automation (Skills + MCP + deterministic runs + audit) | Stable v0.8.0 |
176| [Agentic-MIKE-Plus](https://github.com/Zhonghao1995/Agentic-MIKE-Plus) | **MIKE+ engine:** headless DHI MIKE+ automation (Skills + MCP), built on the Agentic SWMM design and the same [method paper](https://doi.org/10.3390/aieng1010005) | Active development |
177 
178## Codex / Claude / OpenClaw / Hermes ready
179 
180Beyond its own aiswmm runtime, the Agentic SWMM workflow can be driven by external agent runtimes: Codex, Claude Code, OpenClaw, or Hermes. For an agent-orchestrated run, preload the `agent/memory/` package and point the runtime at the top-level entry skill `skills/swmm-end-to-end/SKILL.md`, which decides which workflow path to take, which QA gates must pass, and when to stop rather than invent missing inputs.
181 
182Install the skills into any skills-aware runtime (Claude Code, Codex, OpenCode, …) with one command:
183 
184```bash
185npx skills add Zhonghao1995/agentic-swmm-workflow
186```
187 
188The skills carry the workflow and evidence contracts; pair them with the [project install](docs/installation.md) for the executable toolchain (aiswmm CLI, SWMM solver, MCP servers).
189 
190More details: [Codex runtime path](docs/codex-runtime.md) · [OpenClaw execution path](docs/openclaw-execution-path.md) · [Skill installation](integrations/skills/README.md) · [MCP runtime integration](integrations/mcp/README.md).
191 
192## Documentation map
193 
194- [Validation evidence](docs/validation-evidence.md) - benchmark scope, commands, audit example, and evidence boundaries
195- [Installation and CLI guide](docs/installation.md) - Docker, local install, Windows options, and CLI examples
196- [Two interfaces, one engine](docs/interfaces.md) - how natural-language goals and CLI verbs map onto the same deterministic tools and artifacts, and when to use which
197- [LLM provider routes](docs/llm_providers.md) - ten routes out of the box (OpenAI, Anthropic, OpenRouter, DeepSeek, Groq, Gemini, local Ollama/LM Studio, gateways, custom endpoints), the `aiswmm setup` wizard, per-route auth, and the local fallback chain
198- [Climate scenario batches](docs/climate-scenarios.md) - `aiswmm climate`: calibrate first, then compare the model's response under precipitation-scaled climate scenarios, one canonical `03_climate/` summary per run
199- [Experiment audit framework](docs/experiment-audit-framework.md) - provenance, comparison, and Obsidian note contracts
200- [Modeling memory and skill evolution](docs/modeling-memory-and-skill-evolution.md) - controlled memory-to-skill refinement loop
201- [Memory runtime](docs/memory_runtime.md) - on-disk substrate, four confidence quadrants, and runtime opt-out flags
202- [Memory runtime CLI examples](docs/memory_runtime_cli.md) - one worked example per memory verb
203- [Codex runtime path](docs/codex-runtime.md) - local development, audit, Obsidian, and evidence-review workflow
204- [OpenClaw execution path](docs/openclaw-execution-path.md) - MCP tool-call sequence for agent runtimes
205- [Repository map](docs/repo-map.md) - folder-level walkthrough
206- [Calibration example](examples/calibration/README.md) - compact calibration support example
207 
208## Where collaborators can help
209 
210Contributions are welcome in additional SWMM case studies, stronger calibration and validation workflows, DEM / land-use / soil / drainage-asset workflows, new MCP tools, QA testing, tutorials, and interoperability with GIS, ML, and hydrologic toolchains.
211 
212Contact:
213- zhonghaoz@uvic.ca
214- valeo@uvic.ca
215 
216## Citation
217 
218GitHub citation metadata is provided in `CITATION.cff`. **Please cite the published article.**
219 
220### APA article (preferred)
221Zhang, Z., & Valeo, C. (2026). Agentic SWMM: Auditable and reproducible stormwater modelling workflow with Agent Skills and Model Context Protocol. *AI for Engineering, 1*(1), 5. https://doi.org/10.3390/aieng1010005
222 
223 
224### APA repository
225Zhang, Z., & Valeo, C. (2026). *agentic-swmm-workflow* [Computer software]. GitHub. https://github.com/Zhonghao1995/agentic-swmm-workflow
226