Versions & aliases

Every commit produces an immutable version with a monotonic integer index. Aliases are movable names that point at a version — latest is managed for you; the rest are yours to set. This page covers the read/label functions that complement upload and download.

Inspecting a version

get_artifact_version resolves a version — by version_index, by alias, or (with neither) the latest alias — and returns its VersionInfo:

v = metrana.get_artifact_version("model", "llm", alias="production")

v.version_index   # int | None — the committed index
v.state           # str        — lifecycle state
v.size_bytes      # int        — total managed bytes
v.num_files       # int        — files in the manifest
v.metadata        # dict       — the queryable metadata set at upload
v.description     # str | None
v.created_by_run  # str | None — run lineage, if recorded
v.artifact_id     # str
v.version_id      # str

Supplying both alias and version_index raises MetranaArtifactValidationError; the same rule holds for every resolve-by-version function on this page.

Listing files

list_artifact_files returns every entry in a version’s manifest (paging through the API for you) as a list of FileEntry:

for f in metrana.list_artifact_files("model", "llm", version_index=3):
    f.path          # str        — in-artifact path
    f.digest        # str        — SHA-256 hex
    f.size          # int
    f.is_reference  # bool       — True if the bytes live in your bucket
    f.storage_uri   # str        — where the bytes are
    f.content_type  # str | None

Use is_reference / storage_uri to fetch reference bytes yourself (Metrana never serves them — see Downloading → references are skipped).

Pointing aliases

set_artifact_alias points a user-managed alias at a version. Target the version by exactly one of version_index or target_alias (point one alias at wherever another currently resolves):

# Point "production" at version 3.
metrana.set_artifact_alias(type="model", name="llm", alias="production", version_index=3)

# Point "production" at wherever "best-eval" currently resolves.
metrana.set_artifact_alias(type="model", name="llm", alias="production", target_alias="best-eval")

It returns an AliasInfo (.alias, .version_id, .version_index) describing what the alias now resolves to. Aliases can be re-pointed freely — that’s the point of them: keep production stable in your deploy code and move it to a new version when you promote one.

delete_artifact_alias removes a user alias:

metrana.delete_artifact_alias(type="model", name="llm", alias="v2.1-rc")

latest is reserved

latest always points at the most recently committed version and is managed automatically. You cannot set it, delete it, or pass it in an upload’s aliases list — attempting to raises an error. Use your own aliases (production, stable, best-eval, …) for anything you want to control.

Index vs alias: which to use

• Version index — reproducibility. An index is immutable and always resolves to the same bytes. Pin it in a paper’s artifact list or a frozen eval config.
• Alias — a moving target you control. production in your serving code always fetches whatever you last promoted, without editing the code.
• latest — convenience for “the newest thing”, and the default when you resolve without specifying either.