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

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.3 · pip install aiswmm==0.9.3 · Registro de cambios

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

Aspectos destacados

Agentic SWMM para modelado de aguas pluviales reproducible: el runtime aiswmm + Skills + MCP + SWMM, con un flujo de trabajo de verificación primero y un rastro de auditoría compatible con Obsidian.
Cinco minutos, un comando: un flujo de trabajo de Agentic SWMM que es auditable, informado por memoria y listo para agentes.
Demo en vivo (sin instalación, reproducción de casos sin conexión): pruébalo en el navegador en aiswmm.com.
Caso de estudio, un modelo que dijo que no confiáramos en él: la misma AOI de Victoria contra la red municipal real en una laptop Windows 11 ARM, donde la semana solicitada resultó seca: la ejecución reportó un error de continuidad de enrutamiento del 6.111% y un volumen de inundación contra cero precipitación, nombró ambos como descalificantes, y propuso la tormenta de diseño que lo resolvería, en cases/downtown-victoria-on-arm.md.
Caso de estudio, de un prompt a entregable para el cliente: una sola oración en inglés obtuvo la red municipal de tormentas real del centro de Victoria, BC (423 subcuencas), ejecutó SWMM, la auditó, la evaluó contra el libro de reglas de diseño, graficó el hidrograma y exportó un informe de Word con las figuras incrustadas; el prompt exacto, los números y cada artefacto están en cases/downtown-victoria.
SWMMCanada aguas arriba, listo para usar: dentro de Canadá, redes municipales de tormentas reales para 35 ciudades o síntesis en cualquier otro lugar del país, construidas a partir de datos abiertos canadienses y obtenidas directamente en aiswmm a través de la herramienta fetch_swmm_from_canada; fuera de Canadá, la síntesis basada en SWMManywhere cubre el resto del mundo. Dos fuentes aguas arriba complementarias, y un objetivo puede encadenar la obtención, simulación y auditoría en una sola carpeta de ejecución.
Trae el LLM que ya pagas: diez rutas de proveedores detrás de un asistente de detección primero aiswmm setup (OpenAI, Anthropic, OpenRouter, DeepSeek, Groq, Gemini, Ollama local y LM Studio, pasarelas compatibles con OpenAI, endpoints personalizados), con una cadena de respaldo local opcional que mantiene las sesiones activas durante interrupciones y ventanas de cuota.
Calibra, luego fuerza: aiswmm climate agrupa escenarios climáticos escalados por precipitación sobre un modelo calibrado y escribe una comparación por escenario de escorrentía, inundación, flujo de salida y flujo máximo.
Un runtime de agente específico de dominio, estilo agente gestionado: cada sesión es autodescriptiva (objetivo textual, instantánea de agente derivada automáticamente con hashes de herramienta/habilidad/prompt, huella del entorno, registro de eventos de solo añadir, ciclo de vida de estado), y la orquestación más las reglas de verificación son de código abierto y auditables.
Portátil en tiempo de ejecución: los servidores de Skills y MCP también funcionan con Codex, OpenClaw y Hermes Agent.
Investigación publicada: nuestro artículo está publicado en AI for Engineering (MDPI), 9 de junio de 2026: lee el artículo.

Resumen del proyecto

Agentic SWMM es un marco de código abierto, de 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 a SWMM ni al modelador, sino construir una capa de modelado agéntica 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 repetidos y proponer refinamientos de Skills, pero los cambios aceptados aún requieren revisión humana y verificación de referencia.

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 típico de SWMM puede implicar preprocesamiento GIS, formato de precipitación, 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 de 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 de Docker y Python documentadas por separado.
Guiado por agente, basado en SWMM: los agentes pueden coordinar tareas, mientras que la ejecución del modelo permanece determinista, inspeccionable y ejecutable por CLI.
Capa de habilidades modular: GIS, clima, construcción, ejecución, trazado, calibración, incertidumbre, auditoría y orquestación se separan en módulos reutilizables con interfaces MCP donde estén disponibles.
Procedencia de verificación primero: las etapas de construcción, ejecución, auditoría y comparación emiten artefactos trazables antes de que los resultados se traten como evidencia.
Evolución de habilidades supervisada: las ejecuciones auditadas pueden revelar patrones de flujo de trabajo recurrentes y proponer actualizaciones a habilidades existentes o nuevas habilidades, mientras permanecen acopladas al marco actual impulsado por habilidades.

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.3), sin instalación local:

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

Después de la instalación, lanza 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 lista cada ruta y detecta lo que ya está en ejecución; tres de ellas no necesitan ninguna clave API, incluida una pasarela local que se sitúa frente 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 entrar (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 controlada de habilidades. Las solicitudes en lenguaje natural pueden desencadenar acciones reproducibles de SWMM; los artefactos auditados actualizan la memoria legible por humanos y por máquinas; los patrones repetidos pueden producir propuestas de refinamiento de habilidades que aún requieren revisión humana y verificación de referencia.

Qué puede producir una ejecución

archivos de entrada SWMM generados o suministrados, como model.inp
informes SWMM y salidas binarias como .rpt y .out
manifiestos, trazas 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

_{▶ Prueba la demo en vivo: Greenwich Peninsula, SWMManywhere síntesis → ejecución de swmm5 → auditoría → renderizado, de principio a fin en el navegador.}

Instantánea de validación

El repositorio incluye benchmarks 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 utilizando conceptos de entropía y similitud difusa del artículo de Journal of Hydrology de Zhang y Valeo	Concepto de preprocesamiento GIS, no una afirmación de rendimiento calibrado de SWMM
Benchmark de GeoPackage sin procesar a INP	Capas públicas de TUFLOW GeoPackage convertidas en artefactos listos para SWMM, control de calidad y auditoría	Ruta GIS estructurada sin procesar, no reconocimiento arbitrario de CAD/GIS
Benchmark SWMM con entrada preparada	Ejecución del modelo externo Tecnopolo de 40 subcuencas, trazado 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 hidrogramas	Prueba de humo de incertidumbre previa, no calibración
Benchmark opcional de adaptador sin procesar derivado de INP	Entradas similares a las sin procesar extraídas de un fixture público de SWMM y reconstruidas a través de la ruta modular	Verificación de transferencia del adaptador, no generación de cuencas desde cero
Reproducibilidad byte-idéntica entre entornos	Un prompt en lenguaje natural (`Run the Tecnopolo (Rome 1994) demo`) impulsa la cadena aiswmm (agente LLM → MCP → habilidad swmm-runner) al mismo `model.out` byte-idéntico que el `swmm5` puro, en macOS y Docker. Re-verificación v0.7.1: la longitud mínima del prompt en lenguaje natural para esta cadena es ahora 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 de SWMM, no reproducibilidad del flujo de trabajo agéntico
Despacho impulsado por LLM + modelado urbano con datos escasos (SWMManywhere)	Una sola oración en lenguaje natural que se refiere solo a un cuadro delimitador WGS84 impulsa el flujo de trabajo integral SWMManywhere → SWMM → auditoría → mapa de red en dos regiones independientes (Península de Greenwich y Midtown de Nueva York, ~1 km² cada una), sin shapefile, sin archivo DEM y sin instrucciones paso a paso de herramientas. 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 alcance del próximo hito.
Activación autónoma de memoria entre sesiones	Un prompt 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 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 caudal máximo registrado que no coincide con el valor re-parseado de la sección de fuente del informe SWMM.

Experiment audit comparison showing a peak-flow provenance mismatch

La capa de memoria de modelado posterior puede resumir historiales de ejecuciones auditadas en patrones de fallo recurrentes, suposiciones, evidencia faltante, problemas de control de calidad, lecciones aprendidas y propuestas controladas para actualizar habilidades existentes o crear nuevas. Debido a que las habilidades impulsan el flujo de trabajo, estas propuestas permanecen acopladas al marco actual de Agentic SWMM y aún requieren revisión humana y verificación de benchmark antes de su aceptación.

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

Conozca más sobre el ecosistema

Agentic SWMM es el motor SWMM dentro de un esfuerzo más amplio hacia una plataforma de modelado hidrológico urbano confiable, auditable y totalmente automatizada: 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 gobierna datos, selección de modelos, ejecuciones y auditoría en todas las ramas de motores	Pipeline de modelado de cuencas LSTM activo; orquestación entre motores (SWMM / MIKE+) en progreso
SWMMCanada	Capa de datos y construcción de modelos: ingiere y limpia datos GIS / abiertos y sintetiza archivos de modelo confiables; el front-end compartido para los motores. Agentic SWMM lo consume como fuente INP ascendente vía `fetch_swmm_from_canada` (tuberías municipales reales para 8 ciudades canadienses)	SWMM hoy; extendiéndose a MIKE+ e InfoWorks ICM
Agentic SWMM (este repositorio)	Motor SWMM: automatización de EPA SWMM con verificación primero (Skills + MCP + ejecuciones deterministas + auditoría)	Estable v0.9.3
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 de agentes externos: Codex, Claude Code, OpenClaw o Hermes. Para una ejecución orquestada por agente, precargue el paquete agent/memory/ y apunte el runtime a la habilidad 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 pasar y cuándo detenerse en lugar de inventar entradas faltantes.

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

npx skills add Zhonghao1995/agentic-swmm-workflow

Las habilidades llevan los contratos de flujo de trabajo y evidencia; combínelas con la instalación del proyecto para el conjunto de herramientas ejecutables (CLI aiswmm, solucionador SWMM, servidores MCP).

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

Mapa de documentación

Evidencia de validación - alcance del benchmark, 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 solución de problemas - el comando de una línea por plataforma, qué sale mal 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, pasarelas, 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 de 03_climate/ por ejecución
Marco de auditoría de experimentos - procedencia, comparación y contratos de notas de Obsidian
Memoria de modelado y evolución de habilidades - bucle controlado de refinamiento de memoria a habilidad
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 - desarrollo local, auditoría, Obsidian y flujo de trabajo de revisión de evidencia
Ruta de ejecución OpenClaw - secuencia de llamadas a herramientas MCP para runtimes de agentes
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 de suelo / suelo / activos de drenaje, nuevas herramientas MCP, pruebas de control de calidad, 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