api

type API string

type AnthropicMessagesCompat struct {
	ThinkingMode               *AnthropicThinkingMode  `json:"thinking_mode,omitempty"`
	ThinkingOffType            *string                 `json:"thinking_off_type,omitempty"`
	SupportsEffort             *bool                   `json:"supports_effort,omitempty"`
	ThinkingBudgets            map[ReasoningEffort]int `json:"thinking_budgets,omitempty"`
	DefaultMaxTokens           *int                    `json:"default_max_tokens,omitempty"`
	SupportsTemperature        *bool                   `json:"supports_temperature,omitempty"`
	TemperatureWithThinking    *bool                   `json:"temperature_with_thinking,omitempty"`
	SupportsTopP               *bool                   `json:"supports_top_p,omitempty"`
	SupportsCacheControl       *bool                   `json:"supports_cache_control,omitempty"`
	SupportsCacheControlOnTool *bool                   `json:"supports_cache_control_on_tools,omitempty"`
	LongCacheTTL               *string                 `json:"long_cache_ttl,omitempty"`
	Version                    *string                 `json:"version,omitempty"`
	BetaHeaders                []string                `json:"beta_headers,omitempty"`
	InterleavedThinkingBeta    *string                 `json:"interleaved_thinking_beta,omitempty"`
	PromptCacheAccounting      *bool                   `json:"prompt_cache_accounting,omitempty"`
	ExtraBody                  map[string]any          `json:"extra_body,omitempty"`
}

type AnthropicMessagesSettings struct {
	ThinkingMode AnthropicThinkingMode
	// ThinkingOffType is the thinking.type sent to turn thinking off in
	// adaptive mode; empty means "disabled". Claude Sonnet 5.5 rejects
	// "disabled" and turns off up-front thinking with "between_tools".
	ThinkingOffType string `json:",omitempty"`
	SupportsEffort  bool
	// ThinkingBudgets maps graded levels to budget_tokens for budget mode.
	ThinkingBudgets map[ReasoningEffort]int
	// DefaultMaxTokens is used when the caller set no budget (max_tokens is
	// mandatory on this protocol).
	DefaultMaxTokens           int
	SupportsTemperature        bool
	TemperatureWithThinking    bool
	SupportsTopP               bool
	SupportsCacheControl       bool
	SupportsCacheControlOnTool bool
	LongCacheTTL               string
	Version                    string
	BetaHeaders                []string
	// InterleavedThinkingBeta is added to anthropic-beta when thinking and
	// tools are both active (budget mode only). Empty disables it.
	InterleavedThinkingBeta string
	PromptCacheAccounting   bool
	ExtraBody               map[string]any
}

type AnthropicThinkingMode string

type AuthFunc func(req *http.Request, body []byte)

type Batch struct {
	Start int
	Items []string
}

type BatchLimits struct {
	// MaxItems caps how many documents one request may carry.
	MaxItems int
	// MaxItemRunes caps a single document. Vendors state these in characters
	// or tokens; runes are the closest thing we can count without a
	// tokenizer, and undercounting is the safe direction.
	MaxItemRunes int
	// MaxTotalRunes caps the whole request, query included.
	MaxTotalRunes int
}

type CacheControlMarker struct {
	Type string `json:"type"`
	TTL  string `json:"ttl,omitempty"`
}

type CacheRetention string

type Credentials struct {
	APIKey    string
	AppID     string
	AppSecret string
}

type Delta struct {
	Reasoning    string
	Content      string
	ToolCalls    []ToolCallDelta
	FinishReason string
}

type EmbedImage struct {
	Data     []byte
	MIMEType string
}

type EmbedInputType string

type Embedder interface {
	Embed(ctx context.Context, texts []string, kind EmbedInputType) ([][]float32, error)
}

type EmbeddingAPI string

type EmbeddingImageFormat string

type EmbeddingsCompat struct {
	// API overrides the vendor's embedding protocol for one model. Aliyun and
	// Volcengine each serve two: a text endpoint in the OpenAI shape and a
	// multimodal one of their own, chosen by which model the row names.
	API                *EmbeddingAPI     `json:"api,omitempty"`
	Path               *string           `json:"path,omitempty"`
	SendEncodingFormat *bool             `json:"send_encoding_format,omitempty"`
	DimensionsField    *string           `json:"dimensions_field,omitempty"`
	TruncateField      *string           `json:"truncate_field,omitempty"`
	TruncateValue      *string           `json:"truncate_value,omitempty"`
	InputTypeField     *string           `json:"input_type_field,omitempty"`
	InputTypeValues    map[string]string `json:"input_type_values,omitempty"`
	MaxBatchSize       *int              `json:"max_batch_size,omitempty"`
	MaxInputChars      *int              `json:"max_input_chars,omitempty"`
	// AcceptsTruncatePromptTokens marks a vLLM-class runtime, the only kind
	// that implements the `truncate_prompt_tokens` extension.
	AcceptsTruncatePromptTokens *bool                 `json:"accepts_truncate_prompt_tokens,omitempty"`
	RequestTimeout              *int                  `json:"request_timeout_seconds,omitempty"`
	ExtraBody                   map[string]any        `json:"extra_body,omitempty"`
	ImageField                  *string               `json:"image_field,omitempty"`
	MaxImageBatchSize           *int                  `json:"max_image_batch_size,omitempty"`
	MaxImageBytes               *int                  `json:"max_image_bytes,omitempty"`
	ImageMIMETypes              []string              `json:"image_mime_types,omitempty"`
	ImageFormat                 *EmbeddingImageFormat `json:"image_format,omitempty"`
	ImagePrompt                 *string               `json:"image_prompt,omitempty"`
	TextAsMessages              *bool                 `json:"text_as_messages,omitempty"`
	BatchMessages               *bool                 `json:"batch_messages,omitempty"`
}

type EmbeddingsSettings struct {
	// API is the protocol this model speaks, which may differ from the
	// vendor's default.
	API EmbeddingAPI
	// Path is appended to the base URL; vendors whose default base URL names
	// the full endpoint leave it empty.
	Path string
	// SendEncodingFormat sends encoding_format: "float". OpenAI documents it;
	// several compatible gateways do not list it at all.
	SendEncodingFormat bool
	// DimensionsField carries the requested vector width: "dimensions" on the
	// OpenAI shape, "dimension" on DashScope (nested under parameters),
	// "outputDimensionality" on Gemini, and empty where the vendor does not
	// let a request choose. It is sent only when the row opted in with
	// supports_dimension_override; the field name is the vendor's fact, the
	// decision to narrow the vector is the operator's.
	DimensionsField string
	// TruncateField and TruncateValue are the vendor's server-side truncation
	// switch for over-long input: a boolean on Jina, an enum on NIM. Empty
	// sends nothing.
	TruncateField string
	TruncateValue string
	// InputTypeField names the parameter that distinguishes an indexed
	// document from a search query, and InputTypeValues maps the neutral
	// EmbedInputType values onto the vendor's vocabulary. Asymmetric
	// models score the two sides differently and are measurably worse when
	// both are embedded the same way.
	InputTypeField  string
	InputTypeValues map[string]string
	// MaxBatchSize and MaxInputChars are the documented per-request ceilings.
	MaxBatchSize  int
	MaxInputChars int
	// AcceptsTruncatePromptTokens reports a vLLM-class runtime. The extension
	// appears in no managed vendor's schema, so it must never be sent to one.
	AcceptsTruncatePromptTokens bool
	// TruncatePromptTokens is the budget the operator opted into on this row,
	// honoured only where the vendor accepts the extension.
	TruncatePromptTokens int
	// RequestTimeout caps one request, in seconds. 0 leaves the client
	// without its own deadline and lets the caller's context govern.
	RequestTimeout int
	ExtraBody      map[string]any
	// ImageInput is how this endpoint takes images: on the OpenAI shape, the
	// key of the input object that carries one ("image" on Jina; that shape
	// has no standard image input, so an endpoint that names none takes no
	// images), plus the documented per-request and per-image limits.
	ImageInput
	// ImageFormat chooses between ImageField's object in `input` and a chat
	// conversation in `messages`. Empty means object when ImageField is set.
	ImageFormat EmbeddingImageFormat `json:",omitempty"`
	// ImagePrompt is the text sent beside each image in the messages format;
	// some chat templates (VLM2Vec's) expect an instruction there. Empty
	// sends the image alone.
	ImagePrompt string `json:",omitempty"`
	// TextAsMessages sends texts in the messages format too. A model whose
	// chat template frames its inputs only places text and images in the same
	// space when both pass through it; a plain `input` skips the template.
	TextAsMessages bool `json:",omitempty"`
	// BatchMessages enables independent conversations in a two-dimensional
	// messages array (vLLM 0.29 supports this). False preserves the one-input
	// request shape for older servers. Single inputs always keep that shape.
	BatchMessages bool `json:",omitempty"`
}

type Endpoint struct {
	// BaseURL is the vendor root without a trailing slash.
	BaseURL string
	// URL, when set, is the complete request URL and overrides the protocol
	// default of BaseURL + protocol path. Vendors with non-standard paths
	// (Azure deployments, WeKnora Cloud) set it.
	URL string
	// Query is appended to the final URL (Azure api-version).
	Query map[string]string
	// Model is the name sent on the wire; ModelID is WeKnora's own identifier.
	Model   string
	ModelID string
	// Auth stamps credentials; Headers are static extra headers (vendor
	// betas, user-configured custom headers). User headers never override
	// the protocol's own reserved headers.
	Auth    AuthFunc
	Headers map[string]string
	// Client is the HTTP client; nil uses the shared SSRF-safe client.
	Client *http.Client
}

type FormField struct {
	Name  string
	Value string
}

type FormFile struct {
	Field    string
	FileName string
	Data     []byte
}

type FunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"` // JSON string
}

type FunctionDef struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
}

type GoogleGenerativeAICompat struct {
	ThinkingMode     *GoogleThinkingMode     `json:"thinking_mode,omitempty"`
	ThinkingBudgets  map[ReasoningEffort]int `json:"thinking_budgets,omitempty"`
	IncludeThoughts  *bool                   `json:"include_thoughts,omitempty"`
	SupportsSeed     *bool                   `json:"supports_seed,omitempty"`
	SupportsPenalty  *bool                   `json:"supports_penalty,omitempty"`
	ExtraGeneration  map[string]any          `json:"extra_generation_config,omitempty"`
	PromptCacheAcct  *bool                   `json:"prompt_cache_accounting,omitempty"`
	APIVersionPrefix *string                 `json:"api_version_prefix,omitempty"`
}

type GoogleGenerativeAISettings struct {
	ThinkingMode    GoogleThinkingMode
	ThinkingBudgets map[ReasoningEffort]int
	IncludeThoughts bool
	SupportsSeed    bool
	SupportsPenalty bool
	ExtraGeneration map[string]any
	PromptCacheAcct bool
	// APIVersionPrefix is appended to a bare host base URL ("/v1beta").
	APIVersionPrefix string
}

type GoogleThinkingMode string

type HTTPError struct {
	StatusCode int
	Body       string
	// Header is the reply's headers, kept so a retry can honour the vendor's
	// Retry-After on a 429 or 503 instead of guessing its own backoff.
	Header http.Header
}

type ImageEmbedder interface {
	// AcceptsImages reports whether this endpoint can carry an image at all.
	AcceptsImages() bool
	EmbedImages(ctx context.Context, images []EmbedImage, kind EmbedInputType) ([][]float32, error)
}

type ImageInput struct {
	// ImageField is the key of the object that carries an image on a shape
	// with no standard image input ("image" on Jina). Protocols whose schema
	// fixes the image part ignore it.
	ImageField string `json:",omitempty"`
	// MaxImageBatchSize is the documented number of images per request.
	// 0 means one: a vendor that fuses its inputs, or does not say, must not
	// be sent several.
	MaxImageBatchSize int `json:",omitempty"`
	// MaxImageBytes is the documented size limit of one image, 0 when the
	// vendor states none. The caller shrinks an image to fit; the client
	// refuses one that does not rather than spend a request on it.
	MaxImageBytes int `json:",omitempty"`
	// ImageMIMETypes lists the formats the vendor documents, empty when it
	// takes any common one.
	ImageMIMETypes []string `json:",omitempty"`
}

type ImageReranker interface {
	// AcceptsImages reports whether this endpoint can carry an image at all.
	AcceptsImages() bool
	RerankImages(ctx context.Context, query string, images []EmbedImage) ([]RerankResult, error)
}

type ImageURL struct {
	URL    string `json:"url"`              // URL or base64 data URI
	Detail string `json:"detail,omitempty"` // "auto", "low", "high"
}

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

type Message struct {
	Role         string               `json:"role"`                    // 角色：system, user, assistant, tool
	Content      string               `json:"content"`                 // 消息内容
	MultiContent []MessageContentPart `json:"multi_content,omitempty"` // 多内容消息（文本+图片）
	Name         string               `json:"name,omitempty"`          // Function/tool name (for tool role)
	ToolCallID   string               `json:"tool_call_id,omitempty"`  // Tool call ID (for tool role)
	ToolCalls    []ToolCall           `json:"tool_calls,omitempty"`    // Tool calls (for assistant role)
	// Images are image URLs for multimodal input (current user message only).
	Images []string `json:"images,omitempty"`
	// ReasoningContent 是 assistant 推理类模型上一轮输出的思考内容。部分供应商
	// （MiMo、DeepSeek V3.2+、Kimi K2.5+）要求多轮对话中把 assistant 的
	// reasoning_content 原样回传，否则会以 400 拒绝请求；其他不要求的供应商会
	// 忽略未知字段。Anthropic 则要求把 thinking block 连同签名一起回放。
	ReasoningContent string `json:"reasoning_content,omitempty"`
	// ReasoningSignature is the provider-issued signature that must accompany
	// ReasoningContent when it is replayed (Anthropic thinking blocks, Gemini
	// thought signatures on text parts). Empty when the provider issues none.
	ReasoningSignature string `json:"reasoning_signature,omitempty"`
	// ReasoningMetadata carries opaque provider state that must round-trip
	// with the assistant turn but has no protocol-neutral representation:
	// OpenAI Responses reasoning items (encrypted_content), OpenRouter
	// reasoning_details, and so on. Keyed by protocol / vendor namespace.
	ReasoningMetadata types.ProviderMetadata `json:"reasoning_metadata,omitempty"`
	// Kind is engine-internal bookkeeping. `json:"-"` keeps it off the wire:
	// providers reject unknown message fields on some endpoints, and this one
	// means nothing to them anyway.
	Kind MessageKind `json:"-"`
	// TurnID is the stored assistant message whose turn this history message
	// was replayed from. It is empty for the live turn and for messages the
	// engine synthesized. Compaction uses it to tell whether a summary ends
	// exactly on a stored turn, the only kind it can persist for later turns.
	// Engine-internal like Kind, and kept off the wire for the same reason.
	TurnID string `json:"-"`
}

type MessageContentPart struct {
	Type     string    `json:"type"`                // "text" or "image_url"
	Text     string    `json:"text,omitempty"`      // For type="text"
	ImageURL *ImageURL `json:"image_url,omitempty"` // For type="image_url"
}

type MessageKind string

type OpenAICompletionsCompat struct {
	MaxTokensField               *string         `json:"max_tokens_field,omitempty"`
	ThinkingFormat               *ThinkingFormat `json:"thinking_format,omitempty"`
	ThinkingEnabledValue         *string         `json:"thinking_enabled_value,omitempty"`
	ThinkingAlwaysSend           *bool           `json:"thinking_always_send,omitempty"`
	ThinkingDisableOnNonStream   *bool           `json:"thinking_disable_on_non_stream,omitempty"`
	ThinkingBudgetField          *string         `json:"thinking_budget_field,omitempty"`
	ThinkingBudgetExcludesEffort *bool           `json:"thinking_budget_excludes_effort,omitempty"`
	ReasoningEffortField         *string         `json:"reasoning_effort_field,omitempty"`
	SupportsReasoningEffort      *bool           `json:"supports_reasoning_effort,omitempty"`
	SupportsDeveloperRole        *bool           `json:"supports_developer_role,omitempty"`
	SupportsStore                *bool           `json:"supports_store,omitempty"`
	SupportsUsageInStreaming     *bool           `json:"supports_usage_in_streaming,omitempty"`
	SupportsTemperature          *bool           `json:"supports_temperature,omitempty"`
	FixedTemperature             *float64        `json:"fixed_temperature,omitempty"`
	SupportsSeed                 *bool           `json:"supports_seed,omitempty"`
	ToolChoiceModes              []string        `json:"tool_choice_modes,omitempty"`
	SupportsParallelToolCalls    *bool           `json:"supports_parallel_tool_calls,omitempty"`
	SupportsResponseFormat       *bool           `json:"supports_response_format,omitempty"`
	SupportsMultiContent         *bool           `json:"supports_multi_content,omitempty"`
	ReplayReasoningContent       *bool           `json:"replay_reasoning_content,omitempty"`
	PromptCacheKey               *bool           `json:"prompt_cache_key,omitempty"`
	CacheControlFormat           *string         `json:"cache_control_format,omitempty"`
	PromptCacheAccounting        *bool           `json:"prompt_cache_accounting,omitempty"`
	ToolCallExtraFields          []string        `json:"tool_call_extra_fields,omitempty"`
	ExtraBody                    map[string]any  `json:"extra_body,omitempty"`
	ReasoningFields              []string        `json:"reasoning_fields,omitempty"`
}

type OpenAICompletionsSettings struct {
	// MaxTokensField is "max_tokens" or "max_completion_tokens".
	MaxTokensField string
	ThinkingFormat ThinkingFormat
	// ThinkingEnabledValue is the "type" sent for thinking-type when enabled
	// ("enabled" by default; MiniMax M3 uses "adaptive").
	ThinkingEnabledValue string
	// ThinkingAlwaysSend pins the switch on every request even when the
	// caller expressed no preference (DashScope hybrid models require it).
	ThinkingAlwaysSend bool
	// ThinkingDisableOnNonStream forces the switch off for non-streaming
	// calls (Qwen3 rejects thinking without stream).
	ThinkingDisableOnNonStream bool
	// ThinkingBudgetField carries Options.ThinkingBudgetTokens ("thinking_budget").
	ThinkingBudgetField string
	// ThinkingBudgetExcludesEffort marks a vendor that rejects a request
	// carrying both the budget and the effort (DashScope's qwen3.8-max
	// series: "不支持 reasoning_effort 与 thinking_budget 同时设置，同时设置
	// 会报错"). The graded level is what the caller actually picked, so the
	// budget is the field that yields.
	ThinkingBudgetExcludesEffort bool
	// ReasoningEffortField is "reasoning_effort" unless a vendor renames it.
	ReasoningEffortField    string
	SupportsReasoningEffort bool
	// SupportsDeveloperRole switches the system prompt to the developer role
	// on reasoning models.
	SupportsDeveloperRole bool
	// SupportsStore sends store:false (OpenAI keeps completions otherwise).
	SupportsStore            bool
	SupportsUsageInStreaming bool
	// SupportsTemperature false drops every sampling parameter (o-series,
	// GPT-5 family, Kimi K2.5+).
	SupportsTemperature bool
	// FixedTemperature pins the value when the vendor only accepts one.
	FixedTemperature          *float64
	SupportsSeed              bool
	ToolChoiceModes           []string
	SupportsParallelToolCalls bool
	SupportsResponseFormat    bool
	// SupportsMultiContent false flattens image/text parts to plain text.
	SupportsMultiContent bool
	// ReplayReasoningContent sends reasoning_content on prior assistant turns.
	ReplayReasoningContent bool
	// PromptCacheKey sends prompt_cache_key / prompt_cache_retention and the
	// session-affinity headers.
	PromptCacheKey bool
	// CacheControlFormat "anthropic" injects cache_control breakpoints.
	CacheControlFormat string
	// PromptCacheAccounting states the vendor reports cache usage at all.
	PromptCacheAccounting bool
	// ToolCallExtraFields lists tool_call keys to round-trip opaquely
	// (Gemini-through-OpenAI "extra_content").
	ToolCallExtraFields []string
	// ExtraBody is merged into every request body (vendor knobs such as
	// enable_search, sampling defaults).
	ExtraBody map[string]any
	// ReasoningFields are the delta keys that carry thinking text, in
	// priority order.
	ReasoningFields []string
}

type OpenAIResponsesCompat struct {
	SupportsDeveloperRole      *bool          `json:"supports_developer_role,omitempty"`
	SupportsMaxOutputTokens    *bool          `json:"supports_max_output_tokens,omitempty"`
	SupportsReasoningSummary   *bool          `json:"supports_reasoning_summary,omitempty"`
	SupportsEncryptedReasoning *bool          `json:"supports_encrypted_reasoning,omitempty"`
	SupportsStore              *bool          `json:"supports_store,omitempty"`
	SupportsTemperature        *bool          `json:"supports_temperature,omitempty"`
	PromptCacheKey             *bool          `json:"prompt_cache_key,omitempty"`
	SupportsLongCacheRetention *bool          `json:"supports_long_cache_retention,omitempty"`
	SupportsParallelToolCalls  *bool          `json:"supports_parallel_tool_calls,omitempty"`
	ExtraBody                  map[string]any `json:"extra_body,omitempty"`
}

type OpenAIResponsesSettings struct {
	SupportsDeveloperRole      bool
	SupportsMaxOutputTokens    bool
	SupportsReasoningSummary   bool
	SupportsEncryptedReasoning bool
	SupportsStore              bool
	SupportsTemperature        bool
	PromptCacheKey             bool
	SupportsLongCacheRetention bool
	SupportsParallelToolCalls  bool
	ExtraBody                  map[string]any
}

type OpenAIUsage struct {
	PromptTokens             int  `json:"prompt_tokens"`
	CompletionTokens         int  `json:"completion_tokens"`
	TotalTokens              int  `json:"total_tokens"`
	PromptCacheHitTokens     *int `json:"prompt_cache_hit_tokens"`
	PromptCacheMissTokens    *int `json:"prompt_cache_miss_tokens"`
	CachedTokens             *int `json:"cached_tokens"`
	CacheReadInputTokens     *int `json:"cache_read_input_tokens"`
	CacheCreationInputTokens *int `json:"cache_creation_input_tokens"`
	PromptTokensDetails      *struct {
		CachedTokens     *int `json:"cached_tokens"`
		CacheWriteTokens *int `json:"cache_write_tokens"`
	} `json:"prompt_tokens_details"`
	CompletionTokensDetails *struct {
		ReasoningTokens int `json:"reasoning_tokens"`
	} `json:"completion_tokens_details"`
}

type Options struct {
	Temperature float64 `json:"temperature"` // 温度参数
	TopP        float64 `json:"top_p"`       // Top P 参数
	Seed        int     `json:"seed"`        // 随机种子
	// MaxTokens and MaxCompletionTokens are aliases for one completion budget.
	// Callers may set either; CompletionBudget() prefers MaxCompletionTokens.
	// The outbound JSON carries exactly one field, named per vendor.
	MaxTokens           int     `json:"max_tokens"`
	MaxCompletionTokens int     `json:"max_completion_tokens"`
	FrequencyPenalty    float64 `json:"frequency_penalty"` // 频率惩罚
	PresencePenalty     float64 `json:"presence_penalty"`  // 存在惩罚
	// Thinking is the legacy on/off switch. Prefer ReasoningEffort; when both
	// are set ReasoningEffort wins. true maps to ReasoningAuto, false to
	// ReasoningOff.
	Thinking *bool `json:"thinking"`
	// ReasoningEffort selects the thinking intensity. Empty leaves the model
	// default untouched (no thinking fields are sent unless the vendor
	// requires them on every request).
	ReasoningEffort ReasoningEffort `json:"reasoning_effort,omitempty"`
	// ThinkingBudgetTokens caps the thinking tokens where the vendor exposes a
	// budget (Anthropic budget_tokens, DashScope thinking_budget, Gemini
	// thinkingBudget). 0 leaves the vendor default.
	ThinkingBudgetTokens int    `json:"thinking_budget_tokens,omitempty"`
	Tools                []Tool `json:"tools,omitempty"` // 可用工具列表
	// ToolChoice is "auto", "required", "none" or a specific tool name.
	ToolChoice        string          `json:"tool_choice,omitempty"`
	ParallelToolCalls *bool           `json:"parallel_tool_calls,omitempty"` // 是否允许并行工具调用（默认 nil 表示由模型决定）
	Format            json.RawMessage `json:"format,omitempty"`              // 响应格式定义
	// PromptCacheKey is the provider routing key (OpenAI prompt_cache_key).
	// Empty falls back to the session ID on the call context.
	PromptCacheKey string `json:"-"`
	// CacheRetention controls provider prompt-cache TTL. none disables cache
	// markers; empty/short is the default 5-minute cache; long requests 1h/24h
	// where the provider accepts it.
	CacheRetention CacheRetention `json:"-"`
}

type ReasoningEffort string

type RerankAPI string

type RerankCompat struct {
	Path             *string     `json:"path,omitempty"`
	SendTopN         *bool       `json:"send_top_n,omitempty"`
	SendReturnDocs   *bool       `json:"send_return_documents,omitempty"`
	ScoreScale       *ScoreScale `json:"score_scale,omitempty"`
	Truncate         *string     `json:"truncate,omitempty"`
	MaxDocuments     *int        `json:"max_documents,omitempty"`
	MaxQueryChars    *int        `json:"max_query_chars,omitempty"`
	MaxDocumentChars *int        `json:"max_document_chars,omitempty"`
	MaxRequestChars  *int        `json:"max_request_chars,omitempty"`
	MaxConcurrency   *int        `json:"max_concurrency,omitempty"`
	RequestTimeout   *int        `json:"request_timeout_seconds,omitempty"`
	// AcceptsTruncatePromptTokens marks a vLLM-class runtime.
	AcceptsTruncatePromptTokens *bool `json:"accepts_truncate_prompt_tokens,omitempty"`
	// UnsupportedReason marks a model this build cannot call.
	UnsupportedReason *string        `json:"unsupported_reason,omitempty"`
	ExtraBody         map[string]any `json:"extra_body,omitempty"`
	ImageField        *string        `json:"image_field,omitempty"`
	MaxImageBatchSize *int           `json:"max_image_batch_size,omitempty"`
	MaxImageBytes     *int           `json:"max_image_bytes,omitempty"`
	ImageMIMETypes    []string       `json:"image_mime_types,omitempty"`
}

type RerankResult struct {
	Index int
	Score float64
	// Text is the document echoed back, empty when the vendor was not asked
	// to return documents. Callers index into their own slice instead of
	// relying on it.
	Text string
}

type RerankSettings struct {
	// Path is appended to the base URL by protocols that use one. Vendors
	// whose default base URL already names the full endpoint leave it empty.
	Path string
	// SendTopN asks for every document back by naming their count. Omitting
	// it means "all", which is what every protocol here does by default.
	SendTopN bool
	// SendReturnDocs asks the vendor to echo the document text. Callers index
	// into their own slice, so this is off unless a vendor needs it.
	SendReturnDocs bool
	// ScoreScale says what the returned numbers mean. See ScoreScale:
	// getting this wrong makes a relevance threshold meaningless.
	ScoreScale ScoreScale
	// Truncate is the vendor's server-side truncation setting for
	// over-long input ("END" on NIM). Empty sends nothing.
	Truncate string
	// Limits carry the documented per-request ceilings. MaxQueryChars is
	// checked on its own rather than through BatchLimits: the query is not an
	// item to be split, so an over-long one cannot be made to fit by batching.
	MaxDocuments     int
	MaxQueryChars    int
	MaxDocumentChars int
	MaxRequestChars  int
	// MaxConcurrency bounds in-flight batches when the input is split. 0
	// means the caller's default.
	MaxConcurrency int
	// RequestTimeout caps one request, in seconds. 0 uses the rerank
	// client's default (see rerank.newRerankHTTPClient).
	RequestTimeout int
	// AcceptsTruncatePromptTokens reports that this vendor is a vLLM-class
	// runtime, which is the only kind that implements the
	// `truncate_prompt_tokens` extension. It is not part of the Cohere shape
	// and appears in no managed vendor's schema, so it must never be sent to
	// one: that is how an undocumented field ends up on every request.
	AcceptsTruncatePromptTokens bool
	// UnsupportedReason is set on a catalog entry naming a rerank dialect no
	// protocol package implements. Resolve refuses it rather than letting a
	// request go out shaped for a different protocol, which surfaces as a
	// decode error far from its cause.
	UnsupportedReason string
	// TruncatePromptTokens is the budget the operator opted into on this row,
	// honoured only where AcceptsTruncatePromptTokens is set. It is a row
	// setting rather than a vendor fact because one runtime serves models
	// with different context windows. Zero sends nothing.
	TruncatePromptTokens int
	ExtraBody            map[string]any
	// ImageInput is how this endpoint takes image documents, for the models
	// whose catalog input lists image. Image documents are sent in requests
	// of their own, at most ImageBatchLimit per request; each is scored
	// against the query on its own, so their scores compare with the text
	// documents' as any two batches do.
	ImageInput
}

type Reranker interface {
	Rerank(ctx context.Context, query string, documents []string) ([]RerankResult, error)
}

type RetryPolicy struct {
	// MaxRetries is the number of retries after the first attempt.
	MaxRetries int
	// BaseDelay is the wait before the first retry; it doubles each time.
	BaseDelay time.Duration
	// MaxDelay caps the backoff.
	MaxDelay time.Duration
}

type SSEEvent struct {
	Data []byte
	Done bool
}

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

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

type ScoreScale string

type StreamAssembler struct {
	ThinkingEmitter

	// Usage is captured from the final stream chunk when the vendor reports it.
	Usage *types.TokenUsage
	// LastFinishReason is the last observed finish_reason for the EOF fallback.
	LastFinishReason string
	// ReasoningSignature / ReasoningMetadata accumulate provider artifacts that
	// the final Done chunk hands back to the caller through Data.
	ReasoningSignature string
	ReasoningMetadata  types.ProviderMetadata
	// contains filtered or unexported fields
}

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

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

type ThinkingFormat string

type ThinkingLevelMap map[ReasoningEffort]*string

type Tool struct {
	Type     string      `json:"type"` // "function"
	Function FunctionDef `json:"function"`
}

type ToolCall struct {
	ID               string                 `json:"id"`
	Type             string                 `json:"type"` // "function"
	Function         FunctionCall           `json:"function"`
	ProviderMetadata types.ToolCallMetadata `json:"provider_metadata,omitempty"`
}

type ToolCallDelta struct {
	Index     int
	ID        string
	Type      string
	Name      string
	Arguments string
}

type Transcriber interface {
	Transcribe(ctx context.Context, req TranscriptionRequest) (*Transcription, error)
}

type Transcription struct {
	Text     string
	Segments []TranscriptionSegment
	// Duration is the audio length in seconds when the reply states it —
	// OpenAI-shaped duration or usage.seconds — and 0 otherwise.
	Duration float64
}

type TranscriptionAPI string

type TranscriptionRequest struct {
	Audio    []byte
	FileName string
	// Language is the operator's hint, empty for auto-detection. Where it is
	// sent, and whether at all, is the vendor's declaration.
	Language string
}

type TranscriptionSegment struct {
	Start float64
	End   float64
	Text  string
}

type TranscriptionsCompat struct {
	API  *TranscriptionAPI `json:"api,omitempty"`
	Path *string           `json:"path,omitempty"`
	// ResponseFormat is sent as response_format when non-empty. OpenAI's
	// gpt-4o-transcribe and gpt-4o-mini-transcribe accept only json, which is
	// also the default, so most models leave it unset.
	ResponseFormat *string `json:"response_format,omitempty"`
	// LanguageParam names where the language hint goes: form, header or
	// asr_options; empty sends none.
	LanguageParam *string `json:"language_param,omitempty"`
	// MaxFileBytes is the documented upload ceiling for the audio itself.
	MaxFileBytes *int `json:"max_file_bytes,omitempty"`
	// MaxEncodedBytes is the documented ceiling on the base64 data URI, for
	// the protocols that send the audio that way.
	MaxEncodedBytes *int `json:"max_encoded_bytes,omitempty"`
	// Formats lists the file extensions the vendor documents, without the
	// dot. Empty means the vendor documents no closed list.
	Formats        []string `json:"formats,omitempty"`
	RequestTimeout *int     `json:"request_timeout_seconds,omitempty"`
	// UnsupportedReason marks a model this build cannot call.
	UnsupportedReason *string `json:"unsupported_reason,omitempty"`
}

type TranscriptionsSettings struct {
	API            TranscriptionAPI
	Path           string
	ResponseFormat string
	LanguageParam  string
	// MaxFileBytes and MaxEncodedBytes refuse an upload the vendor would
	// reject anyway, before sending it; 0 leaves the check to the vendor.
	MaxFileBytes    int
	MaxEncodedBytes int
	Formats         []string
	// RequestTimeout caps one request, in seconds.
	RequestTimeout int
	// UnsupportedReason is set where a vendor's recognition models, or some
	// of them, cannot be called with the audio in the request — they take a
	// public URL or run as asynchronous tasks. Resolve refuses such a model
	// rather than sending it a shape it does not accept.
	UnsupportedReason string
}

type TransportError struct {
	// Op is the phase that failed: "send request" or "read response".
	Op  string
	Err error
}