common

package
v1.0.58 Latest Latest
Warning

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

 Go to latest Published: Dec 18, 2025 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package common provides shared utilities and infrastructure for AI provider implementations. This includes standardized error handling, authentication helpers, configuration management, health checking, metrics collection, and other common functionality across providers.

Package common provides shared utilities and helper functions for AI providers. It includes file operations, configuration helpers, and other common functionality used across different provider implementations.

Package common provides shared utilities for AI provider implementations.

Package common provides shared utilities for AI provider implementations.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ReadConfigFile 

func ReadConfigFile(configPath string) ([]byte, error)

ReadConfigFile reads a configuration file and returns its raw byte content. This is commonly used by providers to read YAML/JSON configuration files. Returns the raw file content as bytes and any error encountered.

func ResolveModel added in v1.0.39 

func ResolveModel(optionsModel, configDefaultModel, providerDefaultModel string) string

ResolveModel returns the model to use, with fallback priority: 1. Model specified in options 2. Default model from provider config 3. Provider's hardcoded default model

Types

type APIError added in v1.0.4 

type APIError struct {
	StatusCode int
	Type       APIErrorType
	Message    string
	RawBody    string
	Retryable  bool
}

APIError represents a standardized provider error

func ClassifyHTTPError added in v1.0.4 

func ClassifyHTTPError(statusCode int, body []byte) *APIError

ClassifyHTTPError creates an APIError from HTTP status code This provides a basic classification based on standard HTTP status codes

func (*APIError) Error added in v1.0.4 

func (e *APIError) Error() string

Error implements the error interface

func (*APIError) IsRateLimit added in v1.0.4 

func (e *APIError) IsRateLimit() bool

IsRateLimit checks if the error is a rate limit error

func (*APIError) IsRetryable added in v1.0.4 

func (e *APIError) IsRetryable() bool

IsRetryable checks if the error is retryable

type APIErrorType added in v1.0.4 

type APIErrorType string

APIErrorType classifies API errors 

const (
	APIErrorTypeRateLimit      APIErrorType = "rate_limit"
	APIErrorTypeAuth           APIErrorType = "auth"
	APIErrorTypeNotFound       APIErrorType = "not_found"
	APIErrorTypeInvalidRequest APIErrorType = "invalid_request"
	APIErrorTypeServer         APIErrorType = "server_error"
	APIErrorTypeUnknown        APIErrorType = "unknown"
)

type ConnectivityCache added in v1.0.17 

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

ConnectivityCache provides thread-safe caching of connectivity test results It prevents hammering provider APIs during rapid health checks by caching results for a configurable TTL

func NewConnectivityCache added in v1.0.17 

func NewConnectivityCache(config ConnectivityCacheConfig) *ConnectivityCache

NewConnectivityCache creates a new connectivity cache with the given configuration

func NewDefaultConnectivityCache added in v1.0.17 

func NewDefaultConnectivityCache() *ConnectivityCache

NewDefaultConnectivityCache creates a new connectivity cache with default configuration

func (*ConnectivityCache) CleanupExpired added in v1.0.17 

func (cc *ConnectivityCache) CleanupExpired() int

CleanupExpired removes all expired entries from the cache This is useful for periodic cleanup to prevent memory growth

func (*ConnectivityCache) Clear added in v1.0.17 

func (cc *ConnectivityCache) Clear(providerType types.ProviderType)

Clear removes a specific provider's cached result This is useful when you want to force a fresh check on the next call without using bypassCache

func (*ConnectivityCache) ClearAll added in v1.0.17 

func (cc *ConnectivityCache) ClearAll()

ClearAll removes all cached results This is useful for resetting the cache state

func (*ConnectivityCache) GetCachedResult added in v1.0.17 

func (cc *ConnectivityCache) GetCachedResult(providerType types.ProviderType) (time.Time, bool, error)

GetCachedResult returns the cached result for a provider without performing a test Returns the timestamp of the cache entry, whether a valid (non-expired) entry exists, and the cached error

func (*ConnectivityCache) GetConfig added in v1.0.17 

func (cc *ConnectivityCache) GetConfig() ConnectivityCacheConfig

GetConfig returns the current cache configuration

func (*ConnectivityCache) GetStats added in v1.0.17 

func (cc *ConnectivityCache) GetStats() ConnectivityCacheStats

GetStats returns statistics about the cache

func (*ConnectivityCache) SetConfig added in v1.0.17 

func (cc *ConnectivityCache) SetConfig(config ConnectivityCacheConfig)

SetConfig updates the cache configuration Note: Changing the TTL doesn't invalidate existing cache entries

func (*ConnectivityCache) TestConnectivity added in v1.0.17 

func (cc *ConnectivityCache) TestConnectivity(
	ctx context.Context,
	providerType types.ProviderType,
	testFunc func(context.Context) error,
	bypassCache bool,
) error

TestConnectivity performs a cached connectivity test If a valid cached result exists (not expired), it returns the cached result Otherwise, it calls the actual test function and caches the result

Parameters:

  • ctx: Context for the connectivity test
  • providerType: The type of provider being tested
  • testFunc: The actual connectivity test function to call if cache miss or bypass
  • bypassCache: If true, forces a fresh connectivity check and updates the cache

Returns an error if the connectivity test fails, or nil if successful

type ConnectivityCacheConfig added in v1.0.17 

type ConnectivityCacheConfig struct {
	// TTL is the time-to-live for cached connectivity results
	// After this duration, the cache entry will be considered stale and a fresh check will be performed
	TTL time.Duration

	// Enabled controls whether caching is enabled
	// When disabled, all TestConnectivity calls will perform actual connectivity checks
	Enabled bool
}

ConnectivityCacheConfig holds configuration for the connectivity cache

func DefaultConnectivityCacheConfig added in v1.0.17 

func DefaultConnectivityCacheConfig() ConnectivityCacheConfig

DefaultConnectivityCacheConfig returns the default cache configuration Default TTL is 30 seconds to prevent hammering provider APIs during rapid health checks

type ConnectivityCacheStats added in v1.0.17 

type ConnectivityCacheStats struct {
	// TotalEntries is the current number of cached entries
	TotalEntries int

	// ValidEntries is the number of non-expired cached entries
	ValidEntries int

	// ExpiredEntries is the number of expired cached entries
	ExpiredEntries int

	// SuccessfulChecks is the number of cached successful connectivity checks
	SuccessfulChecks int

	// FailedChecks is the number of cached failed connectivity checks
	FailedChecks int
}

ConnectivityCacheStats represents statistics about the connectivity cache

type ErrorClassifier added in v1.0.4 

type ErrorClassifier interface {
	Classify(statusCode int, body []byte) *APIError
}

ErrorClassifier interface for provider-specific error parsing Providers can implement this to provide more detailed error classification based on their specific API error response formats

type ErrorSummary 

type ErrorSummary struct {
	TotalErrors int64       `json:"total_errors"`
	ErrorTypes  []ErrorType `json:"error_types"`
}

ErrorSummary represents a summary of errors

type ErrorType 

type ErrorType struct {
	Type       string  `json:"type"`
	Count      int64   `json:"count"`
	Percentage float64 `json:"percentage"`
}

ErrorType represents an error type with count and percentage

type HealthCheckCallback 

type HealthCheckCallback func(provider types.ProviderType, health *ProviderHealth)

HealthCheckCallback is called when a health check completes

type HealthCheckResult 

type HealthCheckResult struct {
	Healthy      bool                   `json:"healthy"`
	ResponseTime time.Duration          `json:"response_time"`
	Error        string                 `json:"error,omitempty"`
	Details      map[string]interface{} `json:"details,omitempty"`
}

HealthCheckResult represents the result of a single health check

type HealthChecker 

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

HealthChecker performs health checks on providers

func NewHealthChecker 

func NewHealthChecker(interval time.Duration) *HealthChecker

NewHealthChecker creates a new health checker

func (*HealthChecker) AddCallback 

func (hc *HealthChecker) AddCallback(callback HealthCheckCallback)

AddCallback adds a callback to be called when health checks complete

func (*HealthChecker) CheckProvider 

func (hc *HealthChecker) CheckProvider(ctx context.Context, provider *InitializedProvider) error

CheckProvider performs a health check on a specific provider

func (*HealthChecker) GetAllHealthStatus 

func (hc *HealthChecker) GetAllHealthStatus() map[types.ProviderType]ProviderHealth

GetAllHealthStatus returns health status for all providers

func (*HealthChecker) GetHealthStatus 

func (hc *HealthChecker) GetHealthStatus(providerType types.ProviderType) ProviderHealth

GetHealthStatus returns the current health status for a provider

func (*HealthChecker) GetHealthSummary 

func (hc *HealthChecker) GetHealthSummary() HealthSummary

GetHealthSummary returns a summary of health status across all providers

func (*HealthChecker) GetHealthyProviders 

func (hc *HealthChecker) GetHealthyProviders() []types.ProviderType

GetHealthyProviders returns a list of currently healthy providers

func (*HealthChecker) GetUnhealthyProviders 

func (hc *HealthChecker) GetUnhealthyProviders() []types.ProviderType

GetUnhealthyProviders returns a list of currently unhealthy providers

func (*HealthChecker) IsHealthy 

func (hc *HealthChecker) IsHealthy(providerType types.ProviderType) bool

IsHealthy checks if a provider is currently healthy

func (*HealthChecker) ResetHealthStatus 

func (hc *HealthChecker) ResetHealthStatus(providerType types.ProviderType)

ResetHealthStatus resets the health status for a provider

func (*HealthChecker) Start 

func (hc *HealthChecker) Start()

Start starts the health checker

func (*HealthChecker) Stop 

func (hc *HealthChecker) Stop()

Stop stops the health checker

type HealthSummary 

type HealthSummary struct {
	TotalProviders     int64                            `json:"total_providers"`
	HealthyProviders   int64                            `json:"healthy_providers"`
	UnhealthyProviders int64                            `json:"unhealthy_providers"`
	LastCheckTimes     map[types.ProviderType]time.Time `json:"last_check_times"`
}

HealthSummary represents a summary of health status across providers

type InitializedProvider 

type InitializedProvider struct {
	Type            types.ProviderType   `json:"type"`
	Config          types.ProviderConfig `json:"config"`
	HTTPClient      *http.HTTPClient     `json:"-"`
	AvailableModels []types.Model        `json:"available_models,omitempty"`
	Metrics         *ProviderMetrics     `json:"-"`
	HealthCheck     *HealthChecker       `json:"-"`
	InitializedAt   time.Time            `json:"initialized_at"`
	Status          ProviderStatus       `json:"status"`
}

InitializedProvider represents a fully initialized provider

type InitializerConfig 

type InitializerConfig struct {
	DefaultTimeout      time.Duration `json:"default_timeout"`
	MaxRetries          int           `json:"max_retries"`
	EnableHealthCheck   bool          `json:"enable_health_check"`
	HealthCheckInterval time.Duration `json:"health_check_interval"`
	EnableMetrics       bool          `json:"enable_metrics"`
	AutoDetectModels    bool          `json:"auto_detect_models"`
	CacheModels         bool          `json:"cache_models"`
	ModelCacheTTL       time.Duration `json:"model_cache_ttl"`
}

InitializerConfig configures provider initialization

type MetricsSnapshot 

type MetricsSnapshot struct {
	TotalRequests    int64                `json:"total_requests"`
	SuccessRequests  int64                `json:"success_requests"`
	FailedRequests   int64                `json:"failed_requests"`
	SuccessRate      float64              `json:"success_rate"`
	AvgResponseTime  time.Duration        `json:"avg_response_time"`
	MinResponseTime  time.Duration        `json:"min_response_time"`
	MaxResponseTime  time.Duration        `json:"max_response_time"`
	TotalTokensUsed  int64                `json:"total_tokens_used"`
	ErrorsByType     map[string]int64     `json:"errors_by_type"`
	ErrorsByProvider map[string]int64     `json:"errors_by_provider"`
	Initializations  map[string]int64     `json:"initializations"`
	HealthChecks     map[string]int64     `json:"health_checks"`
	HealthCheckFails map[string]int64     `json:"health_check_fails"`
	ModelUsage       map[string]int64     `json:"model_usage"`
	RateLimitHits    map[string]int64     `json:"rate_limit_hits"`
	LastRequestTime  map[string]time.Time `json:"last_request_time"`
	Uptime           time.Duration        `json:"uptime"`
}

MetricsSnapshot represents a snapshot of metrics at a point in time

type ModelUsage 

type ModelUsage struct {
	ModelID string `json:"model_id"`
	Count   int64  `json:"count"`
}

ModelUsage represents model usage statistics

type ProviderHealth 

type ProviderHealth struct {
	Provider     types.ProviderType     `json:"provider"`
	Healthy      bool                   `json:"healthy"`
	LastCheck    time.Time              `json:"last_check"`
	LastSuccess  time.Time              `json:"last_success"`
	LastError    time.Time              `json:"last_error"`
	ErrorMessage string                 `json:"error_message,omitempty"`
	ResponseTime time.Duration          `json:"response_time"`
	CheckCount   int64                  `json:"check_count"`
	SuccessCount int64                  `json:"success_count"`
	FailureCount int64                  `json:"failure_count"`
	Details      map[string]interface{} `json:"details,omitempty"`
}

ProviderHealth represents the health status of a provider

type ProviderInitializer 

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

ProviderInitializer handles common provider initialization patterns

func NewProviderInitializer 

func NewProviderInitializer(config InitializerConfig) *ProviderInitializer

NewProviderInitializer creates a new provider initializer

func (*ProviderInitializer) InitializeProvider 

func (pi *ProviderInitializer) InitializeProvider(
	ctx context.Context,
	providerType types.ProviderType,
	config types.ProviderConfig,
) (*InitializedProvider, error)

InitializeProvider initializes a provider with common patterns

type ProviderMetrics 

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

ProviderMetrics tracks performance and usage metrics for providers

func NewProviderMetrics 

func NewProviderMetrics() *ProviderMetrics

NewProviderMetrics creates a new provider metrics instance

func (*ProviderMetrics) GetErrorSummary 

func (pm *ProviderMetrics) GetErrorSummary() ErrorSummary

GetErrorSummary returns a summary of errors by type

func (*ProviderMetrics) GetMetricsForProvider 

func (pm *ProviderMetrics) GetMetricsForProvider(providerType types.ProviderType) ProviderMetricsSnapshot

GetMetricsForProvider returns metrics specific to a provider

func (*ProviderMetrics) GetSnapshot 

func (pm *ProviderMetrics) GetSnapshot() MetricsSnapshot

GetSnapshot returns a snapshot of current metrics

func (*ProviderMetrics) GetTopModels 

func (pm *ProviderMetrics) GetTopModels(limit int) []ModelUsage

GetTopModels returns the most used models

func (*ProviderMetrics) RecordError 

func (pm *ProviderMetrics) RecordError(providerType types.ProviderType, errorType string)

RecordError records a failed request

func (*ProviderMetrics) RecordHealthCheck 

func (pm *ProviderMetrics) RecordHealthCheck(providerType types.ProviderType, success bool)

RecordHealthCheck records a health check attempt

func (*ProviderMetrics) RecordInitialization 

func (pm *ProviderMetrics) RecordInitialization(providerType types.ProviderType)

RecordInitialization records a provider initialization

func (*ProviderMetrics) RecordRateLimitHit 

func (pm *ProviderMetrics) RecordRateLimitHit(providerType types.ProviderType)

RecordRateLimitHit records a rate limit occurrence

func (*ProviderMetrics) RecordRequest 

func (pm *ProviderMetrics) RecordRequest(providerType types.ProviderType)

RecordRequest records a request attempt

func (*ProviderMetrics) RecordSuccess 

func (pm *ProviderMetrics) RecordSuccess(providerType types.ProviderType, responseTime time.Duration, tokens int64, modelID string)

RecordSuccess records a successful request

func (*ProviderMetrics) Reset 

func (pm *ProviderMetrics) Reset()

Reset resets all metrics

type ProviderMetricsSnapshot 

type ProviderMetricsSnapshot struct {
	Provider         string    `json:"provider"`
	Errors           int64     `json:"errors"`
	HealthChecks     int64     `json:"health_checks"`
	HealthCheckFails int64     `json:"health_check_fails"`
	RateLimitHits    int64     `json:"rate_limit_hits"`
	Initializations  int64     `json:"initializations"`
	LastRequestTime  time.Time `json:"last_request_time"`
}

ProviderMetricsSnapshot represents metrics for a specific provider

type ProviderStatus 

type ProviderStatus struct {
	Healthy      bool          `json:"healthy"`
	LastCheck    time.Time     `json:"last_check"`
	ErrorCount   int64         `json:"error_count"`
	RequestCount int64         `json:"request_count"`
	ResponseTime time.Duration `json:"avg_response_time"`
}

ProviderStatus represents the current status of a provider

type RateLimitHelper 

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

RateLimitHelper provides shared rate limiting functionality for all AI providers. It encapsulates the common patterns of rate limit tracking, parsing, and enforcement used across different provider implementations.

func NewRateLimitHelper 

func NewRateLimitHelper(parser ratelimit.Parser) *RateLimitHelper

NewRateLimitHelper creates a new RateLimitHelper with the given provider-specific parser.

func (*RateLimitHelper) CanMakeRequest 

func (h *RateLimitHelper) CanMakeRequest(model string, estimatedTokens int) bool

CanMakeRequest checks if a request can be made for the given model and estimated tokens. Returns true if the request should proceed, false if rate limited.

func (*RateLimitHelper) CheckRateLimitAndWait 

func (h *RateLimitHelper) CheckRateLimitAndWait(model string, estimatedTokens int) bool

CheckRateLimitAndWait checks rate limits and waits if necessary before making a request. This combines the common pattern of checking limits and sleeping if needed. Returns true if the caller should proceed with the request, false if rate limited.

func (*RateLimitHelper) GetParser 

func (h *RateLimitHelper) GetParser() ratelimit.Parser

GetParser returns the underlying rate limit parser for advanced operations. This should be used sparingly when the helper methods don't provide sufficient functionality.

func (*RateLimitHelper) GetRateLimitInfo 

func (h *RateLimitHelper) GetRateLimitInfo(model string) (*ratelimit.Info, bool)

GetRateLimitInfo retrieves the current rate limit information for a model. Returns the info and a boolean indicating whether data exists for the model.

func (*RateLimitHelper) GetTracker 

func (h *RateLimitHelper) GetTracker() *ratelimit.Tracker

GetTracker returns the underlying rate limit tracker for advanced operations. This should be used sparingly when the helper methods don't provide sufficient functionality.

func (*RateLimitHelper) GetWaitTime 

func (h *RateLimitHelper) GetWaitTime(model string) time.Duration

GetWaitTime returns the duration to wait before the next request can be made. Returns 0 if no waiting is required.

func (*RateLimitHelper) ParseAndUpdateRateLimits 

func (h *RateLimitHelper) ParseAndUpdateRateLimits(headers http.Header, model string)

ParseAndUpdateRateLimits parses rate limit headers from an HTTP response and updates the tracker. This is the most common operation performed after receiving API responses.

func (*RateLimitHelper) ShouldThrottle 

func (h *RateLimitHelper) ShouldThrottle(model string, threshold float64) bool

ShouldThrottle determines if requests should be throttled based on current usage. threshold is a value between 0 and 1 representing the percentage of limits consumed at which throttling should begin (e.g., 0.8 = throttle at 80% usage).

func (*RateLimitHelper) UpdateRateLimitInfo 

func (h *RateLimitHelper) UpdateRateLimitInfo(info *ratelimit.Info)

UpdateRateLimitInfo directly updates the rate limit info for a model. This is useful for providers that get rate limit info from API endpoints rather than response headers.

type RateLimitInfo added in v1.0.8 

type RateLimitInfo struct {
	RequestsLimit     int
	RequestsRemaining int
	RequestsReset     int64 // Unix timestamp
	TokensLimit       int
	TokensRemaining   int
	TokensReset       int64 // Unix timestamp
	RetryAfter        int   // Seconds to wait
}

RateLimitInfo holds parsed rate limit information in a simplified format. This provides easy access to the most commonly used rate limit fields without requiring knowledge of the underlying ratelimit.Info structure.

type RateLimitTracker added in v1.0.8 

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

RateLimitTracker wraps RateLimitHelper with automatic response tracking. It provides a cleaner API that reduces code duplication by combining rate limit parsing and tracking into a single method call.

func NewRateLimitTracker added in v1.0.8 

func NewRateLimitTracker(parser ratelimit.Parser) *RateLimitTracker

NewRateLimitTracker creates a new tracker with the given parser.

func (*RateLimitTracker) GetHelper added in v1.0.8 

func (t *RateLimitTracker) GetHelper() *RateLimitHelper

GetHelper returns the underlying helper for backwards compatibility. This allows access to advanced features like CheckRateLimitAndWait, ShouldThrottle, and provider-specific rate limit information.

func (*RateLimitTracker) GetLastInfo added in v1.0.8 

func (t *RateLimitTracker) GetLastInfo() *RateLimitInfo

GetLastInfo returns the most recent rate limit info. This can be used to check rate limits without making another API call.

func (*RateLimitTracker) GetRetryAfter added in v1.0.8 

func (t *RateLimitTracker) GetRetryAfter() int

GetRetryAfter returns seconds to wait, or 0 if not rate limited.

func (*RateLimitTracker) IsRateLimited added in v1.0.8 

func (t *RateLimitTracker) IsRateLimited() bool

IsRateLimited returns true if we should back off based on the last check. This provides a simple way to check if rate limits have been exceeded.

func (*RateLimitTracker) TrackResponse added in v1.0.8 

func (t *RateLimitTracker) TrackResponse(headers http.Header, model string) *RateLimitInfo

TrackResponse extracts and stores rate limit info from response headers. This is the single point where rate limits are parsed, replacing multiple ParseAndUpdateRateLimits() calls throughout the codebase.

Usage: 

info := p.rateLimitTracker.TrackResponse(resp.Header, modelName)
if info != nil && info.RetryAfter > 0 {
    // Handle rate limit
}

Source Files

View all Source files

Directories

Path Synopsis
Package auth provides authentication utilities and helper functions for AI provider implementations
 Package auth provides authentication utilities and helper functions for AI provider implementations
Package config provides configuration utilities for AI provider implementations
 Package config provides configuration utilities for AI provider implementations
Package errors provides rich error context for AI provider operations.
 Package errors provides rich error context for AI provider operations.
Package middleware provides a flexible middleware infrastructure for AI provider requests and responses.
 Package middleware provides a flexible middleware infrastructure for AI provider requests and responses.
Package models provides model metadata, caching, and registry functionality for AI providers, including capability tracking and discovery.
 Package models provides model metadata, caching, and registry functionality for AI providers, including capability tracking and discovery.
Package retry provides retry infrastructure for AI provider implementations.
 Package retry provides retry infrastructure for AI provider implementations.
Package streaming provides streaming utilities for AI provider implementations.
 Package streaming provides streaming utilities for AI provider implementations.
decoders
Package decoders provides pluggable stream decoders for various streaming formats including Server-Sent Events (SSE), NDJSON, and EventStream.
 Package decoders provides pluggable stream decoders for various streaming formats including Server-Sent Events (SSE), NDJSON, and EventStream.
Package telemetry provides telemetry utilities for AI provider tracking and monitoring.
 Package telemetry provides telemetry utilities for AI provider tracking and monitoring.

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.