Skip to content
Metrana Docs

Artifacts SDK overview

The Metrana artifacts SDK (part of the same metrana package) lets you version and share files — model checkpoints, datasets, tokenizers, eval sets — alongside your runs. You upload a file or directory as a named, versioned artifact; anyone with access to the workspace can download an exact version back, or point an alias like production at the version they want.

import metrana


# Upload a directory as version N of model/my-llm.
metrana.upload_artifact("checkpoints/step-5000/", type="model", name="my-llm", workspace="my-team")


# Later, somewhere else, pull the latest version back down.
metrana.download_artifact("model", "my-llm", dest="./restored", workspace="my-team")

That is the whole shape of it. Everything else is detail: aliases, metadata, external references, and the options that make uploading large files fast and correct.

The data model

Section titled “The data model”

An artifact is identified by a type and a name within a workspace — for example model/my-llm or dataset/imagenet-subset. The type is a free-form label you choose (commonly "model" or "dataset"); the name is unique within its type.

Each artifact holds an ordered series of immutable versions:

  • Version index — every committed version gets a monotonic integer index (0, 1, 2, …). Indices never change and never point at different bytes.
  • latest alias — automatically maintained to point at the most recently committed version. You cannot set or remove it.
  • User aliases — names you manage (production, best-eval, v2.1) that point at a version of your choosing and can be re-pointed at any time.

A version is a manifest of files. Each file has an in-artifact path (like weights/model.safetensors) and is one of:

  • Managed file — the bytes live in Metrana-managed storage. These are what upload_artifact uploads and download_artifact fetches.
  • Reference — a pointer to bytes that live in your own bucket (an s3://… URI you supply). Metrana records the path, digest, and size but never copies or serves the bytes. Useful for cataloguing large existing data without re-uploading it.

Content-addressed, so bytes dedup

Section titled “Content-addressed, so bytes dedup”

Files are content-addressed by their SHA-256 digest. When you upload, the SDK hashes each file first and the server only asks for the bytes it doesn’t already have. Re-uploading an unchanged file across versions — or the same file under two paths — transfers it once. A version that is byte-for-byte identical to an existing one deduplicates on commit rather than storing a second copy.

The functions

Section titled “The functions”

Everything is a module-level function on metrana:

Function What it does
upload_artifact Upload files/directories as a new committed version.
download_artifact Download every managed file of a version into a directory.
get_artifact_version Resolve a version (by index or alias) and read its metadata.
list_artifact_files List the files in a version’s manifest.
set_artifact_alias Point a user alias at a version.
delete_artifact_alias Remove a user alias.

For advanced, one-call-per-endpoint control there is also the low-level ArtifactClient — but the functions above cover almost every use.

Where to go next

Section titled “Where to go next”