Agentic SWMM Workflow is an open-source, validation-first framework for EPA SWMM stormwater modeling. Its goal is not to replace SWMM or modelers, but to build an agentic modeling layer on top of them, making the stormwater modeling workflow easier to reproduce, audit, extend, remember, and trust. The authors are Zhonghao Zhang and Caterina Valeo, and it is under the MIT License. The project is currently Pre-1.0, with stable version v0.9.4, installable via pip install aiswmm==0.9.4. It also provides one-line installation scripts for macOS/Linux and Windows, a Docker image, and a Python package path.
Purpose The framework takes EPA SWMM as its starting point and integrates steps such as GIS preprocessing, rainfall formatting, parameter assignment, pipe network assembly, INP construction, model execution, QA checks, plotting, calibration, uncertainty analysis, and reporting into a reproducible workflow. Users can describe modeling goals in natural language, while actual execution remains deterministic, inspectable, and artifact-based.
Main Capabilities It includes a built-in aiswmm runtime and CLI, supporting deterministic SWMM execution; a modular Skills layer covering GIS, climate, modeling, running, plotting, calibration, uncertainty, auditing, and orchestration; and provides an MCP interface that can work with external agent runtimes such as Codex, Claude Code, OpenClaw, and Hermes. For upstream model generation, within Canada, real stormwater networks for 35 cities can be obtained through SWMMCanada, or synthetic ones for any region; outside Canada, synthesis can be based on SWMManywhere. A single run can produce model.inp, .rpt, .out, manifests, command traces, QA summaries, peak flow metrics, rainfall-runoff plots, calibration summaries, fuzzy uncertainty summaries, as well as audit records such as experiment_provenance.json, comparison.json, and experiment_note.md, and generates modeling notes and modeling memory summaries usable by Obsidian.
Modeling Memory and Skill Evolution The memory layer stores parameter fingerprints from audited runs, calibration results, known poor parameter regions, tool failures, and effective fixes, so that the agent can be prompted when similar failures occur later. Repeated patterns can lead to proposed Skill improvements, but any change requires human review and benchmark validation.
Usage After installation, run aiswmm to start the runtime. The setup wizard supports routing for ten LLM providers, including OpenAI, Anthropic, OpenRouter, DeepSeek, Groq, Gemini, local Ollama/LM Studio, gateways, and custom endpoints, three of which require no API key, and includes a local fallback chain. A fixed Docker image can also be used for reproducible runs. External agent runtimes need to preload the agent/memory/ package and point to the top-level entry skill skills/swmm-end-to-end/SKILL.md, which determines the workflow path, QA gates, and when to stop rather than fabricate missing inputs. Skills can be installed into a skills-capable runtime with a single command.
Applicable Scenarios and Limitations It is suitable for reproducible, auditable stormwater modeling, urban hydrology research, batch analysis of calibration and climate scenarios, benchmark validation, and teaching demonstrations. The repository provides a browser replay demo, allowing an end-to-end session to be viewed without installation. Regarding limitations, the project has not yet reached 1.0; although model execution is deterministic, it depends on specific data and configuration; memory and skill evolution suggestions require human review; and some features such as specific platform coverage, Docker details, and API key configuration require consulting the corresponding documentation. Content not covered in this introduction is not yet provided.
