Buckets:

hf-doc-build
/

doc-dev

Files

xet

hf-doc-build/doc-dev / trackio /pr_676 /en /registry.html

qgallouedec

4 days ago

download

raw

65 kB

	<meta charset="utf-8" /><meta name="hf:doc:metadata" content="{"title":"Registry","local":"registry","sections":[{"title":"Create a registry","local":"create-a-registry","sections":[],"depth":2},{"title":"Create a collection","local":"create-a-collection","sections":[{"title":"Collection types","local":"collection-types","sections":[],"depth":3}],"depth":2},{"title":"Link an artifact version to a collection","local":"link-an-artifact-version-to-a-collection","sections":[{"title":"The linked artifact","local":"the-linked-artifact","sections":[],"depth":3},{"title":"Collection versions","local":"collection-versions","sections":[],"depth":3}],"depth":2},{"title":"Promote a version with aliases","local":"promote-a-version-with-aliases","sections":[],"depth":2},{"title":"Unlink a version","local":"unlink-a-version","sections":[],"depth":2},{"title":"Remote registries","local":"remote-registries","sections":[{"title":"What lives in the bucket","local":"what-lives-in-the-bucket","sections":[],"depth":3},{"title":"Concurrency","local":"concurrency","sections":[],"depth":3}],"depth":2},{"title":"Inspect a registry","local":"inspect-a-registry","sections":[],"depth":2},{"title":"Command-line interface","local":"command-line-interface","sections":[],"depth":2},{"title":"Browse registries in the dashboard","local":"browse-registries-in-the-dashboard","sections":[],"depth":2},{"title":"Audit history","local":"audit-history","sections":[],"depth":2}],"depth":1}"/>
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/entry/start.BRWY-7Pk.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/BI0o03iR.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/c5epZbRJ.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/entry/app.BWp3UJuk.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/CTPvGMXu.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/Cbx9Bn2j.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/DsnmJJEf.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/CldSabhm.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/nodes/0.Cdh0K3im.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/DoyOpfDJ.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/nodes/19.Cxc1U15F.js" rel="modulepreload">
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/chunks/BQnA81uy.js" rel="modulepreload">
	<!--1wf5eb0--><meta name="hf:doc:metadata" content="{"title":"Registry","local":"registry","sections":[{"title":"Create a registry","local":"create-a-registry","sections":[],"depth":2},{"title":"Create a collection","local":"create-a-collection","sections":[{"title":"Collection types","local":"collection-types","sections":[],"depth":3}],"depth":2},{"title":"Link an artifact version to a collection","local":"link-an-artifact-version-to-a-collection","sections":[{"title":"The linked artifact","local":"the-linked-artifact","sections":[],"depth":3},{"title":"Collection versions","local":"collection-versions","sections":[],"depth":3}],"depth":2},{"title":"Promote a version with aliases","local":"promote-a-version-with-aliases","sections":[],"depth":2},{"title":"Unlink a version","local":"unlink-a-version","sections":[],"depth":2},{"title":"Remote registries","local":"remote-registries","sections":[{"title":"What lives in the bucket","local":"what-lives-in-the-bucket","sections":[],"depth":3},{"title":"Concurrency","local":"concurrency","sections":[],"depth":3}],"depth":2},{"title":"Inspect a registry","local":"inspect-a-registry","sections":[],"depth":2},{"title":"Command-line interface","local":"command-line-interface","sections":[],"depth":2},{"title":"Browse registries in the dashboard","local":"browse-registries-in-the-dashboard","sections":[],"depth":2},{"title":"Audit history","local":"audit-history","sections":[],"depth":2}],"depth":1}"/><!---->
	<link href="/docs/trackio/v0.36.0/en/_app/immutable/assets/0.tn0RQdqM.css" rel="modulepreload"> <!--[--><!--[0--><!--[--><!--[0--><!--[--><p></p> <div class="items-center shrink-0 min-w-[100px] max-sm:min-w-[50px] justify-end ml-auto flex" style="float: right; margin-left: 10px; display: inline-flex; position: relative; z-index: 10;"><div class="inline-flex rounded-md max-sm:rounded-sm"><button class="inline-flex items-center gap-1 h-7 max-sm:h-7 px-2 max-sm:px-1.5 text-sm font-medium text-gray-800 border border-r-0 rounded-l-md max-sm:rounded-l-sm border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-live="polite"><span class="inline-flex items-center justify-center rounded-md p-0.5 max-sm:p-0 hover:text-gray-800 dark:hover:text-gray-200"><svg class="sm:size-3.5 size-3" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----></span> <span>Copy page</span></button> <button class="inline-flex items-center justify-center w-6 max-sm:w-5 h-7 max-sm:h-7 disabled:pointer-events-none text-sm text-gray-500 hover:text-gray-700 dark:hover:text-white rounded-r-md max-sm:rounded-r-sm border border-l transition border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-haspopup="menu" aria-expanded="false" aria-label="Open copy menu"><svg class="transition-transform text-gray-400 overflow-visible sm:size-3.5 size-3 rotate-0" width="1em" height="1em" viewBox="0 0 12 7" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 1L6 6L11 1" stroke="currentColor"></path></svg><!----></button></div> <!--[-1--><!--]--></div><!----> <!--[0--><h1 class="relative group"><a id="registry" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#registry"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Registry</span></h1><!--]--><!----> <blockquote class="note"><p>The registry is under active development (<a href="https://github.com/gradio-app/trackio/issues/607" rel="nofollow">#607</a>). Publishing — linking and promoting versions, described on this page — plus CLI commands and read-only dashboard browsing are available today. Resolving registry versions with <code>use_artifact</code> is a planned follow-up.</p></blockquote> <p>A <strong>registry</strong> is a shared catalog of your best artifact versions. A project lists the artifacts your experiments produced; a registry lists selected artifacts <strong>across</strong> projects.</p> <p>A registry contains <strong>collections</strong>. Each collection represents one asset — a model you retrain over time, a golden evaluation set — and holds the versions of it you chose to publish. You <em>link</em> an artifact version into a collection. A link is a pointer to the source version: nothing is copied. You then promote a linked version through lifecycle stages by moving aliases such as <code>staging</code> and <code>production</code>.</p> <p>For example, a registry named <code>models</code> might contain one collection per deployable model, and a registry named <code>datasets</code> one collection per benchmark. How you split assets across registries and collections is up to you.</p> <p><img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/trackio/registry-overview.png" alt="How projects, artifact versions, collections, links, and aliases relate"/></p> <p>A collection has its own version line (<code>v0</code>, <code>v1</code>, …) that is independent of the source artifacts’ version numbers, and its versions may point at different source artifacts in different projects. Aliases name exactly one version per collection.</p> <p>A registry is either <strong>local</strong> — stored next to your other Trackio data as a project named <code>registry-models</code> (the <code>registry-</code> prefix is reserved) — or backed by a <strong>Hugging Face bucket</strong>, which is what makes it reachable from other machines and from runs that log to a Space. See <a href="#remote-registries">Remote registries</a>.</p> <!--[1--><h2 class="relative group"><a id="create-a-registry" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#create-a-registry"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Create a registry</span></h2><!--]--><!----> <p>Create a registry with <code>Api.create_registry()</code>:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-keyword">import</span> trackio

	registry = trackio.Api().create_registry(<span class="hljs-string">"models"</span>, description=<span class="hljs-string">"Our deployable models"</span>)<!----></pre></div><!----> <p>The optional <code>description</code> is stored on the registry and readable as <code>registry.description</code>.</p> <p>Registries are never created implicitly. Linking into a registry that does not exist raises an error.</p> <p>Use <code>Api.registry()</code> to fetch an existing registry. It also raises if the registry does not exist.</p> <!--[1--><h2 class="relative group"><a id="create-a-collection" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#create-a-collection"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Create a collection</span></h2><!--]--><!----> <p>A <em>collection</em> is a set of linked artifact versions within a registry, with a single version history. The versions may come from different source artifacts: if a resnet-based and a unet-based model are candidates for the same deployable product, link them into one collection and they become successive versions of it. If they are separate products, give each its own collection.</p> <p>You usually don’t create collections manually: linking into a collection that does not exist creates it automatically. Create one explicitly when you want to set a description up front:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->registry.create_collection(<span class="hljs-string">"my-model"</span>, <span class="hljs-string">"model"</span>, description=<span class="hljs-string">"The model we deploy"</span>)<!----></pre></div><!----> <!--[2--><h3 class="relative group"><a id="collection-types" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#collection-types"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Collection types</span></h3><!--]--><!----> <p>Each collection accepts a single <em>type</em> of artifact, fixed when the collection is created. The type comes from the artifact itself — the <code>type</code> field you pass to <code>trackio.Artifact</code> or <code>trackio.log_artifact</code> — so a collection created by a first link adopts that artifact’s type.</p> <p>For example, if you link a <code>"dataset"</code> artifact into a collection that accepts <code>"model"</code> artifacts, Trackio raises an error.</p> <p>The registry itself accepts every type: a model collection and a dataset collection can live side by side in the same registry.</p> <!--[1--><h2 class="relative group"><a id="link-an-artifact-version-to-a-collection" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#link-an-artifact-version-to-a-collection"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Link an artifact version to a collection</span></h2><!--]--><!----> <p>Publish an artifact version with <a href="/docs/trackio/pr_676/en/api#trackio.Run.link_artifact">Run.link_artifact()</a>:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-keyword">import</span> trackio

	trackio.Api().create_registry(<span class="hljs-string">"models"</span>)

	run = trackio.init(project=<span class="hljs-string">"my-experiments"</span>)
	artifact = trackio.log_artifact(<span class="hljs-string">"model.pt"</span>, name=<span class="hljs-string">"resnet"</span>, <span class="hljs-built_in">type</span>=<span class="hljs-string">"model"</span>)

	run.link_artifact(artifact, <span class="hljs-string">"registry-models/my-model"</span>, aliases=[<span class="hljs-string">"staging"</span>])<!----></pre></div><!----> <p>The target path is <code>"registry-<registry>/<collection>"</code>. The first segment is the registry’s full name, prefix included.</p> <p><code>link_artifact</code> takes the artifact object itself, so the version you hold is exactly the version that gets published:</p> <table><thead><tr><th>Use case</th><th>How</th><th>What gets recorded</th></tr></thead><tbody><tr><td>Link the artifact you just logged</td><td><code>run.link_artifact(artifact, ...)</code></td><td>A link, published by the run</td></tr><tr><td>Link a specific existing version</td><td><code>run.link_artifact(run.use_artifact("resnet:v3"), ...)</code></td><td>The run consumes <code>resnet:v3</code>, then a link, published by the run</td></tr><tr><td>Link an artifact that was never logged</td><td><code>run.link_artifact(draft_artifact, ...)</code></td><td>The artifact is logged to the run’s project first, then linked</td></tr></tbody></table> <p>You can also link from the artifact itself with <a href="/docs/trackio/pr_676/en/api#trackio.Artifact.link">Artifact.link()</a>, handy when the run isn’t in scope:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->artifact.link(<span class="hljs-string">"registry-models/my-model"</span>, aliases=[<span class="hljs-string">"staging"</span>])<!----></pre></div><!----> <p><code>Artifact.link</code> requires the artifact to be already logged or fetched — it won’t log a draft for you — and the link records no publishing run.</p> <!--[2--><h3 class="relative group"><a id="the-linked-artifact" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#the-linked-artifact"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>The linked artifact</span></h3><!--]--><!----> <p><code>link_artifact</code> returns the artifact at its registry location. Its <code>name</code> is the collection, its <code>project</code> is the registry, and its <code>version</code> and <code>aliases</code> are the collection’s. Its content — <code>manifest</code>, <code>manifest_digest</code>, <code>size</code>, <code>metadata</code> — is the source version’s, and the <code>source_project</code>, <code>source_name</code>, <code>source_version</code>, and <code>source_qualified_name</code> properties point back at it:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->linked = run.link_artifact(artifact, <span class="hljs-string">"registry-models/my-model"</span>)
	linked.qualified_name <span class="hljs-comment"># "registry-models/my-model:v0"</span>
	linked.source_qualified_name <span class="hljs-comment"># "my-experiments/resnet:v0"</span><!----></pre></div><!----> <p>Linking a linked artifact links its source version directly (with a warning), so links never chain.</p> <blockquote class="note"><p>Downloading through a registry location is not supported yet; it arrives together with registry resolution. Until then, download the source artifact version.</p></blockquote> <!--[2--><h3 class="relative group"><a id="collection-versions" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#collection-versions"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Collection versions</span></h3><!--]--><!----> <p>Each new link gets the next version number in the collection, starting at <code>v0</code>. Collection versions are independent of the source artifacts’ own version numbers, because linked versions typically come from different artifacts and projects.</p> <p>Linking a source version that is already in the collection does not create a new version. You get the existing version back, and any <code>aliases</code> you passed still move. Version numbers are never reused, so a published <code>my-model:v3</code> can never silently change meaning.</p> <!--[1--><h2 class="relative group"><a id="promote-a-version-with-aliases" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#promote-a-version-with-aliases"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Promote a version with aliases</span></h2><!--]--><!----> <p>An alias references one version per collection. Assigning an alias that another version already holds moves it — that move <em>is</em> the promotion. Consumers that resolve <code>my-model:production</code> follow the alias, so nothing downstream changes when it moves.</p> <p>Most promotions happen at publish time: you link a new version and place the alias in the same call.</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->run.link_artifact(artifact, <span class="hljs-string">"registry-models/my-model"</span>, aliases=[<span class="hljs-string">"staging"</span>])<!----></pre></div><!----> <p>To promote a version that is <em>already</em> in the collection, re-link it with the alias. Re-linking creates nothing new — you get the existing collection version back, and the aliases you pass move onto it. Find the version’s source in the collection’s links, fetch it, and link it again:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->registry.collection(<span class="hljs-string">"my-model"</span>).links
	<span class="hljs-comment"># [..., {"collection_version": 1, "source_project": "my-experiments",</span>
	<span class="hljs-comment"># "source_artifact": "resnet", "source_version": 3, ...}]</span>

	candidate = run.use_artifact(<span class="hljs-string">"resnet:v3"</span>)
	run.link_artifact(candidate, <span class="hljs-string">"registry-models/my-model"</span>, aliases=[<span class="hljs-string">"production"</span>])<!----></pre></div><!----> <p>Today the candidate is fetched by its source name, as recorded in the collection’s links. Fetching it from the registry directly — <code>use_artifact("registry-models/my-model:v1")</code> — arrives together with registry resolution; the re-link step stays the same. Rolling an alias back to an older version works the same way.</p> <p>Trackio manages the <code>latest</code> alias for you: it always points at the newest linked version.</p> <!--[1--><h2 class="relative group"><a id="unlink-a-version" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#unlink-a-version"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Unlink a version</span></h2><!--]--><!----> <p>Remove a link with <a href="/docs/trackio/pr_676/en/api#trackio.Artifact.unlink">Artifact.unlink()</a>, called on the linked artifact:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->linked = run.link_artifact(artifact, <span class="hljs-string">"registry-models/my-model"</span>)
	linked.unlink()<!----></pre></div><!----> <p>The source artifact and its files are untouched — only the collection membership is removed. Any aliases on the link go with it, and the collection version number is never reused, so <code>my-model:v0</code> can’t later mean something else. If the version you remove held <code>latest</code>, that alias moves to the highest remaining version, so <code>latest</code> keeps pointing at the newest version in the collection.</p> <!--[1--><h2 class="relative group"><a id="remote-registries" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#remote-registries"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Remote registries</span></h2><!--]--><!----> <p>A local registry only exists on the machine that wrote it. To share a catalog across machines — or to publish from a run that logs to a Space or a self-hosted server — back the registry with a <strong>Hugging Face bucket</strong> by passing <code>bucket_id</code>:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->registry = trackio.Api().create_registry(
	<span class="hljs-string">"models"</span>, description=<span class="hljs-string">"Our deployable models"</span>, bucket_id=<span class="hljs-string">"my-org/models-registry"</span>
	)<!----></pre></div><!----> <p>The bucket is created (private) if it does not exist. Set <code>TRACKIO_REGISTRY_BUCKET_ID</code> to make it the default for every registry call in a process, so scripts don’t have to pass it.</p> <p>Fetching, inspecting, and publishing all take the same argument:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->registry = trackio.Api().registry(<span class="hljs-string">"models"</span>, bucket_id=<span class="hljs-string">"my-org/models-registry"</span>)

	run = trackio.init(project=<span class="hljs-string">"my-experiments"</span>, space_id=<span class="hljs-string">"my-org/my-dashboard"</span>)
	artifact = trackio.log_artifact(<span class="hljs-string">"model.pt"</span>, name=<span class="hljs-string">"resnet"</span>, <span class="hljs-built_in">type</span>=<span class="hljs-string">"model"</span>)

	run.link_artifact(
	artifact,
	<span class="hljs-string">"registry-models/my-model"</span>,
	aliases=[<span class="hljs-string">"staging"</span>],
	bucket_id=<span class="hljs-string">"my-org/models-registry"</span>,
	)<!----></pre></div><!----> <p>Everyone with access to the bucket writes to it directly with their own Hugging Face credentials — there is no server in the path, so a registry is not tied to any one Space and outlives all of them. <code>Artifact.link</code> and <code>Artifact.unlink</code> accept <code>bucket_id</code> the same way, and a linked artifact remembers the bucket it came from, so <code>linked.unlink()</code> goes back to the right registry.</p> <p>The registry’s own bucket is deliberately <em>not</em> the run’s bucket: a registry is a cross-project catalog, so you name it explicitly rather than inheriting wherever metrics happen to go.</p> <!--[2--><h3 class="relative group"><a id="what-lives-in-the-bucket" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#what-lives-in-the-bucket"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>What lives in the bucket</span></h3><!--]--><!----> <p>Each mutation is stored as one immutable object, and state is a fold of that log:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class=" "><!---->trackio/registries/<registry>/registry.json name, description, created_at
	trackio/registries/<registry>/events/<event_uid>.json one object per mutation<!----></pre></div><!----> <p>Reading a remote registry folds those events into a local projection database under <code>registry-cache/</code>, which is a cache: delete it and the next read rebuilds it from the bucket.</p> <!--[2--><h3 class="relative group"><a id="concurrency" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#concurrency"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Concurrency</span></h3><!--]--><!----> <p>Object storage has no compare-and-swap, so writers cannot take a lock — they can only add objects nobody else is writing. Two consequences, both by design:</p> <ul><li><strong>Version numbers are assigned by the fold, not by the writer.</strong> Concurrent links are ordered by their event id (timestamp, then writer, then sequence), so each gets a distinct, never-reused number. A version reported by one writer can shift once a concurrent writer’s events are folded in.</li> <li><strong>Alias moves are last-writer-wins</strong> under that same order, <code>latest</code> included. Two people promoting <code>production</code> at the same instant is settled by event order.</li></ul> <p>Links stay pure pointers: nothing is copied into the registry bucket, so resolving a version reads the source project’s storage, which has to stay reachable. Copying (pinning) a version’s bytes into the registry is a planned follow-up.</p> <!--[1--><h2 class="relative group"><a id="inspect-a-registry" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#inspect-a-registry"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Inspect a registry</span></h2><!--]--><!----> <p>The <a href="/docs/trackio/pr_676/en/api#trackio.Registry">Registry</a> handle lists collections and their linked versions. Reads return <a href="/docs/trackio/pr_676/en/api#trackio.Collection">Collection</a> snapshots:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->registry = trackio.Api().registry(<span class="hljs-string">"models"</span>)

	registry.collections()
	<span class="hljs-comment"># [Collection(name="my-model", type="model", num_links=2, latest_version=1, ...)]</span>

	registry.collection(<span class="hljs-string">"my-model"</span>).links
	<span class="hljs-comment"># [{"collection_version": 1, "source_project": "my-experiments",</span>
	<span class="hljs-comment"># "source_artifact": "resnet", "source_version": 4,</span>
	<span class="hljs-comment"># "aliases": ["latest", "production"], ...}]</span><!----></pre></div><!----> <p>Each link records where the version came from (<code>source_project</code>, <code>source_artifact</code>, <code>source_version</code>), the source’s storage coordinates when it is not local (<code>source_space_id</code>, <code>source_bucket_id</code>), and the aliases currently on it. A link is a pure pointer to that source version; resolving it (a follow-up) reads the source version directly.</p> <!--[1--><h2 class="relative group"><a id="command-line-interface" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#command-line-interface"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Command-line interface</span></h2><!--]--><!----> <p>The <code>trackio registry</code> commands cover the same publishing and inspection workflow without requiring a Python script:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-sh "><!---->trackio registry create models --description <span class="hljs-string">"Models we deploy"</span>
	trackio registry create-collection models/churn-model --<span class="hljs-built_in">type</span> model

	trackio registry <span class="hljs-built_in">link</span> models/churn-model my-experiments/resnet:v3 --<span class="hljs-built_in">alias</span> staging
	trackio registry promote models/churn-model production v0

	trackio registry list models
	trackio registry show models/churn-model
	trackio registry events models

	trackio registry <span class="hljs-built_in">unlink</span> models/churn-model v0<!----></pre></div><!----> <p><code>link</code> resolves its source from local Trackio data. It accepts an explicit version or alias and defaults to <code>latest</code> when the suffix is omitted. The registry may still be bucket-backed; pass <code>--bucket-id my-org/models-registry</code> to any command. Use <code>--json</code> for structured output suitable for scripts.</p> <p>The CLI accepts both <code>models/churn-model</code> and the Python API’s full <code>registry-models/churn-model</code> target syntax. See <a href="cli_commands#registry-commands">CLI Commands</a> for the complete command reference.</p> <!--[1--><h2 class="relative group"><a id="browse-registries-in-the-dashboard" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#browse-registries-in-the-dashboard"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Browse registries in the dashboard</span></h2><!--]--><!----> <p>Launch the standalone, read-only registry dashboard to browse registry descriptions, collections, linked versions, aliases, source locations, and audit events:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-bash "><!---->trackio show registry<!----></pre></div><!----> <p>Or launch it from Python with <code>trackio.show(dashboard="registry")</code>. The registry dashboard is separate from the project dashboard because registries catalog artifacts across projects.</p> <p>The <strong>Local</strong> source shows registries stored on the dashboard machine. Choose <strong>HF Bucket</strong> to select an accessible Hugging Face bucket or enter a bucket id such as <code>my-org/models-registry</code>. On a Space, private bucket access uses the signed-in viewer’s Hugging Face credentials. A self-hosted dashboard only uses its saved Hugging Face token for viewers who opened its write-access URL. Public read-only dashboards never expose buckets through a server-owned token. Registry browsing is not included in static dashboard snapshots.</p> <!--[1--><h2 class="relative group"><a id="audit-history" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#audit-history"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Audit history</span></h2><!--]--><!----> <p>Every mutation appends an event to the registry’s audit log: registry and collection creation (<code>create</code>), <code>link</code>, <code>promote</code>, description changes (<code>update</code>), and <code>unlink</code>. The log answers questions like “which version was in production last month, and which run published it?“:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->registry.events()
	<span class="hljs-comment"># [{"id": 1, "ts": "...", "kind": "create", "payload": {...}},</span>
	<span class="hljs-comment"># {"id": 2, "ts": "...", "kind": "link",</span>
	<span class="hljs-comment"># "payload": {"collection": "my-model", "collection_version": 0,</span>
	<span class="hljs-comment"># "source_project": "my-experiments", "run_name": "exp-1", ...}},</span>
	<span class="hljs-comment"># {"id": 3, "ts": "...", "kind": "promote",</span>
	<span class="hljs-comment"># "payload": {"alias": "staging", "collection_version": 0,</span>
	<span class="hljs-comment"># "previous_version": None, ...}}]</span><!----></pre></div><!----> <p>Link and promote events record the publishing run. Promote events also record the version the alias moved from.</p> <a class="!text-gray-400 !no-underline text-sm flex items-center not-prose mt-4" href="https://github.com/gradio-app/trackio/blob/main/docs/source/registry.md" target="_blank"><svg class="mr-1" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M31,16l-7,7l-1.41-1.41L28.17,16l-5.58-5.59L24,9l7,7z"></path><path d="M1,16l7-7l1.41,1.41L3.83,16l5.58,5.59L8,23l-7-7z"></path><path d="M12.419,25.484L17.639,6.552l1.932,0.518L14.351,26.002z"></path></svg><!----> <span><span class="underline">Update</span> on GitHub</span></a><!----> <p></p><!--]--><!----><!--]--><!--]--><!--]--> <!--[-1--><!--]--><!--]-->

	<script>
	{
	__sveltekit_1fjrczi = {
	base: "/docs/trackio/v0.36.0/en",
	assets: "/docs/trackio/v0.36.0/en"
	};

	const element = document.currentScript.parentElement;

	Promise.all([
	import("/docs/trackio/v0.36.0/en/_app/immutable/entry/start.BRWY-7Pk.js"),
	import("/docs/trackio/v0.36.0/en/_app/immutable/entry/app.BWp3UJuk.js")
	]).then(([kit, app]) => {
	kit.start(app, element, {
	node_ids: [0, 19],
	data: [null,null],
	form: null,
	error: null
	});
	});
	}
	</script>

Xet Storage Details

Size:: 65 kB
Xet hash:: a627406d44fb5ebdf69b91feacd309a86f638e8f18005629519d7126959f0ad5

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.