Model Hub Reference¶

Nomad can download and cache model weights from various sources. Config files use the name_or_path field to choose the source.

Name	Example
Local directory URI	`file:models/my-model`
Hugging Face URI	`hf://my-org/my-model`
ORAS artifact	`oras://registry.example.org/my-org/my-model:v1`
Git/Git LFS HTTPS URI	`git+https://example.org/my-org/models.git@main`
Git/Git LFS SSH URI	`git+ssh://git@example.org/my-org/models.git@main`
Local path[1]	`models/my-model`
Hugging Face repo ID[1]	`my-org/my-model`
Plain HTTPS Git URL[2]	`https://example.org/my-org/models.git@main`
SCP-style Git URL[2]	`git@example.org:my-org/models.git@main`

Nomad resolves mutable remote sources, downloads them into a local cache, and reuses cached artifacts across runs. Add #path/to/dir to any source when the model files live in a subdirectory.

The Python API for these sources is nomad.hub.RepoSpec. Use RepoSpec.resolved().uri() or RepoSpec.lock(...) when application code needs a pinned URI for a remote source.

nomad.hub.looks_like_digest(value)¶

Return True when value looks like a bare or algorithm-prefixed digest.

Parameters:: value (str)
Return type:: bool

nomad.hub.get_cache_root()¶

Return the cache root, honoring XDG conventions or defaulting to ~/.cache.

Return type:: pathlib.Path

class nomad.hub.OrasRegistry(hostname=None, insecure=False, tls_verify=True, auth_backend='token')¶

ORAS registry client that refreshes stale bearer tokens after scope changes.

Parameters:

hostname (str | None)
insecure (bool)
tls_verify (bool | str)
auth_backend (str)

load_auth_config(target, *, config_path=None)¶

Parameters:: config_path (str | None)

push(target, *args, config_path=None, do_chunked=True, **kwargs)¶

Push a set of files to a target

Parameters:

config_path (str) – path to a config file
disable_path_validation (bool) – ensure paths are relative to the running directory.
files (list) – list of files to push
insecure (bool) – allow registry to use http
annotation_file (str) – manifest annotations file
manifest_annotations (dict) – manifest annotations
target (str) – target location to push to
do_chunked (bool) – if true do chunked blob upload
chunk_size (int) – chunk size in bytes
subject (oras.oci.Subject) – optional subject reference

pull(target, *args, config_path=None, **kwargs)¶

Pull an artifact from a target

Parameters:

config_path (str) – path to a config file
allowed_media_type (list or None) – list of allowed media types
overwrite (bool) – if output file exists, overwrite
manifest_config_ref (str) – save manifest config to this file
outdir (str) – output directory path
target (str) – target location to pull from

request(target, url, method='GET', *, config_path=None, data=None, headers=None, json=None, stream=False)¶

Parameters:

target (str)
url (str)
method (str)
config_path (str | None)
headers (dict | None)
stream (bool)

do_request(url, method='GET', data=None, headers=None, json=None, stream=False)¶

Do a request. This is a wrapper around requests to handle retry auth.

Parameters:

url (str) – the URL to issue the request to
method (str) – the method to use (GET, DELETE, POST, PUT, PATCH)
data (dict or bytes) – data for requests
headers (dict) – headers for the request
json (dict) – json data for requests
stream (bool) – stream the responses

nomad.hub.run(cmd, cwd=None, capture=False, env=None)¶

Execute a subprocess, exiting the interpreter if the command fails.

Parameters:

cmd (list[str])
cwd (TypeAliasForwardRef('pathlib.Path') | None)
capture (bool)
env (dict[str, str] | None)

Return type:

str

nomad.hub.check_dependencies()¶

Ensure required git tooling is available, exiting with a helpful message.

Return type:: None

class nomad.hub.RepoSpec(scheme, location, reference=None, subpath=None)¶

Normalized model-weight source URI with download and cache behavior.

Parameters:

scheme (str)
location (str)
reference (str | None)
subpath (str | None)

scheme: str¶

location: str¶

reference: str | None = None¶

subpath: str | None = None¶

classmethod can_parse(spec, *, base_dir=None)¶

Return True when the input can be normalized into a RepoSpec.

Parameters:

spec (str)
base_dir (TypeAliasForwardRef('pathlib.Path') | None)

Return type:

bool

classmethod parse(spec, *, base_dir=None)¶

Normalize a model source string into a RepoSpec.

Missing schemes are treated as local files when the path exists and as Hugging Face model IDs otherwise.

Parameters:

spec (str)
base_dir (TypeAliasForwardRef('pathlib.Path') | None)

Return type:

RepoSpec

classmethod normalize(spec, *, base_dir=None)¶

Return a canonical model source URI for supported shorthand inputs.

Parameters:

spec (str)
base_dir (TypeAliasForwardRef('pathlib.Path') | None)

Return type:

str

property is_remote: bool¶: Return True for sources that can be left remote in exported configs.

name()¶

Return a human-readable name suitable for exported model directories.

Return type:: str

uri(*, base_dir=None)¶

Render this source as a canonical URI without resolving remote refs.

Parameters:: base_dir (TypeAliasForwardRef('pathlib.Path') | None)
Return type:: str

resolved()¶

Return this source with mutable remote refs resolved where applicable.

Return type:: RepoSpec

classmethod lock(spec, *, base_dir=None)¶

Return spec pinned to its current remote revision.

Parameters:

spec (str)
base_dir (TypeAliasForwardRef('pathlib.Path') | None)

Return type:

str

as_https()¶

Return a copy that uses HTTPS transport when the scheme supports it.

Return type:: RepoSpec

classmethod to_https_spec(spec, *, base_dir=None)¶

Return spec rewritten to HTTPS transport when possible.

Parameters:

spec (str)
base_dir (TypeAliasForwardRef('pathlib.Path') | None)

Return type:

str

pull()¶

Return a local path containing this source, using the cache if needed.

Return type:: pathlib.Path

push(source)¶

Push source to this destination and return the exported spec.

Parameters:: source (pathlib.Path)
Return type:: RepoSpec

repo_key()¶

Return a stable cache key based on the source identity.

Return type:: str

cache_digest()¶

Return the resolved cache version for this source.

Return type:: str

cache_dir()¶

Return the cache directory for the resolved source.

Return type:: pathlib.Path

class nomad.hub.FileRepoSpec(scheme, location, reference=None, subpath=None)¶

Local filesystem model-weight source.

Parameters:

scheme (str)
location (str)
reference (str | None)
subpath (str | None)

property is_remote: bool¶: Return True for sources that can be left remote in exported configs.

name()¶

Return a human-readable name suitable for exported model directories.

Return type:: str

as_https()¶

Return a copy that uses HTTPS transport when the scheme supports it.

Return type:: RepoSpec

uri(*, base_dir=None)¶

Render this source as a canonical URI without resolving remote refs.

Parameters:: base_dir (TypeAliasForwardRef('pathlib.Path') | None)
Return type:: str

pull()¶

Return a local path containing this source, using the cache if needed.

Return type:: pathlib.Path

push(source)¶

Push source to this destination and return the exported spec.

Parameters:: source (pathlib.Path)
Return type:: RepoSpec

class nomad.hub.HuggingFaceRepoSpec(scheme, location, reference=None, subpath=None)¶

Hugging Face model repository source.

Parameters:

scheme (str)
location (str)
reference (str | None)
subpath (str | None)

property is_remote: bool¶: Return True for sources that can be left remote in exported configs.

name()¶

Return a human-readable name suitable for exported model directories.

Return type:: str

as_https()¶

Return a copy that uses HTTPS transport when the scheme supports it.

Return type:: RepoSpec

uri(*, base_dir=None)¶

Render this source as a canonical URI without resolving remote refs.

Parameters:: base_dir (TypeAliasForwardRef('pathlib.Path') | None)
Return type:: str

resolved()¶

Return this source with mutable remote refs resolved where applicable.

Return type:: RepoSpec

cache_digest()¶

Return the resolved Hugging Face revision used as the cache version.

Return type:: str

pull()¶

Download or reuse a Hugging Face snapshot and return its local path.

Return type:: pathlib.Path

class nomad.hub.GitRepoSpec(scheme, location, reference=None, subpath=None)¶

Git/Git LFS repository model-weight source.

Parameters:

scheme (str)
location (str)
reference (str | None)
subpath (str | None)

property is_remote: bool¶: Return True for sources that can be left remote in exported configs.

name()¶

Return a human-readable name suitable for exported model directories.

Return type:: str

as_https()¶

Return a copy that uses HTTPS transport when the scheme supports it.

Return type:: RepoSpec

uri(*, base_dir=None)¶

Render this source as a canonical URI without resolving remote refs.

Parameters:: base_dir (TypeAliasForwardRef('pathlib.Path') | None)
Return type:: str

resolved()¶

Return this source with mutable remote refs resolved where applicable.

Return type:: RepoSpec

repo_key()¶

Return a stable cache key based on the repository or artifact URL.

Return type:: str

cache_digest()¶

Return the resolved commit used as this source’s cache version.

Return type:: str

pull()¶

Clone or reuse a cached git repository and return its path.

Return type:: pathlib.Path

class nomad.hub.OrasRepoSpec(scheme, location, reference=None, subpath=None)¶

ORAS artifact model-weight source.

Parameters:

scheme (str)
location (str)
reference (str | None)
subpath (str | None)

property is_remote: bool¶: Return True for sources that can be left remote in exported configs.

name()¶

Return a human-readable name suitable for exported model directories.

Return type:: str

as_https()¶

Return a copy that uses HTTPS transport when the scheme supports it.

Return type:: RepoSpec

uri(*, base_dir=None)¶

Render this source as a canonical URI without resolving remote refs.

Parameters:: base_dir (TypeAliasForwardRef('pathlib.Path') | None)
Return type:: str

resolved()¶

Return this source with mutable remote refs resolved where applicable.

Return type:: RepoSpec

repo_key()¶

Return a stable cache key based on the artifact repository URL.

Return type:: str

cache_digest()¶

Return the resolved digest used as this source’s cache version.

Return type:: str

pull()¶

Pull or reuse a cached ORAS artifact and return its path.

Return type:: pathlib.Path

push(source)¶

Push a local model directory and return a digest-pinned ORAS spec.

Parameters:: source (pathlib.Path)
Return type:: RepoSpec