Documentation
¶
Overview ¶
Package catalog is Seshat's view of the public models.dev catalog of providers and models: which providers exist, the base URL and API key variable of each, and what each model can do (context window, output limit, image input, reasoning, cost, status). It is the data opencode builds its provider list from.
Two rules govern how the data is used:
- The catalog is data about models, not an authority over where a key is sent. The base URL, the API key variable and the protocol of a provider come from the snapshot embedded in this binary (reviewed when it was built). A catalog fetched later can update models and add providers, but a provider it adds is Unverified: its URL must be shown to the user and confirmed before a key is sent to it. See Merge.
- Our own catalog of models (internal/providers) wins over this one. The catalog's limits are community data: some are placeholders (an output limit equal to the context window usually means "unknown").
Index ¶
- Constants
- Variables
- func CacheAge(cacheDir string) (time.Duration, bool)
- func Refresh(ctx context.Context, client *http.Client, url, cacheDir string) error
- func RefreshIfStale(ctx context.Context, client *http.Client, url, cacheDir string) (bool, error)
- type Catalog
- type Cost
- type Model
- type Provider
Constants ¶
const DefaultURL = "https://models.dev/api.json"
DefaultURL is where the public models.dev catalog is served.
const RefreshInterval = 24 * time.Hour
RefreshInterval is how old the cache may be before a background refresh fetches the catalog again.
Variables ¶
var ErrCatalogTooSmall = errors.New("the catalog has too few providers to be genuine")
ErrCatalogTooSmall is returned when a catalog has too few providers to be believed.
Functions ¶
Types ¶
type Catalog ¶
type Catalog struct {
Providers map[string]Provider
// Source says where the data came from: "embedded", "cache" or the URL it was fetched from.
Source string
}
Catalog is a set of providers.
func Embedded ¶
Embedded returns the catalog built into the binary. It is read once. Every provider in it is verified.
func Fetch ¶
Fetch downloads the catalog from url (DefaultURL when empty). It sends nothing about the user: a plain GET.
func Load ¶
Load returns the catalog to use: the embedded one, with the cached fetch merged over it when there is one. It never touches the network. cacheDir may be empty to ignore the cache. A damaged cache is ignored, not an error: the embedded catalog stands.
func Merge ¶
Merge puts a catalog fetched at run time over the trusted one (the embedded snapshot) and returns the result. The rule is the security rule of the package:
- A provider that is in trusted keeps its BaseURL, Env and Protocol from trusted. The fetched catalog may only update its name and its models. A fetched catalog that moves a provider to another URL changes nothing here.
- A provider that is only in fetched is added with Unverified set: a host must show its URL and have the user confirm it before an API key is sent there.
- A model that is only in trusted is kept (a provider that drops a model from its list does not make a conversation that uses it fail); a model in both takes the fetched data.
func Parse ¶
Parse reads a catalog in the models.dev format. Every provider of the result is Unverified: it came from outside this binary. Models that do not produce text or cannot call tools are left out, as an agent cannot use them.
func (*Catalog) OpenAICompatibleProviders ¶
OpenAICompatibleProviders returns the providers the generic OpenAI-compatible client can call, sorted by name.
type Cost ¶
Cost is the price of a model in US dollars per million tokens. A zero value means the price is unknown.
type Model ¶
type Model struct {
ID string
Name string
ContextWindow int
// MaxOutput is the output limit, 0 when unknown. See OutputIsKnown.
MaxOutput int
// InputModalities lists what the model accepts besides text: "image", "audio", "video", "pdf".
InputModalities []string
Reasoning bool
Cost Cost
// Status is "", "alpha", "beta" or "deprecated".
Status string
ReleaseDate string
}
Model describes one model of a provider.
func (Model) Deprecated ¶
Deprecated reports whether the provider has retired or is retiring the model.
func (Model) OutputIsKnown ¶
OutputIsKnown reports whether the output limit is a real one. The catalog often repeats the context window when the limit is not known, so a limit equal to the window, or a missing one, is not trusted.
type Provider ¶
type Provider struct {
ID string
Name string
// BaseURL is the API base URL, empty for providers that have no fixed one (Anthropic, OpenAI, Gemini, AWS...).
BaseURL string
// Env lists the environment variables that can hold the API key, the first one first.
Env []string
// Protocol is the SDK package the catalog names for the provider: "@ai-sdk/openai-compatible" for most.
Protocol string
Models map[string]Model
// Unverified is true for a provider that is not in the embedded snapshot: its BaseURL comes from a catalog fetched at run
// time and must be confirmed by the user before an API key is sent to it.
Unverified bool
}
Provider describes one provider of the catalog.
func (Provider) OpenAICompatible ¶
OpenAICompatible reports whether the provider can be called with the generic OpenAI-compatible client: it speaks that protocol and the catalog gives its base URL.
func (Provider) SortedModels ¶
SortedModels returns the models, newest first, then by id. Deprecated models come last.
Source Files