catalog

Documentation

Index

• Constants
• func ContextWindow(model string) int
• func CostUSD(model string, inTok, outTok, cacheRead, cacheWrite int) float64
• func DefaultModel() string
• func FallbackChain(idOrLabel string) []string
• func MaxOutputTokens(model string) int
• func ModelVendor(idOrLabel string) string
• func SearchFeeUSD(vendor string, searches int) float64
• func UtilityModel() string
• type CatalogModel
  • func CatalogModels() []CatalogModel
  • func LookupModel(idOrLabel string) (CatalogModel, bool)
• type Pricing
  • func ModelPricing(model string) Pricing

Constants

const (
	ModelOpus   = "claude-opus-5"             // anthropic frontier tier
	ModelSonnet = "claude-sonnet-5"           // advisor default (second-opinion, cross-vendor); anthropic balanced tier
	ModelHaiku  = "claude-haiku-4-5-20251001" // anthropic cheap tier
)

Canonical Claude model IDs (current as of build). These back the ADVISOR (Sonnet) and per-vendor tier fallbacks; the default inference tiers use the GPT-5.6 ids below.

const (
	ModelSol   = "gpt-5.6-sol"   // frontier — escalation target
	ModelTerra = "gpt-5.6-terra" // balanced — everyday default + fallback absorb
	ModelLuna  = "gpt-5.6-luna"  // fast/cheap — classifier + reviewer
)

GPT-5.6 model IDs — the default inference tiers (OpenAI Responses API). Sol is the frontier escalation target, Terra the balanced everyday default + fallback absorb target, Luna the fast/cheap classifier.

const (
	ModelGeminiPro       = "gemini-3.1-pro-preview" // frontier — escalation target
	ModelGeminiFlash     = "gemini-3.8-flash"       // the Gemini vendor's everyday model
	ModelGeminiFlashLite = "gemini-3.5-flash-lite"  // fast/cheap — classifier
)

Gemini 3 model IDs (Google, via the native genai SDK).

const (
	ModelGrok46 = "grok-4.6" // single model — serves frontier/balanced/cheap tiers
)

Grok model ID (xAI, via the OpenAI-compatible api.x.ai endpoint). Grok 4.5 is the single model for all three strong-tier roles, so the selector resolves every tier to this id.

Functions

func ContextWindow

func ContextWindow(model string) int

ContextWindow returns the input context-window size (tokens) for a model id or label: the catalog entry if it declares one, else the first matching family rule, else the default. Used by the footer's "ctx N%" meter and the overflow ceiling when a backend doesn't report its window on the wire.

func CostUSD

func CostUSD(model string, inTok, outTok, cacheRead, cacheWrite int) float64

CostUSD prices one response's token usage under its model's rate card.

func DefaultModel

func DefaultModel() string

DefaultModel returns the seed label for an install with no pin anywhere. Its ONLY legitimate caller is the pin resolver, and only when the session/workspace/user chain came up empty; the result is persisted so the next run reads a concrete pin instead of re-deriving this.

func FallbackChain

func FallbackChain(idOrLabel string) []string

FallbackChain returns the mid-turn failure chain (labels) for a model id or label. Nil when the catalog declares none.

func MaxOutputTokens

func MaxOutputTokens(model string) int

MaxOutputTokens returns the model's max output tokens from the catalog, or 0 when the catalog doesn't declare one. Callers that must send a max_tokens value on the wire (Anthropic requires the field) use this to translate "uncapped" (request MaxTokens 0) into the largest value the model accepts.

func ModelVendor

func ModelVendor(idOrLabel string) string

ModelVendor returns the authoritative serving vendor for a model id or label ("openai" | "anthropic" | "gemini" | "grok" | "fireworks"), "" when unknown.

func SearchFeeUSD

func SearchFeeUSD(vendor string, searches int) float64

SearchFeeUSD prices the PER-REQUEST native web-search surcharge for a call: the serving vendor's catalog fee (models.json search_fees, USD per 1,000 searches) times the number of searches the vendor billed (Response.SearchCount). Tokens alone under-billed searched turns — the upstream per-request fee never entered cost_usd. A vendor without a search_fees entry (gemini, the cheap lane, unknown backends) returns 0.

func UtilityModel

func UtilityModel() string

UtilityModel returns the label for internal plumbing (classify/authorize, compact, shrinkwrap). Never user-facing, never in the picker, never a substitute for the pinned model.

Types

type CatalogModel

type CatalogModel struct {
	ID             string  `json:"id"`
	Label          string  `json:"label"`          // client-facing short name — the only id the CLI sees
	Vendor         string  `json:"vendor"`         // authoritative serving vendor ("openai" | "anthropic" | "gemini" | "grok" | "fireworks") — selection/steering identity, distinct from the display Group
	Name           string  `json:"name,omitempty"` // friendly display name ("Sonnet 5", "Grok 4.5") — the /model picker's name column
	Desc           string  `json:"desc,omitempty"` // one-line picker description ("1M context · Efficient for routine tasks")
	Window         int     `json:"window"`
	MaxOutput      int     `json:"max_output,omitempty"` // model's max output tokens; consumed where the provider REQUIRES max_tokens (Anthropic) to mean "uncapped"
	Vision         bool    `json:"vision"`
	PDF            bool    `json:"pdf,omitempty"` // accepts PDFs natively on the LLM call (document block / input_file / inline blob)
	Reasoning      bool    `json:"reasoning"`
	Pinnable       bool    `json:"pinnable,omitempty"` // offered in the /model picker
	Group          string  `json:"group,omitempty"`    // picker display family ("OpenAI", "Kimi", …)
	PriceIn        float64 `json:"price_in,omitempty"` // $/M tokens
	PriceOut       float64 `json:"price_out,omitempty"`
	PriceCacheRead float64 `json:"price_cache_read,omitempty"` // optional override (default in×0.1)

	// Fallback is the model's mid-turn failure chain, in LABELS: who covers
	// when this model errors after transport retries, walked IN ORDER by the
	// CLI's recovery executor (availability/billing filtering happens at walk
	// time, client-side). Data, not Go — the routing doctrine lives here.
	Fallback []string `json:"fallback,omitempty"`
}

CatalogModel is one models.json entry: a model's identity and its static facts. A zero Window or zero pricing means "not declared here" — lookups fall through to the family rules, then the defaults.

func CatalogModels

func CatalogModels() []CatalogModel

CatalogModels returns every models.json entry in file order (the display order).

func LookupModel

func LookupModel(idOrLabel string) (CatalogModel, bool)

LookupModel resolves a raw id or a client-facing label to its catalog entry.

type Pricing

type Pricing struct{ Input, Output, CacheWrite, CacheRead float64 }

Pricing is APPROXIMATE per-model rates in USD per MILLION tokens. Cache write ≈ 1.25× base input; cache read ≈ 0.1× base input unless the catalog overrides it.

func ModelPricing

func ModelPricing(model string) Pricing

ModelPricing returns the rate card for a model id or label: the catalog entry if it declares one, else the first matching family rule, else the default. Both ledgers price against this (the CLI's and the gateway's), so every id that can serve must resolve to a non-zero card — the family floor guarantees Fireworks-served ids are never $0.