Documentation
¶
Overview ¶
Package catalog is the pure SDK view of the public relay catalog: embedded host/bindings/pricing data plus model-ref resolution and per-binding cost.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Binding ¶
type Binding struct {
Name string `json:"upstream"`
MetadataName string `json:"model"`
Adapter string `json:"adapter"`
Providers []string `json:"providers"`
Featured bool `json:"featured,omitempty"`
Pricing []Rate `json:"pricing,omitempty"`
// Aliases are the model's declared resolution-only matchers, attached
// to the pointer-snapshot row: exact strings or single-'*' wildcard
// patterns. Last-priority lookup keys for Resolve, never identity —
// the relay routes them to this binding and passes the requested
// string upstream verbatim.
Aliases []string `json:"aliases,omitempty"`
}
Binding is one callable (snapshot, host) pair with wire metadata. Featured carries the catalog's `labels.featured` curation flag (the same one the control API exposes) so SDK consumers can shortlist without re-curating.
Name is the model's real provider wire name: the id the provider answers to and echoes back as the ran model — the identity a consumer recognizes. Always non-empty: the generator falls back to the snapshot slug when the catalog carries no distinct wire name, so consumers never need a fallback of their own. MetadataName is the catalog key, the DNS-1123 snapshot slug (== catalog metadata.name), an internal addressing handle (e.g. name gpt-5.5-2026-04-23, MetadataName gpt-5-5-2026-04-23). Both are first-class matchable keys — consumers matching a response's model against the catalog must compare it to Name AND MetadataName (or just call Resolve, which indexes both). The json tags are unchanged from the on-wire catalog (`upstream`/`model`).
func (Binding) Cost ¶
Cost returns total cost in the rate sheet's currency and ok=false when the binding carries no pricing. Tier axis = input tokens (matches app/pricing). It is the terse form of CostBreakdown, discarding the unpriced-meter list; callers rendering an estimate should prefer CostBreakdown so unpriced meters don't silently deflate the total.
func (Binding) CostBreakdown ¶ added in v0.4.0
CostBreakdown prices tokens against the binding's rate sheet and reports the meters that carried a non-zero count but produced no cost. cost is the total in the rate sheet's currency; unpriced lists the usage keys that went unpriced — a meter this binding doesn't price, or a key outside the catalog's meter vocabulary — sorted for stable output; ok is false only when the binding has no pricing at all (cost 0, unpriced nil). Tier axis = input tokens. Surface unpriced rather than presenting cost as complete: an unpriced meter is silently missing money otherwise, and a newly-priced meter type would quietly deflate every estimate that ignored it.
type Capabilities ¶
type Capabilities struct {
Chat bool `json:"chat,omitempty"`
Embeddings bool `json:"embeddings,omitempty"`
Streaming bool `json:"streaming,omitempty"`
Tools bool `json:"tools,omitempty"`
ParallelTools bool `json:"parallelTools,omitempty"`
Vision bool `json:"vision,omitempty"`
Audio bool `json:"audio,omitempty"`
PromptCache bool `json:"promptCache,omitempty"`
Reasoning bool `json:"reasoning,omitempty"`
JSONMode bool `json:"jsonMode,omitempty"`
StructuredOutputs bool `json:"structuredOutputs,omitempty"`
Batch bool `json:"batch,omitempty"`
ComputerUse bool `json:"computerUse,omitempty"`
WebSearch bool `json:"webSearch,omitempty"`
FileInput bool `json:"fileInput,omitempty"`
AudioInput bool `json:"audioInput,omitempty"`
AudioOutput bool `json:"audioOutput,omitempty"`
SystemMessages bool `json:"systemMessages,omitempty"`
AssistantPrefill bool `json:"assistantPrefill,omitempty"`
}
Capabilities mirrors app/model.Capabilities (same json tags) so the embed can carry it by a plain json round-trip without the SDK importing app/.
type Catalog ¶
type Catalog struct {
Version string `json:"version"`
GeneratedAt time.Time `json:"generatedAt"`
Hosts []Host `json:"hosts"`
Models []ModelInfo `json:"models,omitempty"`
Providers []ProviderInfo `json:"providers,omitempty"`
}
Catalog is the embedded catalog payload written by cmd/catalog-embed.
Hosts carry the routing/pricing bindings (the call-path shape). Models and Providers are the normalized rich-metadata sidecars — emitted once per slug, not duplicated onto every (model, host) binding — that the discovery graph (sdk/internal/graph, surfaced via the model/host/provider packages) joins to the bindings. They are display data; nothing on the request path reads them.
type Host ¶
type Host struct {
Name string `json:"name"`
BaseURL string `json:"baseURL"`
Models []Binding `json:"models"`
DisplayName string `json:"displayName,omitempty"`
Description string `json:"description,omitempty"`
HomepageURL string `json:"homepageURL,omitempty"`
DocsURL string `json:"docsURL,omitempty"`
ConsoleURL string `json:"consoleURL,omitempty"`
StatusPageURL string `json:"statusPageURL,omitempty"`
Icon string `json:"icon,omitempty"`
}
Host is one upstream serving endpoint and its model bindings. The display fields are operator-set metadata for catalog UIs; they do not affect routing.
type IndexedCatalog ¶
type IndexedCatalog struct {
Catalog *Catalog
// contains filtered or unexported fields
}
IndexedCatalog is a loaded catalog with O(1) resolution maps.
func Load ¶
func Load() (*IndexedCatalog, error)
Load inflates and unmarshals the embedded catalog and builds resolution indexes.
func LoadBytes ¶
func LoadBytes(data []byte) (*IndexedCatalog, error)
LoadBytes unmarshals catalog JSON and builds resolution indexes. The override seam for callers carrying their own catalog data.
func LoadFile ¶ added in v0.7.0
func LoadFile(path string) (*IndexedCatalog, error)
LoadFile loads a catalog from a local JSON file, transparently inflating gzip (as produced by catalog-embed -o *.gz). The lib never fetches anything — a newer or custom catalog is supplied by path, the embedded one is the shipped default.
func (*IndexedCatalog) Cost ¶ added in v0.4.0
func (ic *IndexedCatalog) Cost(ref string, tokens usage.Tokens) (cost float64, unpriced []string, ok bool)
Cost resolves ref to a binding and prices tokens against it — the one-call path for "given a model ref and accumulated token counts, what did it cost?" The catalog ships knowing every model's rate sheet, so a consumer holding only session token totals needs no local price table. unpriced carries the meters the model doesn't price (see Binding.CostBreakdown); ok is false when ref doesn't resolve or the binding carries no pricing.
func (*IndexedCatalog) Resolve ¶
func (ic *IndexedCatalog) Resolve(ref string) (Binding, Host, error)
Resolve maps a model ref to its binding and host. Ref forms: bare snapshot name, provider/model, or model@host (and provider/model@host). The model segment accepts either the catalog key (Binding.MetadataName) or the served wire name (Binding.Name) — the string a provider echoes back as the ran model resolves as-is. Ambiguous bare or provider-qualified refs across multiple hosts return an error listing candidate host@model pins.
func (*IndexedCatalog) ResolveModelSlug ¶
func (ic *IndexedCatalog) ResolveModelSlug(ref string) (string, error)
ResolveModelSlug maps a ref to the unique model slug (Binding.MetadataName), aggregating across hosts. Unlike Resolve, several hosts serving the same model is NOT ambiguous here — they share one slug, and the discovery graph wants the model, not a single (model, host) pin. It errors only when the ref is unknown or genuinely maps to more than one distinct model. Same ref forms + priority as Resolve (real names beat declared aliases; wildcards last).
type Modalities ¶
type Modalities struct {
Input []string `json:"input,omitempty"`
Output []string `json:"output,omitempty"`
}
Modalities mirrors app/model.Modalities.
type ModelInfo ¶
type ModelInfo struct {
MetadataName string `json:"metadataName"`
Provider string `json:"provider,omitempty"` // author provider slug
DisplayName string `json:"displayName,omitempty"`
Description string `json:"description,omitempty"`
Family string `json:"family,omitempty"`
Version string `json:"version,omitempty"`
Capabilities Capabilities `json:"capabilities,omitempty"`
Modalities Modalities `json:"modalities,omitempty"`
ContextWindowInput int `json:"contextWindowInput,omitempty"`
ContextWindowOutput int `json:"contextWindowOutput,omitempty"`
ContextWindowTotal int `json:"contextWindowTotal,omitempty"`
MaxOutputTokens int `json:"maxOutputTokens,omitempty"`
KnowledgeCutoff string `json:"knowledgeCutoff,omitempty"`
ReleaseDate string `json:"releaseDate,omitempty"`
License string `json:"license,omitempty"`
Tags []string `json:"tags,omitempty"`
Documentation string `json:"documentation,omitempty"`
ProviderModelPageURL string `json:"providerModelPageURL,omitempty"`
}
ModelInfo is the rich per-model metadata, keyed by MetadataName (the snapshot slug that bindings reference). The graph joins it to the bindings to build a Model node; the model's real wire name + per-host pricing come from the bindings, so they are not repeated here.
type ProviderInfo ¶
type ProviderInfo struct {
Name string `json:"name"`
DisplayName string `json:"displayName,omitempty"`
Description string `json:"description,omitempty"`
HomepageURL string `json:"homepageURL,omitempty"`
DocsURL string `json:"docsURL,omitempty"`
StatusPageURL string `json:"statusPageURL,omitempty"`
Icon string `json:"icon,omitempty"`
}
ProviderInfo is the rich per-provider (model author) metadata, keyed by Name.
Source Files