Zhonghao1995/agentic-swmm-workflow

> **Pre-1.0** · stable **v0.9.4** · pip install aiswmm==0.9.4 · CHANGELOG
> [!TIP]
> **Headaches from tedious model setup?** Try our another project **SWMMCanada**, our automated model-building project: draw an area anywhere in Canada and get a ready-to-run SWMM model. Up and running now.
Highlights
- **Agentic SWMM for reproducible stormwater modeling:** the **aiswmm** runtime + Skills + MCP + SWMM, verification-first, with a full audit trail.
- **Live replay demo, no install:** a recorded end-to-end session, replayed in the browser at aiswmm.com.
- **One sentence to a client deliverable:** one English sentence fetched the real downtown Victoria storm network, ran SWMM, audited it, and exported a Word report, then did the same on a fifth city, Kelowna, with the model committed so the run reproduces offline: cases/downtown-victoria · cases/kelowna.
- **A model that said not to trust it:** when the requested week turned out dry, the run named its own errors as disqualifying instead of handing over bad numbers: cases/downtown-victoria-on-arm.md.
- **Published method:** *AI for Engineering* (MDPI, 2026): read the paper.
Project Overview
Agentic 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 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.
**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.
This 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.
Authors: **Zhonghao Zhang** & **Caterina Valeo**
License: **MIT**
Why this project exists
Stormwater 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.
Agentic SWMM provides a middle path: natural-language orchestration with deterministic SWMM execution, explicit provenance, project memory, and verification-first modelling.
What makes it different
- **Quick onboarding:** start from one-line macOS/Linux or Windows installers, with Docker and Python package paths documented separately.
- **Bring the LLM you already pay for:** ten provider routes behind one aiswmm setup wizard, with a local fallback chain.
- **Agent-guided, SWMM-grounded:** agents can coordinate tasks, while model execution stays deterministic, inspectable, and CLI-runnable.
- **Modular skill layer:** GIS, climate, building, running, plotting, calibration, uncertainty, audit, and orchestration are separated into reusable modules with MCP interfaces where available.
- **Verification-first provenance:** build, run, audit, and comparison stages emit traceable artifacts before outputs are treated as evidence.
- **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.