router

type APIKeyConfig struct {
	// Allowed providers for this API key
	AllowedProviders []string

	// Allowed models for this API key
	AllowedModels []string

	// Model-specific overrides
	ModelOverrides map[string]string

	// Rate limit tier
	RateLimitTier string

	// CredentialStrategy selects request-bound operator and tenant credential order.
	CredentialStrategy byok.Strategy
}

type Config struct {
	// Latency tracking configuration
	LatencyAlpha      float64 // EMA smoothing factor (0-1)
	LatencyWindowSize int     // Samples before EMA kicks in

	// Cost optimization
	EnableCostOptimization bool

	// Sticky sessions
	EnableStickySessions bool
	SessionTTL           time.Duration

	// Execution owns the one total retry and fallback budget.
	Execution execution.Config

	// Availability owns exact offering circuit state.
	Availability availability.Config
}

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

type EmbeddingRequest struct {
	*connectors.EmbeddingsRequest
	APIKeyConfig *APIKeyConfig
	TenantID     string
}

type EmbeddingResponse struct {
	Response        inference.EmbeddingResponse
	ModelUsed       string
	ProviderUsed    string
	Attempts        int
	Metadata        *Metadata
	CatalogSnapshot *runtimecatalog.RoutableSnapshot
}

type LatencyTracker interface {
	// RecordLatency records a latency measurement for a provider
	RecordLatency(provider string, latency time.Duration)

	// GetLatency returns the current EMA latency for a provider
	GetLatency(provider string) time.Duration

	// GetAllLatencies returns latencies for all tracked providers
	GetAllLatencies() map[string]time.Duration

	// Reset clears all latency data
	Reset()
}

type Metadata struct {
	// Models that were tried
	ModelsAttempted []ModelAttempt `json:"models_attempted"`

	// Total routing time
	RoutingDuration time.Duration `json:"routing_duration_ms"`

	// Reason for final model selection
	SelectionReason string `json:"selection_reason"`
}

type ModelAttempt struct {
	Model    string        `json:"model"`
	Provider string        `json:"provider"`
	Error    string        `json:"error,omitempty"`
	Duration time.Duration `json:"duration_ms"`
	Status   string        `json:"status"` // "success", "failed", "skipped"
}

type ModelRouter interface {
	// SelectModel chooses the best model based on the request and routing strategy
	// Returns the selected model ID and the connector to use
	SelectModel(ctx context.Context, req *Request) (modelID string, connector connectors.Connector, err error)

	// RouteWithFallback attempts to route a request through multiple models with fallback logic
	// Returns the response and which model was actually used
	RouteWithFallback(ctx context.Context, req *Request) (*Response, error)

	// RouteStream executes the same immutable route plan and budget for streaming.
	RouteStream(ctx context.Context, req *Request) (execution.ManagedStream, error)

	// RouteEmbeddings executes one embedding request through the same route,
	// credential, availability, and total-attempt policies as chat requests.
	RouteEmbeddings(ctx context.Context, req *EmbeddingRequest) (*EmbeddingResponse, error)
}

type Option func(*modelRouter)

type ProviderPreferences struct {
	// Try providers in this order
	Order []string `json:"order,omitempty"`

	// Only use these providers
	Only []string `json:"only,omitempty"`

	// Never use these providers
	Ignore []string `json:"ignore,omitempty"`

	// Allow fallback to other providers not in order list
	AllowFallbacks bool `json:"allow_fallbacks,omitempty"`
}

type Request struct {
	// Original chat request
	*connectors.ChatRequest

	// Models to try in order (fallback chain)
	Models []string

	// Provider routing preferences
	ProviderPreferences *ProviderPreferences

	// API key configuration (for provider restrictions)
	APIKeyConfig *APIKeyConfig

	// TenantID selects the exact user-scoped provider credential record.
	TenantID string

	// Request metadata for routing decisions
	Metadata *RequestMetadata

	// PrepareAttempt optionally adjusts the provider request for the selected
	// model immediately before invoking the connector.
	PrepareAttempt func(route routing.Route, req *connectors.ChatRequest) *connectors.ChatRequest
}

type RequestMetadata struct {
	// Estimated tokens in the request
	EstimatedTokens int

	// Required features (e.g., "vision", "function_calling")
	RequiredFeatures []string

	// Conversation ID for sticky routing
	ConversationID string

	// User preferences
	UserPreferences map[string]any
}

type Response struct {
	// The actual response from the model
	*connectors.ChatResponse

	// Which model was actually used
	ModelUsed string `json:"model_used"`

	// Provider that handled the request
	ProviderUsed string `json:"provider_used"`

	// Number of attempts made
	Attempts int `json:"attempts"`

	// Routing metadata
	Metadata *Metadata `json:"metadata,omitempty"`

	// CatalogSnapshot is the exact leased runtime generation that produced the
	// response.
	CatalogSnapshot *runtimecatalog.RoutableSnapshot `json:"-"`
}

type StickyProviderSessionManager interface {
	// GetProvider returns the provider for a conversation, if any
	GetProvider(conversationID string) (string, bool)

	// SetProvider sets the provider for a conversation
	SetProvider(conversationID string, provider string)

	// RemoveSession removes a conversation's sticky session
	RemoveSession(conversationID string)

	// CleanupExpired removes expired sessions
	CleanupExpired()
}

type UserCredentialResolver interface {
	ResolveUserMaterial(context.Context, string, catalogs.Provider) (credentials.Material, error)
}