models

Documentation

Index

• Constants
• func LoadCachedProviders() (map[string]modelsDBProvider, string)
• func ParseModelString(modelString string) (provider, model string, err error)
• func ReloadGlobalRegistry()
• func RemoveCachedProviders() error
• func StoreCachedProviders(providers map[string]modelsDBProvider, etag string) error
• func ThinkingBudgetTokens(level ThinkingLevel) int64
• func ThinkingLevelDescription(level ThinkingLevel) string
• type Cost
• type Limit
• type ModelInfo
• type ModelsDBProviders
• type ModelsRegistry
  • func GetGlobalRegistry() *ModelsRegistry
  • func NewModelsRegistry() *ModelsRegistry
  • func (r *ModelsRegistry) GetFantasyProviders() []string
  • func (r *ModelsRegistry) GetModelsForProvider(provider string) (map[string]ModelInfo, error)
  • func (r *ModelsRegistry) GetProviderInfo(provider string) *ProviderInfo
  • func (r *ModelsRegistry) GetRequiredEnvVars(provider string) ([]string, error)
  • func (r *ModelsRegistry) GetSupportedProviders() []string
  • func (r *ModelsRegistry) LookupModel(provider, modelID string) *ModelInfo
  • func (r *ModelsRegistry) SuggestModels(provider, invalidModel string) []string
  • func (r *ModelsRegistry) ValidateEnvironment(provider string, apiKey string) error
  • func (r *ModelsRegistry) ValidateModel(provider, modelID string) (*ModelInfo, error)
• type OllamaLoadingResult
• type PoolStats
• type ProviderConfig
• type ProviderInfo
• type ProviderPool
  • func GetGlobalPool() *ProviderPool
  • func NewProviderPool(ttl time.Duration) *ProviderPool
  • func (p *ProviderPool) Close()
  • func (p *ProviderPool) Get(ctx context.Context, modelString string) (fantasy.LanguageModel, fantasy.ProviderOptions, func(), error)
  • func (p *ProviderPool) Stats() PoolStats
• type ProviderResult
  • func CreateProvider(ctx context.Context, config *ProviderConfig) (*ProviderResult, error)
• type ThinkingLevel
  • func ParseThinkingLevel(s string) ThinkingLevel
  • func ThinkingLevels() []ThinkingLevel

Constants

const (
	// ClaudeCodePrompt is the required system prompt for OAuth authentication.
	ClaudeCodePrompt = "You are Claude Code, Anthropic's official CLI for Claude."
)

const DefaultPoolTTL = 5 * time.Minute

DefaultPoolTTL is the default time-to-live for idle pooled providers.

Functions

func LoadCachedProviders

func LoadCachedProviders() (map[string]modelsDBProvider, string)

LoadCachedProviders reads the cached provider data from disk. Returns nil, "" if no cache exists or the cache is unreadable.

func ParseModelString

func ParseModelString(modelString string) (provider, model string, err error)

ParseModelString parses a model string in "provider/model" format (e.g. "anthropic/claude-sonnet-4-5"). It splits on the first "/" to extract the provider and model name. For backward compatibility, the legacy "provider:model" format is also accepted with a deprecation warning printed to stderr. Returns the provider name, model name, and any error.

func ReloadGlobalRegistry

func ReloadGlobalRegistry()

ReloadGlobalRegistry rebuilds the global registry from the current data sources (cache → embedded). Call after updating the cache.

func RemoveCachedProviders

func RemoveCachedProviders() error

RemoveCachedProviders deletes the cache file, causing the registry to fall back to the embedded model database on next load.

func StoreCachedProviders

func StoreCachedProviders(providers map[string]modelsDBProvider, etag string) error

StoreCachedProviders writes provider data to the cache file on disk.

func ThinkingBudgetTokens

func ThinkingBudgetTokens(level ThinkingLevel) int64

ThinkingBudgetTokens returns the token budget for a thinking level, or 0 for "off".

func ThinkingLevelDescription

func ThinkingLevelDescription(level ThinkingLevel) string

ThinkingLevelDescription returns a human-readable description of a thinking level.

Types

type Cost

type Cost struct {
	Input      float64
	Output     float64
	CacheRead  *float64
	CacheWrite *float64
}

Cost represents the pricing information for a model.

type Limit

type Limit struct {
	Context int
	Output  int
}

Limit represents the context and output limits for a model.

type ModelInfo

type ModelInfo struct {
	ID          string
	Name        string
	Attachment  bool
	Reasoning   bool
	Temperature bool
	Cost        Cost
	Limit       Limit
}

ModelInfo represents information about a specific model.

type ModelsDBProviders

type ModelsDBProviders = map[string]modelsDBProvider

ModelsDBProviders is the top-level type for models.dev/api.json data: a map of provider ID → provider object.

type ModelsRegistry

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

ModelsRegistry provides validation and information about models. It maintains a registry of all supported LLM providers and their models, including capabilities, pricing, and configuration requirements. The registry data comes from models.dev.

func GetGlobalRegistry

func GetGlobalRegistry() *ModelsRegistry

GetGlobalRegistry returns the global models registry instance.

func NewModelsRegistry

func NewModelsRegistry() *ModelsRegistry

NewModelsRegistry creates a new models registry populated from models.dev data.

func (*ModelsRegistry) GetFantasyProviders

func (r *ModelsRegistry) GetFantasyProviders() []string

GetFantasyProviders returns provider IDs that can be used with fantasy, either through a native provider or via openaicompat auto-routing.

func (*ModelsRegistry) GetModelsForProvider

func (r *ModelsRegistry) GetModelsForProvider(provider string) (map[string]ModelInfo, error)

GetModelsForProvider returns all models for a specific provider.

func (*ModelsRegistry) GetProviderInfo

func (r *ModelsRegistry) GetProviderInfo(provider string) *ProviderInfo

GetProviderInfo returns the full provider info, or nil if not found.

func (*ModelsRegistry) GetRequiredEnvVars

func (r *ModelsRegistry) GetRequiredEnvVars(provider string) ([]string, error)

GetRequiredEnvVars returns the required environment variables for a provider.

func (*ModelsRegistry) GetSupportedProviders

func (r *ModelsRegistry) GetSupportedProviders() []string

GetSupportedProviders returns a list of all provider IDs in the registry.

func (*ModelsRegistry) LookupModel

func (r *ModelsRegistry) LookupModel(provider, modelID string) *ModelInfo

LookupModel returns model metadata from the database if available. Returns nil when the model or provider is not in the database — this is expected for new models, custom fine-tunes, or providers the database doesn't track yet. Callers should treat a nil return as "unknown model" and continue with sensible defaults.

func (*ModelsRegistry) SuggestModels

func (r *ModelsRegistry) SuggestModels(provider, invalidModel string) []string

SuggestModels returns similar model names when an invalid model is provided.

func (*ModelsRegistry) ValidateEnvironment

func (r *ModelsRegistry) ValidateEnvironment(provider string, apiKey string) error

ValidateEnvironment checks if required credentials are available for a provider. It checks the explicit API key, stored credentials (for providers that support them, such as Anthropic OAuth), and environment variables. Returns nil for providers not in the registry (unknown providers are assumed to handle auth themselves or via --provider-api-key).

func (*ModelsRegistry) ValidateModel

func (r *ModelsRegistry) ValidateModel(provider, modelID string) (*ModelInfo, error)

ValidateModel validates if a model exists and returns detailed information. Deprecated: Use LookupModel instead — it returns nil for unknown models rather than an error, letting the provider API be the authority.

type OllamaLoadingResult

type OllamaLoadingResult struct {
	Message string
}

OllamaLoadingResult contains the result of model loading with actual settings used.

type PoolStats

type PoolStats struct {
	TotalProviders  int
	ActiveProviders int
	IdleProviders   int
}

PoolStats contains provider pool statistics.

type ProviderConfig

type ProviderConfig struct {
	ModelString    string
	SystemPrompt   string
	ProviderAPIKey string
	ProviderURL    string
	MaxTokens      int
	Temperature    *float32
	TopP           *float32
	TopK           *int32
	StopSequences  []string
	NumGPU         *int32
	MainGPU        *int32
	TLSSkipVerify  bool
	ThinkingLevel  ThinkingLevel
}

ProviderConfig holds configuration for creating LLM providers.

type ProviderInfo

type ProviderInfo struct {
	ID     string
	Env    []string
	NPM    string // npm package identifier from models.dev (e.g. "@ai-sdk/openai-compatible")
	API    string // base API URL for openai-compatible providers
	Name   string
	Models map[string]ModelInfo
}

ProviderInfo represents information about a model provider.

type ProviderPool

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

ProviderPool manages reusable LLM provider instances to reduce overhead when spawning multiple subagents or making repeated completion calls.

func GetGlobalPool

func GetGlobalPool() *ProviderPool

GetGlobalPool returns the singleton provider pool instance.

func NewProviderPool

func NewProviderPool(ttl time.Duration) *ProviderPool

NewProviderPool creates a provider pool with the given TTL for idle providers.

func (*ProviderPool) Close

func (p *ProviderPool) Close()

Close shuts down the pool and releases all providers.

func (*ProviderPool) Get

func (p *ProviderPool) Get(ctx context.Context, modelString string) (fantasy.LanguageModel, fantasy.ProviderOptions, func(), error)

Get returns a provider for the model string, creating one if needed. The returned release function must be called when the provider is no longer needed. The provider may be reused by subsequent Get calls.

func (*ProviderPool) Stats

func (p *ProviderPool) Stats() PoolStats

Stats returns current pool statistics.

type ProviderResult

type ProviderResult struct {
	// Model is the created fantasy LanguageModel
	Model fantasy.LanguageModel
	// Message contains optional feedback for the user
	Message string
	// Closer is an optional cleanup function for providers that hold
	// resources (e.g. kronk's loaded models). May be nil.
	Closer io.Closer
	// ProviderOptions contains provider-specific options to be passed to the
	// fantasy agent (e.g. OpenAI Responses API reasoning options).
	ProviderOptions fantasy.ProviderOptions
}

ProviderResult contains the result of provider creation.

func CreateProvider

func CreateProvider(ctx context.Context, config *ProviderConfig) (*ProviderResult, error)

CreateProvider creates a fantasy LanguageModel based on the provider configuration. Model metadata is looked up from the models.dev database for cost tracking and capability detection, but unknown models are passed through to the provider API — the database is advisory, not a gatekeeper.

Native providers: anthropic, openai, google, ollama, azure, google-vertex-anthropic, openrouter, bedrock, vercel. Any provider in models.dev with an api URL or openai-compatible npm package is auto-routed through fantasy's openaicompat provider.

type ThinkingLevel

type ThinkingLevel string

ThinkingLevel controls extended thinking / reasoning budget for supported models.

const (
	ThinkingOff     ThinkingLevel = "off"
	ThinkingMinimal ThinkingLevel = "minimal"
	ThinkingLow     ThinkingLevel = "low"
	ThinkingMedium  ThinkingLevel = "medium"
	ThinkingHigh    ThinkingLevel = "high"
)

func ParseThinkingLevel

func ParseThinkingLevel(s string) ThinkingLevel

ParseThinkingLevel converts a string to a ThinkingLevel, defaulting to ThinkingOff.

func ThinkingLevels

func ThinkingLevels() []ThinkingLevel

ThinkingLevels returns the ordered list of available thinking levels for cycling.