proxy

type APIKeyRoutingConfig struct {
	AllowedProviders   []string
	AllowedModels      []string
	ModelOverrides     map[string]string
	RateLimitTier      string
	CredentialStrategy keyring.Strategy

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

	// BYOKProviders gates which providers the BYOK credential source may
	// serve: nil allows every provider, an empty list none, a non-empty
	// list only its members. It is the account's BYOK policy resolved to
	// plain data, so this package never learns the account vocabulary.
	BYOKProviders *[]string
}

type AuthorInfo = view.AuthorInfo

type AuthorsResponse struct {
	Authors []AuthorInfo `json:"authors"`

	// Internal fields (not serialized)
	CacheStatus string `json:"-"`
}

type CacheConfig struct {
	// Enable caching for different endpoints
	EnableChatCache      bool `env:"ENABLE_CHAT_CACHE,default=true"`
	EnableEmbeddingCache bool `env:"ENABLE_EMBEDDING_CACHE,default=true"`
	EnableModelCache     bool `env:"ENABLE_MODEL_CACHE,default=true"`
	EnableProviderCache  bool `env:"ENABLE_PROVIDER_CACHE,default=true"`
	// Skip cache for specific models or patterns
	SkipCacheModels []string `env:"SKIP_CACHE_MODELS"`
	// Force cache refresh header
	CacheControlHeader string `env:"CACHE_CONTROL_HEADER,default=X-Cache-Control"`

	// EnableSemanticCache turns on the similarity layer beside the exact
	// identity. Each request still opts in per call, and the layer only
	// runs where the exact cache already deemed the request cacheable.
	// Composition sets these fields from the deployment configuration, so
	// they carry no env tags.
	EnableSemanticCache bool
	// SemanticThreshold is the minimum cosine similarity that answers.
	// Zero takes the cache package default.
	SemanticThreshold float64
	// SemanticMaxEntries bounds the vectors one similarity scope holds.
	// Zero takes the cache package default.
	SemanticMaxEntries int
	// SemanticEmbedder embeds the canonical prompt text through the
	// gateway's own embeddings path. Nil keeps the layer off.
	SemanticEmbedder SemanticEmbedder
}

type CacheCost struct {
	WriteTokens float64 `json:"write_tokens"` // Cost of writing tokens to cache
	ReadTokens  float64 `json:"read_tokens"`  // Cost of reading tokens from cache
	TotalCost   float64 `json:"total_cost"`   // Total cost including cache operations
}

type CacheManager interface {
	GetModel(ctx context.Context, key string) (any, bool, error)
	SetModel(ctx context.Context, key string, value any) error
	GetResponse(ctx context.Context, key string) ([]byte, bool, error)
	SetResponse(ctx context.Context, key string, response []byte) error
}

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

type CacheSimilarityProvider interface {
	GetCacheSimilarity() float64
}

type CacheStatusProvider interface {
	GetCacheStatus() string
	GetCacheAge() int // Returns cache age in seconds, or 0 if not cached
}

type ChatCompletionRequest struct {
	Request  inference.ChatRequest
	Route    string
	Provider *ProviderPreferences
	// Preset names a stored preset selected by the request body. A
	// "@preset/<name>" model reference selects one the same way and wins
	// over this field.
	Preset string

	// Internal fields
	APIKey string `json:"-"`
	// AccountID is the account the request runs under. Credential selection,
	// response cache scope, and account limits read this.
	AccountID string `json:"-"`
	// KeyID is the gateway API key that authenticated the request. Usage
	// attribution and per-key limits read this. Many keys share one account, so
	// the two values are distinct and neither substitutes for the other.
	KeyID string `json:"-"`
	// TeamID is the team the serving key is attributed to, or empty for a
	// teamless key. Usage attribution and the team budget read this.
	TeamID       string               `json:"-"`
	APIKeyConfig *APIKeyRoutingConfig `json:"-"`
	RequestID    string               `json:"-"`
	Protocol     string               `json:"-"` // Protocol surface that received the request
	// BatchID names the batch this request runs inside, or is empty for an
	// online request. The usage record carries it, so an operator can read
	// what one batch spent.
	BatchID string `json:"-"`
	// SemanticCache opts this request into the similarity layer, when the
	// deployment enables one. The X-Semantic-Cache header states it.
	SemanticCache bool `json:"-"`
}

type ChatCompletionResponse struct {
	Response inference.ChatResponse

	// ExtractionCached reports that every document this turn attached came
	// back from the extraction cache. It is separate from CacheStatus below,
	// which reports the response cache: a turn can read its attachments from
	// the cache and still call the model, and that is the common case for a
	// conversation about one document.
	ExtractionCached bool `json:"-"`

	// The rest of the document read, as the usage record reports it: which
	// engine ran, how many pages it read each way, which model recognized
	// them, what that cost in integer nano-USD, and how long it took.
	ExtractionEngine   string        `json:"-"`
	ExtractionPages    int           `json:"-"`
	RecognizedPages    int           `json:"-"`
	NativePages        int           `json:"-"`
	ExtractionOffering string        `json:"-"`
	ExtractionNanoUSD  int64         `json:"-"`
	ExtractionUnpriced bool          `json:"-"`
	ExtractionDuration time.Duration `json:"-"`

	// Internal fields (not serialized)
	CacheStatus string     `json:"-"`
	CacheAge    int        `json:"-"` // Seconds since cached
	ETag        string     `json:"-"` // Entity tag for response
	CacheCost   *CacheCost `json:"-"` // Cache pricing information
	// CacheSimilarity is the cosine similarity a semantic hit served
	// under, or zero for an exact hit or a miss. The X-Cache-Similarity
	// header reports it beside the shared cache status vocabulary.
	CacheSimilarity float64 `json:"-"`

	// Route evidence (not serialized)
	ProviderUsed     string                           `json:"-"`
	CredentialSource string                           `json:"-"`
	Attempts         int                              `json:"-"`
	RoutingDuration  time.Duration                    `json:"-"`
	CatalogSnapshot  *runtimecatalog.RoutableSnapshot `json:"-"`

	// GuardrailVerdict is the strongest verdict the guardrail pipeline
	// answered over this turn: allow, redact, or refuse. Empty means no
	// guardrail ran. The usage record carries it; the wire never does.
	GuardrailVerdict string `json:"-"`
}

type ChatCompletionStreamResponse interface {
	// Read returns the next canonical event or io.EOF when done.
	Read() (*inference.StreamEvent, error)

	// Close releases any resources
	Close() error
}

type Config struct {
	// Registry provides access to LLM provider connectors
	Registry connectors.LeasingRegistry

	// Router handles intelligent model selection and failover
	Router router.ModelRouter

	// CacheManager handles response caching (optional)
	CacheManager CacheManager

	// CacheConfig configures caching behavior (optional)
	CacheConfig *CacheConfig

	// TokenEstimator synthesizes estimated usage for streams that end
	// without provider-reported usage (optional)
	TokenEstimator *tokenize.Estimator

	// FileResolver reads the bytes behind a stored document reference
	// (optional). A deployment without one refuses a request that names a
	// file rather than sending the model an empty document.
	FileResolver FileResolver

	// DocumentExtractor is the native parser engine, with the page and time
	// bounds this deployment sets (optional). A deployment without one reads
	// documents under the engine's own default bounds.
	DocumentExtractor *document.Extractor

	// DocumentCache holds one document's text for reuse inside a window
	// (optional). A deployment without one reads every attachment on every
	// turn, which is correct and pays the page price each time.
	DocumentCache *document.Cache
}

type CredentialFieldInfo = view.CredentialFieldInfo

type EmbeddingsRequest struct {
	Request inference.EmbeddingRequest

	// Internal fields
	APIKey string `json:"-"`
	// AccountID is the account the request runs under. Credential selection,
	// response cache scope, and account limits read this.
	AccountID string `json:"-"`
	// KeyID is the gateway API key that authenticated the request. Usage
	// attribution and per-key limits read this. Many keys share one account, so
	// the two values are distinct and neither substitutes for the other.
	KeyID string `json:"-"`
	// TeamID is the team the serving key is attributed to, or empty for a
	// teamless key. Usage attribution and the team budget read this.
	TeamID       string               `json:"-"`
	APIKeyConfig *APIKeyRoutingConfig `json:"-"`
	RequestID    string               `json:"-"`
	Protocol     string               `json:"-"` // Protocol surface that received the request
	// BatchID names the batch this request runs inside, or is empty for an
	// online request. The usage record carries it, so an operator can read
	// what one batch spent.
	BatchID string `json:"-"`
}

type EmbeddingsResponse struct {
	Response inference.EmbeddingResponse

	// Internal fields (not serialized)
	CacheStatus string     `json:"-"`
	CacheAge    int        `json:"-"` // Seconds since cached
	ETag        string     `json:"-"` // Entity tag for response
	CacheCost   *CacheCost `json:"-"` // Cache pricing information

	// Route evidence (not serialized)
	ModelUsed        string                           `json:"-"`
	ProviderUsed     string                           `json:"-"`
	CredentialSource string                           `json:"-"`
	Attempts         int                              `json:"-"`
	RoutingDuration  time.Duration                    `json:"-"`
	CatalogSnapshot  *runtimecatalog.RoutableSnapshot `json:"-"`
}

type EndpointInfo = view.EndpointInfo

type FileResolver interface {
	ResolveDocument(ctx context.Context, account, id string) (StoredDocument, bool, error)
}

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

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

type GuardrailVerdictProvider interface {
	GuardrailVerdict() string
}

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

type ImagesRequest = OperationRequest[inference.ImagesRequest]

type ImagesResponse = OperationResponse[inference.ImagesResponse]

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

type MediaRequest[Request any] = OperationRequest[Request]

type MediaResponse[Response any] = OperationResponse[Response]

type Middleware interface {
	// Wrap wraps the given proxy with the middleware functionality
	Wrap(Proxy) Proxy
}

type ModelArchitecture = view.ModelArchitecture

type ModelAuthorInfo = view.ModelAuthorInfo

type ModelEndpointsResponse struct {
	Model     string         `json:"model"`
	Endpoints []EndpointInfo `json:"endpoints"`
}

type ModelInfo = view.ModelInfo

type ModelLineageInfo = view.ModelLineageInfo

type ModelOfferingInfo = view.ModelOfferingInfo

type ModelPricing = view.ModelPricing

type ModelsResponse struct {
	Object string      `json:"object"`
	Data   []ModelInfo `json:"data"`

	// Internal fields (not serialized)
	CacheStatus string `json:"-"`
}

type ModerationRequest = OperationRequest[inference.ModerationRequest]

type ModerationResponse = OperationResponse[inference.ModerationResponse]

type OfferingPricingInfo = view.OfferingPricingInfo

type OperationRequest[Request any] struct {
	Request Request

	APIKey string `json:"-"`
	// AccountID is the account the request runs under. Credential selection
	// and account limits read this.
	AccountID string `json:"-"`
	// KeyID is the gateway API key that authenticated the request. Usage
	// attribution and per-key limits read this.
	KeyID string `json:"-"`
	// TeamID is the team the serving key is attributed to, or empty for a
	// teamless key. Usage attribution and the team budget read this.
	TeamID       string               `json:"-"`
	APIKeyConfig *APIKeyRoutingConfig `json:"-"`
	RequestID    string               `json:"-"`
	Protocol     string               `json:"-"`
}

type OperationResponse[Response any] struct {
	Response Response

	ModelUsed        string                           `json:"-"`
	ProviderUsed     string                           `json:"-"`
	CredentialSource string                           `json:"-"`
	Attempts         int                              `json:"-"`
	RoutingDuration  time.Duration                    `json:"-"`
	CatalogSnapshot  *runtimecatalog.RoutableSnapshot `json:"-"`

	// Cost is what this turn cost, once the accounting middleware has priced it
	// against the snapshot that routed it. It is nil until then, and it stays
	// nil on a turn the catalog could not price. A protocol that names a cost on
	// its usage block reads this field, so the number the caller sees and the
	// number the account is billed come from one derivation.
	Cost *usage.Cost `json:"-"`
}

type Option func(*Config)

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

type PresetSource interface {
	Get(ctx context.Context, name string) (presets.Record, error)
	GetRevision(ctx context.Context, name string, revision uint64) (presets.Record, error)
}

type ProviderError struct {
	Provider string
	Code     string
	Message  string
	Err      error
}

type ProviderInfo = view.ProviderInfo

type ProviderPolicyInfo = view.ProviderPolicyInfo

type ProviderPreferences struct {
	Order         []string `json:"order,omitempty"`
	Ignore        []string `json:"ignore,omitempty"`
	Only          []string `json:"only,omitempty"`
	AllowFallback bool     `json:"allow_fallback,omitempty"`

	// Sort selects route ordering: "price", "latency", "throughput"
	// (routed by measured latency), or "spread" (weighted balance inside
	// 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 ProvidersResponse struct {
	Providers []ProviderInfo `json:"providers"`

	// Internal fields (not serialized)
	CacheStatus string `json:"-"`
}

type Proxy interface {
	// ProcessChatCompletion handles chat completion requests with routing and processing
	ProcessChatCompletion(ctx context.Context, req *ChatCompletionRequest) (*ChatCompletionResponse, error)

	// ProcessChatCompletionStream handles streaming chat completion requests
	ProcessChatCompletionStream(ctx context.Context, req *ChatCompletionRequest) (ChatCompletionStreamResponse, error)

	// ProcessEmbeddings handles embedding generation requests
	ProcessEmbeddings(ctx context.Context, req *EmbeddingsRequest) (*EmbeddingsResponse, error)

	// ProcessRerank scores one document list against a query and answers with
	// the caller's own document positions in ranked order.
	ProcessRerank(ctx context.Context, req *RerankRequest) (*RerankResponse, error)

	// ProcessModerations classifies each input against a provider's harm
	// categories and answers with a verdict and a score per category.
	ProcessModerations(ctx context.Context, req *ModerationRequest) (*ModerationResponse, error)

	// ProcessImages handles image generation and image edit requests.
	ProcessImages(ctx context.Context, req *ImagesRequest) (*ImagesResponse, error)

	// ProcessSpeech handles text-to-speech requests.
	ProcessSpeech(ctx context.Context, req *SpeechRequest) (*SpeechResponse, error)

	// ProcessTranscription handles speech-to-text requests, in the spoken
	// language or translated into English.
	ProcessTranscription(ctx context.Context, req *TranscriptionRequest) (*TranscriptionResponse, error)

	// SubmitVideoJob starts one video generation and answers with the
	// provider's own job identifier. Nothing above this interface stores that
	// identifier except the job record, which never hands it back out.
	SubmitVideoJob(ctx context.Context, req *VideoSubmitRequest) (*VideoJobAnswer, error)

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

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

	// FetchVideoAsset reads the finished output of one accepted job.
	FetchVideoAsset(ctx context.Context, req *VideoAssetRequest) (*VideoAsset, error)

	// VideoJobRunner returns the provider side of one caller's video jobs,
	// bound to the gateway identity the request carries. The record store
	// drives a job through this value and names no transport itself.
	VideoJobRunner(req *VideoSubmitRequest) jobs.Runner

	// ListModels returns available models based on routing configuration
	ListModels(ctx context.Context) (*ModelsResponse, error)

	// ListProviders returns available provider information
	ListProviders(ctx context.Context) (*ProvidersResponse, error)

	// ListAuthors returns catalog author information
	ListAuthors(ctx context.Context) (*AuthorsResponse, error)

	// GetAuthor returns one catalog author. It reports a not_found
	// provider error for an unknown author ID.
	GetAuthor(ctx context.Context, authorID string) (*AuthorInfo, error)

	// GetModelEndpoints returns provider endpoints for a specific model
	GetModelEndpoints(ctx context.Context, modelID string) (*ModelEndpointsResponse, error)

	// GetLogo returns the catalog-carried SVG brand mark for one provider
	// or author. It reports a not_found provider error when the catalog
	// carries no bytes for this kind and ID.
	GetLogo(ctx context.Context, kind view.LogoKind, id string) ([]byte, error)
}

type RerankRequest = OperationRequest[inference.RerankRequest]

type RerankResponse = OperationResponse[inference.RerankResponse]

type RoutingError struct {
	Model  string
	Reason string
	Err    error
}

type SemanticEmbedIdentity struct {
	AccountID string
	KeyID     string
	TeamID    string
	RequestID string
	Protocol  string
}

type SemanticEmbedder interface {
	Embed(ctx context.Context, identity SemanticEmbedIdentity, text string) ([]float32, error)
}

type SpeechRequest = OperationRequest[inference.SpeechRequest]

type SpeechResponse = OperationResponse[inference.SpeechResponse]

type StoredDocument struct {
	Filename string
	Data     []byte
}

type StreamUnwrapper interface {
	Unwrap() ChatCompletionStreamResponse
}

type TopProviderInfo = view.TopProviderInfo

type TranscriptionRequest = OperationRequest[inference.TranscriptionRequest]

type TranscriptionResponse = OperationResponse[inference.TranscriptionResponse]

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

type UsageObserver interface {
	ObserveUsage(record usage.Record)
}

type UsageRecorder interface {
	Put(ctx context.Context, record usage.Record) error
}

type ValidationError struct {
	Field   string
	Message string
}

type VideoAsset struct {
	ContentType  string
	Bytes        []byte
	ModelUsed    string
	ProviderUsed string
}

type VideoAssetReference = router.VideoAssetReference

type VideoAssetRequest = MediaRequest[VideoAssetReference]

type VideoJobAnswer struct {
	ProviderJobID string
	State         jobs.JobState
	Reason        string
	ModelUsed     string
	ProviderUsed  string
}

type VideoJobReference = router.VideoJobReference

type VideoJobRequest = MediaRequest[VideoJobReference]

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

type VideoSubmitRequest = MediaRequest[inference.VideoJobRequest]