catalog

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 7, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package catalog is the model catalog: a vetted, versioned list of models with provenance, so a user (or the agent) can discover, compare, and choose a model on evidence instead of guessing. The adapter registry (provider) knows how to talk to a provider:model; this package knows which models exist, what they cost in size and context, what they can do, and where they came from.

The catalog ships as data, not code: a models.json embedded in the binary so it works offline, authored and reviewed in the public repository, and intended to be published as a public artifact that can update without a rebuild. Every entry carries a provenance record and a license, and is held at a trust tier, so the list is auditable and nothing is offered as if vetted when it is not.

This package is the discovery foundation. Hardware-fit ranking, fetch-to-run, the per-model eval, and live enrichment from upstream sources build on the same schema.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Capabilities 

type Capabilities struct {
	Tools     bool `json:"tools"`
	Vision    bool `json:"vision"`
	Reasoning bool `json:"reasoning"`
}

Capabilities is what a model can do, used to filter to models that fit a task.

type Catalog 

type Catalog struct {
	// Version is the catalog schema/content version.
	Version string `json:"version"`
	// Updated is the date the catalog was last revised (ISO 8601), set by the
	// publisher, not at runtime, so the embedded copy is deterministic.
	Updated string `json:"updated"`
	// Models are the entries.
	Models []ModelSpec `json:"models"`
}

Catalog is a versioned set of model entries.

func Load 

func Load() (Catalog, error)

Load parses and validates the embedded curated catalog. A malformed or invalid embedded catalog is a build-time mistake, so it returns a terminal error rather than shipping a broken list.

func (Catalog) Find 

func (c Catalog) Find(q Query) []ModelSpec

Find returns the entries matching q, sorted by kind then smallest footprint then id, so a list reads stably and the cheapest option surfaces first.

func (Catalog) Validate 

func (c Catalog) Validate() error

Validate checks every entry has the provenance and license the catalog promises, and that quant formats are known. It is the gate that keeps an unlabeled or unsafe entry out of a shipped catalog.

type Fit 

type Fit string

Fit is how a model sits against a memory budget: can the box run it, run it with little headroom, or not at all. It is the answer to "which of these can I actually run" once the machine's memory is known. 

const (
	// FitFeasible means the weights and a working runtime headroom fit comfortably.
	FitFeasible Fit = "feasible"
	// FitTight means the weights fit but the headroom for the cache and activations is
	// thin, so a long context or a second process may not.
	FitTight Fit = "tight"
	// FitOverBudget means the weights alone do not fit; the model is out of spec.
	FitOverBudget Fit = "over-budget"
	// FitUnknown means there was not enough information to judge (no size, or no
	// detected/!given memory budget).
	FitUnknown Fit = "unknown"
)

func Feasibility 

func Feasibility(availBytes, sizeBytes int64) Fit

Feasibility classifies whether a quantization of sizeBytes runs within availBytes of memory, reserving a headroom over the weights so a model judged feasible has room to actually run, not just to load. A non-positive size or budget is unknown rather than a false verdict.

func (Fit) Runnable 

func (f Fit) Runnable() bool

Runnable reports whether a fit verdict means the model can run at all (feasible or tight), so a "what can I run" view can keep the runnable ones and a recommendation can ignore the rest.

type Format 

type Format string

Format is a weight file's encoding, which determines whether loading it is safe. 

const (
	// FormatSafetensors stores tensors only and executes no code on load (preferred).
	FormatSafetensors Format = "safetensors"
	// FormatGGUF is the quantized single-file format local runtimes use; tensors plus
	// metadata, no code execution.
	FormatGGUF Format = "gguf"
	// FormatPickle (.bin/.pt) can execute arbitrary code when loaded, so it is unsafe
	// and an entry using it is flagged, never silently fetched.
	FormatPickle Format = "pickle"
)

type Kind 

type Kind string

Kind is how a model is reached: a hosted API, or local weights run on this machine. 

const (
	// KindAPI is a model served behind a provider API (no weights to download).
	KindAPI Kind = "api"
	// KindLocal is open weights run by a local model runtime or inference server.
	KindLocal Kind = "local"
)

type ModelSpec 

type ModelSpec struct {
	// ID is the provider:model selector the adapter registry resolves, e.g.
	// "anthropic:claude-opus-4-8" for an API model or a "runtime:model" form for a
	// local one.
	ID string `json:"id"`
	// Name is the human-readable model name.
	Name string `json:"name"`
	// Kind is API or local.
	Kind Kind `json:"kind"`
	// Source is the provenance record.
	Source Source `json:"source"`
	// License is the SPDX id or license name; surfaced so commercial use is an
	// informed choice. Required, so an unknown-license entry cannot slip in unlabeled.
	License string `json:"license"`
	// ParamsB is the parameter count in billions (0 when undisclosed, as for hosted
	// proprietary models).
	ParamsB float64 `json:"paramsB,omitempty"`
	// ContextTokens is the usable context window (0 when unknown).
	ContextTokens int `json:"contextTokens,omitempty"`
	// Capabilities is what the model supports.
	Capabilities Capabilities `json:"capabilities"`
	// Quants are the downloadable quantizations (local models); empty for API models.
	Quants []Quant `json:"quants,omitempty"`
	// Trust is how far the entry has been vetted.
	Trust Trust `json:"trust"`
	// ChatTemplate is the trusted chat template a local model is served with, named so
	// the runtime applies a known-good prompt contract instead of the template embedded
	// in the weights (which a hostile model could use to rewrite the contract). It is
	// the name of a template the runtime recognizes, for example "chatml". Required for
	// a local model; empty for a hosted API model, which formats prompts server-side.
	ChatTemplate string `json:"chatTemplate,omitempty"`
	// Notes is an optional one-line human note (why it is here, caveats).
	Notes string `json:"notes,omitempty"`
}

ModelSpec is one catalog entry: how to select it, where it came from, what it costs, and what it can do.

func (ModelSpec) FitFor 

func (m ModelSpec) FitFor(availBytes int64) Fit

FitFor reports how a model fits a memory budget, judged by its smallest quantization (the cheapest way to run it). An API model downloads nothing and is always feasible; a local model with no size is unknown.

func (ModelSpec) Local 

func (m ModelSpec) Local() bool

Local reports whether the entry is local weights.

func (ModelSpec) SmallestQuant 

func (m ModelSpec) SmallestQuant() (Quant, bool)

SmallestQuant returns the smallest-on-disk quantization and whether the model has any, so callers can rank a local model by its cheapest footprint.

type Quant 

type Quant struct {
	// Name is the quantization label (e.g. "Q4_K_M", "fp16").
	Name string `json:"name"`
	// Format is the weight encoding; an unsafe format is refused at fetch.
	Format Format `json:"format"`
	// SizeBytes is the on-disk size, the headline number for hardware fit.
	SizeBytes int64 `json:"sizeBytes"`
	// Ref is the pull reference a runtime fetches this quantization by (a registry tag
	// or a file path).
	Ref string `json:"ref"`
	// URL is the direct https location of the weights file, when the quantization can
	// be downloaded and verified directly. Empty means there is no pinned direct
	// download yet, so the verified fetch path treats the entry as not downloadable
	// rather than reaching for an unverified source.
	URL string `json:"url,omitempty"`
	// Digest is the content hash (e.g. "sha256:...") the download is verified against.
	// Empty means unpinned: the fetcher pins it from the registry's own manifest at
	// pull time and still verifies the bytes, so an unpinned entry is never trusted
	// blindly.
	Digest string `json:"digest,omitempty"`
	// Files, when set, is the multi-file manifest for a model served from a directory
	// rather than a single file: a safetensors model is a set of weight shards plus the
	// tokenizer and config files a GPU runtime loads from a directory. It is the multi-file
	// counterpart to URL: a single-file quantization (GGUF) names URL, a directory model
	// names Files. A quant names one or the other, never both.
	Files []QuantFile `json:"files,omitempty"`
}

Quant is one downloadable quantization of a local model: its on-disk cost, the reference a runtime pulls it by, and the content digest used to verify the download.

func (Quant) MultiFile 

func (q Quant) MultiFile() bool

MultiFile reports whether the quant is a directory model (a set of files) rather than a single downloadable file.

type QuantFile 

type QuantFile struct {
	// Name is the file's path within the model directory (for example "model.safetensors"
	// or "tokenizer.json"). It is relative and must not escape the directory.
	Name string `json:"name"`
	// URL is the direct https location of the file.
	URL string `json:"url"`
	// Digest is the content hash the file is verified against; empty pins on fetch.
	Digest string `json:"digest,omitempty"`
	// SizeBytes is the file's size, the per-file download cap.
	SizeBytes int64 `json:"sizeBytes,omitempty"`
}

QuantFile is one file of a multi-file quantization: its name within the model directory, where to fetch it, and the digest it is verified against. The set of these is how a safetensors model (shards + tokenizer + config) is acquired with the same per-file verification a single-file weight gets.

type Query 

type Query struct {
	// Kind, when set, restricts to API or local models.
	Kind Kind
	// Capability, when set ("tools", "vision", "reasoning"), keeps models that support
	// it.
	Capability string
	// MaxParamsB, when > 0, keeps models at or below this parameter count (the lever
	// for "what a small box can run"); entries with an undisclosed count are dropped,
	// since fit cannot be claimed for them.
	MaxParamsB float64
	// Publisher, when set, keeps entries from that publisher (case-insensitive).
	Publisher string
	// SafeOnly drops entries whose only quantizations are an unsafe (code-executing)
	// format, so a fit list never steers toward weights that run code on load.
	SafeOnly bool
}

Query filters the catalog. The zero Query matches everything.

type Source 

type Source struct {
	// Publisher is the first-party namespace that released the model (e.g. "Qwen",
	// "meta-llama", "Anthropic"). Preferring publisher orgs over reuploads is part of
	// the trust check.
	Publisher string `json:"publisher"`
	// URL is the official model card or release page the entry was taken from.
	URL string `json:"url"`
	// Registry is the catalog or service the weights or the API come from, recorded so
	// the entry can be traced back to its origin.
	Registry string `json:"registry"`
}

Source is where a model came from, so an entry can be traced to an authoritative publisher rather than hearsay.

type Trust 

type Trust string

Trust is how far an entry has been vetted. It is surfaced, never hidden, so a model is never presented as trusted when it is merely known. 

const (
	// TrustBlessed is vetted and shipped in the curated catalog, with full provenance.
	TrustBlessed Trust = "blessed"
	// TrustDiscovered came from an upstream source this run: metadata only, not vetted.
	TrustDiscovered Trust = "discovered"
	// TrustLocal is already present on this machine (detected on disk).
	TrustLocal Trust = "local"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.