llm

type AssetSource string

type BackoffAdvisor interface {
	// AdviseBackoff returns a suggested backoff duration and whether the error is
	// retryable for the given attempt index (0-based). Returning retry=false means
	// the error should not be retried by this advisor.
	AdviseBackoff(err error, attempt int) (delay time.Duration, retry bool)
}

type CallSpan struct {
	StartedAt time.Time `json:"startedat"`
	EndedAt   time.Time `json:"endedat"`
}

type Choice struct {
	// Index is the index of the choice.
	Index int `json:"index"`

	// Message is the generated message.
	Message Message `json:"message"`

	// FinishReason is the reason why the generation stopped.
	FinishReason string `json:"finish_reason,omitempty"`
}

type ContentItem struct {
	Name string `json:"name,omitempty"`

	// Type indicates the type of the content.
	Type ContentType `json:"type"`

	// Source indicates how the asset is provided (url, base64, raw bytes).
	Source AssetSource `json:"source"`

	// Data is the actual content of the asset.
	// - For SourceURL: URL as string.
	// - For SourceBase64: Base64-encoded data.
	// - For SourceRaw: Raw binary data (usually base64 encoded or omitted in JSON).
	Data string `json:"data,omitempty"`

	MimeType string `json:"mimeType,omitempty"`

	// Metadata is optional structured metadata (e.g., for video timestamps, image detail levels).
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// Legacy fields for backward compatibility
	Text string `json:"text,omitempty"`
}

type ContentType string

type Finder interface {
	Find(ctx context.Context, id string) (Model, error)
}

type FunctionCall struct {
	// Name is the name of the function to call.
	Name string `json:"name"`

	// Arguments is a JSON string containing the arguments to pass to the function.
	Arguments string `json:"arguments"`
}

type GenerateRequest struct {
	// Messages is the list of messages in the conversation.
	Messages []Message `json:"messages"`

	// Options contains additional options for the request.
	Options *Options `json:"options,omitempty"`

	// PreviousResponseID optionally links this request to a prior provider
	// response when the backend supports incremental continuation (e.g.,
	// OpenAI Responses API).
	PreviousResponseID string `json:"previous_response_id,omitempty"`
}

type GenerateResponse struct {
	// Choices contains the generated responses.
	Choices []Choice `json:"choices"`

	// Usage contains token usage information.
	Usage *Usage `json:"usage,omitempty"`
	Model string `json:"model,omitempty"`

	// ResponseID is a provider response identifier when available.
	ResponseID string `json:"response_id,omitempty"`
}

type ImageURL struct {
	// URL is the URL of the image.
	URL string `json:"url"`

	// Detail specifies the detail level for image analysis.
	// Options: "auto", "low", "high"
	Detail string `json:"detail,omitempty"`
}

type Matcher interface {
	Best(preferences *ModelPreferences) string
}

type Message struct {
	// Role of the sender (user, assistant, system, etc.)
	Role MessageRole `json:"role"`

	// Name is the optional sender/tool name.
	Name string `json:"name,omitempty"`

	// Items contains multiple, diverse content assets.
	Items []ContentItem `json:"items,omitempty"`

	// ToolCalls represents structured function/tool calls.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// Legacy fields for backward compatibility
	Content      string        `json:"content,omitempty"`
	ToolCallId   string        `json:"tool_call_id,omitempty"`
	ContentItems []ContentItem `json:"content_items,omitempty"`
	FunctionCall *FunctionCall `json:"function_call,omitempty"`
}

type MessageRole string

type Messages []Message

type Model interface {
	Generate(ctx context.Context, request *GenerateRequest) (*GenerateResponse, error)
	Implements(feature string) bool
}

type ModelPreferences struct {
	IntelligencePriority float64  `yaml:"intelligencePriority,omitempty" json:"intelligencePriority,omitempty"`
	SpeedPriority        float64  `yaml:"speedPriority,omitempty" json:"speedPriority,omitempty"`
	CostPriority         float64  `yaml:"costPriority,omitempty" json:"costPriority,omitempty"`
	Hints                []string `yaml:"hints,omitempty" json:"hints,omitempty"`
}

type ModelPreferencesOption func(*ModelPreferences)

type ModelSelection struct {
	Model       string            `yaml:"model,omitempty" json:"model,omitempty"`
	Preferences *ModelPreferences `yaml:"modelPreferences,omitempty" json:"modelPreferences,omitempty"`
	Options     *Options          `yaml:"options,omitempty" json:"options,omitempty"`
}

type Options struct {
	// Model is the model to use.
	Model string `json:"model" yaml:"model"`

	// CandidateCount is the number of response candidates to generate.
	CandidateCount int `json:"candidate_count" yaml:"candidate_count"`

	// MaxTokens is the maximum number of tokens to generate.
	MaxTokens int `json:"max_tokens" yaml:"max_tokens"`

	// Temperature is the temperature for sampling, between 0 and 1.
	Temperature float64 `json:"temperature" yaml:"temperature"`

	// StopWords is a list of words to stop on.
	StopWords []string `json:"stop_words" yaml:"stop_words"`

	// TopK is the number of tokens to consider for top-k sampling.
	TopK int `json:"top_k" yaml:"top_k"`

	// TopP is the cumulative probability for top-p sampling.
	TopP float64 `json:"top_p" yaml:"top_p"`

	// Seed is a seed for deterministic sampling.
	Seed int `json:"seed" yaml:"seed"`

	// MinLength is the minimum length of the generated text.
	MinLength int `json:"min_length" yaml:"min_length"`

	// MaxLength is the maximum length of the generated text.
	MaxLength int `json:"max_length" yaml:"max_length"`

	// N is how many chat completion choices to generate for each input message.
	N int `json:"n" yaml:"n"`

	// RepetitionPenalty is the repetition penalty for sampling.
	RepetitionPenalty float64 `json:"repetition_penalty" yaml:"repetition_penalty"`

	// FrequencyPenalty is the frequency penalty for sampling.
	FrequencyPenalty float64 `json:"frequency_penalty" yaml:"frequency_penalty"`

	// PresencePenalty is the presence penalty for sampling.
	PresencePenalty float64 `json:"presence_penalty" yaml:"presence_penalty"`

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

	// Tools is a list of tools to use. Each tool can be a specific tool or a function.
	Tools []Tool `json:"tools,omitempty" yaml:"tools,omitempty"`

	// ToolChoice is the choice of tool to use: "none", "auto" (default), or a specific tool.
	ToolChoice ToolChoice `json:"tool_choice,omitempty" yaml:"tool_choice,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" yaml:"metadata,omitempty"`

	// ResponseMIMEType MIME type of the generated candidate text.
	// Supported MIME types: text/plain (default), application/json.
	ResponseMIMEType string `json:"response_mime_type,omitempty" yaml:"response_mime_type,omitempty"`

	Thinking *Thinking `json:"thinking,omitempty" yaml:"thinking,omitempty"`
	// Reasoning configures the model's reasoning behavior, e.g. summarization of chain-of-thought.
	Reasoning *Reasoning `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`

	// Stream enables streaming responses.
	Stream bool `json:"stream,omitempty" yaml:"stream,omitempty"`

	Mode string `json:"mode,omitempty" yaml:"mode,omitempty"`

	// ParallelToolCalls requests the provider to execute multiple tool calls
	// in parallel within a single reasoning step, when supported by the model.
	// This is honored by providers that implement base.CanExecToolsInParallel
	// (e.g., OpenAI). Others will ignore it.
	ParallelToolCalls bool `json:"parallel_tool_calls,omitempty" yaml:"parallelToolCalls,omitempty"`

	// ContinuationEnabled explicitly enables/disables provider continuation
	// via previous_response_id for models that support it. When nil, it
	// defaults to enabled if the model supports continuation.
	ContinuationEnabled bool `json:"continuationEnabled,omitempty" yaml:"continuationEnabled,omitempty"`
}

type Reasoning struct {
	// Effort controls provider-native reasoning depth. For OpenAI o-series
	// valid values are: "low" | "medium" | "high".
	Effort  string `json:"effort,omitempty" yaml:"effort,omitempty"`
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
}

type StreamEvent struct {
	Response *GenerateResponse
	Err      error
}

type StreamingModel interface {
	// Stream sends a chat request with streaming enabled and returns a channel of StreamEvent.
	Stream(ctx context.Context, request *GenerateRequest) (<-chan StreamEvent, error)
}

type Thinking struct {
	Type         string `json:"type" yaml:"type"`
	BudgetTokens int    `json:"budget_tokens,omitempty" yaml:"budget_tokens,omitempty"`
}

type Tool struct {
	Ref     string `json:"ref,omitempty" yaml:"ref"`
	Pattern string `json:"pattern,omitempty" yaml:"pattern"`
	// Type is the type of the tool. Currently, only "function" is supported.
	Type string `json:"type" yaml:"type"`

	// Function is the function definition for this tool.
	// This follows the OpenAPI schema specification.
	Definition ToolDefinition `json:"definition" yaml:"definition"`
}

type ToolCall struct {
	// ID is a unique identifier for the tool call.
	ID string `json:"id,omitempty"`

	// Name is the name of the tool to call.
	Name string `json:"name"`

	// Arguments contains the arguments to pass to the tool.
	Arguments map[string]interface{} `json:"arguments"`

	// Legacy fields for backward compatibility
	Type     string       `json:"type,omitempty"`
	Function FunctionCall `json:"function,omitempty"`

	Result string `json:"result,omitempty"`
	//Error tool call error
	Error string `json:"error,omitempty"`
}

type ToolChoice struct {
	// Type is the type of the tool choice. It can be "none", "auto", or "function".
	Type string `json:"type"`

	// Function is the function to call if Type is "function".
	Function *ToolChoiceFunction `json:"function,omitempty"`
}

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

type ToolDefinition struct {
	// Name is the name of the function to be called.
	Name string `json:"name" yaml:"name"`

	// Description is a description of what the function does.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Parameters is a JSON Schema object that defines the input parameters the function accepts.
	// This follows the OpenAPI schema specification.
	Parameters map[string]interface{} `json:"parameters,omitempty" yaml:"parameters,omitempty"`

	// Required is a list of required parameters.
	Required []string `json:"required,omitempty" yaml:"required"`

	OutputSchema map[string]interface{} `json:"output_schema,omitempty" yaml:"output_schema,omitempty"` // Output schema for the function
}

type Usage struct {
	// PromptTokens is the number of tokens used in the prompt.
	PromptTokens int `json:"prompt_tokens"`

	// CompletionTokens is the number of tokens used in the completion.
	CompletionTokens int `json:"completion_tokens"`

	// TotalTokens is the total number of tokens used.
	TotalTokens int `json:"total_tokens"`

	// ContextTokens is the list of token IDs used in the model context (Ollama-specific).
	ContextTokens []int `json:"context_tokens,omitempty"`

	CachedTokens int `json:"cached_tokens,omitempty"`

	ReasoningTokens int `json:"reasoning_tokens,omitempty"`

	AudioTokens int `json:"audio_tokens,omitempty"`

	// Provider-detailed usage (OpenAI-compatible)
	// Prompt-level cached tokens (from prompt_tokens_details.cached_tokens)
	PromptCachedTokens int `json:"prompt_cached_tokens,omitempty"`
	// Prompt-level audio tokens (from prompt_tokens_details.audio_tokens)
	PromptAudioTokens int `json:"prompt_audio_tokens,omitempty"`
	// Completion-level reasoning tokens (from completion_tokens_details.reasoning_tokens)
	CompletionReasoningTokens int `json:"completion_reasoning_tokens,omitempty"`
	// Completion-level audio tokens (from completion_tokens_details.audio_tokens)
	CompletionAudioTokens int `json:"completion_audio_tokens,omitempty"`
	// Speculative decoding accepted/rejected prediction tokens
	AcceptedPredictionTokens int `json:"accepted_prediction_tokens,omitempty"`
	RejectedPredictionTokens int `json:"rejected_prediction_tokens,omitempty"`
}