Agentic SWMM
Onze servidores MCP para modelagem reprodutível de águas pluviais com EPA SWMM — construção, simulação, calibração, GIS, cenários climáticos, incerteza, plotagem e memória de modelagem.
Documentação
Fluxo de Trabalho do Agentic SWMM
Pré-1.0 · estável v0.9.4 ·
pip install aiswmm==0.9.4· CHANGELOG
[!TIP] Dores de cabeça com configuração tediosa de modelos? Conheça nosso outro projeto SWMMCanada, nosso projeto de construção automatizada de modelos: desenhe uma área em qualquer lugar do Canadá e obtenha um modelo SWMM pronto para execução. Já está funcionando.
Destaques
- Agentic SWMM para modelagem de águas pluviais reproduzível: o runtime aiswmm + Skills + MCP + SWMM, com verificação em primeiro lugar e trilha de auditoria completa.
- Demonstração de replay ao vivo, sem instalação: uma sessão completa gravada, reproduzida no navegador em aiswmm.com.
- De uma frase a um entregável para o cliente: uma frase em inglês buscou a rede real de tempestades do centro de Victoria, executou o SWMM, auditou e exportou um relatório em Word, e depois fez o mesmo em uma quinta cidade, Kelowna, com o modelo commitado para que a execução seja reproduzível offline: cases/downtown-victoria · cases/kelowna.
- Um modelo que disse para não confiar nele: quando a semana solicitada acabou sendo seca, a execução nomeou seus próprios erros como desqualificadores em vez de entregar números ruins: cases/downtown-victoria-on-arm.md.
- Método publicado: AI for Engineering (MDPI, 2026): leia o artigo.
Visão Geral do Projeto
O Agentic SWMM é um framework de código aberto, com verificação em primeiro lugar, para modelagem de águas pluviais reproduzível e extensível, começando com o EPA SWMM. Ele conecta pré-processamento baseado em QGIS, geração de modelos a montante a partir do SWMMCanada dentro do Canadá (redes reais de tempestades para 35 cidades, síntese em qualquer outro lugar do país) e síntese baseada em SWMManywhere fora do Canadá, execução determinística do SWMM, verificações de QA, rastreamento de proveniência, suporte a calibração e cenários climáticos, documentação e memória de modelagem, mantendo os modeladores humanos no controle.
O objetivo não é substituir o SWMM ou o modelador, mas construir uma camada de modelagem agêntica que torne os fluxos de trabalho de modelagem de águas pluviais mais fáceis de reproduzir, auditar, estender, lembrar e confiar. O Agentic SWMM vem com o aiswmm como seu runtime integrado. Os usuários podem descrever um objetivo de modelagem em linguagem natural, enquanto a execução do modelo permanece determinística, inspecionável e baseada em artefatos. Os servidores MCP e Skills do repositório também podem ser usados com outros runtimes de agentes, incluindo Codex, Claude, OpenClaw e Hermes.
Isto não é um simples wrapper de chat-para-SWMM. O runtime aiswmm pode ajudar a coordenar o fluxo de trabalho, mas arquivos de modelo, execuções do SWMM, verificações de QA, gráficos, registros de proveniência, notas de auditoria e memória de modelagem permanecem visíveis como artefatos reutilizáveis. A memória de modelagem pode resumir problemas recorrentes e propor refinamentos de Skills, mas as mudanças aceitas ainda exigem revisão humana e verificação de benchmark.
Autores: Zhonghao Zhang & Caterina Valeo
Licença: MIT
Por que este projeto existe
A modelagem de águas pluviais raramente é um único comando. Um projeto típico de SWMM pode envolver pré-processamento GIS, formatação de chuva, atribuição de parâmetros, montagem de rede, construção de INP, execução do modelo, verificações de QA, gráficos, calibração, análise de incerteza e relatórios.
O Agentic SWMM fornece um caminho intermediário: orquestração em linguagem natural com execução determinística do SWMM, proveniência explícita, memória de projeto e modelagem com verificação em primeiro lugar.
O que o torna diferente
- Onboarding rápido: comece com instaladores de uma linha para macOS/Linux ou Windows, com caminhos para pacotes Docker e Python documentados separadamente.
- Traga o LLM que você já paga: dez rotas de provedores por trás de um assistente
aiswmm setup, com uma cadeia de fallback local. - Guiado por agente, fundamentado em SWMM: agentes podem coordenar tarefas, enquanto a execução do modelo permanece determinística, inspecionável e executável via CLI.
- Camada de skills modular: GIS, clima, construção, execução, gráficos, calibração, incerteza, auditoria e orquestração são separados em módulos reutilizáveis com interfaces MCP quando disponíveis.
- Proveniência com verificação em primeiro lugar: as etapas de construção, execução, auditoria e comparação emitem artefatos rastreáveis antes que as saídas sejam tratadas como evidência.
- Evolução supervisionada de skills: execuções auditadas podem revelar padrões recorrentes de fluxo de trabalho e propor atualizações para skills existentes ou novas skills, permanecendo acopladas ao framework atual orientado por skills.
Conheça seu agente em cerca de cinco minutos
macOS e Linux:
curl -fsSL https://aiswmm.com/install.sh | bash
Windows PowerShell:
irm https://aiswmm.com/install.ps1 | iex
Execução reproduzível (imagem Docker fixada, v0.9.4), sem instalação local:
docker run --rm -v "$PWD/runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.9.4 acceptance
Após a instalação, inicie o runtime com aiswmm.
Os instaladores de uma linha executam um script remoto; revise-o primeiro se quiser ver o que é executado. Quando terminar, ele entrega o controle para aiswmm setup, que lista todas as rotas e detecta o que já está em execução; três delas não precisam de chave de API, incluindo um gateway local que atende a um plano ChatGPT. Para armazenar uma chave diretamente, consulte configuração de chave de API. Nunca cole chaves de API na conversa do aiswmm.
Três formas de entrada (instalador de uma linha, Docker ou pip), comparadas lado a lado (o que você obtém, pré-requisitos, reprodutibilidade, quando escolher cada uma): escolhendo um caminho de instalação. Se algo der errado, ou se você quiser um provedor que não precise de chave de API: instalação e solução de problemas.
Fluxo de Trabalho
O fluxo de trabalho tem três camadas conectadas: execução, memória de modelagem e evolução controlada de skills. Solicitações em linguagem natural podem acionar ações reproduzíveis do SWMM; artefatos auditados atualizam a memória legível por humanos e por máquinas; padrões repetidos podem produzir propostas de refinamento de skills que ainda exigem revisão humana e verificação de benchmark.
O que uma execução pode produzir
- arquivos de entrada SWMM gerados ou fornecidos, como
model.inp - relatórios SWMM e saídas binárias, como
.rpte.out - manifestos, rastros de comandos, resumos de QA e métricas de pico de fluxo analisadas
- figuras de chuva-vazão, resumos de calibração e resumos de incerteza fuzzy
- registros de auditoria:
experiment_provenance.json,comparison.jsoneexperiment_note.md - notas de modelagem prontas para Obsidian e resumos de memória de modelagem
▶ Assista à demonstração de replay: Greenwich Peninsula, síntese SWMManywhere → execução swmm5 → auditoria → renderização, de ponta a ponta no navegador.
Instantâneo de Validação
O repositório inclui benchmarks executáveis e prévias de pesquisa com diferentes limites de evidência. O README mantém apenas o índice; figuras, comandos e notas de limite estão em Evidência de validação.
| Caminho | O que mostra | Limite de evidência |
|---|---|---|
| Particionamento de sub-bacias guiado por perda de informação | Pré-processamento QGIS-para-Agentic SWMM orientado pela regra de perda de informação de Zhang & Valeo do artigo da Environmental Modelling & Software, com os conceitos de entropia e similaridade fuzzy do artigo da Journal of Hydrology | Conceito de pré-processamento GIS, não uma alegação de desempenho calibrado do SWMM |
| Benchmark bruto de GeoPackage-para-INP | Camadas públicas de GeoPackage do TUFLOW convertidas em artefatos prontos para SWMM, QA e auditoria | Caminho GIS bruto estruturado, não reconhecimento arbitrário de CAD/GIS |
| Benchmark SWMM com entrada preparada | Execução do modelo externo Tecnopolo de 40 sub-bacias, gráficos e comparação direta com swmm5 | Caminho de validação de INP preparado |
| Teste de fumaça de incerteza Monte Carlo prévia | Perturbação do parâmetro HORTON do Tecnopolo e prévia do envelope de hidrograma | Fumaça de incerteza prévia, não calibração |
| Benchmark opcional de adaptador bruto derivado de INP | Entradas semelhantes a brutas extraídas de um fixture público de SWMM e reconstruídas pelo caminho modular | Verificação de handoff do adaptador, não geração de bacia hidrográfica greenfield |
| Reprodutibilidade byte-idêntica entre ambientes | Um prompt em linguagem natural (Run the Tecnopolo (Rome 1994) demo) aciona a cadeia aiswmm (agente LLM → MCP → skill swmm-runner) para o mesmo model.out byte-idêntico que o swmm5 puro, em macOS e Docker. Re-verificação v0.7.1: o comprimento mínimo do prompt em linguagem natural para esta cadeia agora é 11 palavras, e o SHA256 do model.out permanece idêntico na revisão menor v0.7.0 → v0.7.1. | Reprodutibilidade da camada de execução do SWMM, não reprodutibilidade do fluxo de trabalho agêntico |
| Dispatch orientado por LLM + modelagem urbana com dados escassos (SWMManywhere) | Uma única frase em linguagem natural referindo-se apenas a uma caixa delimitadora WGS84 aciona o fluxo de trabalho completo SWMManywhere → SWMM → auditoria → mapa de rede em duas regiões independentes (Greenwich Peninsula e NYC Midtown, ~1 km² cada), sem shapefile, sem arquivo DEM e sem instruções passo a passo de ferramentas. A síntese é trabalho do SWMManywhere (Imperial College London, BSD-3-Clause). | Encanação do lado do agente para modelagem de linha de base com dados escassos; não é uma rede calibrada ou validada. Calibração é escopo do próximo marco. |
| Ativação autônoma de memória entre sessões | Um prompt de usuário de 11 palavras acionou uma execução completa do Tecnopolo em 2026-05-28, durante a qual o LLM consultou autonomamente recall_session_history e recuperou duas sessões anteriores do Tecnopolo de 12 dias atrás: a primeira ativação observável pelo usuário da camada de memória em uma execução de produção real. | A camada de memória dispara corretamente e molda as decisões do planejador; ponderação de obsolescência e tratamento de precedentes negativos são escopo do próximo marco. |
Memória de auditoria e pesquisa
A camada de auditoria consolida artefatos, verificações de QA e proveniência de métricas em uma nota de experimento compatível com Obsidian. Este exemplo captura um valor de pico de fluxo registrado que não corresponde ao valor re-analisado da seção de fonte do relatório SWMM.
A camada downstream de memória de modelagem pode resumir históricos de execuções auditadas em padrões recorrentes de falha, suposições, evidências ausentes, problemas de QA, lições aprendidas e propostas controladas para atualizar skills existentes ou criar novas skills. Como as skills orientam o fluxo de trabalho, essas propostas permanecem acopladas ao framework atual do Agentic SWMM e ainda exigem revisão humana e verificação de benchmark antes da aceitação.
Mais detalhes: Estrutura de auditoria de experimentos e Memória de modelagem e evolução de skills.
Saiba mais sobre o ecossistema
O Agentic SWMM é o motor SWMM dentro de um esforço maior em direção a uma plataforma de modelagem de hidrologia urbana totalmente automatizada, auditável e confiável: um runtime agêntico de nível superior orquestrando automação específica do motor sobre um front-end compartilhado de dados-para-modelo.
| Projeto | Papel no ecossistema | Status |
|---|---|---|
| agentic-hydrology-platform | Camada de orquestração: runtime agêntico de nível superior que governa dados, seleção de modelos, execuções e auditoria entre os ramos do motor | Pipeline de modelagem de captação LSTM ativo; orquestração entre motores (SWMM / MIKE+) em andamento |
| SWMMCanada | Camada de dados e construção de modelos: ingere e limpa dados GIS / abertos e sintetiza arquivos de modelo confiáveis; o front-end compartilhado para os motores. O Agentic SWMM o consome como fonte upstream de INP via fetch_swmm_from_canada (tubulações pluviais municipais reais para 35 cidades, sanitárias onde a cidade as publica) | Exporta pacotes SWMM, MIKE+, InfoWorks ICM e HEC-RAS 2D |
| Agentic SWMM (este repositório) | Motor SWMM: automação EPA SWMM com verificação em primeiro lugar (Skills + MCP + execuções determinísticas + auditoria) | Estável v0.9.4 |
| Agentic-MIKE-Plus | Motor MIKE+: automação headless DHI MIKE+ (Skills + MCP), construída sobre o design do Agentic SWMM e o mesmo artigo de método | Desenvolvimento ativo |
Pronto para Codex / Claude / OpenClaw / Hermes
Além do próprio runtime aiswmm, o fluxo de trabalho do Agentic SWMM pode ser conduzido por runtimes agênticos externos: Codex, Claude Code, OpenClaw ou Hermes. Para uma execução orquestrada por agente, pré-carregue o pacote agent/memory/ e aponte o runtime para a skill de entrada de nível superior skills/swmm-end-to-end/SKILL.md, que decide qual caminho de fluxo de trabalho seguir, quais portões de QA devem ser aprovados e quando parar em vez de inventar entradas ausentes.
Instale as skills em qualquer runtime compatível com skills (Claude Code, Codex, OpenCode, …) com um único comando:
npx skills add Zhonghao1995/agentic-swmm-workflow
As skills carregam os contratos de fluxo de trabalho e evidências; combine-as com a instalação do projeto para a cadeia de ferramentas executável (CLI aiswmm, solver SWMM, servidores MCP).
Mais detalhes: Caminho de runtime Codex · Caminho de execução OpenClaw · Instalação de skills · Integração de runtime MCP.
Mapa de documentação
- Evidências de validação - escopo de benchmark, comandos, exemplo de auditoria e limites de evidências
- Guia de instalação e CLI - Docker, instalação local, opções para Windows e exemplos de CLI
- Instalação e solução de problemas - o comando de uma linha por plataforma, o que dá errado em uma máquina real e por quê, e quais plataformas são cobertas por um job de instalação no CI
- Duas interfaces, um motor - como objetivos em linguagem natural e verbos de CLI mapeiam para as mesmas ferramentas e artefatos determinísticos, e quando usar cada um
- Rotas de provedores de LLM - dez rotas prontas para uso (OpenAI, Anthropic, OpenRouter, DeepSeek, Groq, Gemini, Ollama/LM Studio locais, gateways, endpoints personalizados), o assistente
aiswmm setup, autenticação por rota e a cadeia de fallback local - Lotes de cenários climáticos -
aiswmm climate: calibre primeiro, depois compare a resposta do modelo sob cenários climáticos com precipitação escalada, um resumo canônico03_climate/por execução - Estrutura de auditoria de experimentos - proveniência, comparação e contratos de notas no Obsidian
- Memória de modelagem e evolução de skills - loop controlado de refinamento de memória para skill
- Runtime de memória - substrato em disco, quatro quadrantes de confiança e flags de exclusão em runtime
- Exemplos de CLI do runtime de memória - um exemplo trabalhado por verbo de memória
- Caminho de runtime Codex - fluxo de trabalho de desenvolvimento local, auditoria, Obsidian e revisão de evidências
- Caminho de execução OpenClaw - sequência de chamadas de ferramentas MCP para runtimes agênticos
- Mapa do repositório - visita guiada por pasta
- Exemplo de calibração - exemplo compacto de suporte à calibração
Onde colaboradores podem ajudar
Contribuições são bem-vindas em estudos de caso adicionais de SWMM, fluxos de trabalho mais robustos de calibração e validação, fluxos de trabalho de DEM / uso do solo / solo / ativos de drenagem, novas ferramentas MCP, testes de QA, tutoriais e interoperabilidade com cadeias de ferramentas GIS, ML e hidrológicas.
Contato:
Citação
Os metadados de citação do GitHub estão fornecidos em CITATION.cff. Por favor, cite o artigo publicado.
Artigo APA (preferido)
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
Repositório APA
Zhang, Z., & Valeo, C. (2026). agentic-swmm-workflow [Software de computador]. GitHub. https://github.com/Zhonghao1995/agentic-swmm-workflow