registry

package
v1.1.8 Latest Latest
Warning

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

Go to latest
Published: Nov 6, 2026 License: MIT Imports: 17 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 ModelsRefreshInterval = 3 * time.Hour

ModelsRefreshInterval is the shared cadence for model catalogs and account entitlements.

Variables

This section is empty.

Functions

func GetAllStaticModelDefinitions added in v1.0.26

func GetAllStaticModelDefinitions() map[string][]*ModelInfo

GetAllStaticModelDefinitions returns static model definitions grouped by channel.

func GetCodexClientModelsJSON added in v1.1.3

func GetCodexClientModelsJSON() []byte

GetCodexClientModelsJSON returns the current Codex client model catalog.

func GetCodexClientModelsRevision added in v1.1.3

func GetCodexClientModelsRevision() uint64

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

func GetCodexClientModelsSnapshot added in v1.1.3

func GetCodexClientModelsSnapshot() ([]byte, uint64)

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

func IsCodexBuiltinModelID added in v1.1.3

func IsCodexBuiltinModelID(id string) bool

IsCodexBuiltinModelID reports whether id names a hard-coded Codex built-in model.

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 StartModelCatalogUpdaters added in v1.1.3

func StartModelCatalogUpdaters(ctx context.Context, sources CatalogSources)

StartModelCatalogUpdaters binds process-wide readers to the Home lifetime.

func UpdateModelCatalogSources added in v1.1.3

func UpdateModelCatalogSources(sources CatalogSources)

UpdateModelCatalogSources updates an already-started process policy on reload. Updates before startup or after shutdown do not start readers.

func ValidateCodexClientModelsJSON added in v1.1.3

func ValidateCodexClientModelsJSON(data []byte) error

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

Types

type CatalogSources added in v1.1.3

type CatalogSources struct {
	Catalog      string `yaml:"catalog" json:"catalog,omitempty"`
	CodexCatalog string `yaml:"codex-catalog" json:"codex-catalog,omitempty"`
	DevinCatalog string `yaml:"devin-catalog" json:"devin-catalog,omitempty"`
}

CatalogSources overrides the source of each model catalog independently. Empty values retain the process default (embedded or official remote catalogs).

func (CatalogSources) Validate added in v1.1.3

func (m CatalogSources) Validate() error

Validate rejects relative paths and unsupported URL schemes.

type ModelInfo

type ModelInfo struct {
	// ID is the unique identifier for the model
	ID string `json:"id"`
	// 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"`
	// Providers lists the exact provider identifiers used by usage records and billing rules.
	Providers []string `json:"providers,omitempty"`
	// 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"`
	// 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"`

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

	// NativeCapabilities is forwarded to CPA for the selected dispatch route.
	NativeCapabilities *NativeCapabilities `json:"native_capabilities,omitempty"`

	// SupportConfigurationUpdate controls Responses input configuration updates.
	SupportConfigurationUpdate bool `json:"support_configuration_update,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:"-"`

	// ConfigDisplayName preserves an explicitly configured display-name across DB round trips.
	ConfigDisplayName string `json:"-"`

	// ForceMapping preserves the configured response model rewrite flag across DB round trips.
	ForceMapping bool `json:"-"`
}

ModelInfo represents information about an available model

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 v1.0.73

func GetDevinModels() []*ModelInfo

GetDevinModels returns the active Devin model catalog. It prefers the independent/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 v1.0.73

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
  • codex
  • kimi
  • antigravity
  • xai
  • devin
  • meta

func GetXAIModels added in v1.0.14

func GetXAIModels() []*ModelInfo

GetXAIModels returns the standard xAI Grok model definitions.

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 ValidateDevinModelsJSON added in v1.0.73

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 fills missing Codex built-ins without replacing configured models. Static catalog getters separately give built-ins precedence over remote definitions.

func WithXAIBuiltins added in v1.0.14

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

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

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

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

ClientSupportsModel reports whether the client registered support for modelID.

func (*ModelRegistry) GetAvailableModelDefinitions added in v1.0.26

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

GetAvailableModelDefinitions returns registered model definitions with at least one available client.

func (*ModelRegistry) GetClientModelRoutes added in v1.1.6

func (r *ModelRegistry) GetClientModelRoutes(clientID string) (string, []string)

GetClientModelRoutes snapshots the registered provider and public model IDs together.

func (*ModelRegistry) GetModelCandidatesForClient added in v1.1.5

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

GetModelCandidatesForClient returns a copy of the exclusion candidates. Nil means no candidate snapshot is available for this client.

func (*ModelRegistry) GetModelInfo

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

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

func (*ModelRegistry) GetModelInfoForClient added in v1.0.73

func (r *ModelRegistry) GetModelInfoForClient(clientID, modelID string) *ModelInfo

GetModelInfoForClient returns one client-specific model definition.

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) 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) RegisterClientWithCandidates added in v1.1.5

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

RegisterClientWithCandidates also records the models that exclusion rules match. Candidates remain available even when every routable model is excluded.

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) 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 NativeCapabilities added in v1.0.74

type NativeCapabilities struct {
	WebSearch *bool `json:"web_search,omitempty"`
	// ToolSearch is computed per Claude route for the CPA models payload: true
	// only when every credential behind the route supports Anthropic native
	// tool search for the model. It is not part of the static catalog.
	ToolSearch *bool `json:"tool_search,omitempty"`
}

NativeCapabilities preserves tri-state capabilities from the model catalog.

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