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

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

type ApproximateLocation struct {
	// Country is the two-letter ISO country code (e.g., "US", "GB").
	Country string `json:"country,omitempty"`

	// City is the city name (e.g., "San Francisco", "London").
	City string `json:"city,omitempty"`

	// Region is the region or state (e.g., "California", "London").
	Region string `json:"region,omitempty"`
}

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

type CacheControl struct {
	Type     string        `json:"type,omitempty"`
	Duration time.Duration `json:"duration,omitempty"`
}

type CallOption func(*CallOptions)

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

	// Reasoning is the configuration for thinking of the model.
	Reasoning *ReasoningConfig `json:"reasoning,omitempty"`

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

	// StructuredOutput requests provider-native, schema-constrained output. When
	// set (via WithStructuredOutput) JSONMode is also true and the provider is
	// asked for strict output matching Schema. nil keeps the legacy schema-less
	// JSON mode governed solely by JSONMode.
	StructuredOutput *StructuredOutputConfig `json:"structured_output,omitempty"`

	// 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,omitempty"`

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

	// TTS options.
	Voice          *string  `json:"voice,omitempty"`
	Speed          *float64 `json:"speed,omitempty"`
	ResponseFormat *string  `json:"response_format,omitempty"`

	// WebSearchOptions configures web search behavior for models that support it.
	// Currently supported by OpenAI models like gpt-4o-search-preview.
	WebSearchOptions *WebSearchOptions `json:"web_search_options,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

	// This field is only used with reasoning models and represents the reasoning contents of the assistant message in completion mode.
	// If the model response has tool calls, this field will be nil and the reasoning contents will be dedicated to each tool call.
	Reasoning *reasoning.ContentReasoning
}

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

type ContentResponse struct {
	Choices []*ContentChoice
}

type ErrStructuredOutputConflict struct {
	Provider string
	Detail   string
}

type ErrStructuredOutputUnsupported struct {
	Provider string
	Model    string
	Reason   string
}

type ErrStructuredOutputValidation struct {
	Provider   string
	Model      string
	Choice     int
	StopReason string
	Cause      error
}

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 ReasoningConfig struct {
	// Mode is the authoritative on/off/defer switch. When Mode is ReasoningDefault
	// (the zero value) the state is inferred from Effort/Tokens/Adaptive for
	// backward compatibility. Use WithReasoningDisabled to set ReasoningOff.
	Mode   ReasoningMode   `json:"mode,omitempty"`
	Effort ReasoningEffort `json:"effort"`
	Tokens int             `json:"tokens"`
	// Adaptive expresses a preference for adaptive thinking (thinking.type=adaptive
	// plus output_config.effort instead of a token budget). Effort sets the level;
	// Tokens is ignored. For Claude the wire mechanism is resolved from the model,
	// not this flag: an adaptive-only generation (Opus 4.7/4.8/5, Sonnet 5, Fable 5)
	// always uses adaptive and drops sampling params it rejects, a budget-only
	// generation always uses budget thinking, and this preference is honored on
	// models that support both. Providers without adaptive support fall back to
	// their effort/budget semantics.
	Adaptive bool `json:"adaptive,omitempty"`
}

type ReasoningEffort string

type ReasoningMode int

type ReasoningSupport struct {
	// Supported reports whether the model reasons at all.
	Supported bool
	// Known reports whether this model is explicitly classified. When false, the
	// remaining fields are best-effort and the UI should offer all controls.
	Known bool
	// CannotDisable is set only for models KNOWN to reject disabling
	// (always-on Claude such as Fable 5, and OpenAI o-series). When false,
	// disabling may still fail at the API for an unclassified model.
	CannotDisable bool
	// RejectsSampling is set for models that reject temperature/top_p while thinking.
	RejectsSampling bool
	// Efforts are the effort tiers worth offering; nil when unknown.
	Efforts []ReasoningEffort
	// DefaultOn reports whether thinking runs when reasoning is unset; nil when unknown.
	DefaultOn *bool
}

type StructuredOutputConfig struct {
	Name        string          `json:"name,omitempty"`
	Description string          `json:"description,omitempty"`
	Schema      json.RawMessage `json:"schema"`
}

type SystemChatMessage struct {
	Content string
}

type TextContent struct {
	Text      string                      `json:"text,omitempty"`
	Reasoning *reasoning.ContentReasoning `json:"reasoning,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"`

	// Reasoning is the reasoning content of the tool call used for Anthropic and Google AI providers.
	Reasoning *reasoning.ContentReasoning `json:"reasoning,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,omitempty"`
	// Name is the name of the tool.
	Name string `json:"tool_name,omitempty"`
	// 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"`
}

type UserLocation struct {
	// Type must be "approximate" for user-provided location.
	Type string `json:"type"`

	// Approximate contains the approximate location details.
	Approximate *ApproximateLocation `json:"approximate,omitempty"`
}

type WebSearchOptions struct {
	// SearchContextSize controls how much context is gathered from web search.
	// Valid values: "low", "medium", "high". Higher values provide more context
	// but increase latency and cost.
	SearchContextSize string `json:"search_context_size,omitempty"`

	// UserLocation provides approximate user location for localized search results.
	UserLocation *UserLocation `json:"user_location,omitempty"`
}