Model versioning

Semantic versioning

Every revision is tagged MAJOR.MINOR.PATCH. Bump:

• MAJOR — input or output schema changes, license changes
• MINOR — accuracy or robustness improvements, new optional inputs
• PATCH — bug fixes, metadata corrections, retraining on the same data

Immutable artifacts

Once published, a revision can never be edited. Replacing weights in-place would silently break consumers. To fix a bad revision, publish a new one and optionally yank the broken one.

Publish a new revision

node.models.create_revision(
    model_id="mdl_01HZ...",
    version="1.5.0",                   # semver: major.minor.patch
    files=["./weights/model.safetensors"],
    changelog="Improved grasp success on transparent objects (+4%).",
    parent="1.4.0",
)

Pinning

# Pin to an exact revision (recommended for production)
node.models.download("acme/grasp-policy-v2", revision="1.4.0")

# Track the latest 1.x line
node.models.download("acme/grasp-policy-v2", revision="^1")

# Always grab the most recent revision (not recommended in production)
node.models.download("acme/grasp-policy-v2", revision="latest")

Yanking a revision

Yanking does not delete files (that would break existing deployments) but does mark the revision as discouraged. New installs print a warning. The model card shows a yank banner.

# Mark a broken revision as yanked
# Buyers still receive the files but downloads emit a warning.
node.models.yank("mdl_01HZ...", revision="1.3.2", reason="memory leak on Jetson")

Revision diffs

Node Data computes a diff between revisions: which files changed, how many parameters were touched, and which benchmarks moved. The diff is shown on the listing page and exposed at GET /v1/models/{id}/revisions/{a}..{b}/diff.

Retention

Public revisions are retained indefinitely. Private revisions follow the retention policy of the workspace they live in.