Skip to content

swatplus-builder

PyPI Python License: MIT

swatplus-builder: Claim-governed SWAT+ workflows with auditable evidence

Calibrated SWAT+ models from a single gauge ID — with evidence you can audit.

swatplus-builder builds and calibrates SWAT+ hydrologic models in Python, starting from one USGS streamgage ID. It can be driven by a person or by an AI agent — and either way, the software, not the operator, decides what each result is allowed to claim.

The idea in one sentence

A capable modeler — human or AI — already knows hydrology. What they lack is an environment that will not let them claim more than the evidence supports. swatplus-builder is that environment: it builds, evaluates, verifies, blocks, and downgrades, and records every decision as machine-readable evidence.

What you can do with it

  • Gauge → calibrated model

    One USGS ID drives delineation, HRUs, gNATSGO soils, weather, and a valid SWAT+ model — start to finish in Python, with no desktop GIS (no QGIS).

  • Calibration you can trust

    A lock → calibrate → verify protocol where the reported numbers come from an independent rerun of the calibrated model, never from the optimizer.

  • Claims you can audit

    Runtime gates decide a result's tier — Exploratory → Diagnostic → Calibration verified → Gate-verified (stored as exploratory → diagnostic → publication_grade → research_grade). A strong metric never promotes itself past a failed gate.

  • A complete evidence bundle

    Every run writes its results and its refusals — each allowed or blocked claim carries a plain reason and a pointer to the evidence behind it.

One command, end to end

swat workflow run --usgs-id 02177000 --model-family full \
  --start 2000-01-01 --end 2019-12-31 --warmup-years 3 \
  --calibrate --claim-tier research_grade --json

This builds the model, runs the engine, locks a baseline, calibrates, verifies a clean rerun, and writes the evidence bundle. Start with the Quickstart.

Find your way

If you want to… Go to
Install and run your first basin Getting Started
Understand why results are governed How claims are governed
Understand the calibration protocol Locked calibration
Drive the pipeline with an AI agent Working with agents
Look up a command, function, or field Reference
Know what the system claims today Project status

This is research software — read the status page

The dated 2026-07-02 objective-suite snapshot promoted 0 of 11 complete workflows to the Gate-verified tier (stored as research_grade); a later focused positive case is reported separately and does not revise that snapshot. The value is an auditable workflow that makes both successes and limitations inspectable — not a claim that automated SWAT+ calibration is a solved problem. See Project status.