types

type AuthConfig struct {
	Method       AuthMethod `json:"method"`
	APIKey       string     `json:"api_key,omitempty"`
	BaseURL      string     `json:"base_url,omitempty"`
	DefaultModel string     `json:"default_model,omitempty"`
}

type AuthMethod string

type AuthMethodDetector interface {
	// IsOAuthConfigured returns true if OAuth credentials are properly configured
	IsOAuthConfigured() bool

	// IsAPIKeyConfigured returns true if API key authentication is properly configured
	IsAPIKeyConfigured() bool
}

type AuthenticatedProvider interface {
	// Authentication
	Authenticate(ctx context.Context, authConfig AuthConfig) error
	IsAuthenticated() bool
	Logout(ctx context.Context) error
}

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

type CapabilityProvider interface {
	// Streaming support
	SupportsStreaming() bool

	// Responses API support
	SupportsResponsesAPI() bool
}

type ChatChoice struct {
	Index        int         `json:"index"`
	Message      ChatMessage `json:"message"`
	FinishReason string      `json:"finish_reason"`
	Delta        ChatMessage `json:"delta"`
}

type ChatCompletionChunk struct {
	ID               string                 `json:"id"`
	Object           string                 `json:"object"`
	Created          int64                  `json:"created"`
	Model            string                 `json:"model"`
	Choices          []ChatChoice           `json:"choices"`
	Usage            Usage                  `json:"usage"`
	Done             bool                   `json:"done"`
	Content          string                 `json:"content"`
	Reasoning        string                 `json:"reasoning,omitempty"`         // Reasoning content for clients that want it
	ReasoningContent string                 `json:"reasoning_content,omitempty"` // Alternative reasoning field
	Error            string                 `json:"error"`
	Metadata         map[string]interface{} `json:"metadata,omitempty"`
}

type ChatCompletionStream interface {
	Next() (ChatCompletionChunk, error)
	Close() error
}

type ChatMessage struct {
	Role             string                 `json:"role"`
	Content          string                 `json:"content"`                     // Simple text content (backwards compatible)
	Parts            []ContentPart          `json:"parts,omitempty"`             // Multimodal content parts
	Reasoning        string                 `json:"reasoning,omitempty"`         // Reasoning content (e.g., from GLM-4.6, OpenCode/Zen)
	ReasoningContent string                 `json:"reasoning_content,omitempty"` // Alternative reasoning field (e.g., from vLLM/Synthetic)
	ToolCalls        []ToolCall             `json:"tool_calls,omitempty"`
	ToolCallID       string                 `json:"tool_call_id,omitempty"`
	Metadata         map[string]interface{} `json:"metadata,omitempty"`
}

type ChatProvider interface {
	// Core chat capability
	GenerateChatCompletion(ctx context.Context, options GenerateOptions) (ChatCompletionStream, error)
}

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

type CodeGenerationResult struct {
	Code  string `json:"code"`
	Usage *Usage `json:"usage,omitempty"`
}

type ConfigurableProvider interface {
	// Configuration
	Configure(config ProviderConfig) error
	GetConfig() ProviderConfig
}

type ContentPart struct {
	Type string `json:"type"` // "text", "image", "document", "audio", "tool_use", "tool_result", "thinking"

	// Text content
	Text string `json:"text,omitempty"`

	// Media content (images, documents, audio)
	Source *MediaSource `json:"source,omitempty"`

	// Tool use (model calling a tool)
	ID    string                 `json:"id,omitempty"`
	Name  string                 `json:"name,omitempty"`
	Input map[string]interface{} `json:"input,omitempty"`

	// Tool result (response to tool call)
	ToolUseID string      `json:"tool_use_id,omitempty"`
	Content   interface{} `json:"content,omitempty"` // string or []ContentPart

	// Extended thinking
	Thinking string `json:"thinking,omitempty"`

	// Escape hatch for future/provider-specific types
	Extra map[string]interface{} `json:"extra,omitempty"`
}

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

type CoreChatProvider interface {
	// Core chat completion using standard request/response format
	GenerateStandardCompletion(ctx context.Context, request StandardRequest) (*StandardResponse, error)

	// Streaming chat completion using standard format
	GenerateStandardStream(ctx context.Context, request StandardRequest) (StandardStream, error)

	// Get the provider's core extension for format conversion
	GetCoreExtension() CoreProviderExtension

	// Provider capabilities using the standardized format
	GetStandardCapabilities() []string

	// Validate a standard request for this provider
	ValidateStandardRequest(request StandardRequest) error
}

type CoreProvider interface {
	// Basic provider information
	Name() string
	Type() ProviderType
	Description() string
}

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

type CoreProviderExtension interface {
	// Extension information
	Name() string
	Version() string
	Description() string

	// Convert between standard and provider-specific formats
	StandardToProvider(request StandardRequest) (interface{}, error)
	ProviderToStandard(response interface{}) (*StandardResponse, error)
	ProviderToStandardChunk(chunk interface{}) (*StandardStreamChunk, error)

	// Validate provider-specific options
	ValidateOptions(options map[string]interface{}) error

	// Get provider-specific capabilities
	GetCapabilities() []string
}

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

type CredentialProvider interface {
	// GetCredentials returns the current OAuth credentials for a provider
	// The provider name is used to look up credentials in the storage
	// Returns an empty slice if no credentials are available
	GetCredentials(ctx context.Context, providerName string) ([]*OAuthCredentialSet, error)

	// UpdateCredential updates a specific credential after token refresh
	// This is called by OAuthKeyManager after it refreshes a token
	// The implementation should persist the updated credential
	UpdateCredential(ctx context.Context, providerName string, credential *OAuthCredentialSet) error
}

type CredentialProviderAware interface {
	// SetCredentialProvider sets a dynamic credential provider for OAuth credentials
	SetCredentialProvider(provider CredentialProvider)
}

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

type DefaultProviderFactoryExtensions struct {
	ProviderFactory
	// contains filtered or unexported fields
}

type ErrorCode string

type ErrorMetrics struct {
	// Total error counts
	TotalErrors int64   `json:"total_errors"`
	ErrorRate   float64 `json:"error_rate"` // Calculated: errors / total_requests

	// Error categorization by type
	ErrorsByType map[string]int64 `json:"errors_by_type"` // e.g., "rate_limit", "timeout", "authentication", "invalid_request"

	// Error categorization by HTTP status
	ErrorsByStatus map[string]int64 `json:"errors_by_status"` // e.g., "400", "401", "429", "500", "503"

	// Error categorization by provider
	ErrorsByProvider map[string]int64 `json:"errors_by_provider"`

	// Error categorization by model
	ErrorsByModel map[string]int64 `json:"errors_by_model,omitempty"`

	// Specific error categories
	RateLimitErrors      int64 `json:"rate_limit_errors"`
	TimeoutErrors        int64 `json:"timeout_errors"`
	AuthenticationErrors int64 `json:"authentication_errors"`
	InvalidRequestErrors int64 `json:"invalid_request_errors"`
	ServerErrors         int64 `json:"server_errors"` // 5xx errors
	NetworkErrors        int64 `json:"network_errors"`
	UnknownErrors        int64 `json:"unknown_errors"`

	// Error percentages (for quick analysis)
	RateLimitErrorRate      float64 `json:"rate_limit_error_rate"`     // Calculated: rate_limit_errors / total_errors
	TimeoutErrorRate        float64 `json:"timeout_error_rate"`        // Calculated: timeout_errors / total_errors
	AuthenticationErrorRate float64 `json:"authentication_error_rate"` // Calculated: auth_errors / total_errors
	ServerErrorRate         float64 `json:"server_error_rate"`         // Calculated: server_errors / total_errors

	// Recent error tracking
	ConsecutiveErrors int64     `json:"consecutive_errors"` // Current consecutive error count
	LastError         string    `json:"last_error"`
	LastErrorType     string    `json:"last_error_type"`
	LastErrorTime     time.Time `json:"last_error_time"`

	// Error recovery metrics
	TotalRetries      int64   `json:"total_retries"`
	SuccessfulRetries int64   `json:"successful_retries"`
	FailedRetries     int64   `json:"failed_retries"`
	RetrySuccessRate  float64 `json:"retry_success_rate"` // Calculated: successful_retries / total_retries

	// Last updated
	LastUpdated time.Time `json:"last_updated"`
}

type ExtensionRegistry interface {
	// Register an extension for a provider type
	Register(providerType ProviderType, extension CoreProviderExtension) error

	// Get extension for a provider type
	Get(providerType ProviderType) (CoreProviderExtension, error)

	// List all registered extensions
	List() map[ProviderType]CoreProviderExtension

	// Check if a provider type has a registered extension
	Has(providerType ProviderType) bool
}

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

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

type FlexibleProviderFactory struct{}

type GenerateOptions struct {
	Prompt         string                 `json:"prompt"`
	Model          string                 `json:"model,omitempty"` // Per-request model override
	Context        string                 `json:"context"`
	ContextObj     context.Context        `json:"-"` // Internal context for operations
	OutputFile     string                 `json:"output_file"`
	Language       *string                `json:"language"`
	ContextFiles   []string               `json:"context_files"`
	Messages       []ChatMessage          `json:"messages"`
	MaxTokens      int                    `json:"max_tokens,omitempty"`
	Temperature    float64                `json:"temperature,omitempty"`
	Stop           []string               `json:"stop,omitempty"`
	Stream         bool                   `json:"stream"`
	Tools          []Tool                 `json:"tools,omitempty"`
	ToolChoice     *ToolChoice            `json:"tool_choice,omitempty"` // Fine-grained tool selection control
	ResponseFormat string                 `json:"response_format,omitempty"`
	Timeout        time.Duration          `json:"timeout,omitempty"`
	Metadata       map[string]interface{} `json:"metadata,omitempty"`
}

type HealthCheckProvider interface {
	// Health and metrics
	HealthCheck(ctx context.Context) error
	GetMetrics() ProviderMetrics
}

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

type HealthStatus struct {
	Healthy      bool      `json:"healthy"`
	LastChecked  time.Time `json:"last_checked"`
	Message      string    `json:"message"`
	ResponseTime float64   `json:"response_time"`
	StatusCode   int       `json:"status_code"`
}

type HookID string

type LatencyMetrics struct {
	// Summary statistics
	TotalRequests  int64         `json:"total_requests"`  // Number of requests measured
	TotalLatency   time.Duration `json:"total_latency"`   // Sum of all latencies
	AverageLatency time.Duration `json:"average_latency"` // Calculated: total_latency / total_requests

	// Min/Max
	MinLatency time.Duration `json:"min_latency"`
	MaxLatency time.Duration `json:"max_latency"`

	// Percentiles (for detailed latency distribution)
	P50Latency time.Duration `json:"p50_latency"` // Median
	P75Latency time.Duration `json:"p75_latency"`
	P90Latency time.Duration `json:"p90_latency"`
	P95Latency time.Duration `json:"p95_latency"`
	P99Latency time.Duration `json:"p99_latency"`

	// Last updated
	LastUpdated time.Time `json:"last_updated"`
}

type MediaSource struct {
	Type      string `json:"type"`                 // "base64", "url"
	MediaType string `json:"media_type,omitempty"` // MIME type: "image/png", "application/pdf", "audio/wav"
	Data      string `json:"data,omitempty"`       // base64-encoded data
	URL       string `json:"url,omitempty"`        // URL to the media
}

type MetricEvent struct {
	// Type of event (request, success, error, etc.)
	Type MetricEventType `json:"type"`

	// Provider identification
	ProviderName string       `json:"provider_name"`
	ProviderType ProviderType `json:"provider_type"`

	// Model identification (may be empty for non-model events)
	ModelID string `json:"model_id,omitempty"`

	// Timestamp when the event occurred
	Timestamp time.Time `json:"timestamp"`

	// Request/response details
	Latency      time.Duration `json:"latency,omitempty"`       // Time taken for request
	TokensUsed   int64         `json:"tokens_used,omitempty"`   // Total tokens consumed
	InputTokens  int64         `json:"input_tokens,omitempty"`  // Input tokens
	OutputTokens int64         `json:"output_tokens,omitempty"` // Output tokens

	// Error details (only for error events)
	ErrorType    string `json:"error_type,omitempty"`    // Categorized error type
	ErrorMessage string `json:"error_message,omitempty"` // Human-readable error

	// HTTP details (optional)
	StatusCode int `json:"status_code,omitempty"` // HTTP status code

	// Streaming context (for streaming events)
	IsStreaming      bool          `json:"is_streaming,omitempty"`        // Indicates this is a streaming request
	StreamSessionID  string        `json:"stream_session_id,omitempty"`   // Correlate related stream events
	StreamChunkIndex int           `json:"stream_chunk_index,omitempty"`  // Which chunk (0-indexed)
	TimeToFirstToken time.Duration `json:"time_to_first_token,omitempty"` // TTFT for stream_start events
	TokensPerSecond  float64       `json:"tokens_per_second,omitempty"`   // Throughput for stream_end events

	// Virtual provider context (for fallback/racing/loadbalance events)
	FromProvider     string                   `json:"from_provider,omitempty"`     // Provider switched from
	ToProvider       string                   `json:"to_provider,omitempty"`       // Provider switched to
	SwitchReason     string                   `json:"switch_reason,omitempty"`     // Why switch occurred (failure, timeout, race_winner)
	AttemptNumber    int                      `json:"attempt_number,omitempty"`    // Which attempt in fallback chain
	RaceParticipants []string                 `json:"race_participants,omitempty"` // Providers in the race
	RaceLatencies    map[string]time.Duration `json:"race_latencies,omitempty"`    // Latencies per racing provider
	RaceWinner       string                   `json:"race_winner,omitempty"`       // Which provider won the race

	// Circuit breaker context
	CircuitState     string `json:"circuit_state,omitempty"`     // Current state: closed, open, half-open
	CircuitFailures  int    `json:"circuit_failures,omitempty"`  // Consecutive failures
	CircuitSuccesses int    `json:"circuit_successes,omitempty"` // Consecutive successes (in half-open)

	// Additional metadata (provider-specific)
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type MetricEventType string

type MetricFilter struct {
	// ProviderNames filters events to specific providers.
	// Empty slice = all providers.
	//
	// Example: []string{"openai-prod", "anthropic-prod"}
	ProviderNames []string `json:"provider_names,omitempty"`

	// ProviderTypes filters events to specific provider types.
	// Empty slice = all provider types.
	//
	// Example: []ProviderType{ProviderTypeOpenAI, ProviderTypeAnthropic}
	ProviderTypes []ProviderType `json:"provider_types,omitempty"`

	// ModelIDs filters events to specific models.
	// Empty slice = all models.
	//
	// Example: []string{"gpt-4", "claude-3-opus"}
	ModelIDs []string `json:"model_ids,omitempty"`

	// EventTypes filters events to specific event types.
	// Empty slice = all event types.
	//
	// Example: []MetricEventType{MetricEventError, MetricEventRateLimit}
	EventTypes []MetricEventType `json:"event_types,omitempty"`

	// MinLatency filters events with latency >= this threshold.
	// Zero value = no minimum threshold.
	//
	// Use case: Monitor only slow requests
	MinLatency time.Duration `json:"min_latency,omitempty"`

	// ErrorTypesOnly filters to only error events with specific error types.
	// Empty slice = all error types.
	// Only applicable when EventTypes includes MetricEventError.
	//
	// Example: []string{"rate_limit", "timeout"}
	ErrorTypesOnly []string `json:"error_types_only,omitempty"`
}

type MetricsCollector interface {
	// ----- Snapshot API (Polling Pattern) -----
	//
	// GetSnapshot returns a complete snapshot of all metrics across all providers and models.
	// This is the primary method for periodic polling and dashboard updates.
	//
	// The snapshot is a point-in-time copy and will not change after being returned.
	// Safe for concurrent access and can be serialized to JSON directly.
	//
	// Use cases:
	//  - Dashboard updates every N seconds
	//  - Periodic export to monitoring systems
	//  - Health check aggregation
	//
	// Example:
	//   snapshot := collector.GetSnapshot()
	//   fmt.Printf("Total requests: %d\n", snapshot.TotalRequests)
	//   json.Marshal(snapshot) // Works seamlessly
	GetSnapshot() MetricsSnapshot

	// GetProviderMetrics returns metrics for a specific provider by its name.
	// Returns nil if the provider is not found.
	//
	// Provider name should match the name used when registering the provider.
	//
	// Use cases:
	//  - Per-provider monitoring dashboards
	//  - Provider-specific alerting
	//  - Comparative analysis between providers
	//
	// Example:
	//   metrics := collector.GetProviderMetrics("openai-prod")
	//   if metrics != nil {
	//     fmt.Printf("Success rate: %.2f%%\n", metrics.SuccessRate*100)
	//   }
	GetProviderMetrics(providerName string) *ProviderMetricsSnapshot

	// GetModelMetrics returns metrics for a specific model across all providers.
	// Returns nil if no metrics exist for the given model ID.
	//
	// Model ID is the standardized model identifier (e.g., "gpt-4", "claude-3-opus").
	//
	// Use cases:
	//  - Model-specific performance analysis
	//  - Cost tracking per model
	//  - Model usage trends
	//
	// Example:
	//   metrics := collector.GetModelMetrics("gpt-4-turbo")
	//   if metrics != nil {
	//     fmt.Printf("Total tokens: %d\n", metrics.TotalTokens)
	//   }
	GetModelMetrics(modelID string) *ModelMetricsSnapshot

	// GetProviderNames returns a sorted list of all provider names currently tracked.
	// Useful for iterating over all providers to fetch individual metrics.
	//
	// Example:
	//   for _, name := range collector.GetProviderNames() {
	//     metrics := collector.GetProviderMetrics(name)
	//     // Process metrics...
	//   }
	GetProviderNames() []string

	// GetModelIDs returns a sorted list of all model IDs currently tracked.
	// Useful for iterating over all models to fetch individual metrics.
	//
	// Example:
	//   for _, modelID := range collector.GetModelIDs() {
	//     metrics := collector.GetModelMetrics(modelID)
	//     // Process metrics...
	//   }
	GetModelIDs() []string

	// ----- Event Streaming API (Pub/Sub Pattern) -----
	//
	// Subscribe creates a new subscription for receiving real-time metrics events.
	// The returned channel will receive all metrics events as they occur.
	//
	// The subscriber MUST continuously read from the channel to avoid blocking the collector.
	// If the buffer fills up (see bufferSize), the oldest events will be dropped (overflow handling).
	//
	// Call Unsubscribe() when done to clean up resources and prevent goroutine leaks.
	//
	// Parameters:
	//   bufferSize: Size of the event channel buffer. Recommended values:
	//               - 100: Low-frequency monitoring (few events per second)
	//               - 1000: Medium-frequency monitoring (tens of events per second)
	//               - 10000: High-frequency monitoring (hundreds of events per second)
	//
	// Use cases:
	//  - Real-time dashboards with WebSocket updates
	//  - Event stream processing
	//  - Live monitoring and alerting
	//
	// Example:
	//   sub := collector.Subscribe(1000)
	//   defer sub.Unsubscribe()
	//
	//   for event := range sub.Events() {
	//     fmt.Printf("Event: %s at %v\n", event.Type, event.Timestamp)
	//   }
	Subscribe(bufferSize int) MetricsSubscription

	// SubscribeFiltered creates a filtered subscription that only receives events matching the filter.
	// This is more efficient than Subscribe() + manual filtering when only specific events are needed.
	//
	// The filter is applied before buffering, reducing memory usage and processing overhead.
	//
	// Parameters:
	//   bufferSize: Size of the event channel buffer (same semantics as Subscribe)
	//   filter: Criteria for selecting which events to receive
	//
	// Use cases:
	//  - Provider-specific monitoring (only events from one provider)
	//  - Error-only monitoring (only failure events)
	//  - Model-specific tracking (only events for specific models)
	//
	// Example:
	//   filter := MetricFilter{
	//     ProviderNames: []string{"openai-prod"},
	//     EventTypes: []MetricEventType{MetricEventRequest, MetricEventError},
	//   }
	//   sub := collector.SubscribeFiltered(500, filter)
	//   defer sub.Unsubscribe()
	//
	//   for event := range sub.Events() {
	//     // Only receives request and error events from openai-prod
	//   }
	SubscribeFiltered(bufferSize int, filter MetricFilter) MetricsSubscription

	// ----- Hook API (Synchronous Callback Pattern) -----
	//
	// RegisterHook registers a synchronous callback that will be invoked for each metrics event.
	// Unlike subscriptions (async), hooks are called inline and can block event processing.
	//
	// Hooks are useful for:
	//  - Immediate actions (alerting, circuit breaking)
	//  - Synchronous processing (updating in-memory caches)
	//  - Low-latency reactions to specific events
	//
	// IMPORTANT: Hook execution blocks the metrics collection pipeline. Keep hook logic fast
	// to avoid degrading overall system performance. For heavy processing, use Subscribe() instead.
	//
	// The returned HookID can be used to unregister the hook later.
	//
	// Parameters:
	//   hook: The hook implementation to register
	//
	// Example:
	//   hook := &MyAlertHook{}
	//   hookID := collector.RegisterHook(hook)
	//   defer collector.UnregisterHook(hookID)
	RegisterHook(hook MetricsHook) HookID

	// UnregisterHook removes a previously registered hook.
	// Safe to call with an invalid HookID (no-op).
	//
	// Parameters:
	//   id: The HookID returned from RegisterHook()
	UnregisterHook(id HookID)

	// ----- Event Recording API (Provider Integration) -----
	//
	// RecordEvent records a single metrics event. This is the primary method used by
	// providers to emit metrics data to the collector.
	//
	// The event will be:
	//  1. Aggregated into snapshot data (for GetSnapshot, etc.)
	//  2. Sent to all active subscriptions (honoring filters)
	//  3. Passed to all registered hooks
	//
	// Thread-safe and designed to be called from provider implementations.
	//
	// Parameters:
	//   ctx: Context for cancellation and timeout (honors context cancellation)
	//   event: The event to record
	//
	// Example (from provider implementation):
	//   collector.RecordEvent(ctx, MetricEvent{
	//     Type: MetricEventRequest,
	//     ProviderName: "openai-prod",
	//     ProviderType: ProviderTypeOpenAI,
	//     ModelID: "gpt-4-turbo",
	//     Timestamp: time.Now(),
	//   })
	RecordEvent(ctx context.Context, event MetricEvent) error

	// RecordEvents records multiple events in a single batch.
	// More efficient than calling RecordEvent repeatedly.
	//
	// All events are processed atomically (all succeed or all fail).
	//
	// Parameters:
	//   ctx: Context for cancellation and timeout
	//   events: Slice of events to record
	//
	// Example:
	//   events := []MetricEvent{event1, event2, event3}
	//   collector.RecordEvents(ctx, events)
	RecordEvents(ctx context.Context, events []MetricEvent) error

	// ----- Reset and Lifecycle -----
	//
	// Reset clears all accumulated metrics data and resets counters to zero.
	// Active subscriptions and hooks are preserved.
	//
	// Use cases:
	//  - Rolling time windows (reset every hour/day)
	//  - Test isolation
	//  - Manual metrics rotation
	//
	// Example:
	//   collector.Reset() // Start fresh without losing subscriptions
	Reset()

	// Close gracefully shuts down the metrics collector.
	// - Closes all active subscriptions
	// - Unregisters all hooks
	// - Flushes any pending events
	//
	// After calling Close(), the collector should not be used.
	Close() error
}

type MetricsHook interface {
	// OnEvent is called for each metrics event.
	// The context may have a timeout to prevent slow hooks from blocking.
	//
	// IMPORTANT: Keep this method fast (<1ms) to avoid blocking the metrics pipeline.
	// For slow operations, spawn a goroutine or use a subscription instead.
	//
	// Parameters:
	//   ctx: Context with potential timeout for hook execution
	//   event: The event being processed
	OnEvent(ctx context.Context, event MetricEvent)

	// Name returns a human-readable name for this hook (for logging/debugging).
	Name() string

	// Filter returns an optional filter for this hook.
	// If nil, the hook receives all events.
	// If non-nil, only matching events are delivered.
	//
	// This is more efficient than filtering in OnEvent() as it avoids
	// unnecessary hook invocations.
	Filter() *MetricFilter
}

type MetricsSnapshot struct {
	// Request metrics
	TotalRequests      int64   `json:"total_requests"`
	SuccessfulRequests int64   `json:"successful_requests"`
	FailedRequests     int64   `json:"failed_requests"`
	SuccessRate        float64 `json:"success_rate"` // Calculated: successful/total

	// Latency metrics
	Latency LatencyMetrics `json:"latency"`

	// Token usage metrics
	Tokens TokenMetrics `json:"tokens"`

	// Error metrics
	Errors ErrorMetrics `json:"errors"`

	// Streaming metrics (aggregated across all streaming requests)
	Streaming *StreamMetrics `json:"streaming,omitempty"`

	// Provider breakdown
	ProviderBreakdown map[string]*ProviderMetricsSnapshot `json:"provider_breakdown"`

	// Model breakdown
	ModelBreakdown map[string]*ModelMetricsSnapshot `json:"model_breakdown"`

	// Timestamps
	LastUpdated      time.Time `json:"last_updated"`
	FirstRequestTime time.Time `json:"first_request_time"`
	Uptime           int64     `json:"uptime_seconds"` // Seconds since first request
}

type MetricsSubscription interface {
	// Events returns the channel for receiving metrics events.
	// The channel is closed when the subscription is unsubscribed or the collector is closed.
	//
	// IMPORTANT: Must be continuously read to prevent blocking the collector.
	//
	// Example:
	//   for event := range subscription.Events() {
	//     processEvent(event)
	//   }
	Events() <-chan MetricEvent

	// Unsubscribe closes the subscription and stops event delivery.
	// The Events() channel will be closed.
	// Safe to call multiple times (idempotent).
	//
	// Should be called when the subscriber is done to free resources.
	// Recommended to use defer: defer subscription.Unsubscribe()
	Unsubscribe()

	// ID returns a unique identifier for this subscription.
	// Useful for debugging and logging.
	ID() string

	// OverflowCount returns the number of events that were dropped due to buffer overflow.
	// A non-zero value indicates the subscriber is not keeping up with event rate.
	//
	// If this value is increasing, consider:
	//  - Increasing the buffer size
	//  - Optimizing event processing logic
	//  - Using filtered subscriptions to reduce event volume
	OverflowCount() int64
}

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

type Model struct {
	ID                   string       `json:"id"`
	Name                 string       `json:"name"`
	Provider             ProviderType `json:"provider"`
	Description          string       `json:"description"`
	MaxTokens            int          `json:"max_tokens"`
	InputTokens          int          `json:"input_tokens"`
	OutputTokens         int          `json:"output_tokens"`
	SupportsStreaming    bool         `json:"supports_streaming"`
	SupportsToolCalling  bool         `json:"supports_tool_calling"`
	SupportsResponsesAPI bool         `json:"supports_responses_api"`
	Capabilities         []string     `json:"capabilities"`
	Pricing              Pricing      `json:"pricing"`
}

type ModelCapabilityOverride struct {
	MaxTokens         *int     `json:"max_tokens,omitempty"`
	ContextWindow     *int     `json:"context_window,omitempty"`
	SupportsStreaming *bool    `json:"supports_streaming,omitempty"`
	SupportsTools     *bool    `json:"supports_tools,omitempty"`
	SupportsVision    *bool    `json:"supports_vision,omitempty"`
	Capabilities      []string `json:"capabilities,omitempty"`
}

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

type ModelMetricsSnapshot struct {
	// Model identification
	ModelID      string       `json:"model_id"`
	Provider     string       `json:"provider"`      // Provider name (instance identifier)
	ProviderType ProviderType `json:"provider_type"` // Provider type

	// Request metrics
	TotalRequests      int64   `json:"total_requests"`
	SuccessfulRequests int64   `json:"successful_requests"`
	FailedRequests     int64   `json:"failed_requests"`
	SuccessRate        float64 `json:"success_rate"` // Calculated: successful/total

	// Latency metrics for this model
	Latency LatencyMetrics `json:"latency"`

	// Token usage for this model
	Tokens TokenMetrics `json:"tokens"`

	// Error metrics for this model
	Errors ErrorMetrics `json:"errors"`

	// Streaming metrics for this model
	Streaming *StreamMetrics `json:"streaming,omitempty"`

	// Model-specific metrics
	AverageTokensPerRequest float64 `json:"average_tokens_per_request"` // Calculated: total_tokens / requests
	EstimatedCostPerRequest float64 `json:"estimated_cost_per_request"` // Calculated: total_cost / requests

	// Timestamps
	LastRequestTime time.Time `json:"last_request_time"`
	LastUpdated     time.Time `json:"last_updated"`
}

type ModelProvider interface {
	// Model management
	GetModels(ctx context.Context) ([]Model, error)
	GetDefaultModel() string
}

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

type OAuthConfig struct {
	ClientID     string    `json:"client_id"`
	ClientSecret string    `json:"client_secret"`
	RedirectURL  string    `json:"redirect_url,omitempty"`
	Scopes       []string  `json:"scopes"`
	AuthURL      string    `json:"auth_url,omitempty"`
	TokenURL     string    `json:"token_url,omitempty"`
	RefreshToken string    `json:"refresh_token,omitempty"`
	AccessToken  string    `json:"access_token,omitempty"`
	ExpiresAt    time.Time `json:"expires_at,omitempty"`

	// OnTokenRefresh is called when OAuth tokens are refreshed
	// Parameters: accessToken, refreshToken, expiresAt
	// The callback should return an error if token persistence fails
	OnTokenRefresh func(accessToken, refreshToken string, expiresAt time.Time) error `json:"-"`
}

type OAuthCredentialSet struct {
	// Unique identifier for this credential set (e.g., "account-1", "team-account")
	ID string `json:"id"`

	// OAuth client credentials
	ClientID     string `json:"client_id"`
	ClientSecret string `json:"client_secret"`

	// OAuth tokens
	AccessToken  string    `json:"access_token"`
	RefreshToken string    `json:"refresh_token"`
	ExpiresAt    time.Time `json:"expires_at"`

	// OAuth scopes for this credential
	Scopes []string `json:"scopes,omitempty"`

	// Metadata for tracking
	LastRefresh  time.Time `json:"last_refresh,omitempty"`
	RefreshCount int       `json:"refresh_count"`

	// Callback for when tokens are refreshed
	// Parameters: id, accessToken, refreshToken, expiresAt
	// The callback should persist the new tokens and return an error if persistence fails
	OnTokenRefresh func(id, accessToken, refreshToken string, expiresAt time.Time) error `json:"-"`
}

type OAuthProvider interface {
	// Embed the full Provider interface to maintain compatibility
	Provider

	// ValidateToken validates the current OAuth token and returns detailed token information
	// This method should check token expiration, scope validity, and retrieve user info
	ValidateToken(ctx context.Context) (*TokenInfo, error)

	// RefreshToken refreshes the OAuth token using the stored refresh token
	// This method should update the internal token state and persist the new tokens
	RefreshToken(ctx context.Context) error

	// GetAuthURL generates an OAuth authorization URL for re-authentication
	// redirectURI: The URI where the OAuth provider should redirect after authentication
	// state: A random string to prevent CSRF attacks
	// Returns the complete authorization URL that the user should be redirected to
	GetAuthURL(redirectURI string, state string) string
}

type Pricing struct {
	InputTokenPrice  float64 `json:"input_token_price"`
	OutputTokenPrice float64 `json:"output_token_price"`
	Unit             string  `json:"unit"`
}

type Provider interface {
	CoreProvider
	ModelProvider
	AuthenticatedProvider
	ConfigurableProvider
	ChatProvider
	ToolCallingProvider
	CapabilityProvider
	HealthCheckProvider
}

type ProviderConfig struct {
	Type           ProviderType           `json:"type"`
	Name           string                 `json:"name"`
	BaseURL        string                 `json:"base_url,omitempty"`
	APIKey         string                 `json:"api_key,omitempty"`
	APIKeyEnv      string                 `json:"api_key_env,omitempty"`
	DefaultModel   string                 `json:"default_model,omitempty"`
	Description    string                 `json:"description,omitempty"`
	ProviderConfig map[string]interface{} `json:"provider_config,omitempty"`

	// Multiple OAuth credentials for failover (multi-OAuth)
	OAuthCredentials []*OAuthCredentialSet `json:"oauth_credentials,omitempty"`

	// Model capability overrides - allows users to override model capabilities
	ModelCapabilities map[string]ModelCapabilityOverride `json:"model_capabilities,omitempty"`

	// Feature flags
	SupportsStreaming    bool `json:"supports_streaming"`
	SupportsToolCalling  bool `json:"supports_tool_calling"`
	SupportsResponsesAPI bool `json:"supports_responses_api"`

	// Limits and timeouts
	MaxTokens int           `json:"max_tokens,omitempty"`
	Timeout   time.Duration `json:"timeout,omitempty"`

	// Tool format
	ToolFormat ToolFormat `json:"tool_format,omitempty"`

	// Logging configuration
	EnableVerboseLogging bool `json:"enable_verbose_logging,omitempty"`
}

type ProviderError struct {
	Code        ErrorCode    // Categorized error code
	Message     string       // Human-readable message
	StatusCode  int          // HTTP status code (0 if not applicable)
	Provider    ProviderType // Which provider generated this error
	Operation   string       // What operation failed (e.g., "chat_completion", "list_models")
	OriginalErr error        // Wrapped original error
	RetryAfter  int          // Seconds to wait before retry (for rate limits)
	RequestID   string       // Provider's request ID if available
}

type ProviderFactory interface {
	RegisterProvider(providerType ProviderType, factoryFunc func(ProviderConfig) Provider)
	CreateProvider(providerType ProviderType, config ProviderConfig) (Provider, error)
	GetSupportedProviders() []ProviderType
}

type ProviderFactoryExtensions interface {
	ProviderFactory

	// Create a core provider adapter
	CreateCoreProvider(providerType ProviderType, config ProviderConfig) (CoreChatProvider, error)

	// Get supported provider types for core API
	GetSupportedCoreProviders() []ProviderType

	// Check if a provider type supports the core API
	SupportsCoreAPI(providerType ProviderType) bool
}

type ProviderInfo struct {
	Name           string       `json:"name"`
	Type           ProviderType `json:"type"`
	Description    string       `json:"description"`
	HealthStatus   HealthStatus `json:"health_status"`
	Models         []Model      `json:"models"`
	SupportedTools []string     `json:"supported_tools"`
	DefaultModel   string       `json:"default_model"`
}

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

type ProviderMetrics struct {
	RequestCount    int64         `json:"request_count"`
	SuccessCount    int64         `json:"success_count"`
	ErrorCount      int64         `json:"error_count"`
	TotalLatency    time.Duration `json:"total_latency"`
	AverageLatency  time.Duration `json:"average_latency"`
	LastRequestTime time.Time     `json:"last_request_time"`
	LastSuccessTime time.Time     `json:"last_success_time"`
	LastErrorTime   time.Time     `json:"last_error_time"`
	LastError       string        `json:"last_error"`
	TokensUsed      int64         `json:"tokens_used"`
	HealthStatus    HealthStatus  `json:"health_status"`
}

type ProviderMetricsSnapshot struct {
	// Provider identification
	Provider     string       `json:"provider"`
	ProviderType ProviderType `json:"provider_type"`

	// Request metrics
	TotalRequests      int64   `json:"total_requests"`
	SuccessfulRequests int64   `json:"successful_requests"`
	FailedRequests     int64   `json:"failed_requests"`
	SuccessRate        float64 `json:"success_rate"` // Calculated: successful/total

	// Latency metrics for this provider
	Latency LatencyMetrics `json:"latency"`

	// Token usage for this provider
	Tokens TokenMetrics `json:"tokens"`

	// Error metrics for this provider
	Errors ErrorMetrics `json:"errors"`

	// Streaming metrics for this provider
	Streaming *StreamMetrics `json:"streaming,omitempty"`

	// Provider-specific operations
	Initializations  int64   `json:"initializations"`
	HealthChecks     int64   `json:"health_checks"`
	HealthCheckFails int64   `json:"health_check_fails"`
	HealthCheckRate  float64 `json:"health_check_success_rate"` // Calculated: (checks - fails) / checks
	RateLimitHits    int64   `json:"rate_limit_hits"`

	// Model usage breakdown for this provider
	ModelUsage map[string]int64 `json:"model_usage"`

	// Timestamps
	LastRequestTime time.Time `json:"last_request_time"`
	LastUpdated     time.Time `json:"last_updated"`
}

type ProviderType string

type RouterHealthStatus struct {
	IsHealthy    bool          `json:"IsHealthy"`
	LastChecked  time.Time     `json:"LastChecked"`
	ErrorMessage string        `json:"ErrorMessage,omitempty"`
	ResponseTime time.Duration `json:"ResponseTime"`
}

type RouterMetrics struct {
	TotalRequests       int64                       `json:"total_requests"`
	SuccessfulRequests  int64                       `json:"successful_requests"`
	FailedRequests      int64                       `json:"failed_requests"`
	ProviderUsage       map[string]int64            `json:"provider_usage"`
	AverageResponseTime time.Duration               `json:"average_response_time"`
	ProviderMetrics     map[string]*ProviderMetrics `json:"provider_metrics"`
	LastReset           time.Time                   `json:"last_reset"`
}

type RunningModel struct {
	Name      string    `json:"name"`       // Model name/identifier
	Model     string    `json:"model"`      // Model identifier (may be same as Name)
	Size      int64     `json:"size"`       // Total model size in bytes
	Digest    string    `json:"digest"`     // Model digest/hash
	ExpiresAt time.Time `json:"expires_at"` // When the model will be unloaded from memory
	SizeVRAM  int64     `json:"size_vram"`  // Size of model in VRAM (GPU memory) in bytes
}

type StandardChoice struct {
	Index        int         `json:"index"`
	Message      ChatMessage `json:"message"`
	FinishReason string      `json:"finish_reason"`
}

type StandardRequest struct {
	// Core content
	Messages []ChatMessage `json:"messages"`

	// Model selection
	Model string `json:"model,omitempty"`

	// Generation parameters
	MaxTokens   int      `json:"max_tokens,omitempty"`
	Temperature float64  `json:"temperature,omitempty"`
	Stop        []string `json:"stop,omitempty"`

	// Streaming control
	Stream bool `json:"stream"`

	// Tool support (if provider supports it)
	Tools      []Tool      `json:"tools,omitempty"`
	ToolChoice *ToolChoice `json:"tool_choice,omitempty"`

	// Response format (for providers that support structured output)
	ResponseFormat string `json:"response_format,omitempty"`

	// Context and metadata
	Context  context.Context        `json:"-"`
	Timeout  time.Duration          `json:"-"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type StandardResponse struct {
	// Core response
	ID      string `json:"id"`
	Model   string `json:"model"`
	Object  string `json:"object"`
	Created int64  `json:"created"`

	// Content
	Choices []StandardChoice `json:"choices"`

	// Usage information
	Usage Usage `json:"usage"`

	// Provider-specific metadata
	ProviderMetadata map[string]interface{} `json:"provider_metadata,omitempty"`
}

type StandardStream interface {
	// Next returns the next chunk from the stream
	Next() (*StandardStreamChunk, error)

	// Close closes the stream
	Close() error

	// Done returns true if the stream is finished
	Done() bool
}

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

type StandardStreamChoice struct {
	Index        int         `json:"index"`
	Delta        ChatMessage `json:"delta"`
	FinishReason string      `json:"finish_reason,omitempty"`
}

type StandardStreamChunk struct {
	ID      string `json:"id"`
	Model   string `json:"model"`
	Object  string `json:"object"`
	Created int64  `json:"created"`

	// Content
	Choices []StandardStreamChoice `json:"choices"`

	// Usage information (may be nil for intermediate chunks)
	Usage *Usage `json:"usage,omitempty"`

	// Stream state
	Done bool `json:"done"`

	// Provider-specific metadata
	ProviderMetadata map[string]interface{} `json:"provider_metadata,omitempty"`
}

type StreamMetrics struct {
	// Streaming request counts
	TotalStreamRequests      int64   `json:"total_stream_requests"`
	SuccessfulStreamRequests int64   `json:"successful_stream_requests"`
	FailedStreamRequests     int64   `json:"failed_stream_requests"`
	StreamSuccessRate        float64 `json:"stream_success_rate"` // Calculated: successful/total

	// Time to First Token (TTFT) metrics
	TimeToFirstToken TimeToFirstTokenMetrics `json:"time_to_first_token"`

	// Throughput metrics
	AverageTokensPerSecond float64 `json:"average_tokens_per_second"` // Calculated: total_tokens / total_duration
	MinTokensPerSecond     float64 `json:"min_tokens_per_second"`
	MaxTokensPerSecond     float64 `json:"max_tokens_per_second"`
	MedianTokensPerSecond  float64 `json:"median_tokens_per_second"`

	// Stream duration statistics
	AverageStreamDuration time.Duration `json:"average_stream_duration"`
	MinStreamDuration     time.Duration `json:"min_stream_duration"`
	MaxStreamDuration     time.Duration `json:"max_stream_duration"`

	// Token statistics for streaming
	TotalStreamedTokens    int64   `json:"total_streamed_tokens"`
	AverageTokensPerStream float64 `json:"average_tokens_per_stream"` // Calculated: total_streamed_tokens / successful_streams

	// Chunk statistics
	TotalChunks            int64   `json:"total_chunks"`
	AverageChunksPerStream float64 `json:"average_chunks_per_stream"` // Calculated: total_chunks / successful_streams
	AverageChunkSize       float64 `json:"average_chunk_size"`        // Calculated: total_streamed_tokens / total_chunks

	// Last updated
	LastUpdated time.Time `json:"last_updated"`
}

type TestError struct {
	ErrorType    TestErrorType `json:"error_type"`
	Message      string        `json:"message"`
	Phase        TestPhase     `json:"phase"`
	ProviderType ProviderType  `json:"provider_type"`
	Retryable    bool          `json:"retryable"`
	StatusCode   int           `json:"status_code,omitempty"`
	OriginalErr  string        `json:"original_err,omitempty"`
}

type TestErrorType string

type TestPhase string

type TestResult struct {
	Status       TestStatus        `json:"status"`
	Error        string            `json:"error,omitempty"`
	Details      map[string]string `json:"details,omitempty"`
	ModelsCount  int               `json:"models_count,omitempty"`
	Phase        TestPhase         `json:"phase"`
	Timestamp    time.Time         `json:"timestamp"`
	Duration     time.Duration     `json:"duration"`
	ProviderType ProviderType      `json:"provider_type"`
	TestError    *TestError        `json:"test_error,omitempty"`
}

type TestStatus string

type TestableProvider interface {
	// Embed the full Provider interface to maintain compatibility
	Provider

	// TestConnectivity performs a connectivity test to verify the provider can reach its service
	// This method should perform a lightweight operation to verify network connectivity,
	// authentication, and basic service availability. It should not perform heavy operations
	// that might impact rate limits or incur costs.
	// Returns an error if connectivity cannot be established
	TestConnectivity(ctx context.Context) error
}

type TimeToFirstTokenMetrics struct {
	// Summary statistics
	TotalMeasurements int64         `json:"total_measurements"`
	AverageTTFT       time.Duration `json:"average_ttft"`

	// Min/Max
	MinTTFT time.Duration `json:"min_ttft"`
	MaxTTFT time.Duration `json:"max_ttft"`

	// Percentiles for TTFT distribution
	P50TTFT time.Duration `json:"p50_ttft"` // Median
	P75TTFT time.Duration `json:"p75_ttft"`
	P90TTFT time.Duration `json:"p90_ttft"`
	P95TTFT time.Duration `json:"p95_ttft"`
	P99TTFT time.Duration `json:"p99_ttft"`

	// Last updated
	LastUpdated time.Time `json:"last_updated"`
}

type TokenInfo struct {
	// Valid indicates whether the token is currently valid
	Valid bool `json:"valid"`

	// ExpiresAt indicates when the token expires
	ExpiresAt time.Time `json:"expires_at"`

	// Scope contains the OAuth scopes granted to the token
	Scope []string `json:"scope"`

	// UserInfo contains user information from the OAuth provider
	UserInfo map[string]interface{} `json:"user_info"`
}

type TokenMetrics struct {
	// Total token counts
	TotalTokens  int64 `json:"total_tokens"`
	InputTokens  int64 `json:"input_tokens"`
	OutputTokens int64 `json:"output_tokens"`

	// Cached token usage (for providers that support prompt caching)
	CachedTokens        int64 `json:"cached_tokens,omitempty"`
	CacheReadTokens     int64 `json:"cache_read_tokens,omitempty"`
	CacheCreationTokens int64 `json:"cache_creation_tokens,omitempty"`

	// Reasoning tokens (for models with extended thinking)
	ReasoningTokens int64 `json:"reasoning_tokens,omitempty"`

	// Average token usage per request
	AverageInputTokens  float64 `json:"average_input_tokens"`  // Calculated: input_tokens / requests
	AverageOutputTokens float64 `json:"average_output_tokens"` // Calculated: output_tokens / requests
	AverageTotalTokens  float64 `json:"average_total_tokens"`  // Calculated: total_tokens / requests

	// Token efficiency metrics
	InputOutputRatio float64 `json:"input_output_ratio"`       // Calculated: input_tokens / output_tokens
	CacheHitRate     float64 `json:"cache_hit_rate,omitempty"` // Calculated: cache_read_tokens / input_tokens

	// Cost estimation
	EstimatedCost       float64 `json:"estimated_cost"`
	Currency            string  `json:"currency"`
	EstimatedInputCost  float64 `json:"estimated_input_cost"`
	EstimatedOutputCost float64 `json:"estimated_output_cost"`
	EstimatedCachedCost float64 `json:"estimated_cached_cost,omitempty"`

	// Cost per token (for reference)
	InputCostPerToken  float64 `json:"input_cost_per_token,omitempty"`
	OutputCostPerToken float64 `json:"output_cost_per_token,omitempty"`
	CachedCostPerToken float64 `json:"cached_cost_per_token,omitempty"`

	// Last updated
	LastUpdated time.Time `json:"last_updated"`
}

type TokenStorage interface {
	StoreToken(key string, token *OAuthConfig) error
	RetrieveToken(key string) (*OAuthConfig, error)
	DeleteToken(key string) error
	ListTokens() ([]string, error)
}

type Tool struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description"`
	InputSchema map[string]interface{} `json:"input_schema"`
}

type ToolCall struct {
	ID       string                 `json:"id"`
	Type     string                 `json:"type"`
	Function ToolCallFunction       `json:"function"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ToolCallFunction struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type ToolCallingProvider interface {
	// Tool invocation
	InvokeServerTool(ctx context.Context, toolName string, params interface{}) (interface{}, error)

	// Tool format support
	SupportsToolCalling() bool
	GetToolFormat() ToolFormat
}

type ToolChoice struct {
	Mode         ToolChoiceMode `json:"mode"`
	FunctionName string         `json:"function_name,omitempty"` // For "specific" mode
}

type ToolChoiceMode string

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

type ToolFormat string

type Usage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type ValidationError struct {
	Message string
}