modelregistry

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 6, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source
const DefaultModelID = "gpt-4.1"
View Source
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

func AgentContextWindow(resolved int) int

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 EnableModelsDevOverlay added in v0.2.0

func EnableModelsDevOverlay()

EnableModelsDevOverlay opts the process into applying the cached models.dev snapshot on top of the curated catalog. The CLI entrypoint calls it; library consumers and tests that never do get the curated catalog byte-identical to before, so hermetic tests can't be perturbed by a cache file on the machine. ZERO_DISABLE_MODELS_FETCH disables both the overlay and the fetch.

func FormatCostUSD

func FormatCostUSD(cost float64) (string, error)

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 RefreshModelsDevCache added in v0.2.0

func RefreshModelsDevCache(ctx context.Context) error

RefreshModelsDevCache fetches models.dev/api.json into the on-disk cache when the cache is missing or older than modelsDevRefreshAfter. It is safe to call fire-and-forget from startup (use a goroutine); it never affects the current process's registry (see cachedModelsDevProviders). Disabled entirely by ZERO_DISABLE_MODELS_FETCH. The URL can be overridden with ZERO_MODELS_URL.

func SupportsVision

func SupportsVision(registry Registry, modelID string) bool

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

func VisionCapableByName(modelID string) bool

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 ContextLimits struct {
	ContextWindow   int
	MaxOutputTokens int
}

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

func LookupMode(name string) (Mode, bool)

LookupMode returns the preset registered under name (case-insensitive, whitespace-trimmed). The second result reports whether a preset matched.

func Modes

func Modes() []Mode

Modes returns a copy of the preset catalog, preserving declaration order so list output and help text stay stable.

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
}

func (ModelCost) Validate

func (cost ModelCost) Validate() error

type ModelCostTier

type ModelCostTier struct {
	UpToInputTokens       int
	InputPerMillion       float64
	OutputPerMillion      float64
	CachedInputPerMillion float64
	CacheWritePerMillion  float64
	Note                  string
}

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 DefaultRegistry() (Registry, error)

func NewRegistry

func NewRegistry(entries []ModelEntry) (Registry, error)

func (Registry) EstimateCost

func (registry Registry) EstimateCost(pattern string, usage zeroruntime.Usage) (CostBreakdown, error)

func (Registry) Get

func (registry Registry) Get(pattern string) (ModelEntry, bool)

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) Require

func (registry Registry) Require(pattern string) (ModelEntry, error)

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) ResolveID

func (registry Registry) ResolveID(pattern string) (string, bool)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL