swmm-canada

Fetch a ready-to-run SWMM model for a Canadian area from the SWMMCanada upstream service, then run, audit, calibrate, and force it in one canonical run folder.

Use for any AOI inside Canada. The service auto-selects the build mode: real published municipal storm networks where a supported city covers the AOI (35 cities at the 2026-08 sync, e.g. Victoria, Ottawa, Toronto, Calgary, Vancouver, Regina), synthesized anywhere else in the country. Outside Canada, route to swmm-anywhere (global, synthesized).

This skill is a documentation contract: the implementation is the in-process typed tool fetch_swmm_from_canada (a pure-stdlib HTTP client, ADR-0001). There is no script directory and no MCP server here, and that is deliberate — the service boundary is HTTP, and the tool is already on the runtime's golden path.

What this skill does

Given an AOI (bbox [min_lon, min_lat, max_lon, max_lat] or a GeoJSON Polygon string) and a rainfall date window (start_date, end_date, ISO dates):

1. Announces a preview (best effort): which mode and city the service will use.
2. Submits the build to the SWMMCanada tasks API and polls with live progress (network fetch, subcatchments, DEM, landcover/soil, climate, build).
3. Downloads the model bundle and lands it in the canonical layout (ADR-0004): model.inp in 05_builder/ (with a [REPORT] section injected when the upstream INP omits one, so the binary output carries per-element series), the full swmm_model.zip in 10_upstream/swmmcanada/ as the pristine provenance artifact, and the bundle's returned DATA unpacked into 00_raw/swmmcanada/ (datastore, DEM, land cover, soil rasters, exports) so the run's raw material is browsable beside the other inputs. A study-area map is rendered best-effort to 00_raw/study_area.png (needs the gis extra; the fetch never fails over the map) and is picked up by swmm-report's figures section.
4. Returns the INP path, run directory, service URL, task id, build mode, and the upstream validation record.

Validated live end to end: a downtown Victoria AOI produced a real 423-subcatchment network in 173 s, ran under the local swmm5 unmodified, and audited cleanly; the whole fetch-run-audit chain took 178 s.

Required inputs

• aoi_geojson (GeoJSON Polygon string) or bbox (four WGS84 floats).
• start_date, end_date: the rainfall window (YYYY-MM-DD). This decides which observed rainfall the service attaches, so changing the window changes the storm.

Demo AOI (verified live)

When the user names a listed place without coordinates, use the verified demo AOI DIRECTLY (do not stop to ask first; asking is reserved for the safe profile):

Place phrase	bbox [min_lon, min_lat, max_lon, max_lat]	Verified
downtown Victoria, BC	[-123.370, 48.425, -123.360, 48.432]	2026-08-08, 423-subcatchment real-pipe network, fetch-run-audit in 178 s

State in the result card that the demo AOI was used and that a project-specific study boundary should replace it for real work. For any other place name, ask for the bbox (interactive) or say exactly what to rerun with (single-shot); never guess a study boundary.

Optional inputs

• run_dir: reuse an existing run directory (otherwise a timestamped runs/agent/swmm-canada-* is created).
• infiltration: CURVE_NUMBER (service default), HORTON, or GREEN_AMPT; passed through verbatim.
• base_url: override the service endpoint for one call.

Configuration

The service URL comes from the AISWMM_SWMMCANADA_URL environment variable (a local container at http://localhost:8000 or a hosted backend). aiswmm doctor probes GET /api/v1/healthz when the variable is set and reports reachability; unset is a quiet OK because the upstream is optional.

What to do next (the chain)

Pass the returned run_dir and inp_path forward so every stage lands in the same run folder:

1. run_swmm_inp (agent) or aiswmm run --inp <inp> --run-dir <run_dir> (CLI) — simulate.
2. audit_run / aiswmm audit --run-dir <run_dir> — provenance, QA verdict, diagnostics.
3. aiswmm calibrate with observed flow data — the fetched model is an uncalibrated first-pass estimate; expect the audit gate to flag routing continuity on raw builds, which is the gate doing its job.
4. review_run / aiswmm review --run-dir <run_dir> — reference-free design-review of the fetched network (soft rulebook verdicts).
5. plot_run — hydrograph figures into the run's canonical plot stage (08_plot/), which is where report generation looks.
6. generate_report / aiswmm report --run-dir <run_dir> — client Word deliverable; embeds the figures plotted in step 5.
7. run_climate_scenarios / aiswmm climate --params-json best_params.json --patch-map <map> — precipitation-scaled what-ifs on the calibrated model.

Boundaries

• Outside Canada: the tool fails soft with a hint before any HTTP round trip; use swmm-anywhere.
• Real network vs synthesized: decided server-side per AOI; the result reports which mode ran. Treat both like the synth path for QA purposes (reference-free checks until calibration).
• Provenance: aiswmm never re-derives what the service already recorded; the zip in 10_upstream/swmmcanada/ is the durable upstream artifact, with the service URL and task id as foreign keys.