Skip to content

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.png and data/jira_balanced_200.csv under puma/_bundled/, used when no source tree is present (D42).
  • PUMA_DATA_DIR and PUMA_SPECS_DIR — data/ files and specs/ 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 to pumacp/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 --version prints puma-cp <version> (D43); the banner, puma env, ProfileSnapshot.puma_version and puma.__version__ read the installed puma-cp version (D50).
  • CI — lint-and-test runs tests/community/ and tests/cli/, an unpinned-deps job 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-community PR #3 (1ee1376): wiki-sync.yml granted contents: write.
  • pumacp/puma-community PR #10 (a0da178): badge generation skips verification sidecars when counting submissions.
  • pumacp/puma-community PR #11 (e9dc524): verification covers only added submissions and writes a sidecar only when verified.
  • pumacp/puma-community PR #12 (fba79b9): validate-submission.yml pins the add-labels action, guards existing submissions and resets the valid label.
  • pumacp/puma-community PR #13 (653a9b3): auto-merge is refused unless every changed file is added.
  • pumacp/puma-community PR #14 (224c4a8): Hugging Face dataset references point at the pumaproject namespace.
  • Leaderboard Space at commit 7de208b: loads only submission records and reads integrity.verification_status.
  • Verifier Space at commit 0975ea5: hashes the client's 4-field canonical CSV (D23).

Install notes

pip install -U puma-cp
puma --version        # puma-cp 4.0.1
  • pip install puma-cp now ships the runtime data (D42) except the TAWOS dataset, which users obtain from its original source and point to with PUMA_DATA_DIR or place in ./data.
  • puma --version prints the installed version.
  • The dashboard is installable from PyPI: matplotlib is 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 migrate with the default --db fails in a working directory without data/; 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.gz and puma_cp-4.0.1-py3-none-any.whl, 0 warning lines
  • wheel-only install outside the repository: puma --version prints puma-cp 4.0.1; puma env reports PUMA version 4.0.1

See also

  • CHANGELOG.md — the [4.0.1] section.
  • docs/known_debt.md — the D40–D68 entries.