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 ( 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.
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) BuildAuthHeaders ¶
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)