catalog

package
v0.1.799 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package catalog knows which models exist. It reads the models.dev catalog (from magpie's own cache or OpenCode's), Codex's model cache, and falls back to a small built-in list so the picker is never empty.

Index

Constants

This section is empty.

Variables

View Source 
var Changed func()

Changed, when set, is told that the models magpie offers may be others now: a provider added, edited or removed, a vendor's list fetched anew. The agent package sets it, to bring the model lists agents keep in files of their own up to date.

View Source 
var Forget func()

Forget, when set, is told so first: the provider package drops the catalog a request holds (provider.Hold).

View Source 
var PublicCatalogs = map[string]string{
	"aihubmix.com": "https://aihubmix.com/api/v1/models",
}

PublicCatalogs are vendors whose /models, asked with a key, leaves out the image models the key can use: AIHubMix lists only its Gemini image models there, while gpt-image-2 and the rest draw with the same key. Its public catalog, by the host of the vendor's base URL, has them.

Functions

func APIOf added in v0.1.166 

func APIOf(providerID, modelID string) string

APIOf is the API a models.dev provider's model is served on, when the catalog says it's one of its own: "responses" or "anthropic" for a model OpenCode serves through OpenAI's or Anthropic's SDK, not the OpenAI-compatible one the rest of its models go through.

func CachePath 

func CachePath() string

CachePath is where `magpie sync` stores the models.dev catalog.

func CodexHome added in v0.1.763 

func CodexHome() string

CodexHome is where Codex CLI keeps its state: $CODEX_HOME, else ~/.codex.

func CodexModelsCache added in v0.1.763 

func CodexModelsCache() string

CodexModelsCache is the model list Codex CLI keeps, under CodexHome.

func ContextOf added in v0.1.54 

func ContextOf(id string) int

ContextOf is the context window models.dev gives a model of this id, as most of the providers it lists serving it do, or 0 when it doesn't know the model. Like SeesImages it reaches a vendor models.dev doesn't list: a proxy serving "openai/gpt-5.4", or "gpt-5.4(high)" with the reasoning level CLIProxyAPI takes in the id, which a static model list would otherwise leave at the agent's default.

func DrawsID added in v0.1.338 

func DrawsID(id string) bool

DrawsID is whether a model's id names one that makes images, for a model the catalog doesn't know (one typed in, or a vendor's own list's).

func Efforts 

func Efforts(models []Model, id string) []string

Efforts returns the reasoning levels a model supports, if known.

func EffortsOf added in v0.1.59 

func EffortsOf(id string) []string

EffortsOf is the reasoning levels models.dev gives a model of this id, as most of the providers giving any for it do, or nil when none does. Like ContextOf it reaches a vendor models.dev doesn't list: a custom provider serving "glm-5.3-flash" takes the levels Z.ai and the others serving it say it does, where it would otherwise be taken for a model that doesn't reason, and an agent offer no levels for it.

func EndpointAPIs added in v0.1.141 

func EndpointAPIs(endpoints []string) []string

EndpointAPIs names the APIs of a model list's supported_endpoints — "chat", "responses", "anthropic" — leaving out any magpie doesn't speak (Copilot's websocket one); nil when it names none of them.

func ImagesAPI added in v0.1.384 

func ImagesAPI(id string) bool

ImagesAPI is whether a model draws on an images API (/images/generations) rather than answering in chat with pictures: gpt-image, dall-e, imagen, flux, seedream… — not gemini-*-image or gpt-5-image, which chat.

func KeepFresh added in v0.1.426 

func KeepFresh()

KeepFresh fetches the catalog whenever it is stale, now and every hour after, for as long as the process runs (the app's backend, `magpie serve`). It never returns.

func Knows added in v0.1.680 

func Knows(id string) bool

Knows reports whether models.dev lists a model of this id at all, under any provider, as ContextOf and EffortsOf match it.

func ListedBy added in v0.1.404 

func ListedBy(providers []string, id string) ([]string, bool)

ListedBy is the reasoning levels the first of providers (models.dev ids) listing a model of this id gives it — none, for one listed with a thinking switch alone or nothing at all — and whether any of them says. One listed with a thinking budget and no levels says nothing of them (Anthropic's claude-sonnet-4-5, whose budget an effort is sent as). The id is matched as EffortsOf matches it: without a vendor's prefix, in any case. It is how a model's maker is heard before its resellers: Xiaomi lists mimo-v2.6-flash with a switch alone, where gateways reselling it give levels up to max, which Xiaomi turns away (#214).

func LivePath 

func LivePath(provider string) string

LivePath is where the fetched model list of one provider is kept.

func MagpieAdded added in v0.1.486 

func MagpieAdded(etag, slug, description string) bool

MagpieAdded reports whether an entry of Codex's models_cache.json is one of magpie's, not Codex's own: the list Codex keeps is the one it was last handed, and handed through the gateway it has magpie's models in it too ("group/semantic", "deepseek/deepseek-v4", "codex/gpt-5.5" — magpie's ids, which Codex's slugs never look like). Read back as Codex's own, they were listed under OpenAI, and kept there after Codex was routed elsewhere.

func Missing added in v0.1.426 

func Missing()

Missing says a call's model has no price: the catalog is fetched again, in the background, when it is older than six hours and wasn't tried in that time. Only in a process that keeps it fresh (KeepFresh), so a CLI command or a test never fetches on its own.

func OutputOf added in v0.1.100 

func OutputOf(id string) int

OutputOf is the most tokens a reply from a model of this id may hold, as most of the providers serving it give it, or 0 when not known.

func ProviderAvailable 

func ProviderAvailable(provider string) bool

ProviderAvailable is true when any of the provider's API-key env vars is set.

func ProviderEnv 

func ProviderEnv(provider string) []string

ProviderEnv lists the env vars that unlock a models.dev provider.

func ProviderName added in v0.1.39 

func ProviderName(id string) string

ProviderName is a models.dev provider's display name ("GitHub Copilot" for "github-copilot"), or "" when the catalog doesn't know it.

func Providers 

func Providers() []string

Providers returns models.dev provider ids known to the catalog.

func Reset 

func Reset()

Reset forgets the loaded catalog so the next call re-reads the cache.

func SaveLive 

func SaveLive(provider, base string, models []Model) error

SaveLive stores a fetched list; an empty list forgets it.

func SeesImages added in v0.1.44 

func SeesImages(id string) bool

SeesImages reports whether models.dev says a model of this id takes images, as most of the providers it lists serving it do; for a vendor it doesn't list, serving a model it knows from others ("z-ai/glm-5.3" is glm-5.3).

func Source 

func Source() string

Source reports which catalog file is in use ("" when only built-ins are).

func Stale 

func Stale() bool

Stale reports whether no catalog exists or the cache is older than a day (fresh.go).

func Sync 

func Sync(ctx context.Context) error

Sync downloads the models.dev catalog into CachePath. It serializes with itself so a background refresh and a manual one cannot interleave writes.

func Thinks added in v0.1.572 

func Thinks(id string) bool

Thinks reports whether models.dev says a model of this id reasons, as most of the providers it lists serving it do, whether or not they give it levels; for a vendor it doesn't list, serving a model it knows from others.

func Touched added in v0.1.54 

func Touched()

Touched tells Forget and Changed, if set.

func Versioned added in v0.1.332 

func Versioned(base string) bool

Versioned reports whether an API base URL has a version in its path — a segment like v1, v3, v4 or v1beta — and so names the vendor's API as it is, with no /v1 left out of it.

Types

type Model 

type Model struct {
	ID          string // e.g. "claude-sonnet-5"
	Name        string // display name
	Provider    string // models.dev provider id
	Released    string // YYYY-MM-DD, used for ordering
	Efforts     []string
	Temperature *bool  // false when the model refuses temperature/top_p
	Price       *Price // USD per million tokens, when models.dev lists it
	// Keys, for a vendor whose keys each see models of their own, are the
	// keys (by fingerprint) whose list has this one; empty is every key.
	Keys []string `json:",omitempty"`
	// APIs, when the vendor says, are the APIs the model is served on
	// ("chat", "responses", "anthropic"); empty is not known.
	APIs []string `json:",omitempty"`
	// Images is set on a model that takes images as input.
	Images bool `json:",omitempty"`
	// ImageInput is the source's explicit answer; nil means it did not say.
	ImageInput *bool `json:",omitempty"`
	// Context is how many tokens a prompt may hold, when known: models.dev's
	// input limit, else its context window.
	Context int `json:",omitempty"`
	// MaxContext is the most a prompt may hold when asked for, above
	// Context: Codex's max_context_window (872k on GPT-6, 272k by default).
	MaxContext int `json:",omitempty"`
	// Output is the most tokens a reply may hold, when known.
	Output int `json:",omitempty"`
	// Fast is set on a model Codex may ask for priority processing (its
	// Fast mode): one a ChatGPT account serves.
	Fast bool `json:",omitempty"`
	// AgentsV2 is set on a model Codex is told multi-agent V2 for, so its
	// Ultra hands work to Codex's agents: one offering Ultra that no
	// ChatGPT account answers for (provider.Entry's).
	AgentsV2 bool `json:",omitempty"`
	// Draws is set on a vendor-listed model that makes images (gpt-image-1,
	// a relay's flux): kept with the list for Settings → Images, never
	// offered to agents as a model to talk to.
	Draws bool `json:",omitempty"`
	// Films is set on a model another magpie lists as one it makes videos
	// with (a Remote magpie's Grok Imagine Video): kept with the list for
	// its videos API, never offered as a model to talk to or draw with.
	Films bool `json:",omitempty"`
	// Free is set on a model a subscription serves at no cost to its
	// allowance: WorkBuddy's "credits": "x0.00".
	Free bool `json:",omitempty"`
	// Rate is what a request costs of a subscription's credits, as a
	// multiple, when its vendor lists it: Qoder's price_factor (0.5),
	// WorkBuddy's "credits": "x0.03". 0 is not listed, or Free.
	Rate float64 `json:",omitempty"`
	// RateWas is the rate before a discount running now, when the vendor
	// says it: Qoder's Qwen3.8-Flash at 0× with 0.1× struck through.
	RateWas float64 `json:",omitempty"`
	// Reasoning is set on a model that thinks, whether or not it takes
	// levels: mimo-v2.6-flash thinks with a switch alone (#402).
	Reasoning bool `json:",omitempty"`
}

Model is one entry the picker can offer.

func Chat added in v0.1.340 

func Chat(ms []Model) []Model

Chat is ms without the models that draw or make videos.

func Codex 

func Codex() []Model

Codex returns the models Codex itself lists, straight from the cache the Codex CLI writes; there is no compiled-in list to fall back to.

func Decorate 

func Decorate(live []Model, known []Model) []Model

Decorate fills in names and reasoning levels for live models from the catalog's entry for the same id, keeping the live order.

func Drawers added in v0.1.338 

func Drawers(id string) []Model

Drawers are the models of one models.dev provider that make images, newest first.

func Fetch 

func Fetch(ctx context.Context, base, key string, anthropic bool, headers map[string]string) ([]Model, error)

Fetch asks an endpoint for its models. base is an API base URL of any flavour (…/v1, …/anthropic, …/api); the usual list paths are tried around it. The result keeps the server's order. anthropic sends the Anthropic version header, which the official API requires but which a dual-protocol relay like OpenRouter reads as a request for its Anthropic-flavoured catalog — namespaced, differently named ids.

func FetchAt added in v0.1.65 

func FetchAt(ctx context.Context, base, key string, anthropic bool, headers map[string]string) ([]Model, string, error)

FetchAt is Fetch, and says which URL answered. An OpenAI-style base with a version in its path (…/v1, …/api/plan/v3, …/api/paas/v4, …/v1beta/openai) names the vendor's API as it is and is asked only as written, at base/models: a /v1 is looked for only around a base without one (a bare host, a relay's …/api), where it may have been left out. An Anthropic base is the root /v1/messages is asked at, so /v1/models under it is its own list. When no URL answers, the error names each one asked and what it said.

func FetchURL added in v0.1.85 

func FetchURL(ctx context.Context, url, key string, anthropic bool, headers map[string]string) ([]Model, error)

FetchURL asks for the model list at exactly url.

func Live 

func Live(provider string) (models []Model, fetched time.Time, ok bool)

Live returns the model list last fetched from the provider, if any: the models to talk to, without the ones that draw (LiveDrawers).

func LiveDrawers added in v0.1.340 

func LiveDrawers(provider string) []Model

LiveDrawers are the models in the provider's fetched list that make images, in the list's order.

func LiveVideomakers added in v0.1.651 

func LiveVideomakers(provider string) []Model

LiveVideomakers are the models in the provider's fetched list that make videos, in the list's order.

func Provider 

func Provider(id string) []Model

Provider returns the text models of one models.dev provider, newest first. The list comes from the synced models.dev catalog; nothing is compiled in. A vendor's own /models answer, once fetched, is layered over it by the provider package (see provider.Provider.Available).

func PublicDrawers added in v0.1.345 

func PublicDrawers(ctx context.Context, base string) []Model

PublicDrawers are the image models the public catalog for base's host lists, marked as drawing; nil when there is none or it can't be read.

func WithDrawers added in v0.1.345 

func WithDrawers(ms, drawers []Model) []Model

WithDrawers adds the drawers not already in ms.

type Price 

type Price struct {
	Input      float64 `json:"input"`
	Output     float64 `json:"output"`
	CacheRead  float64 `json:"cache_read"`
	CacheWrite float64 `json:"cache_write"`
}

Price is what a model costs, in USD per million tokens.

func PriceOf 

func PriceOf(providerID, modelID string) (Price, bool)

PriceOf is the list price of a models.dev provider's model, if known.

func PricedBy added in v0.1.411 

func PricedBy(providers []string, id string) (Price, bool)

PricedBy is the list price the first of providers (models.dev ids) pricing a model of this id gives it: by its own key first, then by its id without a path or case ("openai/GPT-6-Sol" is gpt-6-sol), a Bedrock profile's geography, a "(variant)" or a ":tag".

func (Price) Cost 

func (p Price) Cost(input, output, cacheRead, cacheWrite int) float64

Cost of a call at this price. Reasoning tokens are billed as output by every vendor, and are already inside the output count.

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.