Skip to content

v0.6.4 — Byte-reproducibility hardening

Choose a tag to compare

View all tags
@github-actions github-actions released this 18 May 18:27
· 157 commits to main since this release
v0.6.4
a0650e9
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

v0.6.4 — Byte-reproducibility hardening (pinned dependencies + auto-built Docker images)

Released: 2026-05-18
Status: Stable. First non-pre-release on the 0.6.x line since v0.6.1, intended to support the byte-level reproducibility claims in the companion Agentic SWMM paper.
PyPI version string: 0.6.4

How to install

pip install aiswmm                 # default install now resolves to v0.6.4
pip install aiswmm==0.6.4          # pin explicitly
docker pull ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.6.4   # multi-arch image

One-sentence summary

v0.6.4 closes the three gaps that prevented the v0.6.x line from supporting end-to-end byte-level reproducibility: dependencies are now fully version-pinned via a committed requirements.lock, the Docker image is built reproducibly from that lockfile and from the USEPA SWMM 5.2.4 source, and Docker images are now built and pushed to GHCR automatically on every Git tag rather than on manual dispatch only.

What changed

1. Fully pinned dependency set (requirements.lock)

A new top-level requirements.lock file pins every transitive dependency (86 lines, 14 declared top-level packages) at the exact versions used to generate the figures and SHA-256 hashes reported in the companion paper. Re-installing those exact versions on Python 3.11 (the Docker base image) is now a one-line command:

pip install -r requirements.lock

The lockfile is generated by:

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r scripts/requirements.txt
pip freeze | grep -v "^-e git" | grep -v "^aiswmm==" > requirements.lock

Top-level declared packages remain in scripts/requirements.txt (unpinned, for human readability). The Dockerfile prefers requirements.lock, falling back to scripts/requirements.txt only if the lockfile is missing — so older tags continue to build, and new tags get byte-reproducible installs.

2. Reproducible Docker image, automatically built on tag push

.github/workflows/docker.yml now triggers on push for any tag matching v* (in addition to the previously-supported workflow_dispatch). Every Git tag v0.6.4, v0.6.5, v0.7.0, ... now automatically produces matching tagged images at ghcr.io/zhonghao1995/agentic-swmm-workflow:<tag>, plus a latest alias that follows the most recent tag. This guarantees that the Git tag and the published container image always exist as a pair.

The Dockerfile itself is unchanged in structure but now:

  • Pins AGENTIC_SWMM_REF default to v0.6.4.
  • Installs Python dependencies from requirements.lock (with a fallback path for older tags).
  • Continues to rebuild SWMM 5.2.4 from the USEPA Stormwater-Management-Model source at git tag v5.2.4, so the SWMM binary in the image is byte-reproducible from upstream rather than fetched as a pre-built artifact.

3. CI hygiene

  • The release commit and the release tag now both pass the existing tests/test_no_private_machine_paths_in_public_docs.py guard. v0.6.3a1 had a single offending file (the release-note draft) that has been redacted on main since #139; v0.6.4 re-runs the guard before tagging.
  • pyproject.toml, agentic_swmm/__init__.py, CITATION.cff, README.md, and docs/installation.md are all bumped consistently to 0.6.4. CITATION.cff had drifted to 0.5.0; that is also corrected.

Upgrade notes

  • pip install aiswmm now installs 0.6.4 (a stable release), not v0.6.1. Users who were intentionally pinning to v0.6.1 should add an explicit pin.
  • Users who depend on alpha behaviour from v0.6.2a1 / v0.6.3a1 should pin explicitly (those PyPI releases are unchanged).
  • The Docker image tag latest now points to v0.6.4. CI builds for older tags are unchanged.

What is NOT changed

  • No SWMM engine changes. SWMM 5.2.4 source is still pulled from USEPA upstream.
  • No public agent surface changes. All Skills, MCP servers, and CLI commands behave identically to v0.6.3-alpha.
  • No QA / audit-gate behaviour changes. The verification-first provenance contract is identical.

Companion paper alignment

This release matches the audit chain described in the companion Agentic SWMM paper Section 2.3.1: each run still emits a manifest.json and an experiment_provenance.json recording the INP/OUT/RPT SHA-256 hashes, the QA gate results (continuity errors, peak-metric integrity, SWMM return code, and the eight SWMM-specific screening rules), and the runtime context. With v0.6.4, any reader can reproduce those hashes bit-for-bit by pulling the matching Docker image:

docker pull ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.6.4
docker run --rm ghcr.io/zhonghao1995/agentic-swmm-workflow:v0.6.4 acceptance
Assets 4
Loading