registry

package
v7.3.13 Latest Latest
Warning

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

Go to latest
Published: Sep 22, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package registry provides model definitions and lookup helpers for various AI providers. Static model metadata is loaded from the embedded models.json file and can be refreshed from network.

Package registry provides centralized model management for all AI service providers. It implements a dynamic model registry with reference counting to track active clients and automatically hide models when no clients are available or when quota is exceeded.

Index

Constants

View Source
const (
	DefaultClaudeMaxInputTokens  = 200000
	DefaultClaudeMaxOutputTokens = 64000
)
View Source
const OpenAIImageModelType = "openai-image"

OpenAIImageModelType marks models that are callable through OpenAI-compatible image endpoints.

Variables

This section is empty.

Functions

func AntigravityWebSearchModelFor added in v7.1.74

func AntigravityWebSearchModelFor(modelID string) string

AntigravityWebSearchModelFor returns the Antigravity model that should run a native web search request for modelID.

func GetCodexClientModelsJSON added in v7.1.4

func GetCodexClientModelsJSON() []byte

GetCodexClientModelsJSON returns the current Codex client model catalog.

func GetCodexClientModelsRevision added in v7.2.132

func GetCodexClientModelsRevision() uint64

GetCodexClientModelsRevision returns the current revision of the Codex client model catalog.

func GetCodexClientModelsSnapshot added in v7.2.72

func GetCodexClientModelsSnapshot() ([]byte, uint64)

GetCodexClientModelsSnapshot returns a consistent catalog copy and revision. The revision changes only when validated catalog content changes.

func GetDevinModelsJSON added in v7.3.0

func GetDevinModelsJSON() []byte

GetDevinModelsJSON returns the current raw JSON payload of the Devin model catalog.

func GetDevinModelsRevision added in v7.3.0

func GetDevinModelsRevision() uint64

GetDevinModelsRevision returns the revision counter of the Devin model catalog.

func GetDevinModelsSnapshot added in v7.3.0

func GetDevinModelsSnapshot() ([]byte, uint64)

GetDevinModelsSnapshot returns a copy of raw JSON and current catalog revision.

func ModelOverrideHeaders added in v7.2.58

func ModelOverrideHeaders(modelID string, provider ...string) map[string]string

ModelOverrideHeaders returns models.json config.override_header for the model, if any. The returned map is a defensive copy and may be empty but never nil when overrides exist.

func ResolveResponsesWebSearchCapability added in v7.3.1

func ResolveResponsesWebSearchCapability(routes []NativeCapabilityRoute) *bool

ResolveResponsesWebSearchCapability conservatively resolves native web search across every route that can serve a public model. A known unsupported route or explicit model-level false wins; missing/unknown data produces unknown.

func SetModelRefreshCallback

func SetModelRefreshCallback(cb ModelRefreshCallback)

SetModelRefreshCallback registers a callback that is invoked when startup or periodic model refresh detects changes. Only one callback is supported; subsequent calls replace the previous callback.

func StartCodexClientModelsUpdater added in v7.2.72

func StartCodexClientModelsUpdater(ctx context.Context)

StartCodexClientModelsUpdater starts a background updater that fetches the Codex client model catalog immediately and then refreshes it every 3 hours. Safe to call multiple times; only one updater will run.

func StartDevinModelsUpdater added in v7.3.0

func StartDevinModelsUpdater(ctx context.Context)

StartDevinModelsUpdater starts a background updater that fetches the Devin model catalog immediately and refreshes it every 3 hours. Safe to call multiple times; only one updater runs.

func StartModelsUpdater

func StartModelsUpdater(ctx context.Context)

StartModelsUpdater starts a background updater that fetches models immediately on startup and then refreshes the model catalog every 3 hours. Safe to call multiple times; only one updater will run.

func ValidateCodexClientModelsJSON added in v7.2.72

func ValidateCodexClientModelsJSON(data []byte) error

ValidateCodexClientModelsJSON validates the fields required to serve a complete Codex client model catalog.

Types

type ClientModelProjection added in v7.2.146

type ClientModelProjection struct {
	ModelID       string
	Suspended     bool
	SuspendReason string
	QuotaExceeded bool
}

ClientModelProjection describes the desired availability and quota state for a client's model.

type ModelConfig added in v7.2.58

type ModelConfig struct {
	// OverrideHeader forces upstream request headers when non-empty.
	// Keys are header names (e.g. "user-agent"); values replace any existing header.
	OverrideHeader map[string]string `json:"override_header,omitempty"`
}

ModelConfig holds optional runtime overrides for a model definition.

type ModelInfo

type ModelInfo struct {
	// ID is the unique identifier for the model
	ID string `json:"id"`
	// MetadataModelID identifies the canonical model used to resolve client metadata.
	// It is internal and must not be exposed in model-list responses.
	MetadataModelID string `json:"-"`
	// ExplicitThinking indicates thinking/reasoning configuration was explicitly configured for this model.
	ExplicitThinking bool `json:"-"`
	// ExplicitInputModalities indicates input modalities were explicitly configured for this model.
	ExplicitInputModalities bool `json:"-"`
	// Object type for the model (typically "model")
	Object string `json:"object"`
	// Created timestamp when the model was created
	Created int64 `json:"created"`
	// OwnedBy indicates the organization that owns the model
	OwnedBy string `json:"owned_by"`
	// Type indicates the model type (e.g., "claude", "gemini", "openai")
	Type string `json:"type"`
	// DisplayName is the human-readable name for the model
	DisplayName string `json:"display_name,omitempty"`
	// Name is used for Gemini-style model names
	Name string `json:"name,omitempty"`
	// Version is the model version
	Version string `json:"version,omitempty"`
	// Description provides detailed information about the model
	Description string `json:"description,omitempty"`
	// InputTokenLimit is the maximum input token limit
	InputTokenLimit int `json:"inputTokenLimit,omitempty"`
	// OutputTokenLimit is the maximum output token limit
	OutputTokenLimit int `json:"outputTokenLimit,omitempty"`
	// SupportedGenerationMethods lists supported generation methods
	SupportedGenerationMethods []string `json:"supportedGenerationMethods,omitempty"`
	// ContextLength is the context window size
	ContextLength int `json:"context_length,omitempty"`
	// MaxContextLength is an explicit per-model context window override from configuration.
	// It is carried internally for Codex client model catalog generation.
	MaxContextLength int `json:"-"`
	// MaxCompletionTokens is the maximum completion tokens
	MaxCompletionTokens int `json:"max_completion_tokens,omitempty"`
	// SupportedParameters lists supported parameters
	SupportedParameters []string `json:"supported_parameters,omitempty"`
	// SupportedInputModalities lists supported input modalities (e.g., TEXT, IMAGE, VIDEO, AUDIO)
	SupportedInputModalities []string `json:"supportedInputModalities,omitempty"`
	// SupportedOutputModalities lists supported output modalities (e.g., TEXT, IMAGE)
	SupportedOutputModalities []string `json:"supportedOutputModalities,omitempty"`
	// SupportsWebSearch indicates this Antigravity model is listed by
	// fetchAvailableModels.webSearchModelIds and can execute native googleSearch.
	SupportsWebSearch bool `json:"supports_web_search,omitempty"`

	// NativeCapabilities contains internal, static per-model capability metadata.
	// It is intentionally separate from Antigravity's dynamically probed capability.
	NativeCapabilities *NativeCapabilities `json:"-"`

	// Thinking holds provider-specific reasoning/thinking budget capabilities.
	// This is optional and currently used for Gemini thinking budget normalization.
	Thinking *ThinkingSupport `json:"thinking,omitempty"`

	// Config holds model-specific runtime overrides loaded from models.json.
	Config *ModelConfig `json:"config,omitempty"`

	// UserDefined indicates this model was defined through config file's models[]
	// array (e.g., openai-compatibility.*.models[], *-api-key.models[]).
	// UserDefined models have thinking configuration passed through without validation.
	UserDefined bool `json:"-"`

	// IsCompat enables compatibility handling for this configured API-key model.
	// It is internal metadata and is not exposed in model listings.
	IsCompat bool `json:"-"`
}

ModelInfo represents information about an available model

func GetAIStudioModels

func GetAIStudioModels() []*ModelInfo

GetAIStudioModels returns model definitions for AI Studio.

func GetAntigravityModels

func GetAntigravityModels() []*ModelInfo

GetAntigravityModels returns the standard Antigravity model definitions.

func GetClaudeModels

func GetClaudeModels() []*ModelInfo

GetClaudeModels returns the standard Claude model definitions.

func GetCodexFreeModels

func GetCodexFreeModels() []*ModelInfo

GetCodexFreeModels returns model definitions for the Codex free plan tier.

func GetCodexPlusModels

func GetCodexPlusModels() []*ModelInfo

GetCodexPlusModels returns model definitions for the Codex plus plan tier.

func GetCodexProModels

func GetCodexProModels() []*ModelInfo

GetCodexProModels returns model definitions for the Codex pro plan tier.

func GetCodexTeamModels

func GetCodexTeamModels() []*ModelInfo

GetCodexTeamModels returns model definitions for the Codex team plan tier.

func GetDevinModels added in v7.3.0

func GetDevinModels() []*ModelInfo

GetDevinModels returns the active Devin model catalog. It prioritizes the dynamic/embedded devin_models.json catalog, then models.json's devin section, and finally hardcoded staticDevinModels.

func GetGeminiModels

func GetGeminiModels() []*ModelInfo

GetGeminiModels returns the standard Gemini model definitions.

func GetGeminiVertexModels

func GetGeminiVertexModels() []*ModelInfo

GetGeminiVertexModels returns Gemini model definitions for Vertex AI.

func GetKimiModels

func GetKimiModels() []*ModelInfo

GetKimiModels returns the standard Kimi (Moonshot AI) model definitions.

func GetMetaModels added in v7.3.4

func GetMetaModels() []*ModelInfo

GetMetaModels returns the standard Meta Muse model definitions.

func GetStaticModelDefinitionsByChannel

func GetStaticModelDefinitionsByChannel(channel string) []*ModelInfo

GetStaticModelDefinitionsByChannel returns static model definitions for a given channel/provider. It returns nil when the channel is unknown.

Supported channels:

  • claude
  • gemini
  • gemini-interactions
  • vertex
  • aistudio
  • codex
  • kimi
  • antigravity
  • xai
  • devin
  • meta

func GetXAIModels added in v7.1.0

func GetXAIModels() []*ModelInfo

GetXAIModels returns the standard xAI Grok model definitions.

func LookupDevinModel added in v7.3.0

func LookupDevinModel(modelID string) *ModelInfo

LookupDevinModel looks up a model definition from the active Devin catalog. Accepts both namespaced ("devin/model") and bare ("model") IDs.

func LookupModelInfo

func LookupModelInfo(modelID string, provider ...string) *ModelInfo

LookupModelInfo searches dynamic registry (provider-specific > global) then static definitions.

func LookupStaticModelInfo

func LookupStaticModelInfo(modelID string) *ModelInfo

LookupStaticModelInfo searches all static model definitions for a model by ID. Returns nil if no matching model is found.

func LookupStaticModelInfoByChannel added in v7.3.1

func LookupStaticModelInfoByChannel(modelID, channel string) *ModelInfo

LookupStaticModelInfoByChannel searches one provider-specific static section. It does not fall back across providers, so callers can preserve provenance.

func ValidateDevinModelsJSON added in v7.3.0

func ValidateDevinModelsJSON(data []byte) ([]*ModelInfo, error)

ValidateDevinModelsJSON parses and validates a Devin model catalog payload. Accepts {"devin": [...]}, {"models": [...]}, or a direct JSON array of ModelInfo.

func WithCodexBuiltins

func WithCodexBuiltins(models []*ModelInfo) []*ModelInfo

WithCodexBuiltins injects hard-coded Codex-only model definitions that should not depend on remote models.json updates. Built-ins replace any matching IDs already present in the provided slice.

func WithXAIBuiltins added in v7.1.1

func WithXAIBuiltins(models []*ModelInfo) []*ModelInfo

WithXAIBuiltins injects hard-coded xAI image/video model definitions that should not depend on remote models.json updates.

func (*ModelInfo) UnmarshalJSON added in v7.3.1

func (m *ModelInfo) UnmarshalJSON(data []byte) error

UnmarshalJSON loads internal native capability metadata without exposing it through ModelInfo's normal JSON serialization.

type ModelRefreshCallback

type ModelRefreshCallback func(changedProviders []string)

ModelRefreshCallback is invoked when startup or periodic model refresh detects changes. changedProviders contains the provider names whose model definitions changed.

type ModelRegistration

type ModelRegistration struct {
	// Info contains the model metadata
	Info *ModelInfo
	// InfoByProvider maps provider identifiers to specific ModelInfo to support differing capabilities.
	InfoByProvider map[string]*ModelInfo
	// Count is the number of active clients that can provide this model
	Count int
	// LastUpdated tracks when this registration was last modified
	LastUpdated time.Time
	// QuotaExceededClients tracks which clients have exceeded quota for this model
	QuotaExceededClients map[string]*time.Time
	// Providers tracks available clients grouped by provider identifier
	Providers map[string]int
	// SuspendedClients tracks temporarily disabled clients keyed by client ID
	SuspendedClients map[string]string
}

ModelRegistration tracks a model's availability

type ModelRegistry

type ModelRegistry struct {
	// contains filtered or unexported fields
}

ModelRegistry manages the global registry of available models

func GetGlobalRegistry

func GetGlobalRegistry() *ModelRegistry

GetGlobalRegistry returns the global model registry instance

func (*ModelRegistry) ApplyClientModelCapabilities added in v7.2.156

func (r *ModelRegistry) ApplyClientModelCapabilities(clientID string, expectedEpoch uint64, mutate func(modelID string, info *ModelInfo)) bool

ApplyClientModelCapabilities applies capability mutations to matching models of clientID if the client is currently registered and its registration epoch matches expectedEpoch. Returns true if applied, false if client is unregistered or epoch changed.

func (*ModelRegistry) ApplyClientModelProjections added in v7.2.146

func (r *ModelRegistry) ApplyClientModelProjections(clientID string, epoch uint64, generation uint64, projections []ClientModelProjection) bool

ApplyClientModelProjections atomically applies model suspension and quota exceeded state for clientID if the supplied epoch and generation are current. Stale or mismatched epoch (!= current client epoch) or stale generation (< current client generation), or projections for unregistered clients/models are rejected.

func (*ModelRegistry) CleanupExpiredQuotas

func (r *ModelRegistry) CleanupExpiredQuotas()

CleanupExpiredQuotas removes expired quota tracking entries

func (*ModelRegistry) ClearModelQuotaExceeded

func (r *ModelRegistry) ClearModelQuotaExceeded(clientID, modelID string)

ClearModelQuotaExceeded removes quota exceeded status for a model and client Parameters:

  • clientID: The client to clear quota status for
  • modelID: The model to clear quota status for

func (*ModelRegistry) ClientRegistrationEpoch added in v7.2.146

func (r *ModelRegistry) ClientRegistrationEpoch(clientID string) uint64

ClientRegistrationEpoch returns the current registration epoch for clientID.

func (*ModelRegistry) ClientSupportsModel

func (r *ModelRegistry) ClientSupportsModel(clientID, modelID string) bool

ClientSupportsModel reports whether the client registered support for modelID.

func (*ModelRegistry) GetAvailableModelInfos added in v7.2.117

func (r *ModelRegistry) GetAvailableModelInfos() []*ModelInfo

GetAvailableModelInfos returns cloned metadata for all currently available models.

func (*ModelRegistry) GetAvailableModels

func (r *ModelRegistry) GetAvailableModels(handlerType string) []map[string]any

GetAvailableModels returns all models that have at least one available client Parameters:

  • handlerType: The handler type to filter models for (e.g., "openai", "claude", "gemini")

Returns:

  • []map[string]any: List of available models in the requested format

func (*ModelRegistry) GetAvailableModelsByProvider

func (r *ModelRegistry) GetAvailableModelsByProvider(provider string) []*ModelInfo

GetAvailableModelsByProvider returns models available for the given provider identifier. Parameters:

  • provider: Provider identifier (e.g., "codex", "gemini", "antigravity")

Returns:

  • []*ModelInfo: List of available models for the provider

func (*ModelRegistry) GetFirstAvailableModel

func (r *ModelRegistry) GetFirstAvailableModel(handlerType string) (string, error)

GetFirstAvailableModel returns the first available model for the given handler type. It prioritizes models by their creation timestamp (newest first) and checks if they have available clients that are not suspended or over quota.

Parameters:

  • handlerType: The API handler type (e.g., "openai", "claude", "gemini")

Returns:

  • string: The model ID of the first available model, or empty string if none available
  • error: An error if no models are available

func (*ModelRegistry) GetGeneration added in v7.2.132

func (r *ModelRegistry) GetGeneration() uint64

GetGeneration returns the current generation counter of model registrations.

func (*ModelRegistry) GetModelCount

func (r *ModelRegistry) GetModelCount(modelID string) int

GetModelCount returns the number of available clients for a specific model Parameters:

  • modelID: The model ID to check

Returns:

  • int: Number of available clients for the model

func (*ModelRegistry) GetModelInfo

func (r *ModelRegistry) GetModelInfo(modelID, provider string) *ModelInfo

GetModelInfo returns ModelInfo, prioritizing provider-specific definition if available.

func (*ModelRegistry) GetModelProviders

func (r *ModelRegistry) GetModelProviders(modelID string) []string

GetModelProviders returns provider identifiers that currently supply the given model Parameters:

  • modelID: The model ID to check

Returns:

  • []string: Provider identifiers ordered by availability count (descending)

func (*ModelRegistry) GetModelsAndEpochForClient added in v7.2.146

func (r *ModelRegistry) GetModelsAndEpochForClient(clientID string) ([]*ModelInfo, uint64)

GetModelsAndEpochForClient atomically returns the models registered for clientID along with the client's current registration epoch.

func (*ModelRegistry) GetModelsForClient

func (r *ModelRegistry) GetModelsForClient(clientID string) []*ModelInfo

GetModelsForClient returns the models registered for a specific client. Parameters:

  • clientID: The client identifier (typically auth file name or auth ID)

Returns:

  • []*ModelInfo: List of models registered for this client, nil if client not found

func (*ModelRegistry) GetResponsesWebSearchCapability added in v7.3.1

func (r *ModelRegistry) GetResponsesWebSearchCapability(modelID string) *bool

GetResponsesWebSearchCapability resolves capability metadata across every registered client route for the exact public model ID.

func (*ModelRegistry) IsModelQuotaExceededForClient added in v7.2.146

func (r *ModelRegistry) IsModelQuotaExceededForClient(clientID, modelID string) bool

IsModelQuotaExceededForClient reports whether a model is currently marked quota exceeded for a specific client.

func (*ModelRegistry) IsModelSuspendedForClient added in v7.2.146

func (r *ModelRegistry) IsModelSuspendedForClient(clientID, modelID string) bool

IsModelSuspendedForClient reports whether a model is currently suspended for a specific client.

func (*ModelRegistry) RegisterClient

func (r *ModelRegistry) RegisterClient(clientID, clientProvider string, models []*ModelInfo)

RegisterClient registers a client and its supported models Parameters:

  • clientID: Unique identifier for the client
  • clientProvider: Provider name (e.g., "gemini", "claude", "openai")
  • models: List of models that this client can provide

func (*ModelRegistry) RegistrationEpoch added in v7.3.10

func (r *ModelRegistry) RegistrationEpoch() uint64

RegistrationEpoch returns a monotonically increasing epoch that increments whenever client model registrations or deregistrations occur.

func (*ModelRegistry) ResumeClientModel

func (r *ModelRegistry) ResumeClientModel(clientID, modelID string)

ResumeClientModel clears a previous suspension so the client counts toward availability again. Parameters:

  • clientID: The client to resume
  • modelID: The model being resumed

func (*ModelRegistry) SetHook

func (r *ModelRegistry) SetHook(hook ModelRegistryHook)

SetHook sets an optional hook for observing model registration changes.

func (*ModelRegistry) SetModelQuotaExceeded

func (r *ModelRegistry) SetModelQuotaExceeded(clientID, modelID string)

SetModelQuotaExceeded marks a model as quota exceeded for a specific client Parameters:

  • clientID: The client that exceeded quota
  • modelID: The model that exceeded quota

func (*ModelRegistry) SuspendClientModel

func (r *ModelRegistry) SuspendClientModel(clientID, modelID, reason string)

SuspendClientModel marks a client's model as temporarily unavailable until explicitly resumed. Parameters:

  • clientID: The client to suspend
  • modelID: The model affected by the suspension
  • reason: Optional description for observability

func (*ModelRegistry) UnregisterClient

func (r *ModelRegistry) UnregisterClient(clientID string)

UnregisterClient removes a client and decrements counts for its models Parameters:

  • clientID: Unique identifier for the client to remove

type ModelRegistryHook

type ModelRegistryHook interface {
	OnModelsRegistered(ctx context.Context, provider, clientID string, models []*ModelInfo)
	OnModelsUnregistered(ctx context.Context, provider, clientID string)
}

ModelRegistryHook provides optional callbacks for external integrations to track model list changes. Hook implementations must be non-blocking and resilient; calls are executed asynchronously and panics are recovered.

type NativeCapabilities added in v7.3.1

type NativeCapabilities struct {
	// WebSearch reports explicit per-model support for native web search.
	// nil means the catalog has not established support either way.
	WebSearch *bool `json:"web_search,omitempty"`
}

NativeCapabilities contains tri-state native capability metadata from the catalog.

type NativeCapabilityRoute added in v7.3.1

type NativeCapabilityRoute struct {
	Provider           string
	NativeCapabilities *NativeCapabilities
}

NativeCapabilityRoute describes one registered route to a public model.

type ThinkingSupport

type ThinkingSupport struct {
	// Min is the minimum allowed thinking budget (inclusive).
	Min int `json:"min,omitempty" yaml:"min,omitempty"`
	// Max is the maximum allowed thinking budget (inclusive).
	Max int `json:"max,omitempty" yaml:"max,omitempty"`
	// ZeroAllowed indicates whether 0 is a valid value (to disable thinking).
	ZeroAllowed bool `json:"zero_allowed,omitempty" yaml:"zero-allowed,omitempty"`
	// DynamicAllowed indicates whether -1 is a valid value (dynamic thinking budget).
	DynamicAllowed bool `json:"dynamic_allowed,omitempty" yaml:"dynamic-allowed,omitempty"`
	// Levels defines discrete reasoning effort levels (e.g., "low", "medium", "high").
	// When set, the model uses level-based reasoning instead of token budgets.
	Levels []string `json:"levels,omitempty" yaml:"levels,omitempty"`
}

ThinkingSupport describes a model family's supported internal reasoning budget range. Values are interpreted in provider-native token units.

Jump to

Keyboard shortcuts

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