registry

Documentation

Overview

Package registry provides a model registry with local cache, pull, get, list, and delete operations.

Stability: stable

Index

• Constants
• type Descriptor
• type HFModelInfo
• type HFPullOptions
• type HFSibling
• type LocalRegistry
  • func NewLocalRegistry(cacheDir string) (*LocalRegistry, error)
  • func (r *LocalRegistry) CacheDir() string
  • func (r *LocalRegistry) Delete(modelID string) error
  • func (r *LocalRegistry) Get(modelID string) (*ModelInfo, bool)
  • func (r *LocalRegistry) List() []ModelInfo
  • func (r *LocalRegistry) Pull(ctx context.Context, modelID string) (*ModelInfo, error)
  • func (r *LocalRegistry) SetPullFunc(fn PullFunc)
• type Manifest
• type ModelConfig
• type ModelInfo
• type ModelRegistry
• type Option
  • func WithCredentials(username, password string) Option
  • func WithHTTPClient(client *http.Client) Option
• type ProgressFunc
• type PullFunc
  • func NewHFPullFunc(opts HFPullOptions) PullFunc
• type Reference
• type Registry
  • func NewRegistry(url string, opts ...Option) *Registry
  • func (r *Registry) Pull(ctx context.Context, ref string, destPath string) error
  • func (r *Registry) Push(ctx context.Context, ref string, modelPath string) error
  • func (r *Registry) Resolve(ctx context.Context, ref string) (*Manifest, error)
  • func (r *Registry) Tags(ctx context.Context, repo string) ([]string, error)
• type TagList

Constants

const (
	// MediaTypeGGUF is the media type for GGUF model files.
	MediaTypeGGUF = "application/vnd.zerfoo.model.gguf.v1"
	// MediaTypeModelConfig is the media type for model configuration.
	MediaTypeModelConfig = "application/vnd.zerfoo.model.config.v1+json"
	// MediaTypeOCIManifest is the standard OCI image manifest media type.
	MediaTypeOCIManifest = "application/vnd.oci.image.manifest.v1+json"
)

OCI distribution spec media types.

Types

type Descriptor

type Descriptor struct {
	MediaType string `json:"mediaType"`
	Digest    string `json:"digest"`
	Size      int64  `json:"size"`
}

Descriptor describes an OCI content-addressable blob.

type HFModelInfo

type HFModelInfo struct {
	ID       string      `json:"id"`
	Siblings []HFSibling `json:"siblings"`
}

HFModelInfo represents the model metadata returned by the HuggingFace API.

type HFPullOptions

type HFPullOptions struct {
	// APIURL overrides the HuggingFace API endpoint.
	APIURL string
	// CDNURL overrides the HuggingFace CDN endpoint.
	CDNURL string
	// Token is an optional HuggingFace API token for gated models.
	Token string
	// Quant selects a specific GGUF quantization (e.g. "Q4_K_M", "Q8_0").
	// When set, only the matching GGUF file is downloaded instead of all model files.
	// Default: "Q4_K_M".
	Quant string
	// OnProgress is called during file downloads.
	OnProgress ProgressFunc
	// Client overrides the HTTP client used for downloads.
	Client *http.Client
}

HFPullOptions configures HuggingFace model downloads.

type HFSibling

type HFSibling struct {
	Filename string `json:"rfilename"`
}

HFSibling represents a file entry in a HuggingFace model listing.

type LocalRegistry

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

LocalRegistry implements ModelRegistry with a local filesystem cache. Cache layout: <cacheDir>/<org>/<model>/ containing model.zmf, tokenizer.json, config.json.

func NewLocalRegistry

func NewLocalRegistry(cacheDir string) (*LocalRegistry, error)

NewLocalRegistry creates a LocalRegistry with the given cache directory. If cacheDir is empty, it defaults to ~/.zerfoo/models/.

func (*LocalRegistry) CacheDir

func (r *LocalRegistry) CacheDir() string

CacheDir returns the path to the local model cache directory.

func (*LocalRegistry) Delete

func (r *LocalRegistry) Delete(modelID string) error

Delete removes a locally cached model.

func (*LocalRegistry) Get

func (r *LocalRegistry) Get(modelID string) (*ModelInfo, bool)

Get returns a locally cached model by ID.

func (*LocalRegistry) List

func (r *LocalRegistry) List() []ModelInfo

List returns all locally cached models.

func (*LocalRegistry) Pull

func (r *LocalRegistry) Pull(ctx context.Context, modelID string) (*ModelInfo, error)

Pull downloads a model and caches it locally.

func (*LocalRegistry) SetPullFunc

func (r *LocalRegistry) SetPullFunc(fn PullFunc)

SetPullFunc sets the function used by Pull to download models.

type Manifest

type Manifest struct {
	SchemaVersion int          `json:"schemaVersion"`
	MediaType     string       `json:"mediaType"`
	Config        Descriptor   `json:"config"`
	Layers        []Descriptor `json:"layers"`
}

Manifest represents an OCI image manifest for a GGUF model.

type ModelConfig

type ModelConfig struct {
	Architecture string `json:"architecture,omitempty"`
	Quantization string `json:"quantization,omitempty"`
	Parameters   int64  `json:"parameters,omitempty"`
}

ModelConfig holds model metadata stored as the OCI config blob.

type ModelInfo

type ModelInfo struct {
	ID           string `json:"id"`
	Path         string `json:"path"`
	Architecture string `json:"architecture"`
	VocabSize    int    `json:"vocab_size"`
	MaxSeqLen    int    `json:"max_seq_len"`
	Size         int64  `json:"size"`
}

ModelInfo describes a locally cached model.

type ModelRegistry

type ModelRegistry interface {
	// Pull downloads a model by ID and caches it locally.
	Pull(ctx context.Context, modelID string) (*ModelInfo, error)
	// Get returns a locally cached model by ID.
	Get(modelID string) (*ModelInfo, bool)
	// List returns all locally cached models.
	List() []ModelInfo
	// Delete removes a locally cached model.
	Delete(modelID string) error
}

ModelRegistry manages local model storage and retrieval.

type Option

type Option func(*Registry)

Option configures a Registry.

func WithCredentials

func WithCredentials(username, password string) Option

WithCredentials sets basic auth credentials for the registry.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom HTTP client for the registry.

type ProgressFunc

type ProgressFunc func(downloaded, total int64)

ProgressFunc reports download progress. total may be -1 if unknown.

type PullFunc

type PullFunc func(ctx context.Context, modelID string, targetDir string) (*ModelInfo, error)

PullFunc downloads or converts a model into the target directory. The target directory is guaranteed to exist when this function is called.

func NewHFPullFunc

func NewHFPullFunc(opts HFPullOptions) PullFunc

NewHFPullFunc creates a PullFunc that downloads models from HuggingFace Hub.

type Reference

type Reference struct {
	Registry   string
	Repository string
	Tag        string
	Digest     string
}

Reference holds a parsed OCI reference (registry/repo:tag or registry/repo@digest).

type Registry

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

Registry is an OCI distribution spec client for pushing and pulling GGUF models as OCI artifacts.

func NewRegistry

func NewRegistry(url string, opts ...Option) *Registry

NewRegistry creates a new OCI registry client.

func (*Registry) Pull

func (r *Registry) Pull(ctx context.Context, ref string, destPath string) error

Pull downloads a model from the registry to the given destination path.

func (*Registry) Push

func (r *Registry) Push(ctx context.Context, ref string, modelPath string) error

Push uploads a GGUF model file to the registry as an OCI artifact.

func (*Registry) Resolve

func (r *Registry) Resolve(ctx context.Context, ref string) (*Manifest, error)

Resolve resolves an OCI reference to its manifest.

func (*Registry) Tags

func (r *Registry) Tags(ctx context.Context, repo string) ([]string, error)

Tags lists all tags for a repository.

type TagList

type TagList struct {
	Name string   `json:"name"`
	Tags []string `json:"tags"`
}

TagList represents the response from the OCI tags/list endpoint.