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 MinReasoningEffort(model string) string
• 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 PriceTier
• type Pricing
  • func ModelPricing(model string) Pricing
  • func ModelPricingAt(model string, promptTokens int) 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. Token counts here are cache-EXCLUSIVE (see compat.applyUsage), so the prompt that decides the tier is the sum of all three input components.

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 MinReasoningEffort

func MinReasoningEffort(model string) string

MinReasoningEffort returns the lowest reasoning effort a model accepts, or "" when the catalog declares no floor. Adapters clamp against it so a cheap classifier turn can't 400 on a model whose range starts above "none".

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)

	// PriceTiers bends the rate card by PROMPT SIZE. Several vendors now price a
	// long prompt differently from a short one (GPT-6 Astra doubles input and
	// adds half again to output past 272K), and that is a per-request fact, not a
	// per-model one. Expressing it as ordered multiplier data — rather than a
	// special case in Go — keeps the rule where every consumer already reads it:
	// this file is shared verbatim with the gateway and with apps/www's own
	// calculateCost, and only one of those three can run Go.
	PriceTiers []PriceTier `json:"price_tiers,omitempty"`

	// MinReasoningEffort is the LOWEST reasoning effort this model accepts, in the
	// vendor's own vocabulary. Vendors disagree about the bottom of the range —
	// GPT-5.6 takes "none", GPT-6 Astra's floor is "low" and 400s below it — and
	// that is a model fact, so it lives here rather than as another adapter bool.
	// Empty means "no floor": send whatever the effort maps to.
	MinReasoningEffort string `json:"min_reasoning_effort,omitempty"`

	// 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 PriceTier

type PriceTier struct {
	AbovePromptTokens int     `json:"above_prompt_tokens"`
	In                float64 `json:"in,omitempty"`
	Out               float64 `json:"out,omitempty"`
	CacheRead         float64 `json:"cache_read,omitempty"`
	CacheWrite        float64 `json:"cache_write,omitempty"`
}

PriceTier is one prompt-size pricing band: once a request's prompt exceeds AbovePromptTokens, every rate on the card is multiplied for the WHOLE request (not just the tokens past the line — that is how vendors actually bill it).

A multiplier left at 0 means 1× (unchanged), so a tier states only what it bends. Tiers are independent: the highest threshold a prompt clears wins, so order in JSON doesn't matter and a vendor can declare as many bands as it likes.

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 a model's BASE rate card — the short-prompt rates, before any prompt-size tier applies. Estimates and rate displays want this; anything billing a real request must use ModelPricingAt so a long prompt prices right.

func ModelPricingAt

func ModelPricingAt(model string, promptTokens int) Pricing

ModelPricingAt returns the rate card that actually governs a request whose prompt is promptTokens long — base card with the winning tier's multipliers folded in. promptTokens is the WHOLE prompt: fresh input plus cache reads plus cache writes, since vendors measure the threshold against everything they read.