Documentation
¶
Index ¶
- Constants
- func AgentContextWindow(resolved int) int
- func FormatCostUSD(cost float64) (string, error)
- func ModeNames() []string
- func SupportsVision(registry Registry, modelID string) bool
- func ValidModelCapability(capability ModelCapability) bool
- func ValidModelStatus(status ModelStatus) bool
- func ValidPrimaryProviderKind(provider ProviderKind) bool
- func ValidReasoningEffort(effort ReasoningEffort) bool
- func ValidRuntimeProviderKind(provider ProviderKind) bool
- func VisionCapableByName(modelID string) bool
- type ContextLimits
- type CostBreakdown
- type DeprecationRule
- type ListOptions
- type Mode
- type ModelCapabilities
- type ModelCapability
- type ModelCost
- type ModelCostTier
- type ModelEntry
- type ModelStatus
- type ProviderKind
- type ReasoningEffort
- type Registry
- func (registry Registry) EstimateCost(pattern string, usage zeroruntime.Usage) (CostBreakdown, error)
- func (registry Registry) Get(pattern string) (ModelEntry, bool)
- func (registry Registry) List(options ListOptions) []ModelEntry
- func (registry Registry) ListByCapability(capability ModelCapability) []ModelEntry
- func (registry Registry) ListByProvider(provider ProviderKind) []ModelEntry
- func (registry Registry) ReasoningEfforts(pattern string) []ReasoningEffort
- func (registry Registry) Require(pattern string) (ModelEntry, error)
- func (registry Registry) RequireProvider(pattern string, provider ProviderKind) (ModelEntry, error)
- func (registry Registry) Resolve(input string) (ModelEntry, bool)
- func (registry Registry) ResolveID(pattern string) (string, bool)
- func (registry Registry) ResolveWithFallback(input string) (ModelEntry, string, bool)
- func (registry Registry) SupportsCapability(pattern string, capability ModelCapability) bool
- func (registry Registry) UpgradeTarget(id string) (ModelEntry, bool)
Constants ¶
const DefaultModelID = "gpt-4.1"
const FallbackContextWindow = 200_000
FallbackContextWindow is the assumed context window (max input tokens) for a model that isn't in the curated registry and wasn't resolved from live provider discovery — e.g. proxy/custom models like the GPT-5 Codex, xAI, or Ollama-cloud variants. A positive value here is what enables agent-loop compaction (both the proactive ~80% trigger and the reactive post-overflow recovery) for those models; without it compaction stays disabled and long sessions overflow. It is only a backstop: an exact window from the registry or live discovery always wins.
Variables ¶
This section is empty.
Functions ¶
func AgentContextWindow ¶
AgentContextWindow turns a resolved context window into the value used to enable agent-loop compaction: the resolved window when known, else FallbackContextWindow so compaction is enabled even for uncatalogued models. Kept separate from the raw resolver so display gauges still show nothing (not a guessed denominator) when the real window is unknown.
func FormatCostUSD ¶
func ModeNames ¶
func ModeNames() []string
ModeNames returns the preset names in declaration order, handy for usage and error messages that need to list the valid modes.
func SupportsVision ¶
SupportsVision reports whether the model identified by modelID accepts image input. A model in the curated catalog is authoritative (its declared capability wins). For a model the catalog does NOT know — a custom / openai-compatible / ollama id that will never be in the catalog — it falls back to recognizing well-known multimodal families by name, so a real vision model still accepts images. A name outside those families stays refused (the previous "cannot confirm → drop" behavior), so text-only models are unaffected.
modelID is resolved through the registry's normal alias/pattern matching, so any spelling that Get accepts works here too. This helper is the single capability check shared by the headless (exec) and interactive (TUI) input surfaces; the warn-and-drop behavior lives at those call sites.
func ValidModelCapability ¶
func ValidModelCapability(capability ModelCapability) bool
func ValidModelStatus ¶
func ValidModelStatus(status ModelStatus) bool
func ValidPrimaryProviderKind ¶
func ValidPrimaryProviderKind(provider ProviderKind) bool
func ValidReasoningEffort ¶
func ValidReasoningEffort(effort ReasoningEffort) bool
func ValidRuntimeProviderKind ¶
func ValidRuntimeProviderKind(provider ProviderKind) bool
func VisionCapableByName ¶
VisionCapableByName reports whether modelID names a known multimodal family. It is conservative: it matches the established vision families and leaves everything else refused, so a false "supported" is unlikely. Used only as a fallback for models absent from the curated catalog.
Types ¶
type ContextLimits ¶
type CostBreakdown ¶
type CostBreakdown struct {
ModelID string
Provider ProviderKind
Currency string
InputTokens int
CachedInputTokens int
CacheWriteTokens int
OutputTokens int
ReasoningTokens int
InputCost float64
CachedInputCost float64
CacheWriteCost float64
OutputCost float64
TotalCost float64
PricingTier *ModelCostTier
}
func CalculateCost ¶
func CalculateCost(model ModelEntry, usage zeroruntime.Usage) (CostBreakdown, error)
type DeprecationRule ¶
type DeprecationRule struct {
FallbackID string // model id to redirect to
SoftDate string // ISO-8601: warn but keep working from this date
HardDate string // ISO-8601: treat as fully retired from this date
WarningMsg string // user-facing notice
}
DeprecationRule describes how a deprecated model is phased out and what to use instead. FallbackID is required; the date/warning fields are advisory.
func (*DeprecationRule) Clone ¶
func (rule *DeprecationRule) Clone() *DeprecationRule
Clone returns a deep copy of the rule (or nil).
type ListOptions ¶
type ListOptions struct {
IncludeDeprecated bool
Provider ProviderKind
Capability ModelCapability
}
type Mode ¶
type Mode struct {
Name string
Description string
Model string
Effort ReasoningEffort
MaxTurns int
// EnabledTools / DisabledTools optionally narrow the tool surface for the
// mode. Empty slices leave the existing tool selection untouched.
EnabledTools []string
DisabledTools []string
}
Mode bundles a model selection, reasoning effort, agent-loop turn budget, and an optional tool filter behind a single short name. Modes are presets that let callers switch the whole agent profile (smart/deep/fast/...) with one flag or command instead of tuning --model/--reasoning-effort/--max-turns by hand.
Model holds a registry id or alias (resolved through Resolve/ResolveWithFallback at apply time so deprecation fallbacks and fuzzy aliases stay honored). MaxTurns of 0 means "leave the configured/default turn budget untouched". Effort of "" means "let the model's effective default apply".
func LookupMode ¶
LookupMode returns the preset registered under name (case-insensitive, whitespace-trimmed). The second result reports whether a preset matched.
type ModelCapabilities ¶
type ModelCapabilities []ModelCapability
type ModelCapability ¶
type ModelCapability string
const ( ModelCapabilityChat ModelCapability = "chat" ModelCapabilityStreaming ModelCapability = "streaming" ModelCapabilityToolCalling ModelCapability = "tool-calling" ModelCapabilityVision ModelCapability = "vision" ModelCapabilityJSONMode ModelCapability = "json-mode" ModelCapabilityReasoning ModelCapability = "reasoning" ModelCapabilitySystemPrompt ModelCapability = "system-prompt" ModelCapabilityPromptCache ModelCapability = "prompt-cache" ModelCapabilityLongContext ModelCapability = "long-context" )
type ModelCost ¶
type ModelCost struct {
Currency string
Unit string
InputPerMillion float64
OutputPerMillion float64
CachedInputPerMillion float64
// CacheWritePerMillion is the cache-creation (cache-write) rate, billed at a
// premium over input by providers that support it (Anthropic ~1.25x input).
// Zero means "not priced separately" — cache-write tokens fall back to the
// input rate, preserving prior behavior for models without the rate.
CacheWritePerMillion float64
Tiers []ModelCostTier
Source string
SourceLastVerified string
Notes []string
}
type ModelCostTier ¶
type ModelEntry ¶
type ModelEntry struct {
ID string
DisplayName string
APIModel string
Provider ProviderKind
APIProviders []ProviderKind
ContextLimits ContextLimits
ReasoningEfforts []ReasoningEffort
// DefaultReasoningEffort is the effort used when the caller does not specify
// one (must be a member of ReasoningEfforts, or empty for non-reasoning models).
DefaultReasoningEffort ReasoningEffort
Capabilities ModelCapabilities
Cost ModelCost
Status ModelStatus
Aliases []string
// MatchPatterns are regular expressions that resolve fuzzy user input to this
// model (e.g. `sonnet[^a-z0-9]*4[.\s]?5` -> the canonical id).
MatchPatterns []string
// Deprecation, when set, redirects this model to a replacement.
Deprecation *DeprecationRule
// UpgradeTargetID, when set, names the stronger model this one escalates to
// during mid-run escalation. Empty means no escalation target (e.g. top-tier
// models). Resolved and availability-checked by Registry.UpgradeTarget.
UpgradeTargetID string
Description string
}
func DefaultModelEntries ¶
func DefaultModelEntries() []ModelEntry
func (ModelEntry) AllowsProvider ¶
func (model ModelEntry) AllowsProvider(provider ProviderKind) bool
func (ModelEntry) Supports ¶
func (model ModelEntry) Supports(capability ModelCapability) bool
func (ModelEntry) Validate ¶
func (model ModelEntry) Validate() error
type ModelStatus ¶
type ModelStatus string
const ( ModelStatusActive ModelStatus = "active" ModelStatusPreview ModelStatus = "preview" ModelStatusDeprecated ModelStatus = "deprecated" )
type ProviderKind ¶
type ProviderKind string
const ( ProviderOpenAI ProviderKind = "openai" ProviderAnthropic ProviderKind = "anthropic" ProviderGoogle ProviderKind = "google" ProviderOpenAICompatible ProviderKind = "openai-compatible" )
type ReasoningEffort ¶
type ReasoningEffort string
const ( ReasoningEffortNone ReasoningEffort = "none" ReasoningEffortMinimal ReasoningEffort = "minimal" ReasoningEffortLow ReasoningEffort = "low" ReasoningEffortMedium ReasoningEffort = "medium" ReasoningEffortHigh ReasoningEffort = "high" ReasoningEffortXHigh ReasoningEffort = "xhigh" // ReasoningEffortMax is the top tier some providers expose above xhigh (e.g. // newer Anthropic models). Defined so a capability catalog that lists "max" // has a constant to map to; no curated model lists it yet. ReasoningEffortMax ReasoningEffort = "max" )
func EffectiveReasoningEffort ¶
func EffectiveReasoningEffort(model ModelEntry, requested ReasoningEffort) ReasoningEffort
EffectiveReasoningEffort returns the effort to use for a model: the requested value if the model supports it, otherwise the model's default (or first supported, or none). It resolves the supported set through effectiveReasoningEfforts so it sees the same name-based fallback the /effort picker uses — the two must never disagree about which tiers a model supports.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
func DefaultRegistry ¶
func NewRegistry ¶
func NewRegistry(entries []ModelEntry) (Registry, error)
func (Registry) EstimateCost ¶
func (registry Registry) EstimateCost(pattern string, usage zeroruntime.Usage) (CostBreakdown, error)
func (Registry) List ¶
func (registry Registry) List(options ListOptions) []ModelEntry
func (Registry) ListByCapability ¶
func (registry Registry) ListByCapability(capability ModelCapability) []ModelEntry
func (Registry) ListByProvider ¶
func (registry Registry) ListByProvider(provider ProviderKind) []ModelEntry
func (Registry) ReasoningEfforts ¶
func (registry Registry) ReasoningEfforts(pattern string) []ReasoningEffort
func (Registry) RequireProvider ¶
func (registry Registry) RequireProvider(pattern string, provider ProviderKind) (ModelEntry, error)
func (Registry) Resolve ¶
func (registry Registry) Resolve(input string) (ModelEntry, bool)
Resolve maps user input to a model: exact id/api-model/alias first, then a regex MatchPattern (e.g. "sonnet 4.5" -> the canonical id). It does NOT apply deprecation fallbacks — use ResolveWithFallback for that.
func (Registry) ResolveWithFallback ¶
func (registry Registry) ResolveWithFallback(input string) (ModelEntry, string, bool)
ResolveWithFallback resolves input (exact/alias/pattern) and, when the resolved model is deprecated and declares a fallback, redirects to the replacement. The returned notice is non-empty when a redirect happened or a soft-deprecation warning applies, so callers can surface it to the user.
func (Registry) SupportsCapability ¶
func (registry Registry) SupportsCapability(pattern string, capability ModelCapability) bool
func (Registry) UpgradeTarget ¶
func (registry Registry) UpgradeTarget(id string) (ModelEntry, bool)
UpgradeTarget resolves the stronger model that id escalates to during mid-run escalation. It resolves id to a concrete entry, reads its UpgradeTargetID, resolves THAT to a concrete entry, and returns it only when the target is available and not deprecated. It returns (_, false) when id is unknown, has no configured target, or the target resolves to an unavailable/deprecated model. Pure and registry-only: applies no deprecation fallback redirection.