Agentic SWMM

Once MCP servers para modelización reproducible de aguas pluviales con EPA SWMM: construcción, simulación, calibración, SIG, escenarios climáticos, incertidumbre, gráficos y memoria de modelización.

GitHub

Prueba este MCPPatrocinado

Documentación

Flujo de trabajo de Agentic SWMM

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

Pre-1.0 · estable v0.9.4 · pip install aiswmm==0.9.4 · CHANGELOG

[!TIP] ¿Dolores de cabeza por la configuración tediosa de modelos? Prueba nuestro otro proyecto SWMMCanada, nuestro proyecto de construcción automatizada de modelos: dibuja un área en cualquier lugar de Canadá y obtén un modelo SWMM listo para ejecutar. En funcionamiento ahora.

Aspectos destacados

Agentic SWMM para modelado de aguas pluviales reproducible: el runtime aiswmm + Skills + MCP + SWMM, con verificación primero y un registro de auditoría completo.
Demo de reproducción en vivo, sin instalación: una sesión de extremo a extremo grabada, reproducida en el navegador en aiswmm.com.
De una frase a un entregable para el cliente: una frase en inglés obtuvo la red de tormentas real del centro de Victoria, ejecutó SWMM, la auditó y exportó un informe de Word, y luego hizo lo mismo en una quinta ciudad, Kelowna, con el modelo confirmado para que la ejecución se reproduzca sin conexión: cases/downtown-victoria · cases/kelowna.
Un modelo que dijo que no se debía confiar en él: cuando la semana solicitada resultó seca, la ejecución nombró sus propios errores como descalificantes en lugar de entregar números incorrectos: cases/downtown-victoria-on-arm.md.
Método publicado: AI for Engineering (MDPI, 2026): lee el artículo.

Descripción general del proyecto

Agentic SWMM es un marco de código abierto, con verificación primero, para el modelado de aguas pluviales reproducible y extensible, comenzando con EPA SWMM. Conecta el preprocesamiento basado en QGIS, la generación de modelos aguas arriba desde SWMMCanada dentro de Canadá (redes de tormentas reales para 35 ciudades, síntesis en cualquier otro lugar del país) y la síntesis basada en SWMManywhere fuera de Canadá, la ejecución determinista de SWMM, controles de calidad, seguimiento de procedencia, soporte de calibración y escenarios climáticos, documentación y memoria de modelado, mientras mantiene a los modeladores humanos en control.

El objetivo no es reemplazar SWMM o al modelador, sino construir una capa de modelado agéntico que haga que los flujos de trabajo de modelado de aguas pluviales sean más fáciles de reproducir, auditar, extender, recordar y confiar. Agentic SWMM viene con aiswmm como su runtime integrado. Los usuarios pueden describir un objetivo de modelado en lenguaje natural, mientras que la ejecución del modelo permanece determinista, inspeccionable y basada en artefactos. Los servidores MCP y Skills del repositorio también se pueden usar con otros runtimes de agentes, incluidos Codex, Claude, OpenClaw y Hermes.

Esto no es un simple envoltorio de chat a SWMM. El runtime aiswmm puede ayudar a coordinar el flujo de trabajo, pero los archivos de modelo, las ejecuciones de SWMM, los controles de calidad, los gráficos, los registros de procedencia, las notas de auditoría y la memoria de modelado permanecen visibles como artefactos reutilizables. La memoria de modelado puede resumir problemas recurrentes y proponer refinamientos de Skills, pero los cambios aceptados aún requieren revisión humana y verificación comparativa.

Autores: Zhonghao Zhang y Caterina Valeo
Licencia: MIT

Por qué existe este proyecto

El modelado de aguas pluviales rara vez es un solo comando. Un proyecto SWMM típico puede implicar preprocesamiento GIS, formato de lluvia, asignación de parámetros, ensamblaje de red, construcción de INP, ejecución del modelo, controles de calidad, gráficos, calibración, análisis de incertidumbre y generación de informes.

Agentic SWMM proporciona un camino intermedio: orquestación en lenguaje natural con ejecución determinista de SWMM, procedencia explícita, memoria del proyecto y modelado con verificación primero.

Qué lo hace diferente

Incorporación rápida: comienza con instaladores de una línea para macOS/Linux o Windows, con rutas de paquetes Docker y Python documentadas por separado.
Trae el LLM que ya pagas: diez rutas de proveedores detrás de un asistente aiswmm setup, con una cadena de respaldo local.
Guiado por agente, fundamentado en SWMM: los agentes pueden coordinar tareas, mientras que la ejecución del modelo permanece determinista, inspeccionable y ejecutable por CLI.
Capa de skills modular: GIS, clima, construcción, ejecución, gráficos, calibración, incertidumbre, auditoría y orquestación están separados en módulos reutilizables con interfaces MCP donde estén disponibles.
Procedencia con verificación primero: las etapas de construcción, ejecución, auditoría y comparación emiten artefactos rastreables antes de que los resultados se traten como evidencia.
Evolución de skills supervisada: las ejecuciones auditadas pueden revelar patrones de flujo de trabajo recurrentes y proponer actualizaciones a skills existentes o nuevas skills, mientras permanecen acopladas al marco actual basado en skills.

Conoce a tu agente en unos cinco minutos

macOS y Linux:

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

Windows PowerShell:

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

Ejecución reproducible (imagen Docker fijada, v0.9.4), sin instalación local:

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

Después de la instalación, inicia el runtime con aiswmm.

Los instaladores de una línea ejecutan un script remoto; revísalo primero si quieres ver qué se ejecuta. Cuando termina, entrega el control a aiswmm setup, que enumera cada ruta y detecta lo que ya está en ejecución; tres de ellas no necesitan clave API en absoluto, incluida una puerta de enlace local que se enfrenta a un plan de ChatGPT. Para almacenar una clave directamente, consulta configuración de clave API. Nunca pegues claves API en la conversación de aiswmm.

Tres formas de entrada (instalador de una línea, Docker o pip), comparadas lado a lado (qué obtienes, requisitos previos, reproducibilidad, cuándo elegir cada una): elegir una ruta de instalación. Si algo sale mal, o quieres un proveedor que no necesite clave API: instalación y solución de problemas.

Flujo de trabajo

El flujo de trabajo tiene tres capas conectadas: ejecución, memoria de modelado y evolución de skills controlada. Las solicitudes en lenguaje natural pueden desencadenar acciones SWMM reproducibles; los artefactos auditados actualizan la memoria legible por humanos y por máquinas; los patrones recurrentes pueden producir propuestas de refinamiento de skills que aún requieren revisión humana y verificación comparativa.

Qué puede producir una ejecución

archivos de entrada SWMM generados o proporcionados, como model.inp
salidas binarias y de informe SWMM, como .rpt y .out
manifiestos, rastros de comandos, resúmenes de control de calidad y métricas de flujo máximo analizadas
figuras de lluvia-escorrentía, resúmenes de calibración y resúmenes de incertidumbre difusa
registros de auditoría: experiment_provenance.json, comparison.json y experiment_note.md
notas de modelado listas para Obsidian y resúmenes de memoria de modelado

_{▶ Ver la demo de reproducción: Greenwich Peninsula, SWMManywhere síntesis → ejecución swmm5 → auditoría → renderizado, de extremo a extremo en el navegador.}

Instantánea de validación

El repositorio incluye comparativas ejecutables y vistas previas de investigación con diferentes límites de evidencia. El README mantiene solo el índice; las figuras, los comandos y las notas de límites viven en Evidencia de validación.

Ruta	Qué muestra	Límite de evidencia
Partición de subcuencas guiada por pérdida de información	Preprocesamiento de QGIS a Agentic SWMM impulsado por la regla de pérdida de información de Zhang y Valeo artículo de Environmental Modelling & Software, con los conceptos de entropía y similitud difusa de su artículo de Journal of Hydrology	Concepto de preprocesamiento GIS, no una afirmación de rendimiento SWMM calibrado
Comparativa de GeoPackage sin procesar a INP	Capas GeoPackage públicas de TUFLOW convertidas en artefactos listos para SWMM, control de calidad y auditoría	Ruta GIS estructurada sin procesar, no reconocimiento arbitrario de CAD/GIS
Comparativa SWMM con entrada preparada	Ejecución del modelo externo Tecnopolo de 40 subcuencas, gráficos y comparación directa con `swmm5`	Ruta de validación de INP preparado
Prueba de humo de incertidumbre Monte Carlo previa	Perturbación del parámetro HORTON de Tecnopolo y vista previa del sobre de hidrograma	Prueba de humo de incertidumbre previa, no calibración
Comparativa opcional de adaptador sin procesar derivado de INP	Entradas similares a las sin procesar extraídas de un fixture SWMM público y reconstruidas a través de la ruta modular	Verificación de traspaso del adaptador, no generación de cuencas desde cero
Reproducibilidad byte-idéntica entre entornos	Un mensaje en lenguaje natural (`Run the Tecnopolo (Rome 1994) demo`) impulsa la cadena aiswmm (agente LLM → MCP → skill swmm-runner) al mismo `model.out` byte-idéntico que el `swmm5` simple, en macOS y Docker. Re-verificación v0.7.1: la longitud mínima del mensaje en lenguaje natural para esta cadena ahora es de 11 palabras, y el SHA256 de `model.out` permanece idéntico en la revisión menor v0.7.0 → v0.7.1.	Reproducibilidad de la capa de ejecución SWMM, no reproducibilidad del flujo de trabajo agéntico
Despacho impulsado por LLM + modelado urbano con datos escasos (SWMManywhere)	Una sola frase en lenguaje natural que se refiere solo a un cuadro delimitador WGS84 impulsa el flujo de trabajo de extremo a extremo SWMManywhere → SWMM → auditoría → mapa de red en dos regiones independientes (Greenwich Peninsula y NYC Midtown, ~1 km² cada una), sin shapefile, sin archivo DEM y sin instrucciones de herramientas paso a paso. La síntesis es obra de SWMManywhere (Imperial College London, BSD-3-Clause).	Plomería del lado del agente para modelado de referencia con datos escasos; no es una red calibrada o validada. La calibración es el alcance del próximo hito.
Activación autónoma de memoria entre sesiones	Un mensaje de usuario de 11 palabras impulsó una ejecución completa de Tecnopolo el 2026-05-28 durante la cual el LLM consultó autónomamente `recall_session_history` y recuperó dos sesiones previas de Tecnopolo de 12 días antes: la primera activación observable por el usuario de la capa de memoria en una ejecución de producción real.	La capa de memoria se activa correctamente y da forma a las decisiones del planificador; la ponderación de obsolescencia y el manejo de precedentes negativos son el alcance del próximo hito.

Ejemplos: TUFLOW y Tecnopolo.

Auditoría y memoria de investigación

La capa de auditoría consolida artefactos, controles de calidad y procedencia de métricas en una nota de experimento compatible con Obsidian. Este ejemplo detecta un valor de flujo máximo registrado que no coincide con el valor re-analizado de la sección de fuente del informe SWMM.

Experiment audit comparison showing a peak-flow provenance mismatch

La capa de memoria mantiene lo que las ejecuciones auditadas enseñaron al proyecto en un solo almacén: huellas de parámetros, resultados de calibración, regiones de parámetros conocidas como malas y cada falla de herramienta junto con la solución que funcionó, de lo que se informa al agente la próxima vez que ocurra la misma falla. Las propuestas para cambiar una skill o la memoria enviada están sujetas a evidencia y siempre requieren revisión humana antes de su aceptación.

Más detalles: Marco de auditoría de experimentos y Memoria de modelado y evolución de skills.

Aprende más sobre el ecosistema

Agentic SWMM es el motor SWMM dentro de un esfuerzo más amplio hacia una plataforma de modelado de hidrología urbana totalmente automatizada, confiable y auditable: un runtime agéntico de nivel superior que orquesta la automatización específica del motor sobre un front-end compartido de datos a modelo.

Proyecto	Rol en el ecosistema	Estado
agentic-hydrology-platform	Capa de orquestación: runtime agéntico de nivel superior que gestiona datos, selección de modelos, ejecuciones y auditoría en todas las ramas del motor	Pipeline de modelado de cuencas con LSTM en producción; orquestación entre motores (SWMM / MIKE+) en curso
SWMMCanada	Capa de datos y construcción de modelos: ingiere y limpia datos GIS / abiertos y sintetiza archivos de modelo fiables; el frontend compartido para los motores. Agentic SWMM lo consume como fuente INP ascendente vía `fetch_swmm_from_canada` (tuberías pluviales municipales reales para 35 ciudades, sanitarias donde la ciudad las publica)	Exporta paquetes SWMM, MIKE+, InfoWorks ICM y HEC-RAS 2D
Agentic SWMM (este repositorio)	Motor SWMM: automatización de EPA SWMM con verificación primero (Skills + MCP + ejecuciones deterministas + auditoría)	Estable v0.9.4
Agentic-MIKE-Plus	Motor MIKE+: automatización headless de DHI MIKE+ (Skills + MCP), construido sobre el diseño de Agentic SWMM y el mismo artículo metodológico	Desarrollo activo

Listo para Codex / Claude / OpenClaw / Hermes

Más allá de su propio runtime aiswmm, el flujo de trabajo de Agentic SWMM puede ser impulsado por runtimes agénticos externos: Codex, Claude Code, OpenClaw o Hermes. Para una ejecución orquestada por un agente, precargue el paquete agent/memory/ y apunte el runtime a la skill de entrada de nivel superior skills/swmm-end-to-end/SKILL.md, que decide qué ruta de flujo de trabajo tomar, qué puertas de control de calidad deben superarse y cuándo detenerse en lugar de inventar entradas faltantes.

Instale las skills en cualquier runtime compatible con skills (Claude Code, Codex, OpenCode, …) con un solo comando:

npx skills add Zhonghao1995/agentic-swmm-workflow

Las skills llevan los contratos de flujo de trabajo y evidencia; combínelas con la instalación del proyecto para la cadena de herramientas ejecutable (CLI aiswmm, solver SWMM, servidores MCP).

Más detalles: Ruta de runtime Codex · Ruta de ejecución OpenClaw · Instalación de skills · Integración de runtime MCP.

Mapa de documentación

Evidencia de validación - alcance de benchmarks, comandos, ejemplo de auditoría y límites de evidencia
Guía de instalación y CLI - Docker, instalación local, opciones de Windows y ejemplos de CLI
Instalación y resolución de problemas - el comando de una línea por plataforma, qué falla en una máquina real y por qué, y qué plataformas están cubiertas por un trabajo de instalación en CI
Dos interfaces, un motor - cómo los objetivos en lenguaje natural y los verbos CLI se asignan a las mismas herramientas y artefactos deterministas, y cuándo usar cada uno
Rutas de proveedor LLM - diez rutas listas para usar (OpenAI, Anthropic, OpenRouter, DeepSeek, Groq, Gemini, Ollama/LM Studio local, gateways, endpoints personalizados), el asistente aiswmm setup, autenticación por ruta y la cadena de respaldo local
Lotes de escenarios climáticos - aiswmm climate: calibrar primero, luego comparar la respuesta del modelo bajo escenarios climáticos con precipitación escalada, un resumen canónico 03_climate/ por ejecución
Marco de auditoría de experimentos - contratos de procedencia, comparación y notas de Obsidian
Memoria de modelado y evolución de skills - bucle controlado de refinamiento de memoria a skill
Runtime de memoria - sustrato en disco, cuatro cuadrantes de confianza y banderas de exclusión en runtime
Ejemplos de CLI del runtime de memoria - un ejemplo trabajado por verbo de memoria
Ruta de runtime Codex - flujo de trabajo de desarrollo local, auditoría, Obsidian y revisión de evidencia
Ruta de ejecución OpenClaw - secuencia de llamadas a herramientas MCP para runtimes agénticos
Mapa del repositorio - recorrido a nivel de carpetas
Ejemplo de calibración - ejemplo compacto de soporte de calibración

Dónde pueden ayudar los colaboradores

Se agradecen contribuciones en estudios de caso adicionales de SWMM, flujos de trabajo más sólidos de calibración y validación, flujos de trabajo de DEM / uso del suelo / suelo / activos de drenaje, nuevas herramientas MCP, pruebas de QA, tutoriales e interoperabilidad con cadenas de herramientas GIS, ML e hidrológicas.

Contacto:

Cita

Los metadatos de cita de GitHub se proporcionan en CITATION.cff. Por favor, cite el artículo publicado.

Artículo 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

Repositorio APA

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