PUMA v4.0.1 — Post-v4.0.0 Maintenance Release¶
- Release date: 2026-11-14
- Previous release: v4.0.0 (tagged 2026-06-02)
- Tag: v4.0.1
Overview¶
v4.0.1 is a patch release. It fixes the puma share-results stall (D40),
the Trivy gate that blocked the container image (D41), the runtime data
missing from the wheel (D42), the missing --version flag (D43), the
undeclared dashboard dependency (D48), the CI suites and dependency ranges
that were never tested (D49), the version lookups that fell back to
0.0.0-unknown (D50) and three hygiene findings (D51), and it makes
check_rate_limit() compatible with PyGithub >= 2.7.
The private verifier now computes the same 4-field canonical hash as the client (D23), the community validation and verification workflows were fixed (D38, D39), and the leaderboard loads submissions and shows each one's declared verification status (D46). The verifier can only check a submission that publishes raw_predictions_url; the CLI does not set that field yet, so new submissions remain self-attested until that follow-up lands. The fixed workflows have not yet been exercised by a new submission.
Highlights¶
- Runtime data in the wheel — the wheel carries
config/profiles.yaml,config/models_catalog.yaml, the prompt templates, the run-specs, the Alembic configuration and migrations,assets/img/PUMA.pnganddata/jira_balanced_200.csvunderpuma/_bundled/, used when no source tree is present (D42). PUMA_DATA_DIRandPUMA_SPECS_DIR—data/files andspecs/run-specs are looked up in the named directory first, then the working directory, the source tree and the bundled copy.puma share-results— the upstream owner publishes directly topumacp/puma-community, GitHub retries are bounded with an explicit timeout and a rate-limit pre-check, and transport errors surface as themed CLI errors (D40).puma --versionprintspuma-cp <version>(D43); the banner,puma env,ProfileSnapshot.puma_versionandpuma.__version__read the installedpuma-cpversion (D50).- CI —
lint-and-testrunstests/community/andtests/cli/, anunpinned-depsjob tests the pyproject dependency ranges (D49), bandit reports MEDIUM and higher and fails on HIGH, and the docs build runs on every pull request. - Container image — the published image pins a newer python:3.11-slim digest, applies Debian security updates at build time and pins pip 26.1.2, so the Trivy gate passes (D41 follow-up; D69 records the remaining pip finding).
Resolved debt¶
PR numbers refer to pumacp/puma; every commit below is an ancestor of
origin/develop.
| ID | Summary | PR | develop commit |
|---|---|---|---|
| D40 | share-results owner path and bounded GitHub retries |
#64 | 88d843a |
| D41 | Dockerfile.publish digest pin and setuptools upgrade for the Trivy gate |
#67 | 7d9496c |
| D42 | runtime data bundled into the wheel | #79 | be68d4b |
| D42 | working-directory lookups kept; PUMA_DATA_DIR and PUMA_SPECS_DIR |
#81 | 58d9b56 |
| D43 | top-level --version flag; colour-independent help test |
#63 | 5fdf755, 8bd598d |
| D48 | matplotlib declared; module-level import check |
#71 | 4335e61 |
| D49 | community and CLI suites in CI; unpinned-deps job |
#77 | 8e9d4f4 |
| D50 | version lookups query the puma-cp distribution |
#74 | 9cfd441 |
| D51 | ECE accumulator typed as float on Python 3.12 | #69 | d24aeaa |
| D51 | run artefacts kept out of the checkout | #70 | e98db3a |
| D51 | SPDX license expression and license-files |
#75 | 8476e1c |
| — | check_rate_limit() compatible with PyGithub >= 2.7 |
#66 | 5ad5aaf |
| — | bandit thresholds; docs build on every pull request | #80 | cab0729 |
| — | errata and backlog D58–D68 registered | #82 | d9456d6 |
Companion repositories¶
Changes outside this repository's git log; each commit is on the main
branch of its repository.
pumacp/puma-communityPR #3 (1ee1376):wiki-sync.ymlgrantedcontents: write.pumacp/puma-communityPR #10 (a0da178): badge generation skips verification sidecars when counting submissions.pumacp/puma-communityPR #11 (e9dc524): verification covers only added submissions and writes a sidecar only when verified.pumacp/puma-communityPR #12 (fba79b9):validate-submission.ymlpins the add-labels action, guards existing submissions and resets thevalidlabel.pumacp/puma-communityPR #13 (653a9b3): auto-merge is refused unless every changed file is added.pumacp/puma-communityPR #14 (224c4a8): Hugging Face dataset references point at thepumaprojectnamespace.- Leaderboard Space at commit
7de208b: loads only submission records and readsintegrity.verification_status. - Verifier Space at commit
0975ea5: hashes the client's 4-field canonical CSV (D23).
Install notes¶
pip install puma-cpnow ships the runtime data (D42) except the TAWOS dataset, which users obtain from its original source and point to withPUMA_DATA_DIRor place in./data.puma --versionprints the installed version.- The dashboard is installable from PyPI:
matplotlibis a declared dependency (D48). - The container image ghcr.io/pumacp/puma is pushed to GHCR only by a v* tag push, after the Trivy gate passes; a manual run of the workflow builds and scans the image without pushing it.
Known limitations¶
- D44 / D45 — the H2 estimation and H1 triage inferential tests remain
open in
docs/known_debt.md. - D58 — PyPI publishing uses an API token; trusted publishing is not configured.
- D59–D67 — documentation errata and backlog, deferred to the documentation revision.
- D68 —
puma db migratewith the default--dbfails in a working directory withoutdata/; target: next patch. - D69 — the image pins pip 26.1.2; CVE-2026-13346 remains (MEDIUM in Trivy) because later pip releases do not pass the Trivy gate.
- raw_predictions_url — not set by the CLI, so the verifier cannot check new submissions (see Overview).
Quality at release time¶
Python 3.11.15, pinned requirements.txt and requirements-dev.txt,
measured on a clean checkout of develop d9456d6 with the changes of the
release commit applied:
- ruff check / ruff format --check: clean
- mypy src/puma/: 0 errors / 101 source files
- pytest tests/unit/: 548 passed
- pytest tests/community/: 208 passed, 1 skipped
- pytest tests/cli/: 23 passed
- pytest tests/integration/ -m "not ollama": 166 passed, 3 skipped, 12 deselected
- pytest tests/smoke/ -m smoke: 3 passed
- mkdocs build --strict: exit 0
- python -m build:
puma_cp-4.0.1.tar.gzandpuma_cp-4.0.1-py3-none-any.whl, 0 warning lines - wheel-only install outside the repository:
puma --versionprintspuma-cp 4.0.1;puma envreports PUMA version 4.0.1
See also¶
CHANGELOG.md— the[4.0.1]section.docs/known_debt.md— the D40–D68 entries.