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 is the effective credential order for this request,
	// already resolved against the account's governing strategy by the caller.
	CredentialStrategy keyring.Strategy

	// Access carries the account's paired provider and model grants into
	// planning. Nil grants every provider and model.
	Access []routing.ProviderAccess

	// BYOKProviders gates which providers the BYOK credential source may
	// serve for this request. Nil allows every provider, an empty list
	// allows none, and a non-empty list allows only its members. The caller
	// resolves it from the account's BYOK policy so this package never
	// learns the account vocabulary.
	BYOKProviders *[]string
}

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
	AccountID    string
}

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

type ImagesRequest = MediaRequest[inference.ImagesRequest]

type ImagesResponse = MediaResponse[inference.ImagesResponse]

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 MediaRequest[Request any] = OperationRequest[Request]

type MediaResponse[Response any] = OperationResponse[Response]

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)

	// RouteRerank scores one document list against a query through the same
	// route, credential, availability, and total-attempt policies as chat.
	RouteRerank(ctx context.Context, req *RerankRequest) (*RerankResponse, error)

	// RouteModerations classifies one input list against a provider's harm
	// categories through the same policies as chat.
	RouteModerations(ctx context.Context, req *ModerationRequest) (*ModerationResponse, error)

	// RouteImages executes one image generation or image edit request.
	RouteImages(ctx context.Context, req *ImagesRequest) (*ImagesResponse, error)

	// RouteSpeech executes one text-to-speech request.
	RouteSpeech(ctx context.Context, req *SpeechRequest) (*SpeechResponse, error)

	// RouteTranscription executes one speech-to-text request, in the spoken
	// language or translated into English.
	RouteTranscription(ctx context.Context, req *TranscriptionRequest) (*TranscriptionResponse, error)

	// RouteVideoSubmit starts one video generation at a provider that serves
	// it, and answers with the provider's own job identifier.
	RouteVideoSubmit(ctx context.Context, req *VideoSubmitRequest) (*VideoJobResponse, error)

	// RouteVideoPoll asks the provider that accepted a job where it got to.
	RouteVideoPoll(ctx context.Context, req *VideoJobRequest) (*VideoJobResponse, error)

	// RouteVideoCancel asks the provider that accepted a job to stop it.
	RouteVideoCancel(ctx context.Context, req *VideoJobRequest) (*VideoJobResponse, error)

	// RouteVideoContent reads the finished output of one accepted job from the
	// provider that produced it.
	RouteVideoContent(ctx context.Context, req *VideoAssetRequest) (*VideoAssetResponse, error)

	// RouteDocumentRecognition reads the text off a document whose pages carry
	// none. The gateway orders this read on a caller's behalf inside a chat
	// turn, so it is the one route no HTTP path reaches.
	RouteDocumentRecognition(ctx context.Context, req *RecognitionRequest) (*RecognitionResponse, error)
}

type ModerationRequest = OperationRequest[inference.ModerationRequest]

type ModerationResponse = OperationResponse[inference.ModerationResponse]

type OperationRequest[Request any] struct {
	Request      Request
	APIKeyConfig *APIKeyConfig
	AccountID    string
}

type OperationResponse[Response any] struct {
	Response         Response
	ModelUsed        string
	ProviderUsed     string
	CredentialSource string
	Attempts         int
	Metadata         *Metadata
	CatalogSnapshot  *runtimecatalog.RoutableSnapshot
}

type OperatorCredentialGate interface {
	OperatorMaterialReady(providerID string, materialVersion string) bool
}

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"`

	// Sort selects the route ordering: "price", "latency", "throughput",
	// or "spread". Starport measures latency, not throughput, so
	// "throughput" routes by measured latency. "spread" balances traffic
	// across the leading ranking band. Empty keeps the server default.
	Sort string `json:"sort,omitempty"`

	// MaxPromptPricePer1M and MaxCompletionPricePer1M cap the accepted route
	// price in USD per million tokens. Zero means no cap.
	MaxPromptPricePer1M     float64 `json:"max_prompt_price_per_1m,omitempty"`
	MaxCompletionPricePer1M float64 `json:"max_completion_price_per_1m,omitempty"`
}

type RecognitionRequest = MediaRequest[inference.RecognitionRequest]

type RecognitionResponse = MediaResponse[inference.RecognitionResponse]

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

	// AccountID selects the account whose BYOK credential record the request
	// may read. It is never a gateway API key ID.
	AccountID 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

	// RequiredModalities names the media the request carries, such as
	// "audio". A model that does not read one of them cannot answer the
	// request, so the planner drops it rather than letting the provider
	// refuse the call.
	RequiredModalities []string

	// Conversation ID for sticky routing
	ConversationID string

	// User preferences
	UserPreferences map[string]any
}

type RerankRequest = OperationRequest[inference.RerankRequest]

type RerankResponse = OperationResponse[inference.RerankResponse]

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"`

	// CredentialSource names which credential plane paid for the attempt
	// that answered: the operator's environment, the operator's shared
	// credential, the account's own BYOK, or no credential at all.
	CredentialSource string `json:"credential_source,omitempty"`

	// 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 SharedLatencyTracker struct {
	// contains filtered or unexported fields
}

type SpeechRequest = MediaRequest[inference.SpeechRequest]

type SpeechResponse = MediaResponse[inference.SpeechResponse]

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 StoredCredentialResolver interface {
	ResolveStoredMaterial(context.Context, string, catalogs.Provider) (credentials.Material, error)
	ResolveSharedMaterial(context.Context, string, catalogs.Provider) (credentials.Material, error)
}

type StreamEvidence interface {
	ProviderUsed() string
	CredentialSourceUsed() string
	AttemptCount() int
	RoutingDuration() time.Duration
	CatalogSnapshot() *runtimecatalog.RoutableSnapshot
}

type TranscriptionRequest = MediaRequest[inference.TranscriptionRequest]

type TranscriptionResponse = MediaResponse[inference.TranscriptionResponse]

type VideoAssetReference struct {
	VideoJobReference
	// MaxBytes is the largest asset the caller will store. It travels with the
	// request rather than living here, because the half that stores the bytes
	// is the half that decides what it is willing to store.
	MaxBytes int64
}

type VideoAssetRequest = MediaRequest[VideoAssetReference]

type VideoAssetResponse = MediaResponse[connectors.JobAsset]

type VideoJobReference struct {
	// Provider is who accepted the job. Planning is pinned to it.
	Provider string
	// Model is the catalog model the job runs. The plan needs it to find the
	// offering that names the endpoint.
	Model string
	// ProviderJobID is the provider's own identifier. It reaches this package
	// from the job record and travels no further than the request body.
	ProviderJobID string
}

type VideoJobRequest = MediaRequest[VideoJobReference]

type VideoJobResponse = MediaResponse[connectors.ProviderJob]

type VideoSubmitRequest = MediaRequest[inference.VideoJobRequest]