modelstamp

Model files with receipts.

modelstamp verifies persisted Python machine-learning models, detects relevant dependency drift, and records reproducible environment metadata. Its sidecar manifest connects each artifact to its checksum, serialization backend, model details, runtime dependencies, and caller-provided metadata.

pip install modelstamp

import modelstamp as ms

ms.save(model, "model.joblib", metadata={"validation_auc": 0.91})
model, manifest = ms.load("model.joblib")

The artifact is hashed before deserialization. Dependency changes can warn or block loading, and optional HMAC authentication protects the model/manifest pair against unauthorized replacement.

The Modelstamp preprint documents the threat model, 14 controlled environment-drift scenarios, eight trust-boundary scenarios, and artifact-size scaling results. Cite it as:

Anagha Dhekne. "Modelstamp: Pre-Deserialization Verification of Machine-Learning Artifacts and Runtime Environment State." arXiv:2609.01781, 2026.

Software citation metadata and the archived release remain available through CITATION.cff and the Zenodo software DOI.

Research evidence

The current Modelstamp preprint evaluates 14 controlled environment-drift scenarios, eight controlled trust-boundary scenarios, and verification scaling from 10 MiB to 1 GiB.

Two experiments added to the repository after that preprint extend the evidence base: the PyOD ordering baseline and the controlled deserialization-boundary experiment. They test verification ordering and whether a pre-load rejection can stop before a harmless reconstruction side effect occurs. They do not claim that Modelstamp detects malicious models or makes pickle/joblib safe for untrusted artifacts.

Start with the quick start, then review the security boundary before loading persisted Python objects. The Research & Adoption page is the canonical record of papers, reproducible evidence, independent use, citations, and community review.

Choose a guide

Releases are published from protected v* tags using PyPI Trusted Publishing. Maintainers can use the release checklist for the protected main-to-PyPI workflow.