Hf

Resolve and download Hugging Face GGUF models for the `-hf` CLI flag.

Turns an `owner/repo[:quant]` spec into an installed GGUF in the managed model cache, resolving the concrete file name via the Hugging Face `/v2/<repo>/manifests/<tag>` endpoint and reusing the managed download pipeline for transfer, staging, and manifest bookkeeping.

4 exports 0 methods src/model/hf.zig

4 exports shown

struct

Spec

pub const Spec = struct

Parsed `-hf` argument: a Hugging Face repo plus a quantization tag.

src/model/hf.zig:36

function

parseSpec

pub fn parseSpec(text: []const u8) !Spec

Parses an `-hf` argument of the form `owner/repo[:quant]`.

The quantization suffix is optional; when absent the tag defaults to `latest`, which the Hugging Face manifest endpoint resolves to the repo's recommended quantization. Each component (owner, repo, tag) must match the Hugging Face naming grammar; anything else fails with `error.InvalidHfSpec`.

Parameters

text: Raw CLI argument value.

Returns

A `Spec` whose slices point into `text`.

src/model/hf.zig:53

function

cacheId

pub fn cacheId(allocator: std.mem.Allocator, spec: Spec) ![]u8

Derives the managed-cache model id for a Hugging Face spec.

The id is a single filesystem-safe path component so the download can live in the same `<cache_root>/models/<id>/model.gguf` layout as catalog models. Distinct specs map to distinct ids; `:latest` is cached separately from an explicit quantization even if both resolve to the same upstream file.

Parameters

allocator: Owns the returned id slice.
spec: Parsed Hugging Face spec.

Returns

Heap-allocated id like `hf--unsloth--qwen3.5-9b-gguf--q4_k_m`.

src/model/hf.zig:100

function

ensureModel

pub fn ensureModel(spec_text: []const u8, allocator: std.mem.Allocator, writer: anytype) ![]u8

Ensures the model described by an `-hf` spec is installed and returns its path.

If the spec is already cached the installed path is returned without any network access. Otherwise the GGUF file name and sha256 digest are resolved via the Hugging Face manifest endpoint and the file is downloaded through the managed pull pipeline (staged `.partial` file, progress bar, manifest write), which verifies the download against the pinned digest when the manifest provides one. quantizations with no kernels (`error.UnsupportedQuantization`, detected from the tag and the resolved file name) and architectures the loader does not recognise (`error.UnsupportedArchitecture`, detected from repo metadata when available).

Parameters

spec_text: Raw `-hf` argument (`owner/repo[:quant]`).
allocator: Used for HTTP, path construction, and the returned path.
writer: Receives human-readable status lines and download progress.

Returns

Heap-allocated absolute path to the installed GGUF; caller owns it.

Notes

Models zinc cannot run are rejected before the download starts:

Gated or private repos are not supported: they fail with `error.HfAuthRequired`.

src/model/hf.zig:130