Documentation
¶
Overview ¶
Package reasoning models how each provider's models expose reasoning-effort control. Providers disagree on the concept — OpenAI uses a discrete effort enum, Anthropic and Gemini 2.5 use a thinking-token budget, some models only toggle thinking on/off — so a single flat effort string cannot describe them.
Capability is the typed, per-model description of that control, sourced from a community capability catalog (models.dev). It is the data the rest of Zero consults to decide which reasoning tiers a model actually supports, replacing model-name guessing. This package depends only on the standard library, so the model registry and provider adapters can import it without a cycle.
Source of truth: this catalog is intended to become the authoritative reasoning -capability source. When it is wired into the live path, modelregistry's name-pattern inference (reasoningEffortsForModelName) is demoted to a fallback for models the catalog does not cover; the catalog wins where it has an entry. This commit is additive groundwork — nothing consumes it yet — so there is no behavioral divergence until that wiring lands.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Capability ¶
type Capability struct {
Reasoning bool `json:"reasoning"`
Controls []Control `json:"reasoning_options,omitempty"`
}
Capability is the reasoning capability of a single model: whether it reasons at all, and through which controls. A model may carry more than one control (e.g. a newer Claude model exposes both an effort enum and a token budget); a reasoning model with no controls reasons but exposes no knob (always-on).
func (Capability) BudgetControl ¶
func (c Capability) BudgetControl() (Control, bool)
BudgetControl returns the model's token-budget control and whether it has one. The returned Control is a deep copy: its Min/Max are independent pointers, so a caller cannot mutate the shared catalog through them. Min/Max are nil when that bound is unspecified (a real 0, e.g. Gemini's min: 0, is a non-nil pointer to 0).
func (Capability) EffortControl ¶
func (c Capability) EffortControl() (Control, bool)
EffortControl returns the model's effort control and whether it has one. The returned Control is a deep copy, so a caller cannot mutate the shared catalog through its Values slice.
func (Capability) EffortValues ¶
func (c Capability) EffortValues() []string
EffortValues returns the ordered effort tiers the model accepts, or nil when it has no effort control (a budget- or toggle-only model, or a non-reasoning model).
func (Capability) HasControl ¶
func (c Capability) HasControl(kind ControlKind) bool
HasControl reports whether the model exposes a control of the given kind.
func (Capability) Supported ¶
func (c Capability) Supported() bool
Supported reports whether the model performs any reasoning.
func (Capability) SupportsEffort ¶
func (c Capability) SupportsEffort(tier string) bool
SupportsEffort reports whether tier is one of the model's accepted effort values (case-insensitive).
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog is a reasoning-capability lookup keyed by provider slug and api model id. It is read-only after construction.
func Embedded ¶
func Embedded() Catalog
Embedded returns the catalog parsed from the bundled models.dev snapshot.
func ParseCatalog ¶
ParseCatalog builds a Catalog from a models.dev-style snapshot document.
func (Catalog) Lookup ¶
func (c Catalog) Lookup(provider, apiModel string) (Capability, bool)
Lookup returns the reasoning capability for a model identified by its Zero provider kind and the API model id — the provider's wire name (e.g. "claude-opus-4-1-20250805"), NOT the friendly registry id ("claude-opus-4.1"). The match is exact: the api model id is only trimmed, not case-folded, and no router prefixes ("openai/…") or suffixes (":cloud") are stripped. ok is false when the provider or model is not in the snapshot, in which case the caller falls back to its next capability source.
type Control ¶
type Control struct {
Kind ControlKind `json:"type"`
Values []string `json:"values,omitempty"`
Min *int `json:"min,omitempty"`
Max *int `json:"max,omitempty"`
}
Control is one reasoning control a model accepts. For an effort control, Values lists the accepted tiers ordered weakest to strongest. For a budget control, Min/Max bound the thinking-token budget; each is nil when the provider does not bound that side, kept distinct from an explicit 0 (Gemini uses min: 0 to mean "thinking can be disabled", which a plain int would lose).
type ControlKind ¶
type ControlKind string
ControlKind enumerates how a model exposes reasoning control. The values mirror the models.dev reasoning_options[].type field.
const ( // ControlEffort is a discrete effort enum (OpenAI reasoning_effort, Gemini 3 // thinkingLevel, newer Claude output_config.effort). ControlEffort ControlKind = "effort" // ControlBudget is a thinking-token budget (Gemini 2.5 thinkingBudget, legacy // Claude thinking.budget_tokens). ControlBudget ControlKind = "budget_tokens" // ControlToggle is an on/off thinking switch with no levels. ControlToggle ControlKind = "toggle" )
Source Files