huggingface

Documentation

Overview

Package huggingface provides HuggingFace model configuration parsing.

Stability: beta

Index

• func CacheDir() (string, error)
• func FormatProgress(filename string, downloaded, total int64) string
• func ManifestPath() (string, error)
• func SaveManifest(m *CacheManifest) error
• type CacheManifest
  • func LoadManifest() (*CacheManifest, error)
  • func (m *CacheManifest) Add(model CachedModel)
  • func (m *CacheManifest) FindByRepo(repoID string) (*CachedModel, bool)
  • func (m *CacheManifest) FindByRepoAndFile(repoID, filename string) (*CachedModel, bool)
  • func (m *CacheManifest) List() []CachedModel
  • func (m *CacheManifest) Remove(path string) error
• type CachedModel
• type Client
  • func NewClient() *Client
  • func (c *Client) GetModel(id string) (*ModelInfo, error)
  • func (c *Client) ListGGUFFiles(id string) ([]FileInfo, error)
  • func (c *Client) ResolveGGUF(id string, quant string) (*FileInfo, error)
• type DownloadOption
  • func WithProgress(fn func(downloaded, total int64)) DownloadOption
  • func WithSHA256(hexDigest string) DownloadOption
• type Downloader
  • func NewDownloader(httpClient *http.Client) *Downloader
  • func (d *Downloader) Download(ctx context.Context, url, destPath string, opts ...DownloadOption) error
• type FileInfo
• type ModelInfo

Functions

func CacheDir

func CacheDir() (string, error)

CacheDir returns the directory where model files are stored (~/.cache/zerfoo/models/).

func FormatProgress

func FormatProgress(filename string, downloaded, total int64) string

FormatProgress returns a human-readable progress string suitable for stderr.

func ManifestPath

func ManifestPath() (string, error)

ManifestPath returns the path to the manifest JSON file (~/.cache/zerfoo/manifest.json).

func SaveManifest

func SaveManifest(m *CacheManifest) error

SaveManifest writes the manifest atomically using a temp file and rename.

Types

type CacheManifest

type CacheManifest struct {
	Models []CachedModel `json:"models"`
}

CacheManifest tracks downloaded models.

func LoadManifest

func LoadManifest() (*CacheManifest, error)

LoadManifest reads the manifest from disk. Returns an empty manifest if the file does not exist.

func (*CacheManifest) Add

func (m *CacheManifest) Add(model CachedModel)

Add adds or updates a model entry (upsert by path).

func (*CacheManifest) FindByRepo

func (m *CacheManifest) FindByRepo(repoID string) (*CachedModel, bool)

FindByRepo finds the first cached model matching the given repo ID.

func (*CacheManifest) FindByRepoAndFile

func (m *CacheManifest) FindByRepoAndFile(repoID, filename string) (*CachedModel, bool)

FindByRepoAndFile finds a cached model by repo ID and filename.

func (*CacheManifest) List

func (m *CacheManifest) List() []CachedModel

List returns all cached models.

func (*CacheManifest) Remove

func (m *CacheManifest) Remove(path string) error

Remove removes a model entry by path and deletes the file from disk. Returns an error if the entry is not found.

type CachedModel

type CachedModel struct {
	RepoID   string    `json:"repo_id"`
	Filename string    `json:"filename"`
	Path     string    `json:"path"`
	Size     int64     `json:"size"`
	SHA256   string    `json:"sha256,omitempty"`
	AddedAt  time.Time `json:"added_at"`
}

CachedModel is one entry in the cache.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a HuggingFace API client.

func NewClient

func NewClient() *Client

NewClient creates a new client. Reads HF_TOKEN from environment.

func (*Client) GetModel

func (c *Client) GetModel(id string) (*ModelInfo, error)

GetModel fetches metadata for a model repository.

func (*Client) ListGGUFFiles

func (c *Client) ListGGUFFiles(id string) ([]FileInfo, error)

ListGGUFFiles returns all .gguf files in a repository.

func (*Client) ResolveGGUF

func (c *Client) ResolveGGUF(id string, quant string) (*FileInfo, error)

ResolveGGUF finds the best GGUF file for the requested quantization. quant examples: "Q4_K_M", "Q8_0", "F16". Case-insensitive. Returns the first matching file, preferring exact match then prefix match. Returns error if no match found.

type DownloadOption

type DownloadOption func(*downloadOptions)

DownloadOption configures the behavior of Download.

func WithProgress

func WithProgress(fn func(downloaded, total int64)) DownloadOption

WithProgress sets a callback that is invoked periodically with byte counts.

func WithSHA256

func WithSHA256(hexDigest string) DownloadOption

WithSHA256 sets the expected SHA256 hex digest for post-download verification.

type Downloader

type Downloader struct {
	// contains filtered or unexported fields
}

Downloader handles GGUF file downloads with resume support.

func NewDownloader

func NewDownloader(httpClient *http.Client) *Downloader

NewDownloader creates a Downloader using the given HTTP client.

func (*Downloader) Download

func (d *Downloader) Download(ctx context.Context, url, destPath string, opts ...DownloadOption) error

Download downloads a file from url to destPath. It supports resume via HTTP Range if a partial file exists at destPath.partial. The file is written with a .partial suffix during download and renamed on completion.

type FileInfo

type FileInfo struct {
	Filename string
	Size     int64
}

FileInfo holds metadata about a single file in a repository.

type ModelInfo

type ModelInfo struct {
	ID    string
	Files []FileInfo
}

ModelInfo holds metadata about a HuggingFace model repository.