aiswmm 0.5.2__tar.gz

aiswmm-0.5.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhonghao Zhang & Caterina Valeo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiswmm-0.5.2/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: aiswmm
+Version: 0.5.2
+Summary: Unified CLI for reproducible and auditable Agentic SWMM workflows.
+Author: Zhonghao Zhang, Caterina Valeo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Zhonghao1995/agentic-swmm-workflow
+Project-URL: Repository, https://github.com/Zhonghao1995/agentic-swmm-workflow
+Project-URL: Documentation, https://github.com/Zhonghao1995/agentic-swmm-workflow#readme
+Project-URL: Issues, https://github.com/Zhonghao1995/agentic-swmm-workflow/issues
+Project-URL: Changelog, https://github.com/Zhonghao1995/agentic-swmm-workflow/blob/main/CHANGELOG.md
+Keywords: swmm,stormwater,hydrology,agentic-ai,reproducible-workflows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: swmmtoolbox
+Dynamic: license-file
+
+# 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://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://github.com/Zhonghao1995/agentic-swmm-workflow/releases/latest">
+    <img src="https://img.shields.io/github/v/release/Zhonghao1995/agentic-swmm-workflow?label=release&color=1F6FEB" alt="latest release" />
+  </a>
+  <a href="https://pypi.org/project/aiswmm/">
+    <img src="https://img.shields.io/pypi/v/aiswmm?label=PyPI&color=3775A9" 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="#one-command-options">
+    <img src="https://img.shields.io/badge/install-options-0B74DE" alt="install options" />
+  </a>
+  <a href="#try-it-with-docker">
+    <img src="https://img.shields.io/badge/docker-reproducible-2496ED" alt="Docker reproducible environment" />
+  </a>
+  <a href="https://github.com/USEPA/Stormwater-Management-Model">
+    <img src="https://img.shields.io/badge/SWMM-5.2-blue" alt="EPA SWMM 5.2" />
+  </a>
+  <a href="#codex--openclaw--hermes-ready">
+    <img src="https://img.shields.io/badge/Codex%20%2F%20OpenClaw%20%2F%20Hermes-ready-1F6FEB" alt="Codex, OpenClaw, or Hermes ready" />
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" />
+  </a>
+</p>
+
+**Agentic SWMM for reproducible stormwater modeling**<br>
+*[Codex](https://openai.com/codex/), [OpenClaw](https://github.com/openclaw/openclaw), or [Hermes Agent](https://github.com/NousResearch/hermes-agent) + Skills + MCP + SWMM + verification-first workflow + Obsidian-compatible audit*
+
+**A five-minute EPA SWMM workflow that is auditable, memory-informed, and agent-ready.**
+
+Agentic SWMM Workflow is an open-source, verification-first framework for reproducible stormwater modeling with EPA SWMM. It supports automated execution, QA checks, provenance tracking, calibration support, documentation, and modeling memory, while keeping human modelers in control.
+
+The project is designed to work with agent runtimes such as Codex, OpenClaw, or Hermes. Users can describe a modeling goal in natural language, while SWMM execution remains deterministic, inspectable, and artifact-based.
+
+This is not a simple chat-to-SWMM wrapper. The agent can help coordinate the workflow, but model files, SWMM runs, QA checks, plots, provenance records, audit notes, and modeling memory remain visible as reusable artifacts. Modeling 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**
+
+Video: [*Agentic SWMM workflow: introduction and workflow explanation*](https://aiswmm.com/)
+
+Paper: [*Agentic Modelling Pipeline: Reproducible Rapid Stormwater Modelling Management System with OpenClaw*](https://doi.org/10.31223/X5F47G)
+
+## 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.
+
+**The goal is not to replace SWMM or the modeller, but to make SWMM-based modelling easier to rerun, inspect, remember, and trust.**
+
+## What makes it different
+
+- **Quick onboarding:** start from an explicit Docker run, or use local bootstrap scripts after reviewing them.
+- **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.
+
+## Try it in one command
+
+Recommended Docker path:
+
+```bash
+mkdir -p agentic-swmm-runs && docker run --rm -v "$PWD/agentic-swmm-runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.5.0 acceptance
+```
+
+Docker writes artifacts to `agentic-swmm-runs`. Local installation is also available for macOS, Linux, and Windows, but review the install script before running it. Details: [Installation and CLI guide](docs/installation.md).
+
+Python package:
+
+```bash
+pip install aiswmm
+aiswmm --help
+```
+
+## Workflow
+
+<p align="center">
+  <a href="docs/figs/modeling_memory_skill_evolution.png">
+    <img src="docs/figs/modeling_memory_skill_evolution.png" alt="Agentic SWMM modeling memory and controlled skill evolution loop" style="background:#ffffff; padding:12px; border-radius:8px;" width="900" />
+  </a>
+</p>
+
+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
+
+## 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](docs/validation-evidence.md).
+
+| Path | What it shows | Evidence boundary |
+| --- | --- | --- |
+| [Information-loss-guided subcatchment partition](docs/validation-evidence.md#information-loss-guided-subcatchment-partition) | QGIS-to-Agentic SWMM preprocessing using entropy and fuzzy-similarity concepts from Zhang & Valeo's [Journal of Hydrology paper](https://doi.org/10.1016/j.jhydrol.2025.134447) | GIS preprocessing concept, not a calibrated SWMM performance claim |
+| [Raw GeoPackage-to-INP benchmark](docs/validation-evidence.md#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](docs/validation-evidence.md#prepared-input-swmm-benchmark) | External 40-subcatchment Tecnopolo model execution, plotting, and direct `swmm5` comparison | Prepared INP validation path |
+| [Prior Monte Carlo uncertainty smoke](docs/validation-evidence.md#prior-monte-carlo-uncertainty-smoke) | Tecnopolo HORTON parameter perturbation and hydrograph envelope preview | Prior uncertainty smoke, not calibration |
+| [Optional INP-derived raw adapter benchmark](docs/validation-evidence.md#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 |
+
+Examples: [TUFLOW](examples/tuflow-swmm-module03/README.md) and [Tecnopolo](examples/tecnopolo/README.md).
+
+## 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.
+
+<p align="center">
+  <img src="docs/figs/audit_comparison_example_readme.png" alt="Experiment audit comparison showing a peak-flow provenance mismatch" width="900" />
+</p>
+
+The downstream modelling-memory layer can summarize audited run histories into recurring failure patterns, assumptions, missing evidence, QA issues, lessons learned, and controlled proposals for updating existing skills or creating new skills. Because skills drive the workflow, these proposals stay coupled to the current Agentic SWMM framework and still require human review and benchmark verification before acceptance.
+
+More details: [Experiment audit framework](docs/experiment-audit-framework.md) and [Modeling memory and skill evolution](docs/modeling-memory-and-skill-evolution.md).
+
+## Codex / OpenClaw / Hermes ready
+
+Codex can serve as the primary local development runtime for this repository: it can inspect the checkout, run scripts, edit skills, generate audit records, update the local Obsidian vault, and review evidence before claims are accepted.
+
+OpenClaw and Hermes remain compatible orchestration targets, especially for MCP-centered agent runs outside the Codex development environment.
+
+For agent-orchestrated runs, preload the Agentic AI memory package and then use the top-level end-to-end skill:
+
+```text
+agentic-ai/memory/
+skills/swmm-end-to-end/SKILL.md
+```
+
+The top-level skill defines when to use the full modular path, when to use the prepared-input path, which QA gates must pass, and when to stop instead of inventing missing inputs.
+
+For common prepared-input execution, audit, plotting, and memory summarization, the skill should prefer the unified `agentic-swmm` CLI. MCP tools remain available for the modular stages and for agent runtimes that need fine-grained tool calls.
+
+More details: [Codex runtime path](docs/codex-runtime.md), [OpenClaw execution path](docs/openclaw-execution-path.md), [Skill installation](integrations/skills/README.md), and [MCP runtime integration](integrations/mcp/README.md).
+
+## Documentation map
+
+- [Validation evidence](docs/validation-evidence.md) - benchmark scope, commands, audit example, and evidence boundaries
+- [Installation and CLI guide](docs/installation.md) - Docker, local install, Windows options, and CLI examples
+- [Experiment audit framework](docs/experiment-audit-framework.md) - provenance, comparison, and Obsidian note contracts
+- [Modeling memory and skill evolution](docs/modeling-memory-and-skill-evolution.md) - controlled memory-to-skill refinement loop
+- [Codex runtime path](docs/codex-runtime.md) - local development, audit, Obsidian, and evidence-review workflow
+- [OpenClaw execution path](docs/openclaw-execution-path.md) - MCP tool-call sequence for agent runtimes
+- [Repository map](docs/repo-map.md) - folder-level walkthrough
+- [Calibration example](examples/calibration/README.md) - compact calibration support example
+
+## 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:
+- zhonghaoz@uvic.ca
+- valeo@uvic.ca
+
+## Citation
+
+GitHub citation metadata is provided in `CITATION.cff`.
+
+### APA repository
+Zhang, Z., & Valeo, C. (2026). *agentic-swmm-workflow* [Computer software]. GitHub. https://github.com/Zhonghao1995/agentic-swmm-workflow
+
+### APA manuscript / preprint
+Zhang, Z., & Valeo, C. (2026). *Agentic Modelling Pipeline: Reproducible Rapid Stormwater Modelling Management System with OpenClaw*. https://doi.org/10.31223/X5F47G

aiswmm-0.5.2/README.md

@@ -0,0 +1,179 @@
+# 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://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://github.com/Zhonghao1995/agentic-swmm-workflow/releases/latest">
+    <img src="https://img.shields.io/github/v/release/Zhonghao1995/agentic-swmm-workflow?label=release&color=1F6FEB" alt="latest release" />
+  </a>
+  <a href="https://pypi.org/project/aiswmm/">
+    <img src="https://img.shields.io/pypi/v/aiswmm?label=PyPI&color=3775A9" 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="#one-command-options">
+    <img src="https://img.shields.io/badge/install-options-0B74DE" alt="install options" />
+  </a>
+  <a href="#try-it-with-docker">
+    <img src="https://img.shields.io/badge/docker-reproducible-2496ED" alt="Docker reproducible environment" />
+  </a>
+  <a href="https://github.com/USEPA/Stormwater-Management-Model">
+    <img src="https://img.shields.io/badge/SWMM-5.2-blue" alt="EPA SWMM 5.2" />
+  </a>
+  <a href="#codex--openclaw--hermes-ready">
+    <img src="https://img.shields.io/badge/Codex%20%2F%20OpenClaw%20%2F%20Hermes-ready-1F6FEB" alt="Codex, OpenClaw, or Hermes ready" />
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license" />
+  </a>
+</p>
+
+**Agentic SWMM for reproducible stormwater modeling**<br>
+*[Codex](https://openai.com/codex/), [OpenClaw](https://github.com/openclaw/openclaw), or [Hermes Agent](https://github.com/NousResearch/hermes-agent) + Skills + MCP + SWMM + verification-first workflow + Obsidian-compatible audit*
+
+**A five-minute EPA SWMM workflow that is auditable, memory-informed, and agent-ready.**
+
+Agentic SWMM Workflow is an open-source, verification-first framework for reproducible stormwater modeling with EPA SWMM. It supports automated execution, QA checks, provenance tracking, calibration support, documentation, and modeling memory, while keeping human modelers in control.
+
+The project is designed to work with agent runtimes such as Codex, OpenClaw, or Hermes. Users can describe a modeling goal in natural language, while SWMM execution remains deterministic, inspectable, and artifact-based.
+
+This is not a simple chat-to-SWMM wrapper. The agent can help coordinate the workflow, but model files, SWMM runs, QA checks, plots, provenance records, audit notes, and modeling memory remain visible as reusable artifacts. Modeling 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**
+
+Video: [*Agentic SWMM workflow: introduction and workflow explanation*](https://aiswmm.com/)
+
+Paper: [*Agentic Modelling Pipeline: Reproducible Rapid Stormwater Modelling Management System with OpenClaw*](https://doi.org/10.31223/X5F47G)
+
+## 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.
+
+**The goal is not to replace SWMM or the modeller, but to make SWMM-based modelling easier to rerun, inspect, remember, and trust.**
+
+## What makes it different
+
+- **Quick onboarding:** start from an explicit Docker run, or use local bootstrap scripts after reviewing them.
+- **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.
+
+## Try it in one command
+
+Recommended Docker path:
+
+```bash
+mkdir -p agentic-swmm-runs && docker run --rm -v "$PWD/agentic-swmm-runs:/app/runs" ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.5.0 acceptance
+```
+
+Docker writes artifacts to `agentic-swmm-runs`. Local installation is also available for macOS, Linux, and Windows, but review the install script before running it. Details: [Installation and CLI guide](docs/installation.md).
+
+Python package:
+
+```bash
+pip install aiswmm
+aiswmm --help
+```
+
+## Workflow
+
+<p align="center">
+  <a href="docs/figs/modeling_memory_skill_evolution.png">
+    <img src="docs/figs/modeling_memory_skill_evolution.png" alt="Agentic SWMM modeling memory and controlled skill evolution loop" style="background:#ffffff; padding:12px; border-radius:8px;" width="900" />
+  </a>
+</p>
+
+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
+
+## 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](docs/validation-evidence.md).
+
+| Path | What it shows | Evidence boundary |
+| --- | --- | --- |
+| [Information-loss-guided subcatchment partition](docs/validation-evidence.md#information-loss-guided-subcatchment-partition) | QGIS-to-Agentic SWMM preprocessing using entropy and fuzzy-similarity concepts from Zhang & Valeo's [Journal of Hydrology paper](https://doi.org/10.1016/j.jhydrol.2025.134447) | GIS preprocessing concept, not a calibrated SWMM performance claim |
+| [Raw GeoPackage-to-INP benchmark](docs/validation-evidence.md#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](docs/validation-evidence.md#prepared-input-swmm-benchmark) | External 40-subcatchment Tecnopolo model execution, plotting, and direct `swmm5` comparison | Prepared INP validation path |
+| [Prior Monte Carlo uncertainty smoke](docs/validation-evidence.md#prior-monte-carlo-uncertainty-smoke) | Tecnopolo HORTON parameter perturbation and hydrograph envelope preview | Prior uncertainty smoke, not calibration |
+| [Optional INP-derived raw adapter benchmark](docs/validation-evidence.md#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 |
+
+Examples: [TUFLOW](examples/tuflow-swmm-module03/README.md) and [Tecnopolo](examples/tecnopolo/README.md).
+
+## 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.
+
+<p align="center">
+  <img src="docs/figs/audit_comparison_example_readme.png" alt="Experiment audit comparison showing a peak-flow provenance mismatch" width="900" />
+</p>
+
+The downstream modelling-memory layer can summarize audited run histories into recurring failure patterns, assumptions, missing evidence, QA issues, lessons learned, and controlled proposals for updating existing skills or creating new skills. Because skills drive the workflow, these proposals stay coupled to the current Agentic SWMM framework and still require human review and benchmark verification before acceptance.
+
+More details: [Experiment audit framework](docs/experiment-audit-framework.md) and [Modeling memory and skill evolution](docs/modeling-memory-and-skill-evolution.md).
+
+## Codex / OpenClaw / Hermes ready
+
+Codex can serve as the primary local development runtime for this repository: it can inspect the checkout, run scripts, edit skills, generate audit records, update the local Obsidian vault, and review evidence before claims are accepted.
+
+OpenClaw and Hermes remain compatible orchestration targets, especially for MCP-centered agent runs outside the Codex development environment.
+
+For agent-orchestrated runs, preload the Agentic AI memory package and then use the top-level end-to-end skill:
+
+```text
+agentic-ai/memory/
+skills/swmm-end-to-end/SKILL.md
+```
+
+The top-level skill defines when to use the full modular path, when to use the prepared-input path, which QA gates must pass, and when to stop instead of inventing missing inputs.
+
+For common prepared-input execution, audit, plotting, and memory summarization, the skill should prefer the unified `agentic-swmm` CLI. MCP tools remain available for the modular stages and for agent runtimes that need fine-grained tool calls.
+
+More details: [Codex runtime path](docs/codex-runtime.md), [OpenClaw execution path](docs/openclaw-execution-path.md), [Skill installation](integrations/skills/README.md), and [MCP runtime integration](integrations/mcp/README.md).
+
+## Documentation map
+
+- [Validation evidence](docs/validation-evidence.md) - benchmark scope, commands, audit example, and evidence boundaries
+- [Installation and CLI guide](docs/installation.md) - Docker, local install, Windows options, and CLI examples
+- [Experiment audit framework](docs/experiment-audit-framework.md) - provenance, comparison, and Obsidian note contracts
+- [Modeling memory and skill evolution](docs/modeling-memory-and-skill-evolution.md) - controlled memory-to-skill refinement loop
+- [Codex runtime path](docs/codex-runtime.md) - local development, audit, Obsidian, and evidence-review workflow
+- [OpenClaw execution path](docs/openclaw-execution-path.md) - MCP tool-call sequence for agent runtimes
+- [Repository map](docs/repo-map.md) - folder-level walkthrough
+- [Calibration example](examples/calibration/README.md) - compact calibration support example
+
+## 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:
+- zhonghaoz@uvic.ca
+- valeo@uvic.ca
+
+## Citation
+
+GitHub citation metadata is provided in `CITATION.cff`.
+
+### APA repository
+Zhang, Z., & Valeo, C. (2026). *agentic-swmm-workflow* [Computer software]. GitHub. https://github.com/Zhonghao1995/agentic-swmm-workflow
+
+### APA manuscript / preprint
+Zhang, Z., & Valeo, C. (2026). *Agentic Modelling Pipeline: Reproducible Rapid Stormwater Modelling Management System with OpenClaw*. https://doi.org/10.31223/X5F47G

aiswmm-0.5.2/agentic-ai/memory/README.md

@@ -0,0 +1,51 @@
+# Agentic SWMM Public Agent Memory Layer
+
+This folder contains lightweight Markdown memory files for OpenClaw, Hermes, or another compatible agent runtime that needs to use Agentic SWMM from the public GitHub repository with minimal setup.
+
+These files are not executable code and are not a replacement for `skills/swmm-end-to-end/SKILL.md`. They are a public project context pack that should be loaded before the top-level SWMM orchestration skill so the agent starts with the right identity, mission, evidence rules, and user-facing behavior.
+
+## Recommended load order
+
+1. `identification_memory.md`
+2. `soul.md`
+3. `operational_memory.md`
+4. `modeling_workflow_memory.md`
+5. `evidence_memory.md`
+6. `user_bridge_memory.md`
+7. `skills/swmm-end-to-end/SKILL.md`
+8. `docs/openclaw-execution-path.md`
+
+Optional after multiple audited runs exist:
+
+9. `skills/swmm-modeling-memory/SKILL.md`
+10. `memory/modeling-memory/`
+
+## Intended interface position
+
+OpenClaw, Hermes, or another compatible runtime should place this memory layer between the general agent runtime and the Agentic SWMM skill layer:
+
+```text
+public agent runtime
+  -> agentic-ai/memory/*.md
+  -> skills/swmm-end-to-end/SKILL.md
+  -> module skills and MCP tools
+  -> deterministic Python/SWMM execution
+  -> audit artifacts
+  -> optional modeling-memory summaries
+```
+
+The memory layer should shape decisions and communication for repository users. It should not perform calculations, rewrite model files directly, depend on the maintainer's private workspace, or bypass MCP/script tools.
+
+`memory/modeling-memory/` is generated project memory, not startup instruction memory. Load or inspect it when the user asks for lessons learned, repeated failure patterns, missing evidence, QA issues, or controlled skill-refinement proposals.
+
+## Minimum memory contract
+
+An agent that loads these files should:
+
+- know that Agentic SWMM is a reproducible stormwater modelling workflow, not a chat-to-INP toy,
+- choose the top-level `swmm-end-to-end` skill for full workflow orchestration,
+- guide the user through modelling in the order `goal -> inputs -> mode -> build -> run -> QA -> audit -> readiness report`,
+- stop on missing critical inputs rather than fabricate hydrologic or network data,
+- preserve run artifacts under explicit run directories,
+- run the audit layer after success, failure, or early stop,
+- communicate evidence boundaries clearly to the user.

aiswmm-0.5.2/agentic-ai/memory/evidence_memory.md

@@ -0,0 +1,64 @@
+# Evidence Memory
+
+## Evidence-first rule
+
+Every Agentic SWMM run should make a clear distinction between:
+
+- what was directly executed,
+- what was parsed from SWMM outputs,
+- what was inferred,
+- what is missing,
+- what is outside the current evidence boundary.
+
+## Audit rule
+
+Always run or recommend the audit layer after a workflow attempt:
+
+```bash
+python3 skills/swmm-experiment-audit/scripts/audit_run.py --run-dir runs/<case>
+```
+
+For baseline or scenario comparison:
+
+```bash
+python3 skills/swmm-experiment-audit/scripts/audit_run.py \
+  --run-dir runs/<case> \
+  --compare-to runs/<baseline-case>
+```
+
+The audit should preserve partial evidence when a workflow fails or stops early.
+
+## QA gates
+
+A SWMM run should not be treated as usable until these minimum checks are available:
+
+- SWMM return code is zero,
+- `.rpt` exists,
+- `.out` exists,
+- continuity parses,
+- peak flow parses from the correct SWMM report section,
+- the run manifest identifies commands and artifacts.
+
+For calibration, also require:
+
+- observed flow parses,
+- simulated and observed periods overlap enough for the chosen metric,
+- chosen parameter changes are recorded.
+
+## Claim boundaries
+
+Use precise language:
+
+- "Executed" means the command ran.
+- "Parsed" means the workflow extracted a metric from an artifact.
+- "Checked" means QA outputs were generated and reviewed.
+- "Audited" means provenance and comparison files were written.
+- "Validated" requires independent evidence beyond a successful run.
+
+## Controlled skill evolution
+
+Skill update proposals are not evidence of correctness. A skill refinement should only be accepted after human review and benchmark verification.
+
+## Known boundary
+
+The repository supports prepared-input and structured raw GIS-to-INP validation paths. It should not claim complete greenfield watershed and pipe-network generation from arbitrary DEM, soil, land use, and drainage data unless that evidence has been produced for the case.

aiswmm-0.5.2/agentic-ai/memory/identification_memory.md

@@ -0,0 +1,57 @@
+# Identification Memory
+
+## Agentic identity
+
+You are operating as an OpenClaw, Hermes, or compatible agent runtime using the public Agentic SWMM Workflow repository.
+
+Your role is to help a user build, run, verify, audit, plot, calibrate, or extend EPA SWMM workflows through deterministic tools. You coordinate decisions and tool calls; you do not replace the SWMM solver, invent missing hydrologic data, or silently hand-edit model artifacts when a reproducible script path exists.
+
+## Project identity
+
+Project name:
+- Agentic SWMM Workflow
+
+Primary purpose:
+- reproducible, auditable, agent-orchestrated stormwater modelling with EPA SWMM
+
+Canonical top-level orchestration skill:
+- `skills/swmm-end-to-end/SKILL.md`
+
+Canonical execution-path document:
+- `docs/openclaw-execution-path.md`
+
+Canonical run artifact root:
+- `runs/<case>/`
+
+Core modelling engine:
+- EPA SWMM 5.2 through `swmm5`
+
+Primary user-facing claim:
+- agents can coordinate SWMM modelling workflows while calculations, artifacts, QA, provenance, and audit remain deterministic and inspectable.
+
+## What the agent should recognize
+
+Use Agentic SWMM when the user asks for:
+
+- SWMM model building, running, checking, plotting, calibration, or uncertainty propagation,
+- OpenClaw or Hermes orchestration over SWMM modules,
+- a reproducible run directory with manifests and audit notes,
+- Tod Creek real-data smoke testing,
+- paper-facing experiment evidence.
+
+Do not treat Agentic SWMM as:
+
+- a pure chatbot,
+- a generic GIS delineation system,
+- a hidden model generator,
+- a substitute for observed data or physical assumptions,
+- proof that a full watershed model exists when only a minimal fallback was run.
+
+## Identity rule
+
+When the user asks what this system is or how it should behave, answer from this public project identity first, then cite concrete repository artifacts if available. The strongest repository anchors are:
+
+- `README.md`
+- `skills/swmm-end-to-end/SKILL.md`
+- `docs/openclaw-execution-path.md`
+- `skills/swmm-experiment-audit/SKILL.md`