swatplus-builder 0.5.0__tar.gz

swatplus_builder-0.5.0/.gitignore

@@ -0,0 +1,150 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.python-version
+.ipynb_checkpoints/
+.claude/
+demo_runs/
+docs/
+
+
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Docs build
+site/
+_site/
+
+# Data / caches (no large blobs in git)
+data/
+bin/
+*.sqlite
+*.sqlite-journal
+*.tif
+*.tiff
+*.gpkg
+*.shp
+*.shx
+*.dbf
+*.prj
+*.cpg
+*.qpj
+*.nc
+*.nc4
+*.zip
+reference_dbs/
+TxtInOut/
+watershed_data/
+/output/
+scratch/
+cache/
+marsh_creek_output/
+soil_benchmark/
+_e2e_runs/
+diagnostics.out
+simulation.out
+area_calc.out
+files_out.out
+erosion.txt
+docs/
+
+# Local working docs (authoritative docs live elsewhere)
+docs/DECISIONS.md
+docs/PROGRESS.md
+docs/TROUBLESHOOTING_AND_WORKFLOW.md
+
+# Planning / phase docs — local only, never commit
+PROGRESS.md
+DECISIONS.md
+ROADMAP.md
+!PROJECT.md
+!PROGRESS.md
+!DECISIONS.md
+!ROADMAP.md
+!SKILL.md
+BACKLOG.md
+PHASE_*.md
+*_PLAN.md
+*_CLOSEOUT.md
+*_READINESS.md
+CALIBRATION_PLAN*.md
+handover_docs.md
+
+# Local-only notes (never commit)
+local-docs/
+Research_article/
+
+# Allow small test fixtures explicitly
+!tests/fixtures/**/*.sqlite
+!tests/fixtures/**/*.tif
+!tests/fixtures/**/*.gpkg
+!tests/fixtures/**/*.shp
+!tests/fixtures/**/*.dbf
+!tests/fixtures/**/*.prj
+!tests/fixtures/**/*.shx
+!tests/fixtures/**/*.cpg
+
+# Vendored code is tracked (this IS the package), but caches inside are not
+src/swatplus_builder/editor/vendored/**/__pycache__/
+src/swatplus_builder/editor/vendored/**/*.pyc
+# Keep editor vendored runtime-output DB stubs ignored (not used by builder API)
+src/swatplus_builder/editor/vendored/database/output/
+
+# Local test artifacts
+tests/_artifacts/
+
+# Build artifacts and test data
+multibasin_test/
+demo_runs/
+docs/*
+!docs/
+!docs/AGENT_WORKFLOW.md
+!docs/CALIBRATION_PARAMETER_REGISTRY.md
+!docs/PIPELINE_LEARNING_LOG.md
+!docs/PIPELINE_RESEARCH_GRADE_AUDIT.md
+!docs/REPRODUCIBILITY.md
+Research_article/
+SWATplus_original_docs/
+.codebuddy/
+.claude/
+**/__pycache__/
+
+# SWAT+ temp files
+codes.bsn
+.commandcode/
+
+tests/_artifacts/
+
+
+
+
+# Build/test artifact directories
+basins/
+examples/build_real_basin.py
+examples/real_basin_marsh_creek.py
+PROGRESS.md
+PLAYBOOK.md
+
+# stray reproduction virtualenv (session artifact)
+.venv-repro/

swatplus_builder-0.5.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to swatplus-builder are documented here.
+
+## [0.5.0] — 2026-06-12
+
+### Added
+- **`run_workflow` + `workflow_status` MCP tools** (13-tool server): launch the
+  governed end-to-end pipeline as a detached background process — immune to MCP
+  client timeouts and conda/venv drift — and poll it for evidence-bundle
+  pointers. The `build_project` placeholder no longer fake-succeeds silently.
+- **Engine version provenance**: every run now reads the SWAT+ revision directly
+  from the engine — both the startup banner and the persisted output-file header
+  (`MODULAR Rev …`) — and records the verified value in the evidence bundle. If
+  an asserted version disagrees with the binary, the workflow records the
+  engine's value and flags the mismatch. Version is verified, never operator-asserted.
+- **A2 positive-control fixture test**: the claim-governance gate stack
+  (`_claim_lists` / `_effective_claim_tier`) is now tested in the *passing*
+  direction (synthetic research-grade single-channel basin), not only failing.
+- **Overclaiming pilot harness** (`scripts/overclaiming_pilot/`): runner, LLM
+  judge, and H1–H4 analysis scaffold for the pre-registered overclaiming experiment.
+- **`docs/REPRODUCIBILITY.md`**: documents the external reference-DB dependency
+  (esp. `swatplus_wgn.sqlite`) that is required but not bundled — a reproducibility
+  caveat for downstream results.
+
+### Fixed
+- **Daymet date-range defect**: pydaymet ≥ 0.19 could ignore `dates=()` and
+  return the full 1980-present archive. The adapter now clips every response to
+  the requested window and fills the Dec-31 rows Daymet omits in leap years;
+  validation reports "range ignored" vs "server clamped" as distinct failures.
+- **Reference-DB bootstrap honesty**: `scripts/bootstrap_reference_dbs.sh` no
+  longer claims to download from a non-existent mirror. It now checks which DBs
+  are present and exits non-zero with manual-install instructions if any are missing.
+- **MCP health check** improvements; added `mcp-check` command.
+
+### Changed
+- Engine version documentation corrected to the **validated range
+  60.5.7 – 61.0.2.61** (shipped builds use rev 61.0.2.61), replacing the
+  inaccurate single-version claim.
+
+## [0.4.0] — 2026-06-11
+
+### Added
+- **Locked calibration protocol**: `lock-benchmark` → `locked-calibrate` → independent verification chain. Reported metrics always come from a clean rerun, never from the optimizer loop.
+- **Claim governance**: runtime gates assign each result a tier (`exploratory → diagnostic → research_grade → publication_grade`). A strong metric never self-promotes past a failed gate.
+- **Machine-readable evidence bundle**: every run writes `evidence_summary.json`, `run_manifest.json`, `events.jsonl`, `calibration_provenance.json`, `physical_gates.json` — including typed, evidence-backed refusals.
+- **11-tool MCP server** (`swat mcp`): full agent interface for building, running, calibrating, and querying results via the Model Context Protocol.
+- **Full-mode engine compatibility** (Phase 3L): parameter bridge, routing fixes, topology converter, water-balance gate.
+- **New modules**: `nldi_fallback`, ET/mass/volume diagnostics, weather forcing, SoilGrids adapter, Daymet weather, full-build workflow, params governance.
+- **`swat workflow run`**: canonical one-command end-to-end path from USGS gauge ID to evidence bundle.
+- **Container baseline**: Dockerfile + docker-compose with MCP stdio service.
+- **Publication-ready figures**: 7+ figure types including hydro comparison, soil depth, gate matrix.
+- **`swat readiness-table`**: multi-basin calibration readiness summary.
+
+### Changed
+- `swat watershed`, `swat hrus`, `swat project`, `swat build`: now print a clear redirect to `swat workflow run` instead of crashing with an opaque error.
+- `pyproject.toml` description and keywords updated to reflect the package's actual identity.
+- Version aligned to `0.4.0` across `pyproject.toml` and `__init__.py`.
+
+### Infrastructure
+- MkDocs Material documentation site at <https://ai-hydro.github.io/swatplus-builder/>.
+- GitHub Actions: CI (lint + smoke + routing regression), docs deploy, and this publish workflow.
+
+## [0.3.x] — internal development
+
+Phase 3 calibration and engine compatibility work. Not released to PyPI.
+
+## [0.1.0 – 0.2.x] — internal development
+
+Initial pipeline scaffold. Not released to PyPI.

swatplus_builder-0.5.0/CITATION.cff

@@ -0,0 +1,59 @@
+cff-version: 1.2.0
+message: >-
+  If you use swatplus-builder in your research, please cite it using
+  the metadata below. When reporting a specific result, also include
+  the run's provenance hash from evidence_summary.json so the claim
+  is traceable to the exact run.
+title: "swatplus-builder: Claim-governed SWAT+ hydrologic modeling from a USGS gauge ID"
+version: 0.5.0
+date-released: "2026-06-12"
+doi: 10.5281/zenodo.20650908
+license: MIT
+repository-code: "https://github.com/AI-Hydro/swatplus-builder"
+url: "https://ai-hydro.github.io/swatplus-builder/"
+authors:
+  - family-names: Galib
+    given-names: Mohammad
+    affiliation: "Purdue University West Lafayette"
+  - family-names: Merwade
+    given-names: Venkatesh
+    affiliation: "Purdue University West Lafayette"
+    orcid: "https://orcid.org/0000-0002-4572-8531"
+abstract: >-
+  swatplus-builder builds and calibrates SWAT+ hydrologic models in Python,
+  starting from a single USGS streamgage ID. A locked benchmark calibration
+  protocol (lock → calibrate → independently verified rerun) ensures that
+  reported metrics come from a clean rerun, not the optimizer. Runtime gates
+  assign each result a claim tier and write a machine-readable evidence bundle
+  — including typed, evidence-backed refusals — so both successes and
+  limitations are fully inspectable. The pipeline runs with no desktop GIS and
+  exposes an 11-tool MCP surface for AI agent operation.
+keywords:
+  - SWAT+
+  - hydrology
+  - watershed modeling
+  - streamflow calibration
+  - claim governance
+  - scientific reproducibility
+  - GIS
+  - Python
+  - MCP
+  - AI agents
+  - USGS
+  - evidence bundle
+  - locked calibration
+preferred-citation:
+  type: software
+  title: "swatplus-builder: Claim-governed SWAT+ hydrologic modeling from a USGS gauge ID"
+  authors:
+    - family-names: Galib
+      given-names: Mohammad
+      affiliation: "Purdue University West Lafayette"
+    - family-names: Merwade
+      given-names: Venkatesh
+      affiliation: "Purdue University West Lafayette"
+      orcid: "https://orcid.org/0000-0002-4572-8531"
+  doi: 10.5281/zenodo.20650908
+  url: "https://github.com/AI-Hydro/swatplus-builder"
+  year: 2026
+  version: 0.5.0

swatplus_builder-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Galib
+
+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.