swmm-report

SWMM Report Export Skill

Purpose

Assemble a reproducible, client-deliverable Word (.docx) report from the artifacts produced by swmm-experiment-audit and swmm-plot. The script reads only existing files; it never re-runs SWMM or modifies the run directory.

Prerequisite: the run directory must contain a 09_audit/ subdirectory with at least experiment_provenance.json. Run aiswmm audit --run-dir <path> first if that directory is absent.

---

CLI usage

# Standalone script
python3 skills/swmm-report/scripts/generate_report.py \
    --run-dir <path>         # required: audited run directory
    [--out <path.docx>]      # default: <run-dir>/report.docx
    [--template <path>]      # YAML or JSON template (default: built-in)

# CLI verb (registered in aiswmm CLI)
aiswmm report --run-dir <path> [--out <path.docx>] [--template <template.yaml>]

Exit codes: 0 = success; 1 = missing dependency, missing audit dir, or template error; 2 = argument error.

python-docx dependency: install with pip install 'aiswmm[report]'. The script exits immediately with a clear message if python-docx is absent.

---

Agent tool: generate_report

Registered in AgentToolRegistry. Direct handler (not MCP-routed) — shells out to generate_report.py, writes <run-dir>/report.docx (or the path supplied via out).

generate_report(run_dir="runs/my_run/")
generate_report(run_dir="runs/my_run/", out="deliverables/run_report.docx")
generate_report(run_dir="runs/my_run/", template="templates/client_a.yaml")

is_read_only=False — QUICK profile prompts the user (tool writes files).

If python-docx is not installed the tool returns a failure dict whose summary carries the install hint pip install 'aiswmm[report]'.

---

Executed example

# Create a minimal synthetic fixture
mkdir -p /tmp/swmm_report_fixture/09_audit
cat > /tmp/swmm_report_fixture/09_audit/experiment_provenance.json << 'EOF'
{
  "schema_version": "1.0",
  "run_id": "smoke-test-run",
  "generated_at_utc": "2025-01-01T00:00:00Z",
  "metrics": {"peak_flow": {"value": 1.23, "time_hhmm": "06:30"},
              "continuity_error": -0.5, "swmm_return_code": 0},
  "qa": {"checks": [{"id": "continuity", "ok": true, "detail": "within tolerance"}]},
  "repo": {"git_head": "abc1234", "git_branch": "main"},
  "tools": {"swmm5_version": "5.1.015", "python_version": "3.11"},
  "artifacts": {
    "model.inp": {"role": "input", "sha256": "4840dbe4abcdef", "exists": true,
                  "produced_by": "builder"}
  },
  "generated_by": "aiswmm"
}
EOF

python3 skills/swmm-report/scripts/generate_report.py \
    --run-dir /tmp/swmm_report_fixture \
    --out /tmp/swmm_report_smoke.docx
# Output: Report written to: /tmp/swmm_report_smoke.docx