huggingface

Documentation

Index

• Constants
• func ListGGUF(ref string, out io.Writer) error
• func ListGGUFContext(ctx context.Context, ref string, out io.Writer) error
• func ListGGUFContextWithOptions(ctx context.Context, ref string, out io.Writer, opts Options) error
• func ParseHuggingFaceReference(value string) (hfReference, error)
• func PlaceGGUFFiles(files []string, destDir string) ([]string, error)
• func Repository(ref string) (string, error)
• func ResolveHuggingFaceModel(ref string, logw io.Writer) (string, error)
• func ResolveHuggingFaceModelContext(ctx context.Context, ref string, logw io.Writer) (string, error)
• func ResolveHuggingFaceModelContextWithOptions(ctx context.Context, ref string, logw io.Writer, options Options) (string, error)
• func ResolveHuggingFaceModelFilesContextWithOptions(ctx context.Context, ref string, logw io.Writer, options Options) ([]string, error)
• type GGUFOption
• type Options
  • func DefaultOptions() Options
• type ProgressEvent
• type ProgressFunc
• type RepositoryInfo
  • func RepositoryVariants(ctx context.Context, ref string, opts Options) (RepositoryInfo, error)
• type RepositoryVariant
• type SearchResult
  • func SearchGGUFRepositories(ctx context.Context, query string, limit int, opts Options) ([]SearchResult, error)

Constants

const (
	// DefaultSearchLimit keeps interactive Hub searches small enough to remain
	// responsive and considerate of the Hub API's rate limits.
	DefaultSearchLimit = 12
	// MaxSearchLimit prevents a single browser request from turning into an
	// unbounded Hub listing. Callers that need an exhaustive catalogue should
	// use the Hugging Face tools directly rather than the interactive API.
	MaxSearchLimit = 20
)

Functions

func ListGGUF

func ListGGUF(ref string, out io.Writer) error

ListGGUF writes the selectable GGUF variants in an HF repository. ref may be either owner/repository[@revision] or a regular hf: reference.

func ListGGUFContext

func ListGGUFContext(ctx context.Context, ref string, out io.Writer) error

ListGGUFContext is ListGGUF with cancellation support for callers that attach the operation to a request, CLI signal, or shutdown context.

func ListGGUFContextWithOptions

func ListGGUFContextWithOptions(ctx context.Context, ref string, out io.Writer, opts Options) error

ListGGUFContextWithOptions is ListGGUFContext with explicit network policy. In offline mode it lists only complete variants from the cached revision.

func ParseHuggingFaceReference

func ParseHuggingFaceReference(value string) (hfReference, error)

ParseHuggingFaceReference parses hf:owner/repository[:quant][@revision]. The quant selector is matched against GGUF filenames, for example hf:bartowski/Qwen3-4B-GGUF:Q4_K_M@main.

func PlaceGGUFFiles

func PlaceGGUFFiles(files []string, destDir string) ([]string, error)

PlaceGGUFFiles links (or, when linking is unavailable, copies) each resolved GGUF shard into destDir under its original filename, in the order given. This lets a host such as a web UI make a Hub download show up in a local model directory without duplicating storage whenever destDir shares a volume with the Hugging Face cache, using the same link-then-copy fallback ResolveHuggingFaceModelContextWithOptions already relies on for its own blobs-to-snapshot layout. Callers choose destDir; PlaceGGUFFiles performs no sanitization of it, so it must already be a path the caller trusts (for example, derived from a fixed model directory plus a flattened, single path-component name rather than an unvalidated repository string).

func Repository

func Repository(ref string) (string, error)

Repository returns the owner/repository portion of a Hugging Face reference, for callers that need to name a destination (for example, a local directory) after the source repository without duplicating ParseHuggingFaceReference's parsing rules.

func ResolveHuggingFaceModel

func ResolveHuggingFaceModel(ref string, logw io.Writer) (string, error)

ResolveHuggingFaceModel downloads (or reuses) the GGUF selected by ref and returns its local first-shard path. Files use Hugging Face's standard blobs/refs/snapshots layout, so Python, JavaScript, and GopherLLM share a single on-disk cache rather than downloading the same GGUF repeatedly.

func ResolveHuggingFaceModelContext

func ResolveHuggingFaceModelContext(ctx context.Context, ref string, logw io.Writer) (string, error)

ResolveHuggingFaceModelContext resolves and downloads a GGUF while honoring ctx. Cancellation stops repository listing, metadata requests, and any in-flight file transfer while preserving the partial blob for a later resume.

func ResolveHuggingFaceModelContextWithOptions

func ResolveHuggingFaceModelContextWithOptions(ctx context.Context, ref string, logw io.Writer, options Options) (string, error)

ResolveHuggingFaceModelContextWithOptions resolves a GGUF with an explicit network policy. Offline mode never contacts the Hub and requires a complete snapshot for the selected revision to be present in the local cache.

func ResolveHuggingFaceModelFilesContextWithOptions

func ResolveHuggingFaceModelFilesContextWithOptions(ctx context.Context, ref string, logw io.Writer, options Options) ([]string, error)

ResolveHuggingFaceModelFilesContextWithOptions is ResolveHuggingFaceModelContextWithOptions but returns every local shard path, in shard order, instead of only the first. Callers that only need a loadable model path should prefer ResolveHuggingFaceModelContextWithOptions; this variant exists for callers that must place the complete shard set somewhere else on disk (for example, linking a split model's files into a model directory for local discovery), since a split GGUF cannot be loaded from its first shard alone if the siblings are missing.

Types

type GGUFOption

type GGUFOption struct {
	File      string
	Quant     string
	SizeBytes int64
	Shards    int
}

GGUFOption is one downloadable model variant in a Hugging Face repository. Split files are presented as one option because GopherLLM always downloads the complete shard set needed to load them.

type Options

type Options struct {
	Offline bool
	// OnProgress, when set, receives periodic byte-progress updates for each
	// file transferred by a resolve/download call. It is throttled the same
	// way the textual logw progress line is (roughly 4 times per second) plus
	// one call at the start and end of each file, so a caller such as a web
	// UI can drive a progress bar without polling or parsing log text.
	OnProgress ProgressFunc
}

Options controls Hub operations without relying on a global HTTP transport. Offline mirrors Hugging Face's HF_HUB_OFFLINE convention: no Hub request is made and only complete snapshots already in the shared cache are considered.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions reads the Hugging Face-compatible offline setting. Explicit Options supplied by a host or the CLI can enable offline mode as well.

type ProgressEvent

type ProgressEvent struct {
	File      string
	Completed int64
	Total     int64
	Done      bool
	Err       error
}

ProgressEvent reports incremental progress for one file transferred from the Hub. Done is true exactly once per file, on the final event (whether it succeeded or failed; Err is set only on failure).

type ProgressFunc

type ProgressFunc func(ProgressEvent)

ProgressFunc receives ProgressEvents. It may be called from goroutines downloading different shards concurrently, so implementations that share mutable state must synchronize themselves.

type RepositoryInfo

type RepositoryInfo struct {
	Repository string
	Revision   string
	Variants   []RepositoryVariant
}

RepositoryInfo is the structured result of listing a Hugging Face repository's GGUF variants, for callers (such as a web UI) that want to render or filter the list themselves instead of the preformatted text ListGGUFContextWithOptions produces.

func RepositoryVariants

func RepositoryVariants(ctx context.Context, ref string, opts Options) (RepositoryInfo, error)

RepositoryVariants resolves the selectable GGUF variants in a Hugging Face repository reference (accepting the same owner/repository[:quant][@rev] forms as ListGGUF, with or without the "hf:" prefix) without downloading anything.

type RepositoryVariant

type RepositoryVariant struct {
	Quant     string
	SizeBytes int64
	Shards    int
	Selector  string
}

RepositoryVariant is one downloadable GGUF variant together with the exact selector ResolveHuggingFaceModelContextWithOptions (or ResolveHuggingFaceModelFilesContextWithOptions) accepts to fetch it.

type SearchResult

type SearchResult struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Downloads int64  `json:"downloads"`
	Likes     int64  `json:"likes"`
	UpdatedAt string `json:"updated_at"`
	GGUF      bool   `json:"gguf"`
	Private   bool   `json:"private"`
	Gated     bool   `json:"gated"`
}

SearchResult is the safe, small subset of a Hugging Face model record that the browser model picker needs. GGUF means the result came from the Hub's server-side GGUF filter; callers must still inspect variants before a download, because the repository tree is the authoritative file listing.

func SearchGGUFRepositories

func SearchGGUFRepositories(ctx context.Context, query string, limit int, opts Options) ([]SearchResult, error)

SearchGGUFRepositories finds a small, download-sorted set of public or authenticated Hugging Face model repositories matching query. It performs exactly one Hub API request, respects ctx while waiting or reading, and never follows pagination. The returned repositories are GGUF-filtered by the Hub; use RepositoryVariants before offering a concrete download.

A limit of zero selects DefaultSearchLimit. All other limits must be in [1, MaxSearchLimit]. Search is intentionally unavailable in offline mode: a local model cache has no repository search index.