llms

type BatchHandle struct {
	// ID is the provider-assigned batch identifier.
	ID string
	// Provider is the LLM provider that owns this batch.
	Provider ProviderType
	// Status is the current lifecycle state.
	Status BatchStatus
	// RequestCounts summarizes per-request progress.
	RequestCounts BatchRequestCounts
	// CreatedAt is when the batch was submitted to the provider. It is nil if
	// the provider did not report a creation time.
	CreatedAt *time.Time
	// CompletedAt is when the batch reached a terminal state. It is nil while
	// the batch is still in a non-terminal state.
	CompletedAt *time.Time
	// ExpiresAt is the deadline by which the batch must complete. It is nil if
	// the provider did not report an expiration time.
	ExpiresAt *time.Time
	// Metadata mirrors any caller-supplied metadata round-tripped through the provider.
	Metadata map[string]string
	// ProviderMeta is the raw provider-specific batch object, kept as an opaque
	// value for callers that need fields this abstraction does not surface
	// (e.g. OpenAI's input_file_id / output_file_id / error_file_id).
	ProviderMeta any
}

type BatchRequest struct {
	// CustomID is a caller-supplied identifier used to correlate this request to its
	// result. It must be unique within the batch and is echoed back on each BatchResult.
	CustomID string
	// Messages is the input message sequence, identical to Model.GenerateContent.
	Messages []Message
	// Options are the per-request CallOptions, identical to Model.GenerateContent.
	Options []CallOption
}

type BatchRequestCounts struct {
	// Total is the number of requests in the batch.
	Total int
	// Completed is the number of requests that have finished successfully.
	Completed int
	// Failed is the number of requests that returned a per-request error.
	Failed int
}

type BatchRequestError struct {
	// Code is the provider's machine-readable error code (e.g. "rate_limit_exceeded").
	Code string
	// Message is a human-readable error description.
	Message string
}

type BatchResult struct {
	// CustomID matches the CustomID supplied on the original BatchRequest.
	CustomID string
	// Response is the parsed model response. Nil when the per-request call errored.
	Response *ContentResponse
	// Error describes a per-request failure. Nil when the request succeeded.
	Error *BatchRequestError
}

type BatchStatus string

type BatchSubmitOption func(*BatchSubmitOptions)

type BatchSubmitOptions struct {
	// CompletionWindow is the maximum time the provider should hold the batch open.
	// Providers that only support a single window (e.g. OpenAI's "24h") ignore this
	// when it conflicts with their fixed value.
	CompletionWindow time.Duration
	// Metadata is round-tripped through the provider on the batch object.
	Metadata map[string]string
}

type Batcher interface {
	// SubmitBatch enqueues a set of requests for asynchronous processing and
	// returns a handle that callers persist to track the batch across processes.
	SubmitBatch(ctx context.Context, requests []BatchRequest, options ...BatchSubmitOption) (*BatchHandle, error)
	// GetBatch fetches the current state of a submitted batch. Callers poll this
	// until Status.IsTerminal() returns true.
	GetBatch(ctx context.Context, batchID string) (*BatchHandle, error)
	// CancelBatch requests cancellation of an in-flight batch. The returned
	// handle reflects the updated status (typically Cancelling, then Cancelled).
	CancelBatch(ctx context.Context, batchID string) (*BatchHandle, error)
	// FetchBatchResults returns all results for a terminal batch. It returns
	// ErrBatchNotReady if the batch has not yet reached a terminal state.
	// Per-request failures are surfaced on BatchResult.Error rather than as a
	// returned error, so callers can process partial successes.
	FetchBatchResults(ctx context.Context, batchID string) ([]BatchResult, error)
}

type BinaryContent struct {
	MIMEType string `json:"mime_type"`
	Data     []byte `json:"data"`
}

type BinaryContentJSON struct {
	Type   string     `json:"type"`
	Binary BinaryJSON `json:"binary"`
}

type BinaryJSON struct {
	Data     string `json:"data"`
	MIMEType string `json:"mime_type"`
}

type BlockType string

type CallOption func(*CallOptions)

type CallOptions struct {
	// Model is the model to use.
	Model string
	// CandidateCount is the number of response candidates to generate.
	CandidateCount int
	// MaxTokens is the maximum number of tokens to generate.
	MaxTokens int
	// Temperature is the temperature for sampling, between 0 and 1.
	Temperature float64
	// StopWords is a list of words to stop on.
	StopWords []string
	// StreamingFunc is a function to be called for each chunk of a streaming response.
	// Return an error to stop streaming early.
	StreamingFunc func(ctx context.Context, chunk []byte) error
	// StreamingReasoningFunc is a function to be called for each chunk of a streaming response.
	// Return an error to stop streaming early.
	StreamingReasoningFunc func(ctx context.Context, reasoningChunk, chunk []byte) error
	// TopK is the number of tokens to consider for top-k sampling.
	TopK int
	// TopP is the cumulative probability for top-p sampling.
	TopP float64
	// Seed is a seed for deterministic sampling.
	Seed int
	// MinLength is the minimum length of the generated text.
	MinLength int
	// MaxLength is the maximum length of the generated text.
	MaxLength int
	// N is how many chat completion choices to generate for each input message.
	N int
	// RepetitionPenalty is the repetition penalty for sampling.
	RepetitionPenalty float64
	// FrequencyPenalty is the frequency penalty for sampling.
	FrequencyPenalty float64
	// PresencePenalty is the presence penalty for sampling.
	PresencePenalty float64

	// Tools is a list of tools to use. Each tool can be a specific tool or a function.
	Tools []Tool
	// ToolChoice is the choice of tool to use, it can either be "none", "auto" (the default behavior), or a specific tool as described in the ToolChoice type.
	ToolChoice any

	// Metadata is a map of metadata to include in the request.
	// The meaning of this field is specific to the backend in use.
	Metadata map[string]any

	// ResponseFormat is a custom response format.
	// If it's not set the response MIME type is text/plain.
	// Otherwise, from response format the JSON mode is derived.
	ResponseFormat *schema.ResponseFormat

	ReasoningEffort ReasoningEffort

	// PromptCachePolicy configures provider-native prompt caching.
	PromptCachePolicy *PromptCachePolicy
}

type Capability uint64

type ContentChoice struct {
	// Content is the textual content of a response
	Content string `json:"content"`

	// StopReason is the reason the model stopped generating output.
	StopReason string `json:"stop_reason"`

	// GenerationInfo is arbitrary information the model adds to the response.
	GenerationInfo map[string]any `json:"generation_info"`

	// Usage is the usage of the content choice.
	Usage Usage `json:"usage"`

	// FuncCall is non-nil when the model asks to invoke a function/tool.
	// If a model invokes more than one function/tool, this field will only
	// contain the first one.
	FuncCall *FunctionCall `json:"func_call"`

	// ToolCalls is a list of tool calls the model asks to invoke.
	ToolCalls []ToolCall `json:"tool_calls"`

	// ReasoningContent is the model's reasoning before the final answer, when
	// the provider returns it: deepseek-reasoner's reasoning_content, or
	// Anthropic thinking blocks (empty when the thinking display omits them).
	ReasoningContent string `json:"reasoning_content"`
}

type ContentPart interface {
	String() string
	ContentType() ContentPartType
	ContentLength() int
	// contains filtered or unexported methods
}

type ContentPartJSON struct {
	Type         string            `json:"type"`
	Text         string            `json:"text,omitempty"`
	ImageURL     *ImageURLJSON     `json:"image_url,omitempty"`
	Binary       *BinaryJSON       `json:"binary,omitempty"`
	ToolCall     *ToolCallJSON     `json:"tool_call,omitempty"`
	ToolResponse *ToolResponseJSON `json:"tool_response,omitempty"`
}

type ContentPartType string

type ContentResponse struct {
	Choices []*ContentChoice
}

type Effort string

type EffortPolicy struct {
	// Default is used when a call does not request a level.
	Default ReasoningEffort
	// Max is the highest level a call may use. ReasoningEffortDefault means
	// there is no ceiling.
	Max ReasoningEffort
	// Supported holds the levels the provider reports for the client's model.
	// When it is not empty, the client uses it in place of its own table for
	// that model. The empty set means the provider reported none.
	Supported EffortSet
	// Implicit is the level the provider reports the client's model applies
	// to a request that names none. ReasoningEffortDefault means the provider
	// did not report it.
	Implicit ReasoningEffort
}

type EffortSet uint8

type Embedder interface {
	// CreateEmbedding creates embeddings for the given input texts.
	CreateEmbedding(ctx context.Context, texts []string) ([][]float32, error)
}

type FinishReason string

type FormatType string

type FunctionCall struct {
	// The name of the function to call.
	Name string `json:"name"`
	// The arguments to pass to the function, as a JSON string.
	Arguments string `json:"arguments"`
}

type FunctionCallBehavior string

type FunctionDefinition struct {
	// Name is the name of the function.
	Name string `json:"name"`
	// Description is a description of the function.
	Description string `json:"description"`
	// Parameters is a list of parameters for the function.
	Parameters *jsonschema.Schema `json:"parameters,omitempty"`
	// Strict is a flag to indicate if the function should be called strictly. Only used for openai llm structured output.
	Strict bool `json:"strict,omitempty"`
}

type FunctionReference struct {
	// Name is the name of the function.
	Name string `json:"name"`
}

type ImageURLContent struct {
	URL    string `json:"url"`
	Detail string `json:"detail,omitempty"` // Detail is the detail of the image, e.g. "low", "high".
}

type ImageURLContentJSON struct {
	Type     string       `json:"type"`
	ImageURL ImageURLJSON `json:"image_url"`
}

type ImageURLJSON struct {
	URL    string `json:"url"`
	Detail string `json:"detail,omitempty"`
}

type InferenceBlock struct {
	Type      BlockType
	Text      string
	ID        string
	Name      string
	Arguments string
	Opaque    json.RawMessage
	Source    string
}

type InferenceError struct {
	Status int
	Param  string
	Cause  error
}

type InferenceFormat struct {
	Type   FormatType
	Name   string
	Schema json.RawMessage
	Strict bool
}

type InferenceMessage struct {
	Role    InferenceRole
	Content []InferenceBlock
}

type InferenceModel interface {
	// ValidateInference rejects controls the connector cannot translate faithfully.
	// It must return UnsupportedInference for each such control.
	ValidateInference(InferenceRequest) error
	// Infer generates one response without executing tools or retrying.
	Infer(context.Context, InferenceRequest) (*InferenceResponse, error)
}

type InferenceReasoning struct {
	Effort       Effort
	BudgetTokens *int
}

type InferenceRequest struct {
	Model             string
	Messages          []InferenceMessage
	Tools             []InferenceTool
	ToolChoice        *InferenceToolChoice
	ParallelToolCalls *bool
	Temperature       *float64
	TopP              *float64
	MaxTokens         *int
	Stop              []string
	Seed              *int64
	Format            *InferenceFormat
	Reasoning         *InferenceReasoning
}

type InferenceResponse struct {
	Content      []InferenceBlock
	FinishReason FinishReason
	Usage        Usage
	UsageKnown   bool
	UpstreamID   string
}

type InferenceRole string

type InferenceTool struct {
	Name        string
	Description string
	Parameters  json.RawMessage
	Strict      *bool
}

type InferenceToolChoice struct {
	Mode ToolChoiceMode
	Name string
}

type Message struct {
	Role  Role          `json:"role"`
	Parts []ContentPart `json:"parts"`

	// Source is the source of the message.
	// It's used to identify the source of the message.
	Source *MessageSource `json:"source,omitempty"`
}

type MessageContentJSON struct {
	Role   Role           `json:"role"`
	Text   string         `json:"text,omitempty"`
	Source *MessageSource `json:"source,omitempty"`
}

type MessageContentWithPartsJSON struct {
	Role   Role           `json:"role"`
	Parts  []ContentPart  `json:"parts"`
	Source *MessageSource `json:"source,omitempty"`
}

type MessageSource struct {
	// Name is the name of the source of the message.
	Name string `json:"name"`
	// RunID is the ID of the run of the message.
	RunID string `json:"run_id,omitempty"`
	// ActionID is the ID of the action of the message.
	ActionID string `json:"action_id,omitempty"`
}

type Messages = []Message

type Model interface {
	// GetName returns the name of the model.
	GetName() string
	// GetProviderType returns the type of provider.
	GetProviderType() ProviderType
	// GenerateContent asks the model to generate content from a sequence of
	// messages. It's the most general interface for multi-modal LLMs that support
	// chat-like interactions.
	GenerateContent(ctx context.Context, messages []Message, options ...CallOption) (*ContentResponse, error)
}

type ModelInfo struct {
	// ID is the identifier to name the model with in a request.
	ID string
	// DisplayName is the human-readable name of the model.
	DisplayName string
	// Family is the model family as the provider names it, such as "opus".
	// It is empty when the provider does not report one; derive it from the
	// ID with [ParseModelName] in that case.
	Family string
	// Created is the release time of the model.
	Created time.Time
	// Lifecycle is the stage of the model in the provider's catalog.
	Lifecycle ModelLifecycle
	// RetiresAt is the announced time at which the model stops answering
	// requests. It is zero when none is announced.
	RetiresAt time.Time
	// Efforts are the reasoning effort levels the provider reports for the
	// model. The set is empty when the provider reports none, which does not
	// mean that the model has no reasoning control.
	Efforts EffortSet
	// DefaultEffort is the level the provider reports the model applies to a
	// request that names none. It is ReasoningEffortDefault when the provider
	// does not report one.
	DefaultEffort ReasoningEffort
}

type ModelLifecycle string

type ModelLister interface {
	// ListModels returns every model the provider lists for the account, in
	// the provider's order. The list is not limited to chat models: it can
	// hold embedding, image or audio models as well.
	ListModels(ctx context.Context) ([]ModelInfo, error)
}

type ModelName struct {
	// ID is the model ID as given.
	ID string
	// Prefix is the routing or vendor prefix, such as "us.anthropic." in a
	// Bedrock ID or "openai/" in an OpenRouter ID. Empty for first-party IDs.
	Prefix string
	// Family is the name without prefix, version, snapshot and stage, such as
	// "claude-opus", "gpt-mini" or "gemini-flash-lite".
	Family string
	// Version holds the numeric version components, such as [4 8] for
	// claude-opus-4-8 and [5 1] for gpt-5.1. Empty when the ID has none.
	Version []int
	// Snapshot is the dated or numbered build, such as "20250514",
	// "2025-11-13" or "v1:0". Empty for a floating ID.
	Snapshot string
	// Stage is the release stage word, such as "preview". Empty for a
	// generally available model.
	Stage string
	// Variant is the offering a router appends to an ID after a colon, such
	// as "batch" in openai/gpt-5.5:batch or "free". It is the same model
	// served on other terms, so it is not part of the family, but it is part
	// of [ModelName.Key]. Empty for most IDs.
	Variant string
}

type PromptCacheBreakpoint struct {
	// Target identifies the prompt element that should become a cache breakpoint.
	Target PromptCacheTarget
	// TTL overrides the provider cache breakpoint TTL where supported.
	TTL PromptCacheTTL
}

type PromptCachePolicy struct {
	// Request configures request-level prompt caching (e.g. OpenAI).
	Request *PromptCacheRequestPolicy
	// Breakpoints configures explicit cache breakpoints (e.g. Anthropic).
	Breakpoints []PromptCacheBreakpoint
}

type PromptCacheRequestPolicy struct {
	// Key identifies a reusable prompt cache entry on providers that support it.
	Key string
	// Retention controls how long the provider should retain the cached prompt.
	Retention PromptCacheRetention
}

type PromptCacheRetention string

type PromptCacheTTL string

type PromptCacheTarget struct {
	// Kind identifies whether the target is a message part or a tool definition.
	Kind PromptCacheTargetKind
	// MessageIndex selects the original llms.Message index for message_part targets.
	MessageIndex int
	// PartIndex selects the llms.Message.Parts index for message_part targets.
	PartIndex int
	// ToolIndex selects the llms.Tool index for tool targets.
	ToolIndex int
}

type PromptCacheTargetKind string

type PromptValue interface {
	String() string
	Messages() []Message
}

type ProviderType string

type ReasoningEffort int

type Role string

type TextContent struct {
	Text string `json:"text"`
}

type TextContentJSON struct {
	Text string `json:"text"`
	Type string `json:"type"`
}

type Tool struct {
	// Type is the type of the tool.
	Type string `json:"type"`
	// Function is the function to call.
	Function *FunctionDefinition `json:"function,omitempty"`
	// WebSearchOptions are the options for the web search tool,
	// For providers and models that support Web Search grounding.
	WebSearchOptions *WebSearchOptions `json:"-"`
}

type ToolCall struct {
	// ID is the unique identifier of the tool call.
	ID string `json:"id"`
	// Type is the type of the tool call: ToolTypeFunction for function tools,
	// or the tool type for provider-native tools such as web_search.
	Type string `json:"type"`
	// FunctionCall is the function call to be executed.
	FunctionCall *FunctionCall `json:"function,omitempty"`
}

type ToolCallContentJSON struct {
	Type     string       `json:"type"`
	ToolCall ToolCallJSON `json:"tool_call"`
}

type ToolCallJSON struct {
	ID           string        `json:"id"`
	Type         string        `json:"type"`
	FunctionCall *FunctionCall `json:"function"`
}

type ToolCallJSONOrdered struct {
	FunctionCall *FunctionCall `json:"function"`
	ID           string        `json:"id"`
	Type         string        `json:"type"`
}

type ToolCallResponse struct {
	// ToolCallID is the ID of the tool call this response is for.
	ToolCallID string `json:"tool_call_id"`
	// Name is the name of the tool that was called.
	Name string `json:"name"`
	// Content is the textual content of the response.
	Content string `json:"content"`
}

type ToolChoice struct {
	// Type is the type of the tool.
	Type string `json:"type"`
	// Function is the function to call (if the tool is a function).
	Function *FunctionReference `json:"function,omitempty"`
}

type ToolChoiceMode string

type ToolResponseContentJSON struct {
	Type         string           `json:"type"`
	ToolResponse ToolResponseJSON `json:"tool_response"`
}

type ToolResponseJSON struct {
	ToolCallID string `json:"tool_call_id"`
	Name       string `json:"name"`
	Content    string `json:"content"`
}

type ToolResponseJSONOrdered struct {
	ToolCallID string `json:"tool_call_id"`
	Name       string `json:"name"`
	Content    string `json:"content"`
}

type Usage struct {
	InputTokens      uint64
	OutputTokens     uint64
	CacheWriteTokens uint64
	CacheReadTokens  uint64
	ReasoningTokens  uint64
	TotalTokens      uint64
}

type UsageStats struct {
	ModelUsage map[string]*Usage

	// BytesOut is the number of bytes sent to the LLM.
	BytesOut uint64
	// BytesIn is the number of bytes received from the LLM.
	BytesIn uint64
	// LlmCallCount is the number of GenerateContent calls made.
	LlmCallCount uint32
}

type WebSearchOptions struct {
	// AllowedDomains is a list of domains to search on.
	// Supported by OpenAI, Anthropic, and Azure.
	AllowedDomains []string
	// ExcludedDomains is a list of domains to exclude from search.
	// Supported by Google AI.
	ExcludedDomains []string
	// MaxUses is the maximum number of times the tool can be used.
	// Supported by OpenAI, Anthropic, and Azure.
	MaxUses int
}