Agentic SWMM Workflow

# Agentic SWMM Workflow

<p align="center">
  <img src="docs/figs/agentic_swmm_logo.png" alt="Agentic SWMM logo with agentic robot, stormwater system, and SWMM wordmark" width="900" />
</p>

<p align="center">
  <a href="https://aiswmm.com/demo/">
    <img src="https://img.shields.io/badge/demo-live-1a7f37" alt="Demo Live: aiswmm.com/demo" />
  </a>
  <a href="https://github.com/Zhonghao1995/agentic-swmm-workflow/actions/workflows/ci.yml">
    <img src="https://github.com/Zhonghao1995/agentic-swmm-workflow/actions/workflows/ci.yml/badge.svg" alt="CI status" />
  </a>
  <a href="https://pypi.org/project/aiswmm/">
    <img src="https://img.shields.io/pypi/v/aiswmm?label=PyPI&color=3775A9&cacheSeconds=300" alt="PyPI version" />
  </a>
  <a href="https://codecov.io/gh/Zhonghao1995/agentic-swmm-workflow">
    <img src="https://codecov.io/gh/Zhonghao1995/agentic-swmm-workflow/graph/badge.svg" alt="Codecov coverage" />
  </a>
  <a href="https://github.com/Zhonghao1995/agentic-swmm-workflow/pkgs/container/agentic-swmm-workflow">
    <img src="https://img.shields.io/badge/docker-reproducible-2496ED" alt="Docker reproducible environment" />
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" />
  </a>
  <a href="https://zhonghaoz.ca">
    <img src="https://img.shields.io/badge/built%20by-Zhonghao-7C3AED" alt="Built by Zhonghao" />
  </a>
  <a href="https://pepy.tech/project/aiswmm">
    <img src="https://img.shields.io/pepy/dt/aiswmm?label=downloads&color=3775A9" alt="PyPI downloads (total)" />
  </a>
</p>

> **Pre-1.0** · stable **v0.8.0** · `pip install aiswmm==0.8.0` · [CHANGELOG](CHANGELOG.md)

> [!TIP]
> **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.

## Highlights

- **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.
- **Five minutes, one command:** an Agentic SWMM workflow that is auditable, memory-informed, and agent-ready.
- **Live demo (no install, offline case replay):** try it in the browser at [aiswmm.com](https://aiswmm.com/demo/).
- **[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.
- **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.
- **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.
- **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.
- **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).
- **Published research:** our paper is published in *AI for Engineering* (MDPI), June 9, 2026: [read the paper](https://doi.org/10.3390/aieng1010005).

## 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](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.

**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 runtim

... (truncated)