Skip to main content

Release Process

  1. Update VERSION file with new version (e.g. v0.2.0)
  2. Update RELEASE.md with release notes
  3. Create PR, get review, merge
  4. Tag and publish: make publish
  5. Build and publish wheel: make publish-wheel
  6. Build and publish image: make build-image && make publish-image

v0.3.0 - 2026-11-19Direct link to v0.3.0 - 2026-11-19

ChangedDirect link to Changed

  • Bump the openfilter dependency to 1.5.0
  • Bump the openfilter dependency to 1.5.1
  • Bump the openfilter dependency to 1.5.2
  • Breaking: Drop support for Python 3.10; requires-python is now >=3.11. Pillow 13.0.0, the first release with fixes for several critical advisories, requires Python 3.11. The lock now pins pillow 13.0.0 and certifi 2026.10.23. The CI test matrix now runs 3.11–3.14.
  • Breaking: The image no longer contains the model weights. The Moondream3 weights and the moondream/starmie-v1 tokenizer ship as a separate model bundle image (us-west1-docker.pkg.dev/plainsightai-prod/premium-filters/filter-moondream3-model, first version 0.1.0), built from the new models.toml by .github/workflows/model-bundle.yaml and mounted read-only at /app/models. The filter reads /app/models/moondream3-preview/ and /app/models/starmie-v1/tokenizer.json and fails at startup, naming the path, if they are missing. This is what lets the image build on GitHub-hosted runners again (the baked-in ~18.5 GB exhausted their disk).
  • Breaking: New config weights_path (FILTER_WEIGHTS_PATH, default /app/models/moondream3-preview) and tokenizer_path (FILTER_TOKENIZER_PATH, default /app/models/starmie-v1/tokenizer.json). weights_repo / weights_revision (FILTER_WEIGHTS_REPO / FILTER_WEIGHTS_REVISION) are removed: the weights version is now the bundle version, and setting them only logs a warning.
  • Breaking: The filter is now released as a premium filter (filter-release-premium.yaml), publishing the image to us-west1-docker.pkg.dev/plainsightai-prod/premium-filters/filter-moondream3 instead of the per-org filter registry, and publishing the Python wheel as well.
  • The tokenizer is read from tokenizer_path by intercepting the vendored Tokenizer.from_pretrained("moondream/starmie-v1") call while the model is built, so filter_moondream3/vendor/ stays byte-identical to upstream.
  • docker-compose.yaml mounts the published bundle as a type: image volume (tag FILTER_MOONDREAM3_MODEL_TAG, default 0.1.0); this needs Docker's containerd image store. make pull-models copies the bundle into ./models for host use.
  • Removed make vendor-weights, make vendor, make vendor-clobber, make check-revision-sync and make test-hf-download, the vendor-weights and vendor modes of scripts/vendor_model_code.py, and the local .cache/huggingface flow. HF_HOME is no longer set in the images; HF_HUB_OFFLINE=1 / TRANSFORMERS_OFFLINE=1 stay.

v0.2.18 - 2026-09-23Direct link to v0.2.18 - 2026-09-23

ChangedDirect link to Changed

  • Bump the openfilter dependency to 1.4.0

v0.2.17 - 2026-08-19Direct link to v0.2.17 - 2026-08-19

ChangedDirect link to Changed

  • Build the filter image on openfilter-base:py3.14 (was the prior interpreter). The published wheel supports Python 3.14, so the image now ships 3.14. Running on 3.10–3.13 is unaffected.

v0.2.16 - 2026-08-18Direct link to v0.2.16 - 2026-08-18

ChangedDirect link to Changed

  • Update the openfilter dependency to 1.3.0
  • Add Python 3.14 support: raise the requires-python ceiling to <3.15 and add 3.14 to the CI test matrix (3.10–3.13 unchanged).

v0.2.15 - 2026-08-11Direct link to v0.2.15 - 2026-08-11

ChangedDirect link to Changed

  • Build on openfilter-base instead of pytorch/pytorch:*-cuda12.8-*-runtime (never apt-upgraded → OS-package CVEs). Both build stages move to the slim base and torch is pinned to >=2.9,<2.10, whose wheel bundles CUDA 12.8 (cu128) — what Blackwell (sm_120) needs — keeping Blackwell support on the torch wheel; the builder→runtime site-packages COPY now uses /usr/local rather than the conda path. The pin is deliberate: an unpinned torch now resolves to 2.13.x (CUDA 13/cu13, no cu12 runtime); torch 2.9.1+cu128 is validated on Blackwell (RTX 5060) via the lab GPU smoke.
  • Update the openfilter dependency to 1.2.2

v0.2.14 - 2026-08-05Direct link to v0.2.14 - 2026-08-05

ChangedDirect link to Changed

  • Update openfilter[all] to >=1.2.1
  • Refresh the docker-compose.yaml openfilter utility image tags to 1.2.1 (and the commented production-image example to the release version).
  • Bump actions/checkout to v7 in the vendor-check workflow (latest major, Node24 runtime).
  • Switch dev-tooling pins to >= ranges.
  • Fix a malformed docker-compose.yaml service key (filter_moondream3:0.2.3 → filter_moondream3:) that was pre-existing on main and broke YAML parsing of the whole file.
  • Fix the Makefile image tag to strip the v prefix (DOCKER_TAG ?= $(VERSION:v%=%), and build-image/build-image-dev/publish-image now use ${IMAGE}:${DOCKER_TAG}), matching the shared build-include/filter.mk. The custom targets were building/pushing filter-moondream3:v0.2.x, but the shared publish action tags latest off the stripped :0.2.x, so its docker tag step failed with No such image and the release rolled back (this had silently broken every release since v0.2.10). The v0.2.13 attempt was rolled back; this release supersedes it.

v0.2.12 - 2026-07-26Direct link to v0.2.12 - 2026-07-26

ChangedDirect link to Changed

  • README.md: use the exact HyperLabel™ wording specified by Shanker for the filter family.

v0.2.11 - 2026-07-25Direct link to v0.2.11 - 2026-07-25

ChangedDirect link to Changed

  • README.md: document this filter as part of the Plainsight Hyperlabel family of filters.

v0.2.10 - 2026-05-05Direct link to v0.2.10 - 2026-05-05

FixedDirect link to Fixed

  • Dockerfile + scripts/vendor_model_code.py: snapshot_download with a commit SHA does not write refs/main to the HuggingFace cache. At runtime tokenizers.Tokenizer.from_pretrained("moondream/starmie-v1") (no revision argument in the vendored call) resolves the default branch via refs/main; with HF_HUB_OFFLINE=1 this raised LocalEntryNotFoundError and crashed the filter before processing any frames. Both the production Docker build and the local make vendor-weights host cache now write refs/main pointing to the pinned tokenizer SHA after the download, so offline resolution succeeds in both paths.
  • tests/test_tokenizer_offline.py: added test_tokenizer_loads_offline_no_revision to cover the exact from_pretrained("moondream/starmie-v1") call without a revision argument - the path that was failing.

v0.2.9 - 2026-04-29Direct link to v0.2.9 - 2026-04-29

FixedDirect link to Fixed

  • Dockerfile: huggingface_hub was not available when snapshot_download ran because the builder site-packages COPY happens after the download RUN. Added an explicit pip install before the download step (overwritten by the COPY, not present in the final image).
  • Dockerfile: replaced python -c with a heredoc to eliminate potential IndentationError from the inline script.
  • Dockerfile: switched to USER appuser before the download RUN so weights are written with correct ownership, removing the slow chown -R over ~17 GB.
  • Dockerfile: updated build-stage comment to reflect the 2-stage design and guide future pin bumps.

v0.2.8 - 2026-04-29Direct link to v0.2.8 - 2026-04-29

FixedDirect link to Fixed

  • publish-gar-private was failing with ENOSPC on ubuntu-latest runners during the Docker weights build (~17 GB download). Added ci-disk-cleanup Makefile target (runs only when GITHUB_ACTIONS=true, RUNNER_ENVIRONMENT=github-hosted, and RUNNER_OS=Linux) that frees ~20 GB by removing tooling unused in filter builds (Java, Swift, Haskell, Python toolcache, PowerShell, GraalVM). build-image now depends on it.

v0.2.7 - 2026-04-29Direct link to v0.2.7 - 2026-04-29

FixedDirect link to Fixed

  • huggingface-cli was renamed to hf in huggingface_hub>=0.32; updated Dockerfile weights stage to use hf download and pinned huggingface_hub[cli]>=0.32,<2. This was causing the Docker build to fail silently (exit code 1) in publish-gar-private, so the v0.2.6 image was never published to GAR.

AddedDirect link to Added

  • tests/test_smoke.py: end-to-end smoke tests that exercise the real filter code (imports, normalize_config round-trip for all 4 skills, and process() for each skill with a mock model). Catches regressions that pure unit tests miss because they mock at the module level.

v0.2.6 - 2026-04-28Direct link to v0.2.6 - 2026-04-28

FixedDirect link to Fixed

  • publish-gar-private failed with ENOSPC on ubuntu-latest runners because the vendor-weights approach required copying ~18 GB of weights into the Docker build context, exhausting the free disk available on the runner after OS tooling overhead. The Dockerfile now uses a dedicated weights build stage that downloads model weights and tokenizer directly into the HF cache layout via huggingface-cli download (one --include per pattern, no --local-dir). This fixes the original --include silent-drop bug (positional filenames caused the glob to be ignored) and eliminates the large build context entirely. The final runtime image is identical: HF_HOME=/cache/huggingface, HF_HUB_OFFLINE=1, fully air-gapped at container start.
  • make build-image no longer depends on make vendor (host-side 18 GB download is no longer needed for the image build). make vendor-weights remains available for local dev smoke tests.

v0.2.5 - 2026-04-28Direct link to v0.2.5 - 2026-04-28

FixedDirect link to Fixed

  • Release publish-gar-private job failed on v0.2.4 because make build-image runs make vendor on the GitHub Actions runner, and the runner's base Python does not have project deps installed. The vendor-weights Make target now declares install as a prerequisite, so a fresh runner installs the project (which pulls in huggingface_hub via the base dependency set) before the vendor script runs. Mirrors the mise side, where tasks.test already depends on install.

v0.2.4 - 2026-04-27Direct link to v0.2.4 - 2026-04-27

FixedDirect link to Fixed

  • Filter startup is fully offline with respect to HuggingFace Hub. The runtime resolves the model and tokenizer snapshots from a local HuggingFace cache via huggingface_hub.snapshot_download(local_files_only=True), with HF_HUB_OFFLINE=1, TRANSFORMERS_OFFLINE=1 and DO_NOT_TRACK=true set in the production Dockerfile. Required for air-gapped and egress-restricted deployments.
  • Drop the global HF_HOME / TRANSFORMERS_CACHE setdefault at filter import time. The previous force rooted the cache under the current working directory, which silently sent every deployment to a different path depending on launch CWD.

ChangedDirect link to Changed

  • Code-vs-data split: filter_moondream3/vendor/ now ships ONLY upstream Python source as a byte-identical copy of the pinned HuggingFace revision. tokenizer.json and config.json no longer ship inside the wheel; pure-data files live in a project-local, gitignored HuggingFace cache at ./.cache/huggingface/ populated by huggingface_hub.snapshot_download. Vendored .py source is sha256-verified against filter_moondream3/vendor/CHECKSUMS.
  • scripts/vendor_model_code.py rewritten around vendor-code + vendor-weights subcommands. The vendor-code step is a pure copy plus checksum verify (no regex transforms, no mirror_config_to_cache, no patched Tokenizer.from_file); the urllib fetch now applies a 120 s timeout so a hung HF Hub fails loud instead of stalling indefinitely. The vendor-weights step uses snapshot_download with cache_dir=./.cache/huggingface/hub so the cache stays under the repo root.
  • Filter config replaces weights_path with weights_repo (moondream/moondream3-preview) and weights_revision (the pinned sha). The runtime calls snapshot_download(local_files_only=True) and hands the resolved directory to HfMoondream.from_pretrained(..., trust_remote_code=False). The int4 model variant is no longer supported; selecting it raises NotImplementedError.
  • Dockerfile and Dockerfile.dev both export HF_HOME=/cache/huggingface and set HF_HUB_OFFLINE=1, TRANSFORMERS_OFFLINE=1, DO_NOT_TRACK=true so a future regression that reintroduces a from_pretrained call fails the same way in dev as in prod. The production Dockerfile bakes the cache into the image with COPY --chown=appuser:appuser ./.cache/huggingface /cache/huggingface, reading directly from the build context. Dockerfile.dev intentionally drops the COPY; the dev compose file bind-mounts the local cache instead.
  • docker-compose.yaml mounts ${WEIGHTS_PATH:-./.cache/huggingface}:/cache/huggingface:ro and exposes FILTER_WEIGHTS_REPO / FILTER_WEIGHTS_REVISION instead of the legacy FILTER_WEIGHTS_PATH.
  • Makefile + .mise.toml task names stay (vendor-code, vendor-weights, vendor, vendor-clobber) and operate on ./.cache/huggingface/ instead of models/moondream3/. New build-image-dev target builds Dockerfile.dev without the vendor prereq.

v0.2.3 - 2026-04-24Direct link to v0.2.3 - 2026-04-24

FixedDirect link to Fixed

  • Restore RELEASE.md heading format

v0.2.2 - 2026-04-23Direct link to v0.2.2 - 2026-04-23

ChangedDirect link to Changed

  • Bump openfilter SDK to >=0.1.30
  • Add source-paths release gate to CI workflow
  • Bump docker-compose builtin images (openfilter-video-in, openfilter-webvis) from 0.1.20 to 0.1.30

v0.2.1 - 2026-04-20Direct link to v0.2.1 - 2026-04-20

ChangedDirect link to Changed

  • Remove project_id from create-release.yaml (default in gh-actions#73)
  • Delete old ci.yaml (shared workflow handles tests)
  • Switch to shared security-scan workflow
  • Bump openfilter to >=0.1.27
  • Fix Makefile IMAGE to filter-registry-{org_id}/

v0.2.0Direct link to v0.2.0

  • Migrated release workflow to GAR private filter pattern (filter-release-private reusable workflow)
  • Dockerfile installs from local source; model weights downloaded in CI at build time
  • Removed Scarf and python.openfilter.io references

v0.1.0Direct link to v0.1.0

  • Initial release
  • Moondream3 vision-language model as OpenFilter filter
  • Skills: detect, caption, query, point
  • Vendored model code (no trust_remote_code)
  • Support for bfloat16 (full) and int4 model variants
  • torch.compile support with FlexAttention for improved inference performance
  • Model weights in safetensors format
  • Docker image with CUDA runtime