huggingface

README

huggingface

A small, dependency-free Go client for the Hugging Face Hub API. It returns HF-native types (ModelInfo, Safetensors, gated status, …) and does nothing clever — search the Hub and fetch model metadata, no third-party dependencies.

• Stdlib-only. No dependencies to vet.
• Configurable via options: custom *http.Client, base URL, user agent.
• HF-native types. No opinionated remapping — you get the Hub's own fields.

Install

go get github.com/getotium/huggingface

Usage

c := huggingface.New()

// Search the Hub.
models, err := c.Search(ctx, huggingface.SearchOptions{Search: "qwen", Limit: 20})

// Page through results.
page, cursor, err := c.SearchPage(ctx, huggingface.SearchOptions{Search: "gemma"})

// Fetch one model's metadata (parameters, dtype, gated status, safetensors shard info…).
info, err := c.Model(ctx, "Qwen/Qwen2.5-7B-Instruct")

Options:

c := huggingface.New(
    huggingface.WithHTTPClient(myClient),
    huggingface.WithUserAgent("my-app/1.0"),
)

Provenance

Extracted from Otium, where it powers model discovery for the inference catalog. Kept deliberately generic (Hub API only — no VRAM math or catalog mapping), so it's a clean, reusable primitive.

License

Apache-2.0.

Documentation

Overview

Package huggingface is a small, dependency-free client for the Hugging Face Hub API (https://huggingface.co/api). It exposes model search and per-model lookup and returns Hub-native types — it knows nothing about any particular application's domain (no model catalogs, VRAM math, or instance types here).

It is intentionally self-contained (standard library only) so it can be lifted into a shared toolkit or its own repository unchanged. Construct a Client with New and functional options; the base URL, HTTP client, and User-Agent are all injectable so callers can point it at a test server and identify themselves as good API citizens.

Index

• Constants
• Variables
• type Client
  • func New(opts ...Option) *Client
  • func (c *Client) Model(ctx context.Context, id string) (ModelInfo, error)
  • func (c *Client) Search(ctx context.Context, opts SearchOptions) ([]ModelInfo, error)
  • func (c *Client) SearchPage(ctx context.Context, opts SearchOptions) ([]ModelInfo, string, error)
• type Gated
  • func (g Gated) IsGated() bool
  • func (g *Gated) UnmarshalJSON(b []byte) error
• type ModelInfo
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithUserAgent(ua string) Option
• type Safetensors
  • func (s *Safetensors) DominantDtype() string
• type SearchOptions

Constants

const DefaultBaseURL = "https://huggingface.co"

DefaultBaseURL is the public Hugging Face Hub.

Variables

var (
	// ErrNotFound is returned when a model id does not exist (HTTP 404).
	ErrNotFound = errors.New("huggingface: not found")
	// ErrRateLimited is returned when the Hub asks us to slow down (HTTP 429).
	ErrRateLimited = errors.New("huggingface: rate limited")
)

Sentinel errors callers can match with errors.Is.

Types

type Client

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

Client talks to the Hugging Face Hub API. It is safe for concurrent use.

func New

func New(opts ...Option) *Client

New constructs a Client. With no options it targets the public Hub with a 15s timeout and the library's default User-Agent.

func (*Client) Model

func (c *Client) Model(ctx context.Context, id string) (ModelInfo, error)

Model returns a single model by id (GET /api/models/{id}), including its safetensors parameter counts when available. Returns ErrNotFound if the id does not exist.

func (*Client) Search

func (c *Client) Search(ctx context.Context, opts SearchOptions) ([]ModelInfo, error)

Search returns models matching opts (GET /api/models). It is the cursor-less convenience wrapper over SearchPage; use SearchPage to paginate.

func (*Client) SearchPage

func (c *Client) SearchPage(ctx context.Context, opts SearchOptions) ([]ModelInfo, string, error)

SearchPage returns one page of models matching opts along with the cursor for the next page ("" when the listing is exhausted). Pass the returned cursor back in SearchOptions.Cursor to continue. The Hub paginates via an RFC 5988 Link header.

type Gated

type Gated string

Gated captures the Hub's polymorphic "gated" field, which is either the JSON boolean false (open) or a string mode ("auto"/"manual") for gated repos. It unmarshals both into a string: "" means open, otherwise the mode.

func (Gated) IsGated

func (g Gated) IsGated() bool

IsGated reports whether the repo requires access approval.

func (*Gated) UnmarshalJSON

func (g *Gated) UnmarshalJSON(b []byte) error

UnmarshalJSON accepts either a bool or a string.

type ModelInfo

type ModelInfo struct {
	ID           string       `json:"id"`
	SHA          string       `json:"sha"` // the repo's current commit hash — pin this for reproducible pulls
	Author       string       `json:"author"`
	PipelineTag  string       `json:"pipeline_tag"`
	LibraryName  string       `json:"library_name"`
	Gated        Gated        `json:"gated"`
	Downloads    int          `json:"downloads"`
	Likes        int          `json:"likes"`
	CreatedAt    time.Time    `json:"createdAt"`
	LastModified time.Time    `json:"lastModified"`
	Tags         []string     `json:"tags"`
	Safetensors  *Safetensors `json:"safetensors"`
}

ModelInfo is a model record as returned by the Hub. Fields not requested or not applicable to a given endpoint are zero (notably Safetensors is nil on the search list endpoint; fetch a single model to populate it).

type Option

type Option func(*Client)

Option configures a Client.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL overrides the API base URL (default DefaultBaseURL). Trailing slashes are trimmed.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the underlying HTTP client (e.g. to inject a timeout, transport, or a test server's client).

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header. Identifying your application is good Hub etiquette and helps the maintainers reach you if your traffic misbehaves.

type Safetensors

type Safetensors struct {
	Total      int64            `json:"total"`
	Parameters map[string]int64 `json:"parameters"`
}

Safetensors describes a model's parameter counts as reported by the Hub's safetensors metadata. Total is the overall parameter count; Parameters breaks it down by tensor dtype (e.g. {"BF16": 8190735360}).

func (*Safetensors) DominantDtype

func (s *Safetensors) DominantDtype() string

DominantDtype returns the dtype holding the most parameters (e.g. "BF16"), or "" if unknown. It is the dtype a caller would assume for a size estimate.

type SearchOptions

type SearchOptions struct {
	Search      string   // free-text query
	Author      string   // restrict to an author/org
	PipelineTag string   // e.g. "text-generation"
	Filter      string   // tag filter, e.g. "gguf"
	Sort        string   // e.g. "downloads", "likes", "trendingScore", "createdAt"
	Direction   int      // -1 descending, 1 ascending; 0 omits
	Limit       int      // max results; 0 omits
	Full        bool     // request full metadata
	Expand      []string // request specific fields via expand[]=; e.g. "safetensors", "tags".
	// Note: the Hub treats Expand as mutually exclusive with Full — when expand[] is
	// present, full is ignored and only the listed fields (plus id) are returned.
	Cursor string // pagination token from a prior page's Link header; "" for the first page
}

SearchOptions parameterizes a model search. Zero-value fields are omitted from the request, yielding the Hub's defaults.