Skip to main content

Agentic SWMM Workflow

Agentic SWMM logo with agentic robot, stormwater system, and SWMM wordmark

Demo Live: aiswmm.com/demo CI status PyPI version Codecov coverage Docker reproducible environment MIT license Built by Zhonghao PyPI downloads (total)

Pre-1.0 · stable v0.9.5 · pip install aiswmm==0.9.5 · CHANGELOG

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

Introduction video Published in AI for Engineering Preprint on EarthArXiv Zenodo DOI latest release v0.9.5

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.

Meet your agent in about five minutes

macOS and Linux:

curl -fsSL https://aiswmm.com/install.sh | bash

Windows PowerShell:

irm https://aiswmm.com/install.ps1 | iex

Reproducible run (pinned Docker image, v0.9.5), no local install:

docker run --rm -v "$PWD/runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.9.5 acceptance

After installation, launch the runtime with aiswmm.

One-line installers run a remote script; review it first if you want to see what executes. When it finishes it hands over to aiswmm setup, which lists every route and detects what is already running; three of them need no API key at all, including a local gateway that fronts a ChatGPT plan. For storing a key directly, see API key configuration. Never paste API keys into the aiswmm conversation.

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. If something goes wrong, or you want a provider that needs no API key: install and troubleshooting.

Workflow

Agentic SWMM modeling memory and controlled skill evolution loop

The 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.

What a run can produce

  • generated or supplied SWMM input files such as model.inp
  • SWMM report and binary outputs such as .rpt and .out
  • manifests, command traces, QA summaries, and parsed peak-flow metrics
  • rainfall-runoff figures, calibration summaries, and fuzzy uncertainty summaries
  • audit records: experiment_provenance.json, comparison.json, and experiment_note.md
  • Obsidian-ready modelling notes and modelling-memory summaries

Agentic SWMM replay 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

▶ Watch the replay demo: Greenwich Peninsula, SWMManywhere synthesis → swmm5 run → audit → render, end to end in the browser.

Validation snapshot

The 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.

Path What it shows Evidence boundary
Information-loss-guided subcatchment partition QGIS-to-Agentic SWMM preprocessing driven by the information-loss rule from Zhang & Valeo's Environmental Modelling & Software paper, with the entropy and fuzzy-similarity concepts from their Journal of Hydrology paper GIS preprocessing concept, not a calibrated SWMM performance claim
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
Prepared-input SWMM benchmark External 40-subcatchment Tecnopolo model execution, plotting, and direct swmm5 comparison Prepared INP validation path
Prior Monte Carlo uncertainty smoke Tecnopolo HORTON parameter perturbation and hydrograph envelope preview Prior uncertainty smoke, not calibration
Optional 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
Cross-environment byte-identical reproducibility 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
LLM-driven dispatch + data-scarce urban modeling (SWMManywhere) 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 (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.
Cross-session memory autonomous activation 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.

Examples: TUFLOW and Tecnopolo.

Audit and research memory

The 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.

Experiment audit comparison showing a peak-flow provenance mismatch

The memory layer keeps what audited runs taught the project in one store: parameter fingerprints, calibration results, parameter regions known to be bad, and every tool failure together with the fix that worked, which the agent is told about the next time the same failure happens. Proposals to change a skill or the shipped memory are evidence-gated and always require human review before acceptance.

More details: Experiment audit framework and Modeling memory and skill evolution.

Learn more about the ecosystem

Agentic 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.

Project Role in the ecosystem Status
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
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 storm pipes for 35 cities, sanitary where the city publishes it) Exports SWMM, MIKE+, InfoWorks ICM and HEC-RAS 2D packages
Agentic SWMM (this repository) SWMM engine: verification-first EPA SWMM automation (Skills + MCP + deterministic runs + audit) Stable v0.9.5
Agentic-MIKE-Plus MIKE+ engine: headless DHI MIKE+ automation (Skills + MCP), built on the Agentic SWMM design and the same method paper Active development

Codex / Claude / OpenClaw / Hermes ready

Beyond 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 memory/initial/ 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.

Install the skills into any skills-aware runtime (Claude Code, Codex, OpenCode, …) with one command:

npx skills add Zhonghao1995/agentic-swmm-workflow

The skills carry the workflow and evidence contracts; pair them with the project install for the executable toolchain (aiswmm CLI, SWMM solver, MCP servers).

More details: Codex runtime path · OpenClaw execution path · Skill installation · MCP runtime integration.

Documentation map

Where collaborators can help

Contributions 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.

Contact:

Citation

GitHub citation metadata is provided in CITATION.cff. Please cite the published article.

APA article (preferred)

Zhang, 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

APA repository

Zhang, Z., & Valeo, C. (2026). agentic-swmm-workflow [Computer software]. GitHub. https://github.com/Zhonghao1995/agentic-swmm-workflow

Metadata

Release files for aiswmm 0.9.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiswmm 0.9.5
File Size Uploaded Provenance Actions
aiswmm-0.9.5.tar.gz 2.1 MB With provenance Details for aiswmm-0.9.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiswmm 0.9.5
File Interpreter ABI Platform Actions
aiswmm-0.9.5-py3-none-any.whl Python 3 none any Details for aiswmm-0.9.5-py3-none-any.whl

Total release size: 3.6 MB

Release files / aiswmm-0.9.5.tar.gz

Download URL aiswmm-0.9.5.tar.gz
Size 2.1 MB
Tags Source
SHA-256 checksum
How to use checksums
45ef551f06e5159d22ce6b11917c11aac5f386bb8fca4d1f31053f9c10e1ac92
BLAKE2b-256 checksum
How to use checksums
32d2b024e8e8bea79192a964a982c752e9c3b8d1cbf1378a04e00b4bcb711c22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / aiswmm-0.9.5-py3-none-any.whl

Download URL aiswmm-0.9.5-py3-none-any.whl
Size 1.5 MB
Tags Python 3
SHA-256 checksum
How to use checksums
3233c5efb4cb516f431162835af52de211ada1edf48f98c6dc0955d1cada5bf7
BLAKE2b-256 checksum
How to use checksums
3522f085172473f94378787b1a4a96f5cdb55b743cbbf467b1bce120f65ab8e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for aiswmm 0.9.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiswmm-0.9.5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page