llms

type AIChatMessage struct {
	// Content is the content of the message.
	Content string `json:"content,omitempty"`

	// FunctionCall represents the model choosing to call a function.
	FunctionCall *FunctionCall `json:"function_call,omitempty"`

	// ToolCalls represents the model choosing to call tools.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// ReasoningContent is used with deepseek-reasoner model and represents
	// the reasoning contents of the assistant message before the final answer.
	ReasoningContent string `json:"reasoning_content,omitempty"`

	// ThinkingContent contains the model's thinking/reasoning text.
	// Used by Gemini 3.0 and other models that support extended thinking.
	ThinkingContent string `json:"thinking_content,omitempty"`

	// ThoughtSignature is an opaque verification token for Gemini 3.0 thinking.
	// This must be persisted and returned in subsequent API calls to validate
	// the reasoning context in multi-turn conversations.
	ThoughtSignature string `json:"thought_signature,omitempty"`
}

type BinaryContent struct {
	MIMEType string
	Data     []byte
}

type CacheControl struct {
	// Type specifies the type of caching (provider-specific, e.g., "ephemeral").
	Type string `json:"type,omitempty"`

	// Duration specifies cache lifetime (provider-specific limits apply).
	Duration time.Duration `json:"-"`
}

type CachedContent struct {
	ContentPart
	CacheControl *CacheControl `json:"cache_control,omitempty"`
}

type CallOption func(*CallOptions)

type CallOptions struct {
	// Model is the model to use.
	Model string `json:"model"`
	// CandidateCount is the number of response candidates to generate.
	CandidateCount int `json:"candidate_count"`
	// MaxTokens is the maximum number of tokens to generate.
	MaxTokens int `json:"max_tokens"`
	// Temperature is the temperature for sampling, between 0 and 1.
	Temperature float64 `json:"temperature"`
	// StopWords is a list of words to stop on.
	StopWords []string `json:"stop_words"`
	// 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 `json:"-"`
	// 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 `json:"-"`
	// TopK is the number of tokens to consider for top-k sampling.
	TopK int `json:"top_k"`
	// TopP is the cumulative probability for top-p sampling.
	TopP float64 `json:"top_p"`
	// Seed is a seed for deterministic sampling.
	Seed int `json:"seed"`
	// MinLength is the minimum length of the generated text.
	MinLength int `json:"min_length"`
	// MaxLength is the maximum length of the generated text.
	MaxLength int `json:"max_length"`
	// N is how many chat completion choices to generate for each input message.
	N int `json:"n"`
	// RepetitionPenalty is the repetition penalty for sampling.
	RepetitionPenalty float64 `json:"repetition_penalty"`
	// FrequencyPenalty is the frequency penalty for sampling.
	FrequencyPenalty float64 `json:"frequency_penalty"`
	// PresencePenalty is the presence penalty for sampling.
	PresencePenalty float64 `json:"presence_penalty"`

	// JSONMode is a flag to enable JSON mode.
	JSONMode bool `json:"json"`

	// Tools is a list of tools to use. Each tool can be a specific tool or a function.
	Tools []Tool `json:"tools,omitempty"`
	// 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 `json:"tool_choice"`

	// Function defitions to include in the request.
	// Deprecated: Use Tools instead.
	Functions []FunctionDefinition `json:"functions,omitempty"`
	// FunctionCallBehavior is the behavior to use when calling functions.
	//
	// If a specific function should be invoked, use the format:
	// `{"name": "my_function"}`
	// Deprecated: Use ToolChoice instead.
	FunctionCallBehavior FunctionCallBehavior `json:"function_call,omitempty"`

	// 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]interface{} `json:"metadata,omitempty"`

	// ResponseMIMEType MIME type of the generated candidate text.
	// Supported MIME types are: text/plain: (default) Text output.
	// application/json: JSON response in the response candidates.
	ResponseMIMEType string `json:"response_mime_type,omitempty"`
}

type ChatMessage interface {
	// GetType gets the type of the message.
	GetType() ChatMessageType
	// GetContent gets the content of the message.
	GetContent() string
}

type ChatMessageModel struct {
	Type string               `bson:"type" json:"type"`
	Data ChatMessageModelData `bson:"data" json:"data"`
}

type ChatMessageModelData struct {
	Content string `bson:"content" json:"content"`
	Type    string `bson:"type"    json:"type"`
}

type ChatMessageType string

type ContentChoice struct {
	// Content is the textual content of a response
	Content string

	// StopReason is the reason the model stopped generating output.
	StopReason string

	// GenerationInfo is arbitrary information the model adds to the response.
	GenerationInfo map[string]any

	// 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

	// ToolCalls is a list of tool calls the model asks to invoke.
	ToolCalls []ToolCall

	// ReasoningContent is used with deepseek-reasoner model and represents
	// the reasoning contents of the assistant message before the final answer.
	ReasoningContent string

	// ThinkingContent contains the model's thinking/reasoning text.
	// Used by Gemini 3.0 and other models that support extended thinking.
	ThinkingContent string

	// ThoughtSignature is an opaque verification token for Gemini 3.0 thinking.
	// This must be persisted and returned in subsequent API calls to validate
	// the reasoning context in multi-turn conversations.
	ThoughtSignature string
}

type ContentPart interface {
	// contains filtered or unexported methods
}

type ContentResponse struct {
	Choices []*ContentChoice
}

type Error struct {
	// Code is the standardized error code.
	Code ErrorCode

	// Message is a human-readable error message.
	Message string

	// Provider is the name of the provider that generated the error.
	Provider string

	// Details contains provider-specific error details.
	Details map[string]interface{}

	// Cause is the underlying error, if any.
	Cause error
}

type ErrorCode string

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

type ErrorMatcher struct {
	// Match returns true if this matcher handles the error
	Match func(error) bool
	// Code is the error code to use
	Code ErrorCode
	// Transform optionally transforms the error message
	Transform func(error) 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 FunctionChatMessage struct {
	// Name is the name of the function.
	Name string `json:"name"`
	// Content is the content of the function message.
	Content string `json:"content"`
}

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 any `json:"parameters,omitempty"`
	// Strict is a flag to indicate if the function should be called strictly.
	// Provider support varies - typically used for structured output guarantees.
	Strict bool `json:"strict,omitempty"`
}

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

type GenericChatMessage struct {
	Content string
	Role    string
	Name    string
}

type HumanChatMessage struct {
	Content string
}

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

type MessageContent struct {
	Role  ChatMessageType
	Parts []ContentPart
}

type Model interface {
	// 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 []MessageContent, options ...CallOption) (*ContentResponse, error)

	// Call is a simplified interface for a text-only Model, generating a single
	// string response from a single string prompt.
	//
	// Deprecated: this method is retained for backwards compatibility. Use the
	// more general [GenerateContent] instead. You can also use
	// the [GenerateFromSinglePrompt] function which provides a similar capability
	// to Call and is built on top of the new interface.
	Call(ctx context.Context, prompt string, options ...CallOption) (string, error)
}

type Named interface {
	GetName() string
}

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

type ReasoningModel interface {
	Model

	// SupportsReasoning returns true if the model supports reasoning/thinking tokens.
	// This capability allows models to "think" through problems internally before
	// generating a response, improving quality for complex tasks.
	SupportsReasoning() bool
}

type SystemChatMessage struct {
	Content string
}

type TextContent struct {
	Text string
}

type ThinkingConfig struct {
	// Mode specifies the thinking mode (none, low, medium, high, auto).
	Mode ThinkingMode `json:"mode,omitempty"`

	// BudgetTokens sets explicit token budget for thinking.
	// Providers may have different minimum and maximum limits.
	BudgetTokens int `json:"budget_tokens,omitempty"`

	// ReturnThinking controls whether thinking/reasoning is included in response.
	// Provider support and behavior varies.
	ReturnThinking bool `json:"return_thinking,omitempty"`

	// StreamThinking enables streaming of thinking tokens as they're generated.
	// Not all providers support this feature.
	StreamThinking bool `json:"stream_thinking,omitempty"`

	// InterleaveThinking enables thinking between tool calls.
	// Provider support varies.
	InterleaveThinking bool `json:"interleave_thinking,omitempty"`
}

type ThinkingContent struct {
	// Thinking is the model's reasoning/thinking text.
	Thinking string `json:"thinking"`
	// Signature is the opaque verification token that must be returned
	// in subsequent API calls to validate the reasoning context.
	Signature string `json:"signature,omitempty"`
}

type ThinkingMode string

type ThinkingTokenUsage struct {
	// ThinkingTokens is the total number of thinking/reasoning tokens used.
	ThinkingTokens int `json:"thinking_tokens,omitempty"`

	// ThinkingInputTokens is the number of input tokens used for thinking.
	ThinkingInputTokens int `json:"thinking_input_tokens,omitempty"`

	// ThinkingOutputTokens is the number of output tokens from thinking.
	ThinkingOutputTokens int `json:"thinking_output_tokens,omitempty"`

	// ThinkingCachedTokens is the number of cached thinking tokens (if applicable).
	ThinkingCachedTokens int `json:"thinking_cached_tokens,omitempty"`

	// ThinkingBudgetUsed is the actual budget used vs allocated.
	ThinkingBudgetUsed int `json:"thinking_budget_used,omitempty"`

	// ThinkingBudgetAllocated is the budget that was allocated.
	ThinkingBudgetAllocated int `json:"thinking_budget_allocated,omitempty"`
}

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

type ToolCall struct {
	// ID is the unique identifier of the tool call.
	ID string `json:"id"`
	// Type is the type of the tool call. Typically, this would be "function".
	Type string `json:"type"`
	// FunctionCall is the function call to be executed.
	FunctionCall *FunctionCall `json:"function,omitempty"`
	// ThoughtSignature is an opaque verification token for Gemini 3.0 thinking.
	// When present, this must be included when sending tool call responses back
	// to the model. Required for Gemini 3 Pro function calling.
	ThoughtSignature string `json:"thought_signature,omitempty"`
}

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 ToolChatMessage struct {
	// ID is the ID of the tool call.
	ID string `json:"tool_call_id"`
	// Content is the content of the tool message.
	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"`
}