model-hf

Hugging Face Hub repository and cache adapter for model artifact resolution.

model-hf is the concrete model-artifact::ModelRepository implementation backed by the huggingface-hub Rust client. It resolves revisions, lists model repo files, downloads selected artifacts, and recognizes model identity from paths inside the local Hugging Face cache.

Architecture Role

The pure identity and selection crates stay registry-agnostic. This crate owns the Hugging Face edge: endpoint, token, cache layout, repo metadata, downloads, and cache path identity recovery.

flowchart TB
    C["caller<br/>mesh resolver<br/>skippy-model-package<br/>runtime package loader"] --> H["HfModelRepository"]
    H --> API["Hugging Face Hub API<br/>repo info + siblings"]
    H --> Cache["local HF cache<br/>snapshots/revision/file"]
    API --> A["model-artifact<br/>resolve_model_artifact"]
    A --> H
    H --> D["downloaded artifact paths"]
    Cache --> I["HfModelIdentity<br/>repo, revision, file"]
    I --> Mesh["mesh model status<br/>full ref ids"]

Configuration

HfModelRepository::from_env() follows the usual Hugging Face environment:

HF_ENDPOINT
HF_TOKEN
HUGGING_FACE_HUB_TOKEN
HF_HUB_CACHE
HUGGINGFACE_HUB_CACHE
HF_HOME
XDG_CACHE_HOME

Use HfModelRepository::builder() to override the cache directory, endpoint, or token explicitly in tests and embedding applications.

Responsibilities

• resolve branch/tag names to immutable Hugging Face revisions
• list model repository files at a resolved revision
• download the selected artifact file set
• locate the default Hugging Face cache directory
• derive HfModelIdentity and ModelIdentity from cached snapshot paths

Keep artifact ranking in model-artifact, public reference parsing in model-ref, and stage materialization in skippy-runtime or skippy-model-package.

If a path is inside the Hugging Face cache, this crate recovers the repo, revision, and selected file so mesh can continue advertising the full model ref instead of a GGUF basename.