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
- func AllProvidersInfo() map[types.APIProvider]ProviderInfo
- func DefaultBaseURL(providerName string) string
- func DefaultConfigs() map[types.APIProvider]*Config
- func DefaultModelIdentifier(provider types.APIProvider) (types.ModelIdentifier, bool)
- func GetGlobalAPIKey() string
- func GetOAuthToken(ctx context.Context, provider string) (string, error)
- func InitOAuth(clientID string)
- func Is529Error(resp *http.Response, err error) bool
- func IsCircuitBreakerOpenError(err error) bool
- func IsCircuitBreakerTimeoutError(err error) bool
- func IsModelDeprecatedError(err error, resp *http.Response) bool
- func IsQuotaExhaustedError(err error, resp *http.Response) bool
- func IsRateLimitError(resp *http.Response) bool
- func IsRegionallyUnavailableError(err error, resp *http.Response) bool
- func IsRetryableStatus(statusCode int) bool
- func LoginProvider(ctx context.Context, provider string) (string, string, error)
- func NeedsCatalogReseed(providerName string, knownModelIDs []string) bool
- func OllamaModelLookup() map[string]ModelInfo
- func ParseContextOverflowError(err error) (inputTokens, maxTokens, contextLimit int, ok bool)
- func RecoveryHint(classification RetryClassification, modelID string) string
- func ResolveProviderFromString(s string) types.APIProvider
- func RetryWithStrategy(ctx context.Context, strategy *RetryStrategy, model types.ModelIdentifier, ...) (*types.APIResponse, error)
- func SetAPIKey(ctx context.Context, provider, apiKey string) error
- func SetGlobalAPIKey(key string)
- func ValidateProviderConfig(config *Config) error
- func WaitForLogin(ctx context.Context, provider string) error
- type AuthClient
- type BedrockTransport
- type CircuitBreaker
- func (cb *CircuitBreaker) CanExecute() bool
- func (cb *CircuitBreaker) Execute(fn func() error) error
- func (cb *CircuitBreaker) ExecuteWithTimeout(ctx context.Context, fn func(context.Context) error) error
- func (cb *CircuitBreaker) IsAvailable() bool
- func (cb *CircuitBreaker) RecordFailure()
- func (cb *CircuitBreaker) RecordSuccess()
- func (cb *CircuitBreaker) Reset()
- func (cb *CircuitBreaker) State() CircuitState
- func (cb *CircuitBreaker) Stats() CircuitBreakerStats
- type CircuitBreakerConfig
- type CircuitBreakerOpenError
- type CircuitBreakerStats
- type CircuitBreakerTimeoutError
- type CircuitState
- type Client
- func (c *Client) CircuitBreakerStats() CircuitBreakerStats
- func (c *Client) Config() *Config
- func (c *Client) CreateMessage(ctx context.Context, req types.APIRequest) (*types.APIResponse, error)
- func (c *Client) CreateMessageStream(ctx context.Context, req types.APIRequest) (<-chan types.APIResponseChunk, error)
- func (c *Client) CreateMessageStreamResult(ctx context.Context, req types.APIRequest) (*types.APIStreamResult, error)
- func (c *Client) CreateMessageStreamResultWithCallback(ctx context.Context, req types.APIRequest, ...) (*types.APIStreamResult, error)
- func (c *Client) EnableCircuitBreaker()
- func (c *Client) EnableCircuitBreakerWithConfig(config *CircuitBreakerConfig)
- func (c *Client) GetCircuitBreaker() *CircuitBreaker
- func (c *Client) ResetCircuitBreaker()
- func (c *Client) SetCircuitBreaker(cb *CircuitBreaker)
- func (c *Client) SetHTTPClient(client *http.Client)
- func (c *Client) SetMonitoring(monitoringSys *monitoring.System)
- func (c *Client) SetRetryConfig(config types.RetryConfig)
- type Config
- type DiscoveryResult
- type FetchedModel
- type FoundryTransport
- type LoginCommand
- type ModelInfo
- type ProviderInfo
- type RequestFunc
- type RetryClassification
- type RetryState
- type RetryStrategy
- type RoutingConfig
- type Transport
- type VertexTransport
Constants ¶
const ( DefaultLegacySonnetModel = "claude-3-5-sonnet-" + legacyClaude35Date DefaultLegacyHaikuModel = "claude-3-5-haiku-" + legacyClaude35Date )
DefaultLegacySonnetModel and DefaultLegacyHaikuModel are the 2024 Claude 3.5 model identifiers used as defaults across the engine, SDK, and the Anthropic/Foundry alias maps below. They still resolve in the model catalog; this only consolidates the literal so it isn't duplicated.
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 RetryClassificationQuotaExhausted = providerretry.RetryClassificationQuotaExhausted )
Variables ¶
This section is empty.
Functions ¶
func AllProvidersInfo ¶
func AllProvidersInfo() map[types.APIProvider]ProviderInfo
func DefaultBaseURL ¶
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 GetOAuthToken ¶
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 IsCircuitBreakerOpenError ¶
IsCircuitBreakerOpenError checks if an error is a circuit breaker open error
func IsCircuitBreakerTimeoutError ¶
IsCircuitBreakerTimeoutError checks if an error is a circuit breaker timeout error
func IsRateLimitError ¶
func IsRetryableStatus ¶
func LoginProvider ¶
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 ¶
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 ¶
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 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 ValidateProviderConfig ¶
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 BedrockTransport ¶
type BedrockTransport = providertransport.BedrockTransport
func NewBedrockTransport ¶
func NewBedrockTransport(apiKey string, config *Config) (*BedrockTransport, error)
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 ¶
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 ¶
NewClientWithConfig creates a new API client with provider-specific configuration
func NewFallbackClient ¶
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) 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 ¶
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
Region string
ProjectID string
ModelAliasMapping map[string]string
CustomHeaders map[string]string
Routing *RoutingConfig
}
func GetProviderConfig ¶
func GetProviderConfig(provider types.APIProvider) *Config
func (*Config) GetBaseURL ¶
func (*Config) GetEndpoint ¶
func (*Config) IsSupportedModel ¶
func (*Config) ResolveModel ¶
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 FoundryTransport ¶
type FoundryTransport = providertransport.FoundryTransport
func NewFoundryTransport ¶
func NewFoundryTransport(apiKey string, config *Config) (*FoundryTransport, error)
type LoginCommand ¶
LoginCommand performs provider login
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 ProviderInfo ¶
type ProviderInfo struct {
Name string
DisplayName string
Description string
AuthType string
AuthTypes []string
SupportsCVMM bool
SupportsPC bool
Models []ModelInfo
}
func GetProviderInfo ¶
func GetProviderInfo(provider types.APIProvider) (ProviderInfo, bool)
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.
type Transport ¶
type Transport = providertransport.Transport
type VertexTransport ¶
type VertexTransport = providertransport.VertexTransport
func NewVertexTransport ¶
func NewVertexTransport(apiKey string, config *Config) (*VertexTransport, error)