providers

type AudioStreamingCapabilities struct {
	// SupportedEncodings lists supported audio encodings
	// Common values: "pcm", "opus", "mp3", "aac"
	SupportedEncodings []string `json:"supported_encodings"`

	// SupportedSampleRates lists supported sample rates in Hz
	// Common values: 8000, 16000, 24000, 44100, 48000
	SupportedSampleRates []int `json:"supported_sample_rates"`

	// SupportedChannels lists supported channel counts
	// Common values: 1 (mono), 2 (stereo)
	SupportedChannels []int `json:"supported_channels"`

	// SupportedBitDepths lists supported bit depths
	// Common values: 16, 24, 32
	SupportedBitDepths []int `json:"supported_bit_depths,omitempty"`

	// PreferredEncoding is the recommended encoding for best quality/latency
	PreferredEncoding string `json:"preferred_encoding"`

	// PreferredSampleRate is the recommended sample rate
	PreferredSampleRate int `json:"preferred_sample_rate"`
}

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

type BaseEmbeddingProvider struct {
	ProviderModel string
	BaseURL       string
	APIKey        string
	HTTPClient    *http.Client
	// Dimensions is the vector length the configured model produces: the
	// size the caller declared, else the size of a model the provider knows.
	// It is 0 when neither applies — the provider then takes the length of
	// the first vector it gets back rather than guessing one.
	Dimensions int
	ProviderID string
	BatchSize  int
	// PlatformAuth indicates the HTTPClient's transport applies
	// hyperscaler-platform auth (Azure Bearer, etc.) per request, so the
	// per-provider empty-API-key guard must be skipped.
	PlatformAuth bool
	// contains filtered or unexported fields
}

type BaseProvider struct {
	*base.Implementation
	// contains filtered or unexported fields
}

type BaseRerankProvider struct {
	*base.Implementation

	ProviderID    string
	ProviderModel string
	BaseURL       string
	APIKey        string
	HTTPClient    *http.Client
	// MaxDocs is the largest candidate list one call accepts.
	MaxDocs int
	// PlatformAuth indicates the HTTPClient's transport applies
	// hyperscaler-platform auth per request, so the empty-API-key guard in
	// each vendor's constructor must be skipped.
	PlatformAuth bool
}

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

type BedrockEventStreamFrameDetector struct{}

type ContextWindowProvider interface {
	MaxContextTokens() int
}

type Credential interface {
	// Apply adds authentication to the HTTP request.
	Apply(ctx context.Context, req *http.Request) error

	// Type returns the credential type identifier.
	Type() string
}

type DoRequestFunc func() (*http.Response, error)

type EmbedFunc func(ctx context.Context, texts []string, model string) (EmbeddingResponse, error)

type EmbeddingProvider interface {
	// Embed generates embeddings for the given texts.
	// The response contains one embedding vector per input text, in the same order.
	// Implementations should handle batching internally if the request exceeds MaxBatchSize.
	Embed(ctx context.Context, req EmbeddingRequest) (EmbeddingResponse, error)

	// EmbeddingDimensions returns the dimensionality of embedding vectors:
	// the size configured for the provider, else the known size of its model,
	// else the size observed on the first Embed call. It returns 0 when none
	// of these is available yet — embed one text first if you need the size
	// before storing vectors.
	EmbeddingDimensions() int

	// MaxBatchSize returns the maximum number of texts per single API request.
	// Callers should batch requests appropriately, or rely on the provider
	// to handle splitting internally.
	MaxBatchSize() int

	// ID returns the provider identifier (e.g., "openai-embedding", "gemini-embedding")
	ID() string
}

type EmbeddingProviderFactory func(spec EmbeddingProviderSpec) (EmbeddingProvider, error)

type EmbeddingProviderSpec struct {
	// ID is a stable identifier; informational only at this layer.
	ID string
	// Type selects the implementation: openai, gemini, voyageai, ollama.
	Type string
	// Model overrides the provider's default embedding model. Empty
	// uses the per-provider default.
	Model string
	// BaseURL overrides the provider's default API endpoint.
	BaseURL string
	// Credential carries the resolved API key. May be nil for
	// providers that don't require auth (e.g. ollama).
	Credential credentials.Credential
	// AdditionalConfig carries provider-specific extras (voyage
	// dimensions/input_type, etc.). Unknown keys are ignored.
	AdditionalConfig map[string]any
	// Platform identifies the hosting platform ("azure", "bedrock",
	// "vertex"). Empty means direct API access via Credential. Mirrors
	// ProviderSpec.Platform on the chat path.
	Platform string
	// PlatformConfig holds platform-specific settings (endpoint, region,
	// api_version). Only set when Platform != "".
	PlatformConfig *PlatformConfig
	// Tuning carries the provider file's headers, request_timeout and
	// http_transport. CreateEmbeddingProviderFromSpec applies it after
	// construction and rejects it for a provider that is not HTTPTunable.
	Tuning base.HTTPTuning
}

type EmbeddingRequest struct {
	// Texts to embed (batched for efficiency)
	Texts []string

	// Model override for embedding model (optional, uses provider default if empty)
	Model string
}

type EmbeddingResponse struct {
	// Embeddings contains one vector per input text, in the same order
	Embeddings [][]float32

	// Model is the model that was used for embedding
	Model string

	// Usage contains token consumption information (optional)
	Usage *EmbeddingUsage
}

type EmbeddingTransport struct {
	Client       *http.Client
	BaseURL      string
	APIKey       string
	PlatformAuth bool
}

type EmbeddingUsage struct {
	// TotalTokens is the total number of tokens processed
	TotalTokens int
}

type EmbeddingWiring struct {
	Model        string
	BaseURL      string
	Client       *http.Client
	PlatformAuth bool
	// Dimensions is 0 when the spec did not request one, which is what tells
	// the provider to keep its family default.
	Dimensions int
}

type ExecutionResult interface{}

type FrameDetector interface {
	// Name identifies the detector in logs and errors. Should be a
	// short lowercase token: "sse", "ndjson", "json-array", etc.
	Name() string

	// PeekFirstFrame reads from r until at least one complete frame has
	// been seen, then returns the bytes consumed so far. Returns an
	// error if r fails before a complete frame is found, or if the
	// stream ends cleanly before any frame has been observed.
	//
	// On success, the returned slice is non-empty and r is positioned
	// immediately after the last returned byte.
	PeekFirstFrame(r io.Reader) ([]byte, error)
}

type HTTPRequestConfig struct {
	URL         string
	Body        []byte
	UseAPIKey   bool   // If true, adds Authorization: Bearer <APIKey> header
	ContentType string // Defaults to application/json
	// Headers are set on the request before it is sent. Providers that
	// authenticate with a non-Bearer scheme use this — notably Gemini, whose
	// key goes in x-goog-api-key so it never enters the URL and therefore
	// never reaches a log through *url.Error.
	Headers map[string]string
}

type HTTPTransportOptions struct {
	// MaxConnsPerHost caps the total TCP connections the transport may
	// open to any single host (in-use + idle). Zero means unlimited
	// (matching Go's http.Transport default). Negative values fall
	// back to DefaultMaxConnsPerHost.
	MaxConnsPerHost int
	// MaxIdleConnsPerHost caps the number of idle keep-alive
	// connections the transport will retain per host for reuse. Zero
	// uses DefaultMaxIdleConnsPerHost. Usually tracked to
	// MaxConnsPerHost to keep the whole pool reusable.
	MaxIdleConnsPerHost int
	// IdleConnTimeout is how long an idle keep-alive connection lingers
	// before being closed. Zero uses DefaultIdleConnTimeout. Longer
	// timeouts favor reuse; shorter ones release memory and FD slots
	// faster.
	IdleConnTimeout time.Duration
}

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

type ImageDetail string

type InferenceProvider = Provider

type JSONArrayFrameDetector struct{}

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

type LateInputTranscriber interface {
	// EmitsLateInputTranscription reports whether the user transcript can arrive
	// after the assistant reply has started for the same turn.
	EmitsLateInputTranscription() bool
}

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

type MediaLoaderConfig struct {
	// StorageService is optional - required only for loading from storage references
	StorageService storage.MediaStorageService

	// HTTPTimeout for URL fetching (default: 30s)
	HTTPTimeout time.Duration

	// MaxURLSizeBytes is the maximum size for URL-based media (default: 50MB)
	MaxURLSizeBytes int64
}

type MediaStorageConfigurable interface {
	SetMediaStorageService(storage.MediaStorageService)
}

type MockRerankOption func(*MockRerankProvider)

type MockRerankProvider struct {
	*base.Implementation

	// Handler, when set, replaces the built-in scoring entirely. Use it to
	// pin an exact order, or to make the provider fail, without standing up
	// an HTTP server.
	Handler func(ctx context.Context, req RerankRequest) (RerankResponse, error)
	// contains filtered or unexported fields
}

type MultimodalCapabilities struct {
	SupportsImages    bool     // Provider can process image inputs
	SupportsAudio     bool     // Provider can process audio inputs
	SupportsVideo     bool     // Provider can process video inputs
	SupportsDocuments bool     // Provider can process document inputs (PDF, etc.)
	ImageFormats      []string // Supported image MIME types (e.g., "image/jpeg", "image/png")
	AudioFormats      []string // Supported audio MIME types (e.g., "audio/mpeg", "audio/wav")
	VideoFormats      []string // Supported video MIME types (e.g., "video/mp4")
	DocumentFormats   []string // Supported document MIME types (e.g., "application/pdf")
	MaxImageSizeMB    int      // Maximum image size in megabytes (0 = unlimited/unknown)
	MaxAudioSizeMB    int      // Maximum audio size in megabytes (0 = unlimited/unknown)
	MaxVideoSizeMB    int      // Maximum video size in megabytes (0 = unlimited/unknown)
	MaxDocumentSizeMB int      // Maximum document size in megabytes (0 = unlimited/unknown)
}

type MultimodalCapabilityProvider interface {
	GetMultimodalCapabilities() MultimodalCapabilities
}

type NDJSONFrameDetector struct{}

type PlatformConfig = credentials.PlatformConfig

type PlatformEmbeddingSpec struct {
	// PlatformHint completes the "requires a platform block (…)" error, naming
	// the fields that platform actually needs.
	PlatformHint string
	// Build constructs the provider once the transport has been resolved.
	Build func(EmbeddingProviderSpec, EmbeddingTransport) (EmbeddingProvider, error)
}

type PredictionRequest struct {
	System         string          `json:"system"`
	Messages       []types.Message `json:"messages"`
	Temperature    float32         `json:"temperature"`
	TopP           float32         `json:"top_p"`
	MaxTokens      int             `json:"max_tokens"`
	Seed           *int            `json:"seed,omitempty"`
	ResponseFormat *ResponseFormat `json:"response_format,omitempty"` // Optional response format (JSON mode)
	Metadata       map[string]any  `json:"metadata,omitempty"`        // Provider-specific context
}

type PredictionResponse struct {
	Content    string                  `json:"content"`
	Parts      []types.ContentPart     `json:"parts,omitempty"`     // Multimodal content parts (text, image, audio, video)
	CostInfo   *types.CostInfo         `json:"cost_info,omitempty"` // Cost breakdown for this response (includes token counts)
	Latency    time.Duration           `json:"latency"`
	Raw        []byte                  `json:"raw,omitempty"`
	RawRequest any                     `json:"raw_request,omitempty"` // Raw API request (for debugging)
	ToolCalls  []types.MessageToolCall `json:"tool_calls,omitempty"`  // Tools called in this response
	// Reasoning holds the model's reasoning/"thinking" for this response, carried
	// onto Message.Reasoning (off Parts) so it is excluded from content/exports/
	// future context by construction. Nil when the model reported none.
	Reasoning *types.ReasoningTrace `json:"reasoning,omitempty"`
	// FinishReason is the canonical (normalized) reason the model stopped,
	// or "" if the provider did not report one. See runtime/types FinishReason* constants.
	FinishReason string `json:"finish_reason,omitempty"`
}

type Pricing struct {
	InputCostPer1K  float64
	OutputCostPer1K float64
}

type Provider interface {
	base.Provider // adds Name, Type, Pricing, Validate, Init, HealthCheck, Close

	// ID returns the provider ID. Deprecated alias for Name(); kept for back-compat.
	ID() string

	// Model returns the model name/identifier used by this provider.
	Model() string

	Predict(ctx context.Context, req PredictionRequest) (PredictionResponse, error)

	// Streaming support
	PredictStream(ctx context.Context, req PredictionRequest) (<-chan StreamChunk, error)

	SupportsStreaming() bool

	ShouldIncludeRawOutput() bool

	// CalculateCost calculates cost breakdown for given token counts.
	CalculateCost(inputTokens, outputTokens, cachedTokens int) types.CostInfo
}

type ProviderContractTests struct {
	// Provider instance to test
	Provider Provider

	// SupportsToolsExpected indicates whether this provider should support tools
	SupportsToolsExpected bool

	// SupportsStreamingExpected indicates whether this provider should support streaming
	SupportsStreamingExpected bool
}

type ProviderDefaults struct {
	Temperature float32
	TopP        float32
	MaxTokens   int
	Pricing     Pricing
	// DisablePromptCaching, when true, disables Anthropic prompt caching.
	// Default (false) means caching is on for all models that support it.
	DisablePromptCaching bool
}

type ProviderFactory func(spec ProviderSpec) (Provider, error)

type ProviderHTTPError struct {
	StatusCode int
	URL        string
	Body       string
	Provider   string
	// RetryAfter is the delay the response's Retry-After header asked for,
	// or zero when it sent none.
	RetryAfter time.Duration
}

type ProviderSpec struct {
	ID      string
	Type    string
	Model   string
	BaseURL string
	// Headers contains custom HTTP headers to include in every request.
	// Applied after built-in provider headers; collisions cause an error.
	Headers          map[string]string
	Defaults         ProviderDefaults
	IncludeRawOutput bool
	AdditionalConfig map[string]interface{} // Flexible key-value pairs for provider-specific configuration

	// Credential holds the resolved credential for this provider.
	// If nil, providers fall back to environment variable lookup.
	Credential Credential

	// Platform identifies the hosting platform (e.g., "bedrock", "vertex", "azure").
	// Empty string means direct API access to the provider.
	Platform string

	// PlatformConfig holds platform-specific configuration.
	// Only set when Platform is non-empty.
	PlatformConfig *PlatformConfig

	// UnsupportedParams lists model parameters not supported by this provider model.
	// For example, o-series OpenAI models don't support "temperature", "top_p", or "max_tokens".
	UnsupportedParams []string

	// Capabilities lists the modalities/features the configured model supports
	// (e.g. "text", "vision", "audio", "video", "tools", "json"). When set, it
	// is the source of truth for multimodal support, replacing per-model
	// hardcoding inside providers. Empty means "not declared" — providers fall
	// back to their built-in defaults.
	Capabilities []string

	// RequestTimeout caps the wall-clock duration of request/response HTTP
	// calls (Predict, embeddings). Zero falls back to
	// httputil.DefaultProviderTimeout. Does not apply to SSE streaming
	// calls, which are unbounded by wall-clock and governed by
	// StreamIdleTimeout + context cancellation. Pre-parsed from
	// config.Provider.RequestTimeout by the arena loader.
	RequestTimeout time.Duration

	// StreamIdleTimeout bounds how long an SSE streaming body may remain
	// silent before it is aborted; timer resets on every byte. Zero falls
	// back to DefaultStreamIdleTimeout. Pre-parsed from
	// config.Provider.StreamIdleTimeout by the arena loader.
	StreamIdleTimeout time.Duration

	// StreamRetry configures bounded retry for streaming requests that
	// fail in the pre-first-chunk window. Zero value (disabled) leaves
	// the provider with no streaming retry. Pre-parsed from
	// config.Provider.StreamRetry by the arena loader.
	StreamRetry StreamRetryPolicy

	// StreamRetryBudget is a pre-constructed token bucket that
	// rate-limits retry attempts across all in-flight requests on this
	// provider. Nil means "unbounded retries" (only MaxAttempts caps
	// them). Pre-parsed from config.Provider.StreamRetry.Budget by the
	// arena loader. Each provider instance gets its own budget so one
	// misbehaving model cannot starve retry capacity for others.
	StreamRetryBudget *RetryBudget

	// StreamMaxConcurrent caps the number of concurrent streaming
	// requests the provider will have in flight. Zero means unlimited
	// (backwards-compatible default). Pre-parsed from
	// config.Provider.StreamMaxConcurrent by the arena loader. Applied
	// via SetStreamSemaphore on providers that implement the
	// streamConcurrencyConfigurable interface.
	StreamMaxConcurrent int

	// StorageService resolves MediaContent.StorageReference values at
	// request-build time (to a model-fetchable URL via GetURL, or bytes via
	// RetrieveMedia). Applied via SetMediaStorageService on providers
	// implementing MediaStorageConfigurable. Nil = disabled.
	StorageService storage.MediaStorageService

	// HTTPTransport configures the per-provider HTTP connection pool.
	// Zero-valued fields fall back to package-level defaults
	// (DefaultMaxConnsPerHost, etc.). Applied via SetHTTPTransport on
	// providers that implement the httpTransportConfigurable interface,
	// replacing the default pooled transport the factory constructed.
	//
	// See AltairaLabs/PromptKit#873 for motivation: at higher concurrency
	// than the repo was originally sized for, the hardcoded
	// MaxConnsPerHost: 100 becomes the wall before PromptKit's own
	// machinery does. Raising this (paired with operator awareness of
	// the upstream's SETTINGS_MAX_CONCURRENT_STREAMS) is the primary
	// lever on realistic single-process concurrent-stream capacity.
	HTTPTransport HTTPTransportOptions
}

type ProviderTools = any

type ProviderTransportError struct {
	Cause    error
	Provider string
}

type RankedDocument struct {
	// Index is the document's position in the request's Documents slice.
	// This is the field callers key on: the results are reordered, so
	// position in the response says nothing about which document it was.
	Index int

	// Score is the provider's relevance score. Higher is more relevant.
	// The range is provider-specific and NOT comparable across providers
	// or models — use it to order and to threshold within one provider,
	// never to compare two providers' verdicts.
	Score float64

	// Document echoes the input text when the provider returns it. It may
	// be empty even for a valid result; Index is the reliable identifier.
	Document string
}

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

type RequestHeaders map[string]string

type RerankProvider interface {
	// Provider supplies lifecycle and health: Name, Type, Pricing,
	// Validate, Init, HealthCheck, Close.
	base.Provider

	// Rerank orders req.Documents by relevance to req.Query. It honors
	// context cancellation and deadlines.
	//
	// An empty Documents slice returns an empty result and no error: having
	// nothing to rank is a normal outcome of an upstream search, not a
	// failure worth propagating.
	Rerank(ctx context.Context, req RerankRequest) (RerankResponse, error)

	// MaxDocuments reports the most candidates one call accepts. Callers
	// that may exceed it should batch; implementations are free to batch
	// internally instead, and say so in their own docs.
	MaxDocuments() int

	// ID returns the configured provider identifier, e.g. "voyageai-rerank".
	// This is the instance's ID from config, not the vendor name — several
	// instances of one vendor can coexist.
	ID() string
}

type RerankProviderFactory func(spec RerankProviderSpec) (RerankProvider, error)

type RerankProviderSpec struct {
	// ID is a stable identifier for this instance.
	ID string
	// Type selects the implementation: voyageai, cohere, mock.
	Type string
	// Model overrides the provider's default rerank model.
	Model string
	// BaseURL overrides the provider's default API endpoint.
	BaseURL string
	// Credential carries the resolved API key. May be nil for
	// providers that need no auth (e.g. the in-process mock).
	Credential credentials.Credential
	// AdditionalConfig carries provider-specific extras. Unknown keys are
	// ignored, so a config written for one vendor does not fail on another.
	AdditionalConfig map[string]any
	// Platform identifies a hosting platform ("azure", "bedrock",
	// "vertex"). Empty means direct API access via Credential.
	Platform string
	// PlatformConfig holds platform-specific settings. Only set when
	// Platform != "".
	PlatformConfig *PlatformConfig
	// Tuning carries the provider file's headers, request_timeout and
	// http_transport. CreateRerankProviderFromSpec applies it after
	// construction and rejects it for a provider that is not HTTPTunable.
	Tuning base.HTTPTuning
}

type RerankRequest struct {
	// Query is the text documents are ranked against. Required.
	Query string

	// Documents are the candidates to order. The response refers back to
	// them by position, so the caller keeps ownership of whatever richer
	// objects these strings were rendered from.
	Documents []string

	// TopN caps how many results come back. Zero means "all of them",
	// still ordered. A provider may return fewer than TopN but never more.
	TopN int

	// Model overrides the provider's default. Empty uses the default.
	Model string
}

type RerankResponse struct {
	// Results are ordered best-first and contain at most TopN entries.
	// Documents the provider dropped are simply absent.
	Results []RankedDocument

	// Model is the model that actually ran, which may differ from the
	// requested one when the provider substitutes.
	Model string

	// Usage reports token consumption when the provider supplies it.
	Usage *RerankUsage
}

type RerankTransport struct {
	BaseURL string
	APIKey  string
}

type RerankUsage struct {
	// TotalTokens counts query and documents together. Rerankers bill on
	// the combined input; there is no output to bill for.
	TotalTokens int
}

type ResponseFormat struct {
	// Type specifies the response format type
	Type ResponseFormatType `json:"type"`
	// JSONSchema is the schema to use when Type is ResponseFormatJSONSchema
	// This should be a valid JSON Schema object
	JSONSchema json.RawMessage `json:"json_schema,omitempty"`
	// SchemaName is an optional name for the schema (used by OpenAI)
	SchemaName string `json:"schema_name,omitempty"`
	// Strict enables strict schema validation (OpenAI-specific)
	Strict bool `json:"strict,omitempty"`
}

type ResponseFormatType string

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

type RetryableHTTPError struct {
	StatusCode int
	Status     string
}

type SSEFrameDetector struct{}

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

type StreamChunk struct {
	// Content is the accumulated content so far
	Content string `json:"content"`

	// Delta is the new content in this chunk
	Delta string `json:"delta"`

	// Reasoning carries reasoning/thinking tokens emitted by reasoning models
	// (e.g. OpenAI o-series) before any visible content. Reasoning chunks act
	// as keepalives that reset the idle timer; they carry no visible Delta and
	// must not be appended to the content stream.
	Reasoning string `json:"reasoning,omitempty"`

	// OpaqueReasoning carries provider round-trip reasoning tokens (signatures /
	// encrypted blocks) for this chunk. Never displayed, never content; preserved
	// so a provider can feed it back where required (intra-turn).
	OpaqueReasoning []types.OpaqueReasoning `json:"opaque_reasoning,omitempty"`

	// MediaData contains raw streaming media bytes (audio, video, images).
	// Data is always raw bytes, never base64. Providers decode at source.
	MediaData *StreamMediaData `json:"-"`

	// TokenCount is the total number of tokens so far
	TokenCount int `json:"token_count"`

	// DeltaTokens is the number of tokens in this delta
	DeltaTokens int `json:"delta_tokens"`

	// ToolCalls contains accumulated tool calls (for assistant messages that invoke tools)
	ToolCalls []types.MessageToolCall `json:"tool_calls,omitempty"`

	// FinishReason is nil until stream is complete
	// Values: "stop", "length", "content_filter", "tool_calls", "error", "validation_failed", "cancelled"
	FinishReason *string `json:"finish_reason,omitempty"`

	// Interrupted indicates the response was interrupted (e.g., user started speaking)
	// When true, clients should clear any buffered audio and prepare for a new response
	Interrupted bool `json:"interrupted,omitempty"`

	// Reset signals that the stream is being retried from scratch after a
	// mid-stream failure. Consumers must discard all accumulated state
	// (content, tool calls, cost info) and treat subsequent chunks as a
	// fresh response. Only emitted when the provider's retry_window is
	// set to "always" and a mid-stream error triggered a full retry.
	// The retry costs tokens because the provider generates a new
	// response from scratch — this is why the default is off.
	Reset bool `json:"reset,omitempty"`

	// Error is set if an error occurred during streaming
	Error error `json:"error,omitempty"`

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

	// FinalResult contains the complete execution result (only set in the final chunk)
	FinalResult ExecutionResult `json:"final_result,omitempty"`

	// CostInfo contains cost breakdown (only present in final chunk when FinishReason != nil)
	CostInfo *types.CostInfo `json:"cost_info,omitempty"`

	// PendingTools contains client-mode tools awaiting caller fulfillment.
	// Only set when FinishReason is "pending_tools".
	PendingTools []tools.PendingToolExecution `json:"pending_tools,omitempty"`

	// Source labels the input track/speaker for fan-out routing (e.g. "caller",
	// "agent"). Copied onto StreamElement.Source at the session boundary.
	Source string `json:"source,omitempty"`
	// contains filtered or unexported fields
}

type StreamConsumer func(ctx context.Context, body io.ReadCloser, outChan chan<- StreamChunk)

type StreamEvent struct {
	// Type is the event type: "chunk", "complete", "error"
	Type string `json:"type"`

	// Chunk contains the stream chunk data
	Chunk *StreamChunk `json:"chunk,omitempty"`

	// Error is set for error events
	Error error `json:"error,omitempty"`

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

type StreamInputSession interface {
	// SendChunk sends a media chunk to the provider.
	// Returns an error if the chunk cannot be sent or the session is closed.
	// This method is safe to call from multiple goroutines.
	SendChunk(ctx context.Context, chunk *types.MediaChunk) error

	// SendText sends a text message to the provider during the streaming session.
	// This is useful for sending text prompts or instructions during audio streaming.
	// Note: This marks the turn as complete, triggering a response.
	SendText(ctx context.Context, text string) error

	// SendSystemContext sends a text message as context without completing the turn.
	// Use this for system prompts that provide context but shouldn't trigger an immediate response.
	// The audio/text that follows will be processed with this context in mind.
	SendSystemContext(ctx context.Context, text string) error

	// Response returns a receive-only channel for streaming responses.
	// The channel is closed when the session ends or encounters an error.
	// Consumers should read from this channel in a separate goroutine.
	Response() <-chan StreamChunk

	// Close ends the streaming session and releases resources.
	// After calling Close, SendChunk and SendText will return errors.
	// The Response channel will be closed.
	// Close is safe to call multiple times.
	Close() error

	// Error returns any error that occurred during the session.
	// Returns nil if no error has occurred.
	Error() error

	// Done returns a channel that's closed when the session ends.
	// This is useful for select statements to detect session completion.
	Done() <-chan struct{}

	// BargeIn returns a channel that fires OUT-OF-BAND when the provider detects
	// the user interrupting the agent mid-response (server-side barge-in),
	// independent of the Response() FIFO.
	//
	// Why a separate channel: Response() carries the (possibly large) buffered
	// audio of the in-flight response, and a consumer paced to real-time playback
	// drains it slowly. An interruption sent in-band would queue behind that
	// backlog and not be seen until playback caught up — defeating barge-in. This
	// channel lets the consumer learn immediately and flush pending audio.
	//
	// It is buffered and best-effort: rapid repeats may coalesce (the consumer
	// only needs to know the user interrupted, not how many times), and the
	// producer never closes it while the session is live, so consumers should
	// also select on Done(). Providers that cannot detect barge-in return a nil
	// channel (never fires); embed BargeInSignal to satisfy this for free.
	BargeIn() <-chan struct{}
}

type StreamInputSupport interface {
	Provider // Extends the base Provider interface

	// CreateStreamSession creates a new bidirectional streaming session.
	// The session remains active until Close() is called or an error occurs.
	// Returns an error if the provider doesn't support the requested media type.
	CreateStreamSession(ctx context.Context, req *StreamingInputConfig) (StreamInputSession, error)

	// SupportsStreamInput returns the media types supported for streaming input.
	// Common values: types.ContentTypeAudio, types.ContentTypeVideo
	SupportsStreamInput() []string

	// GetStreamingCapabilities returns detailed information about streaming support.
	// This includes supported codecs, sample rates, and other constraints.
	GetStreamingCapabilities() StreamingCapabilities
}

type StreamMediaData struct {
	// Common fields
	Data     []byte // Raw media bytes (PCM audio, JPEG frame, H.264 chunk, etc.)
	MIMEType string // e.g., "audio/pcm", "image/jpeg", "video/h264"

	// Audio metadata
	SampleRate int // Sample rate in Hz (e.g., 16000, 24000). 0 if not audio.
	Channels   int // Channel count (1=mono, 2=stereo). 0 if not audio.

	// Visual metadata (image and video)
	Width  int // Pixels. 0 if unknown or not visual.
	Height int // Pixels. 0 if unknown or not visual.

	// Video/image streaming metadata
	FrameRate  float64 // FPS. 0 if not video.
	IsKeyFrame bool    // True if this is a key frame (video only).
	FrameNum   int64   // Sequence number for ordering frames/chunks.
}

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

type StreamObserver interface {
	OnChunk(chunk StreamChunk)
	OnComplete(totalTokens int, duration time.Duration)
	OnError(err error)
}

type StreamPump struct {
	// BargeInSignal provides the StreamInputSession.BargeIn() channel, fired by
	// Barge(). Embedded so it (and BargeIn()) are promoted to the session.
	BargeInSignal
	// contains filtered or unexported fields
}

type StreamRetryPolicy struct {
	// Enabled turns the retry loop on. Zero value is off.
	Enabled bool
	// MaxAttempts is total attempts including the initial request. Values
	// <1 are normalized to 1 (no retry). Zero falls back to the default.
	MaxAttempts int
	// InitialDelay is the base backoff before the first retry. Zero falls
	// back to the default.
	InitialDelay time.Duration
	// MaxDelay caps per-attempt backoff. Zero falls back to the default.
	MaxDelay time.Duration
	// Window controls which point in the stream lifecycle is eligible for
	// retry. Empty falls back to StreamRetryWindowPreFirstChunk.
	Window StreamRetryWindow
	// MaxRetryAfter is the longest a server's Retry-After may make a retry
	// wait. A failure asking for longer is not retried at all: retrying
	// sooner than the server allows only spends an attempt against a limit
	// still in force. Zero falls back to DefaultStreamRetryMaxRetryAfter.
	MaxRetryAfter time.Duration
}

type StreamRetryRequest struct {
	Policy       StreamRetryPolicy
	Budget       *RetryBudget // nil means unbounded retries
	ProviderName string
	Host         string // metric label; may be empty
	IdleTimeout  time.Duration
	RequestFn    func(ctx context.Context) (*http.Request, error)
	Client       *http.Client
	// FrameDetector identifies the first complete protocol frame on
	// the response body so the retry driver knows when the stream is
	// "established" and retry must not fire. Nil defaults to
	// SSEFrameDetector — set to NDJSONFrameDetector for Ollama,
	// JSONArrayFrameDetector for Gemini, or any custom FrameDetector
	// implementation for new protocols.
	FrameDetector FrameDetector
}

type StreamRetryResult struct {
	// Response is the HTTP response of the successful attempt. Body has
	// already been wrapped; callers must not read directly from
	// Response.Body. Use Body instead.
	Response *http.Response
	// Body is a composite reader that first replays the SSE event bytes
	// consumed by the peek, then streams the remainder of the response.
	// Closing this closes the underlying Response.Body.
	Body io.ReadCloser
	// Attempts is the total number of attempts made (1 on first-try success).
	Attempts int
}

type StreamRetryWindow string

type StreamScanner interface {
	Scan() bool
	Data() string
	Err() error
}

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

type StreamingCapabilities struct {
	// SupportedMediaTypes lists the media types that can be streamed
	// Values: types.ContentTypeAudio, types.ContentTypeVideo
	SupportedMediaTypes []string `json:"supported_media_types"`

	// Audio capabilities
	Audio *AudioStreamingCapabilities `json:"audio,omitempty"`

	// Video capabilities
	Video *VideoStreamingCapabilities `json:"video,omitempty"`

	// BidirectionalSupport indicates if the provider supports full bidirectional streaming
	BidirectionalSupport bool `json:"bidirectional_support"`

	// MaxSessionDuration is the maximum duration for a streaming session (in seconds)
	// Zero means no limit
	MaxSessionDuration int `json:"max_session_duration,omitempty"`

	// MinChunkSize is the minimum chunk size in bytes
	MinChunkSize int `json:"min_chunk_size,omitempty"`

	// MaxChunkSize is the maximum chunk size in bytes
	MaxChunkSize int `json:"max_chunk_size,omitempty"`
}

type StreamingInputConfig struct {
	// Config specifies the media streaming configuration (codec, sample rate, etc.)
	Config types.StreamingMediaConfig `json:"config"`

	// SystemInstruction is the system prompt to configure the model's behavior.
	// For Gemini Live API, this is included in the setup message.
	SystemInstruction string `json:"system_instruction,omitempty"`

	// Tools defines functions the model can call during the session.
	// When configured, the model returns structured tool calls instead of
	// speaking them as text. Supported by Gemini Live API.
	Tools []StreamingToolDefinition `json:"tools,omitempty"`

	// Metadata contains provider-specific session configuration
	// Example: {"response_modalities": ["TEXT", "AUDIO"]} for Gemini
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type StreamingToolDefinition struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description,omitempty"`
	Parameters  map[string]interface{} `json:"parameters,omitempty"` // JSON Schema
}

type ToolDescriptor struct {
	Name         string          `json:"name"`
	Description  string          `json:"description"`
	InputSchema  json.RawMessage `json:"input_schema"`
	OutputSchema json.RawMessage `json:"output_schema"`
}

type ToolResponse struct {
	ToolCallID string `json:"tool_call_id"`
	Result     string `json:"result"`
	IsError    bool   `json:"is_error,omitempty"` // True if the tool execution failed
}

type ToolResponseSupport interface {
	// SendToolResponse sends the result of a tool execution back to the model.
	// The toolCallID must match the ID from the MessageToolCall.
	// The result is typically JSON-encoded but the format depends on the tool.
	// After receiving the tool response, the model will continue generating.
	SendToolResponse(ctx context.Context, toolCallID string, result string) error

	// SendToolResponses sends multiple tool results at once (for parallel tool calls).
	// This is more efficient than sending individual responses for providers that
	// support batched tool responses.
	SendToolResponses(ctx context.Context, responses []ToolResponse) error
}

type ToolResult = types.MessageToolResult

type ToolSupport interface {
	Provider // Extends the base Provider interface

	// BuildTooling converts tool descriptors to provider-native format.
	// Returns a provider-specific type that should be passed to PredictWithTools.
	BuildTooling(descriptors []*ToolDescriptor) (ProviderTools, error)

	// PredictWithTools performs a predict request with tool support.
	// The tools parameter should be the value returned by BuildTooling.
	PredictWithTools(
		ctx context.Context,
		req PredictionRequest,
		tools ProviderTools,
		toolChoice string,
	) (PredictionResponse, []types.MessageToolCall, error)

	// PredictStreamWithTools performs a streaming predict request with tool support.
	// The tools parameter should be the value returned by BuildTooling.
	PredictStreamWithTools(
		ctx context.Context,
		req PredictionRequest,
		tools ProviderTools,
		toolChoice string,
	) (<-chan StreamChunk, error)
}

type UnsupportedContentError struct {
	Provider    string // Provider ID
	ContentType string // "image", "audio", "video", or "multimodal"
	Message     string // Human-readable error message
	PartIndex   int    // Index of the unsupported content part (if applicable)
	MIMEType    string // Specific MIME type that's unsupported (if applicable)
}

type UnsupportedProviderError struct {
	ProviderType string
}

type UnsupportedProviderPlatformError struct {
	ProviderType string
	Platform     string
}

type ValidationAbortError struct {
	Reason string
	Chunk  StreamChunk
}

type VideoResolution struct {
	Width  int `json:"width"`
	Height int `json:"height"`
}

type VideoStreamingCapabilities struct {
	// SupportedEncodings lists supported video encodings
	// Common values: "h264", "vp8", "vp9", "av1"
	SupportedEncodings []string `json:"supported_encodings"`

	// SupportedResolutions lists supported resolutions (width x height)
	SupportedResolutions []VideoResolution `json:"supported_resolutions"`

	// SupportedFrameRates lists supported frame rates
	// Common values: 15, 24, 30, 60
	SupportedFrameRates []int `json:"supported_frame_rates"`

	// PreferredEncoding is the recommended encoding
	PreferredEncoding string `json:"preferred_encoding"`

	// PreferredResolution is the recommended resolution
	PreferredResolution VideoResolution `json:"preferred_resolution"`

	// PreferredFrameRate is the recommended frame rate
	PreferredFrameRate int `json:"preferred_frame_rate"`
}