providers

package
v1.11.1 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

CLI-era credential helpers.

LoginProvider, WaitForLogin, GetOAuthToken, SetAPIKey and LoginCommand are designed for headless / CLI use. They store credentials in a local file (~/.seshat/auth.json via internal/auth/store.FileStore) and are NOT suited for multi-user server deployments.

In server mode, pass credentials to the engine via sdk.ClientConfig.APIKey or by implementing sdk.CredentialResolver for per-user resolution.

Index

Constants

View Source 
const (
	DefaultSonnetModel = "claude-sonnet-5-5"
	DefaultHaikuModel  = "claude-haiku-5-5"
	DefaultOpusModel   = "claude-opus-5-5"
)

DefaultSonnetModel and DefaultHaikuModel are the Claude identifiers used as defaults across the engine, SDK, and the Anthropic alias map below.

View Source 
const (
	RetryClassificationNetwork               = providerretry.RetryClassificationNetwork
	RetryClassificationRateLimit             = providerretry.RetryClassificationRateLimit
	RetryClassificationServerOverload        = providerretry.RetryClassificationServerOverload
	RetryClassificationTimeout               = providerretry.RetryClassificationTimeout
	RetryClassificationServerError           = providerretry.RetryClassificationServerError
	RetryClassificationClientError           = providerretry.RetryClassificationClientError
	RetryClassificationAuthError             = providerretry.RetryClassificationAuthError
	RetryClassificationUnknown               = providerretry.RetryClassificationUnknown
	RetryClassificationModelDeprecated       = providerretry.RetryClassificationModelDeprecated
	RetryClassificationRegionallyUnavailable = providerretry.RetryClassificationRegionallyUnavailable
	RetryClassificationQuotaExhausted        = providerretry.RetryClassificationQuotaExhausted
)

Variables

This section is empty.

Functions

func AllProvidersInfo 

func AllProvidersInfo() map[types.APIProvider]ProviderInfo

AllProvidersInfo returns the built-in providers with their models: the ones listed by hand, whose description and limits we set, followed by the models of the models.dev catalog that the list does not have, newest first. A model added to the catalog therefore shows up in the pickers without anyone editing this package. The first model of a list stays the default large one and the last the default small one (see TestProvidersKeepRegistryOrderAndDefaults in the terminal app): the catalog's models go between them.

func Catalog added in v1.10.5 

func Catalog() *catalog.Catalog

Catalog returns the catalog this package reads.

func CatalogCredentialEnvVars added in v1.10.5 

func CatalogCredentialEnvVars(p types.APIProvider) []string

CatalogCredentialEnvVars returns the environment variables that can hold the API key of a generic provider (the ones of its catalog entry that look like a secret), or nil when p is not one.

func CatalogURLVariables added in v1.11.0 

func CatalogURLVariables(p types.APIProvider) []string

CatalogURLVariables returns the environment variables the base URL of a generic provider needs and that are not set, or nil.

func DefaultBaseURL 

func DefaultBaseURL(providerName string) string

DefaultBaseURL returns the default API base URL for a provider. These are sync/discovery URLs (no /v1 suffix); client endpoints live in config.go.

func DefaultConfigs 

func DefaultConfigs() map[types.APIProvider]*Config

func DefaultModelIdentifier 

func DefaultModelIdentifier(provider types.APIProvider) (types.ModelIdentifier, bool)

func DefaultModelWithPolicy added in v1.11.0 

func DefaultModelWithPolicy(provider types.APIProvider, host ModelPolicy) (types.ModelIdentifier, bool)

DefaultModelWithPolicy is DefaultModelIdentifier under the host's policy: the first model of the list.

func GetGlobalAPIKey 

func GetGlobalAPIKey() string

GetGlobalAPIKey gets the global API key

func GetOAuthToken 

func GetOAuthToken(ctx context.Context, provider string) (string, error)

GetOAuthToken returns a valid OAuth access token for provider, refreshing if needed.

func InitOAuth 

func InitOAuth(clientID string)

InitOAuth initializes the OAuth client. clientID defaults to the Codex CLI client ID.

func Is529Error 

func Is529Error(resp *http.Response, err error) bool

func IsCatalogProvider added in v1.10.5 

func IsCatalogProvider(p types.APIProvider) bool

IsCatalogProvider reports whether p is a generic provider of the catalog, called with the OpenAI-compatible client.

func IsCircuitBreakerOpenError 

func IsCircuitBreakerOpenError(err error) bool

IsCircuitBreakerOpenError checks if an error is a circuit breaker open error

func IsCircuitBreakerTimeoutError 

func IsCircuitBreakerTimeoutError(err error) bool

IsCircuitBreakerTimeoutError checks if an error is a circuit breaker timeout error

func IsModelDeprecatedError 

func IsModelDeprecatedError(err error, resp *http.Response) bool

func IsQuotaExhaustedError 

func IsQuotaExhaustedError(err error, resp *http.Response) bool

func IsRateLimitError 

func IsRateLimitError(resp *http.Response) bool

func IsRegionallyUnavailableError 

func IsRegionallyUnavailableError(err error, resp *http.Response) bool

func IsRetryableStatus 

func IsRetryableStatus(statusCode int) bool

func LoginProvider 

func LoginProvider(ctx context.Context, provider string) (string, string, error)

LoginProvider starts the ChatGPT device-code flow and returns the user code + URL to display. CLI-era: saves result to ~/.seshat/auth.json.

func NeedsCatalogReseed 

func NeedsCatalogReseed(providerName string, knownModelIDs []string) bool

NeedsCatalogReseed returns true when none of the supplied model IDs exist in the provider's static catalog — meaning models from the wrong provider were seeded, or the list is empty.

func OllamaModelLookup 

func OllamaModelLookup() map[string]ModelInfo

OllamaModelLookup returns a name → ModelInfo map of context-window hints for popular Ollama models. It is used as a best-effort fallback when /api/show does not return context length data. The authoritative dynamic model list comes from providers.FetchModels (internal/providers/fetch.go).

func ParseContextOverflowError 

func ParseContextOverflowError(err error) (inputTokens, maxTokens, contextLimit int, ok bool)

func ProviderForCatalogID added in v1.11.0 

func ProviderForCatalogID(catalogID string) types.APIProvider

ProviderForCatalogID is catalogProviderID for hosts and tools.

func RecoveryHint 

func RecoveryHint(classification RetryClassification, modelID string) string

func ResolveProviderFromString 

func ResolveProviderFromString(s string) types.APIProvider

func RetryWithStrategy 

func RetryWithStrategy(
	ctx context.Context,
	strategy *RetryStrategy,
	model types.ModelIdentifier,
	maxTokens int,
	fn RequestFunc,
) (*types.APIResponse, error)

func SetAPIKey 

func SetAPIKey(ctx context.Context, provider, apiKey string) error

SetAPIKey explicitly sets an API key

func SetCatalog added in v1.10.5 

func SetCatalog(cat *catalog.Catalog)

SetCatalog makes cat the catalog this package reads, and registers the models it knows that the curated catalog does not, so context windows and vision support are known for them. A host calls it with catalog.Load's result after a refresh. The curated catalog always wins: a model it lists is never replaced.

func SetGlobalAPIKey 

func SetGlobalAPIKey(key string)

SetGlobalAPIKey sets the global API key

func SmallModelWithPolicy added in v1.11.0 

func SmallModelWithPolicy(provider types.APIProvider, host ModelPolicy) (string, bool)

SmallModelWithPolicy returns the small model of a provider under the host's policy: the last of the list when it has several.

func ValidateProviderConfig 

func ValidateProviderConfig(config *Config) error

func WaitForLogin 

func WaitForLogin(ctx context.Context, provider string) error

WaitForLogin polls Auth0 until the user completes authentication, then persists the full token to ~/.seshat/auth.json. CLI-era.

Types

type AuthClient 

type AuthClient struct {
	*Client
}

AuthClient wraps a Client with authentication support

func NewAuthClient 

func NewAuthClient(ctx context.Context, provider types.APIProvider) (*AuthClient, error)

NewAuthClient creates a new auth-aware client

func NewAuthClientWithConfig 

func NewAuthClientWithConfig(ctx context.Context, config *Config) (*AuthClient, error)

NewAuthClientWithConfig creates a new auth-aware client with config

type CircuitBreaker 

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

CircuitBreaker implements the circuit breaker pattern for fault tolerance

func NewCircuitBreaker 

func NewCircuitBreaker() *CircuitBreaker

NewCircuitBreaker creates a new circuit breaker with default configuration

func NewCircuitBreakerWithConfig 

func NewCircuitBreakerWithConfig(config *CircuitBreakerConfig) *CircuitBreaker

NewCircuitBreakerWithConfig creates a new circuit breaker with custom configuration

func (*CircuitBreaker) CanExecute 

func (cb *CircuitBreaker) CanExecute() bool

CanExecute checks if a request would be allowed right now

func (*CircuitBreaker) Execute 

func (cb *CircuitBreaker) Execute(fn func() error) error

Execute runs the given function through the circuit breaker

func (*CircuitBreaker) ExecuteWithTimeout 

func (cb *CircuitBreaker) ExecuteWithTimeout(ctx context.Context, fn func(context.Context) error) error

ExecuteWithTimeout runs the given function with timeout and circuit breaker protection. The context passed to fn carries the configured CallTimeout deadline; fn must respect ctx.Done() to guarantee no goroutine leaks when the deadline fires.

Not currently wired into any provider's streaming call path. If it ever is, CallTimeout must cover the whole streamed response body, not just headers — the default (30s) would cut off a long-running LLM stream mid-response, the same class of bug a too-short http.Client.Timeout caused for Codex (see getCodexHTTPClient's doc comment in client.go).

func (*CircuitBreaker) IsAvailable 

func (cb *CircuitBreaker) IsAvailable() bool

IsAvailable checks if the circuit breaker allows calls (compatibility method for engine integration)

func (*CircuitBreaker) RecordFailure 

func (cb *CircuitBreaker) RecordFailure()

RecordFailure records a failed call (compatibility method for engine integration)

func (*CircuitBreaker) RecordSuccess 

func (cb *CircuitBreaker) RecordSuccess()

RecordSuccess records a successful call (compatibility method for engine integration)

func (*CircuitBreaker) Reset 

func (cb *CircuitBreaker) Reset()

Reset resets the circuit breaker to closed state

func (*CircuitBreaker) State 

func (cb *CircuitBreaker) State() CircuitState

State returns the current state of the circuit breaker

func (*CircuitBreaker) Stats 

func (cb *CircuitBreaker) Stats() CircuitBreakerStats

Stats returns a snapshot of the current statistics

type CircuitBreakerConfig 

type CircuitBreakerConfig struct {
	// MaxFailures is the number of consecutive failures before opening the circuit
	MaxFailures int `json:"max_failures"`

	// CallTimeout is the timeout for individual calls
	CallTimeout time.Duration `json:"call_timeout"`

	// ResetTimeout is the time to wait before transitioning from open to half-open
	ResetTimeout time.Duration `json:"reset_timeout"`

	// HalfOpenMaxCalls is the maximum number of calls allowed in half-open state
	HalfOpenMaxCalls int `json:"half_open_max_calls"`

	// ReadyToTrip is a callback that can veto the transition to open state
	ReadyToTrip func() bool `json:"-"`

	// OnStateChange is a callback for state transitions
	OnStateChange func(from, to CircuitState) `json:"-"`

	// Embedded circuit breaker instance for backward compatibility
	*CircuitBreaker
}

CircuitBreakerConfig represents the configuration for a circuit breaker

func DefaultCircuitBreakerConfig 

func DefaultCircuitBreakerConfig() *CircuitBreakerConfig

DefaultCircuitBreakerConfig returns default circuit breaker configuration

type CircuitBreakerOpenError 

type CircuitBreakerOpenError struct {
	State CircuitState
}

CircuitBreakerOpenError is returned when the circuit is open

func (*CircuitBreakerOpenError) Error 

func (e *CircuitBreakerOpenError) Error() string

type CircuitBreakerStats 

type CircuitBreakerStats struct {
	// TotalRequests is the total number of requests made
	TotalRequests uint64 `json:"total_requests"`

	// TotalSuccesses is the total number of successful requests
	TotalSuccesses uint64 `json:"total_successes"`

	// TotalFailures is the total number of failed requests
	TotalFailures uint64 `json:"total_failures"`

	// ConsecutiveFailures is the current streak of consecutive failures
	ConsecutiveFailures int `json:"consecutive_failures"`

	// HalfOpenCalls is the number of calls made in half-open state
	HalfOpenCalls int `json:"half_open_calls"`

	// LastFailureTime is when the last failure occurred
	LastFailureTime time.Time `json:"last_failure_time"`

	// LastSuccessTime is when the last success occurred
	LastSuccessTime time.Time `json:"last_success_time"`

	// StateTransitions is the total number of state transitions
	StateTransitions uint64 `json:"state_transitions"`
}

CircuitBreakerStats represents the statistics collected by the circuit breaker

type CircuitBreakerTimeoutError 

type CircuitBreakerTimeoutError struct {
	Timeout  time.Duration
	Duration time.Duration
}

CircuitBreakerTimeoutError is returned when a call times out

func (*CircuitBreakerTimeoutError) Error 

func (e *CircuitBreakerTimeoutError) Error() string

type CircuitState 

type CircuitState string

CircuitState represents the current state of the circuit breaker 

const (
	CircuitStateClosed   CircuitState = "closed"    // Requests are allowed
	CircuitStateOpen     CircuitState = "open"      // Requests are blocked
	CircuitStateHalfOpen CircuitState = "half-open" // Limited requests are allowed to test recovery
)

type Client 

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

Client represents an API client

func NewClient 

func NewClient(apiKey string, providerType types.APIProvider) *Client

NewClient creates a new API client

func NewClientWithConfig 

func NewClientWithConfig(apiKey string, config *Config) *Client

NewClientWithConfig creates a new API client with provider-specific configuration

func NewFallbackClient 

func NewFallbackClient(ctx context.Context, provider types.APIProvider) (*Client, error)

NewFallbackClient builds a provider client from the provider-local credential sources so the engine can follow configured inter-provider fallback chains.

func (*Client) CircuitBreakerStats 

func (c *Client) CircuitBreakerStats() CircuitBreakerStats

CircuitBreakerStats returns the circuit breaker statistics

func (*Client) Config 

func (c *Client) Config() *Config

Config returns the provider configuration currently bound to the client.

func (*Client) CreateMessage 

func (c *Client) CreateMessage(ctx context.Context, req types.APIRequest) (*types.APIResponse, error)

CreateMessage sends a non-streaming message creation request

func (*Client) CreateMessageStream 

func (c *Client) CreateMessageStream(ctx context.Context, req types.APIRequest) (<-chan types.APIResponseChunk, error)

CreateMessageStream sends a streaming message creation request

func (*Client) CreateMessageStreamResult 

func (c *Client) CreateMessageStreamResult(ctx context.Context, req types.APIRequest) (*types.APIStreamResult, error)

CreateMessageStreamResult consumes the provider stream and returns a canonical aggregated response.

func (*Client) CreateMessageStreamResultWithCallback 

func (c *Client) CreateMessageStreamResultWithCallback(ctx context.Context, req types.APIRequest, onChunk func(types.APIResponseChunk)) (*types.APIStreamResult, error)

CreateMessageStreamResultWithCallback consumes the provider stream, emits normalized chunks to the callback, and returns a canonical aggregated response.

func (*Client) EnableCircuitBreaker 

func (c *Client) EnableCircuitBreaker()

EnableCircuitBreaker enables the circuit breaker with default configuration

func (*Client) EnableCircuitBreakerWithConfig 

func (c *Client) EnableCircuitBreakerWithConfig(config *CircuitBreakerConfig)

EnableCircuitBreakerWithConfig enables the circuit breaker with custom configuration

func (*Client) GetCircuitBreaker 

func (c *Client) GetCircuitBreaker() *CircuitBreaker

GetCircuitBreaker returns the current circuit breaker

func (*Client) ResetCircuitBreaker 

func (c *Client) ResetCircuitBreaker()

ResetCircuitBreaker resets the circuit breaker to closed state

func (*Client) SetCircuitBreaker 

func (c *Client) SetCircuitBreaker(cb *CircuitBreaker)

SetCircuitBreaker sets the circuit breaker for this client

func (*Client) SetHTTPClient 

func (c *Client) SetHTTPClient(client *http.Client)

SetHTTPClient sets the HTTP client

func (*Client) SetMonitoring 

func (c *Client) SetMonitoring(monitoringSys *monitoring.System)

SetMonitoring sets the monitoring system

func (*Client) SetRetryConfig 

func (c *Client) SetRetryConfig(config types.RetryConfig)

SetRetryConfig sets the retry configuration

type Config 

type Config struct {
	Provider          types.APIProvider
	APIKey            string
	BaseURL           string
	ModelAliasMapping map[string]string
	CustomHeaders     map[string]string
	Routing           *RoutingConfig
}

func ConfigForCatalogProvider added in v1.10.5 

func ConfigForCatalogProvider(p types.APIProvider) (*Config, bool)

ConfigForCatalogProvider returns the configuration to call a generic catalog provider: its id and its base URL. It refuses a provider that is not in the embedded catalog (Unverified), because the base URL of such a provider comes from a downloaded file and the key would go wherever that file says. A host that has shown the URL to the user and had it confirmed builds the Config itself, with that URL.

func GetProviderConfig 

func GetProviderConfig(provider types.APIProvider) *Config

func (*Config) GetBaseURL 

func (c *Config) GetBaseURL() string

func (*Config) GetEndpoint 

func (c *Config) GetEndpoint(model string) string

func (*Config) IsSupportedModel 

func (c *Config) IsSupportedModel(model string) bool

func (*Config) ResolveModel 

func (c *Config) ResolveModel(model string) string

type DiscoveryResult 

type DiscoveryResult struct {
	Provider    types.APIProvider
	DisplayName string
	Available   bool   // at least one auth credential is present/reachable
	AuthMethod  string // "api_key", "local", "aws", "gcp"
	EnvVar      string // env var name that was checked (empty for local services)
	Recommended bool   // included in the recommended set for first-time setup
	Priority    int    // lower = higher priority in the recommendation list
	Hint        string // human-readable note for the operator
}

DiscoveryResult reports the availability and authentication status of one provider.

func AvailableProviders 

func AvailableProviders(ctx context.Context) []DiscoveryResult

AvailableProviders returns only the providers that have credentials present.

func DiscoverProviders 

func DiscoverProviders(ctx context.Context) []DiscoveryResult

DiscoverProviders scans the environment for configured providers. It checks known env vars and pings Ollama's local endpoint. Results are sorted by recommendation priority; available providers appear before unavailable ones.

The context is used for the Ollama HTTP health check only.

type FetchedModel 

type FetchedModel struct {
	ModelID       string
	DisplayName   string
	ContextWindow int
	MaxOutput     int
	IsDefault     bool
	SortOrder     int
}

FetchedModel is a provider-neutral model description returned by FetchModels and StaticModels. Callers convert it to their own storage type.

func FetchModels 

func FetchModels(ctx context.Context, providerName, baseURL, apiKey string) ([]FetchedModel, error)

FetchModels retrieves the live model list from a provider API. For Ollama it calls /api/tags and enriches each model via /api/show. For OpenAI-compatible providers it calls /v1/models. Returns an error so the caller can fall back to StaticModels.

func NormalizeModels 

func NormalizeModels(providerName string, models []FetchedModel) []FetchedModel

NormalizeModels applies provider-specific post-processing to a raw model list. Currently handles Z.ai (restricts to the 3 allowed GLM models and merges static metadata).

func StaticModels 

func StaticModels(providerName string) []FetchedModel

StaticModels returns the hardcoded catalog for a provider. Returns nil for Ollama, which has no static model list (100% dynamic).

type LoginCommand 

type LoginCommand struct {
	Provider string
	Method   string
}

LoginCommand performs provider login

func (*LoginCommand) Execute 

func (c *LoginCommand) Execute(ctx context.Context) error

Execute performs login

type ModelDefaults added in v1.11.0 

type ModelDefaults struct {
	Large []string
	Small []string
}

ModelDefaults says which models a provider uses when the user has not chosen: the large one (first of the provider's list) and the small one (last, used for titles and compaction). Each entry is a family of the catalog ("claude-sonnet") or an exact model id. The entries are tried in order and the first that the provider has wins; for a family the newest stable model is taken. A side left empty is not settled by this policy.

type ModelInfo 

type ModelInfo struct {
	Identifier         string
	ContextWindow      int
	MaxOutput          int
	DefaultTemperature float64
	SupportsPC         bool
	Pricing            string
	Description        string
	Capabilities       model.Capabilities
}

ModelInfo describes a single model offered by a provider. Capabilities contains fine-grained per-model feature flags. The Pricing field is a legacy string; structured pricing lives in model.Metadata.

func GetModelInfo 

func GetModelInfo(provider types.APIProvider, model string) (ModelInfo, bool)

type ModelPolicy added in v1.11.0 

type ModelPolicy map[types.APIProvider]ModelDefaults

ModelPolicy is a set of ModelDefaults by provider, as a host writes them. It is a plain value passed to the functions below: the package keeps none, so two hosts (or two clients) in one process can use different policies without touching each other.

func DefaultModelPolicy added in v1.11.0 

func DefaultModelPolicy() ModelPolicy

DefaultModelPolicy returns a copy of the runtime's policy, keyed by the runtime's provider names, for a host to read, complete or change before passing it back.

type ProviderInfo 

type ProviderInfo struct {
	Name         string
	DisplayName  string
	Description  string
	AuthType     string
	AuthTypes    []string
	SupportsCVMM bool
	SupportsPC   bool
	Models       []ModelInfo
}

func CatalogProviders added in v1.10.5 

func CatalogProviders() []ProviderInfo

CatalogProviders lists the generic providers of the catalog, sorted by name, as ProviderInfo. A provider that only a fetched catalog knows is marked in its description: the host must have the user confirm its URL before a key is sent (see ConfigForCatalogProvider).

func GetProviderInfo 

func GetProviderInfo(provider types.APIProvider) (ProviderInfo, bool)

func ProviderInfoWithPolicy added in v1.11.0 

func ProviderInfoWithPolicy(provider types.APIProvider, host ModelPolicy) (ProviderInfo, bool)

ProviderInfoWithPolicy is GetProviderInfo with the host's policy applied to the order of the models. It builds a new value and changes nothing shared. A provider whose list the catalog does not build (Codex, Ollama) comes back as it is.

type RequestFunc 

type RequestFunc = providerretry.RequestFunc

type RetryClassification 

type RetryClassification = providerretry.RetryClassification

func ClassifyHTTPError 

func ClassifyHTTPError(err error, statusCode int) RetryClassification

type RetryState 

type RetryState = providerretry.RetryState

func NewRetryState 

func NewRetryState() *RetryState

type RetryStrategy 

type RetryStrategy = providerretry.RetryStrategy

func DefaultRetryStrategy 

func DefaultRetryStrategy() *RetryStrategy

type RoutingConfig 

type RoutingConfig struct {
	// Priority determines which provider to try first (lower = higher priority).
	Priority int `json:"priority"`

	// FallbackModels defines a chain of models to try if the primary fails.
	FallbackModels []types.ModelIdentifier `json:"fallback_models,omitempty"`

	// FallbackProviders defines a chain of providers to try if all models fail.
	FallbackProviders []types.APIProvider `json:"fallback_providers,omitempty"`

	// CircuitBreaker tracks provider health.
	CircuitBreaker *CircuitBreakerConfig `json:"circuit_breaker,omitempty"`
}

RoutingConfig defines provider routing and fallback behavior.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.