v2026.11.2
All Bundles
Bundle

Model downloads from the Hugging Face Hub, into a local cache that later runs, and offline runs, read from: a model by name, as Python's from_pretrained does, with no Python. Compile with -lib gen_collect,cipher,json,net,ai_hub.

HubClient

Downloads files of a Hugging Face model repository into a local cache and gives back their paths: a snapshot folder that TextClassifier and the other pipelines open as they open any model folder.

Each call asks the Hub API which commit the revision ("main" unless named) is at, and downloads from that commit, so every file of a snapshot comes from the same commit. A file already in the cache at the right size is not downloaded again. A downloaded file is checked before it is kept: SHA-256 for a large (LFS) file, the git blob hash for a small one, and the size for both; a file that does not match is deleted and the call fails. Downloads stream to disk, so a file's size is limited only by the disk.

The cache, by environment:

- OBJECK_HUB_CACHE: the cache folder; default .objeck/hub in the user's home folder. The layout is the one Python's huggingface_hub uses -- models--org--name/refs/main holds the commit, models--org--name/snapshots/commit/ the files -- with real files, not symbolic links; - OBJECK_HUB_OFFLINE or HF_HUB_OFFLINE set to 1: no network at all; revisions resolve through the cache's refs. Offline, and when the Hub cannot be reached, a file the cache does not hold is looked for in Python's cache (HF_HUB_CACHE, else HF_HOME/hub, else .cache/huggingface/hub in the home folder), which is read and never written; - OBJECK_HUB_TOKEN or HF_TOKEN: a token for gated and private repositories. It is sent to the Hub only: a redirect to another origin, such as the Hub's file CDN, drops it; - HF_ENDPOINT: another Hub, e.g. a mirror; default https://huggingface.co.

Example

hub := HubClient->New();
folder := hub->Snapshot("Xenova/distilbert-base-uncased-finetuned-sst-2-english",
  ["config.json", "tokenizer.json", "tokenizer_config.json", "onnx/model.onnx"]);
if(folder = Nil) {
  hub->GetError()->ErrorLine();
  return;
};
folder->PrintLine();   # .../models--Xenova--distilbert-.../snapshots/0b6928ef...

Operations

Download #

Downloads one file of a repository at "main".

method : public : Download(repo:String, file:String) ~ String

Parameters

NameTypeDescription
repoStringthe repository, e.g. Xenova/bert-base-uncased
fileStringthe file's path in the repository, e.g. onnx/model.onnx

Return

TypeDescription
Stringthe file's path in the cache; Nil on failure (see GetError)

Download #

Downloads one file of a repository at a revision.

method : public : Download(repo:String, file:String, revision:String) ~ String

Parameters

NameTypeDescription
repoStringthe repository, e.g. Xenova/bert-base-uncased
fileStringthe file's path in the repository, e.g. onnx/model.onnx
revisionStringa branch, tag or commit

Return

TypeDescription
Stringthe file's path in the cache; Nil on failure (see GetError)

GetCacheDir #

The cache folder.

method : public : GetCacheDir() ~ String

Return

TypeDescription
Stringpath

GetCommit #

The commit the last Snapshot or Download used.

method : public : GetCommit() ~ String

Return

TypeDescription
Stringa 40-character commit hash, or Nil

GetDownloadCount #

How many files the last Snapshot or Download fetched from the network; the rest came from the cache.

method : public : GetDownloadCount() ~ Int

Return

TypeDescription
Intfiles downloaded

GetEndpoint #

The Hub's address.

method : public : GetEndpoint() ~ String

Return

TypeDescription
Stringe.g. https://huggingface.co

GetError #

Why the last call returned Nil.

method : public : GetError() ~ String

Return

TypeDescription
Stringthe reason, or Nil

IsOffline #

Whether the client works from the cache alone.

method : public : IsOffline() ~ Bool

Return

TypeDescription
Booltrue when offline

New # constructor

A client with the cache, token, endpoint and offline mode from the environment.

New()

New # constructor

A client with a cache folder of the caller's; token, endpoint and offline mode from the environment.

New(cache_dir:String)

Parameters

NameTypeDescription
cache_dirStringthe cache folder

SetEndpoint #

Sets the Hub's address, e.g. a mirror.

method : public : SetEndpoint(endpoint:String) ~ Nil

Parameters

NameTypeDescription
endpointStringe.g. https://huggingface.co

SetOffline #

Sets whether the client works from the cache alone.

method : public : SetOffline(offline:Bool) ~ Nil

Parameters

NameTypeDescription
offlineBooltrue for no network

SetToken #

Sets the token sent to the Hub for gated and private repositories; Nil sends none.

method : public : SetToken(token:String) ~ Nil

Parameters

NameTypeDescription
tokenStringthe token

Snapshot #

Downloads files of a repository at "main" into one snapshot folder.

method : public : Snapshot(repo:String, files:String[]) ~ String

Parameters

NameTypeDescription
repoStringthe repository, e.g. Xenova/bert-base-uncased
filesStringthe files' paths in the repository

Return

TypeDescription
Stringthe snapshot folder; Nil on failure (see GetError)

Snapshot #

Downloads files of a repository at a revision into one snapshot folder. Every file comes from the commit the revision is at when the call is made.

method : public : Snapshot(repo:String, files:String[], revision:String) ~ String

Parameters

NameTypeDescription
repoStringthe repository, e.g. Xenova/bert-base-uncased
filesStringthe files' paths in the repository
revisionStringa branch, tag or commit

Return

TypeDescription
Stringthe snapshot folder; Nil on failure (see GetError)