llm

type ChatRequest struct {
	// ModelID is the specific model to use.
	ModelID string
	// Messages is the conversation history.
	Messages []Message
	// MaxTokens is the maximum number of tokens to generate.
	MaxTokens int
	// Temperature controls randomness in generation (0-2).
	Temperature float32
	// TopP controls diversity of generation (0-1).
	TopP float32
	// ResponseFormat specifies the format of the response.
	ResponseFormat *ResponseFormat
	// Tools is a list of tools the model can call.
	Tools []Tool
	// ToolChoice controls how the model uses tools.
	ToolChoice *ToolChoice
	// Stream indicates if responses should be streamed.
	Stream bool
}

type ChatResponse struct {
	// ID uniquely identifies this response.
	ID string
	// Message contains the assistant's response message.
	Message Message
	// Usage contains token usage information.
	Usage *TokenUsage
	// FinishReason indicates why the generation stopped.
	FinishReason FinishReason `json:"finish_reason,omitempty"`
}

type ChatResponseChunk struct {
	// ID uniquely identifies the response this chunk belongs to.
	ID string
	// Delta contains the new content in this chunk.
	Delta ChunkDelta
	// Finished indicates if this is the final chunk in the stream.
	Finished bool
	// FinishReason indicates why the generation stopped, if this chunk is the last one
	// and the reason is available.
	FinishReason FinishReason `json:"finish_reason,omitempty"`
}

type ChatResponseStream interface {
	// Next returns the next chunk in the stream.
	Next() (*ChatResponseChunk, error)
	// Close closes the stream.
	Close() error
	// Err returns any error that occurred during streaming, other than io.EOF.
	// This should be checked after Next() returns io.EOF.
	Err() error
}

type ChunkDelta struct {
	// Content is the new content in this delta, if any.
	Content string
	// Role is the role of the message, usually only in the first chunk.
	Role Role
	// ToolCalls contains any tool calls in this delta.
	ToolCalls []ToolCall
	// ToolCallID is the ID of the tool call this message is responding to.
	ToolCallID string
	// Usage contains token usage information for this chunk.
	// Note: This may only be populated in the final chunk of a stream.
	Usage *TokenUsage
}

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

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

type FinishReason string

type Function struct {
	// Name is the name of the function.
	Name string `json:"name"`
	// Description is a human-readable description of the function.
	Description string `json:"description,omitempty"`
	// Parameters represents the function's parameters in JSON schema format.
	Parameters map[string]any `json:"parameters,omitempty"`
}

type ImageContent struct {
	URL string `json:"url"`
}

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

type Message struct {
	// Role is who sent this message (user, assistant, system, etc).
	Role Role `json:"role"`
	// Content is the content of the message, which can be either a string
	// for simple text messages or a slice of MessageContent for multi-modal content.
	Content any `json:"content"`
	// Name is an optional identifier for the sender, used in some providers.
	Name string `json:"name,omitempty"`
	// ToolCalls contains any tool calls made by the assistant in this message.
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	// ToolCallID is the ID of the tool call this message is responding to.
	ToolCallID string `json:"tool_call_id,omitempty"`
}

type MessageContent interface {
	MessageContentType() string
}

type Model struct {
	// ID is the unique identifier for this model within its provider.
	ID string
	// Name is a human-readable name for the model.
	Name string
	// Provider is the provider ID this model belongs to.
	Provider string
	// Capabilities describe what the model can do.
	Capabilities ModelCapabilities
}

type ModelCapabilities struct {
	// SupportsStreaming indicates if the model can stream responses.
	SupportsStreaming bool
	// SupportsJSON indicates if the model supports JSON mode responses.
	SupportsJSON bool
	// SupportsFunctions indicates if the model supports function calling.
	SupportsFunctions bool
	// SupportsVision indicates if the model supports analyzing images.
	SupportsVision bool
}

type ProviderClient interface {
	// ID returns the unique identifier for this provider.
	ID() string
	// Name returns a human-readable name for this provider.
	Name() string
	// ListModels returns all available models from this provider.
	ListModels(ctx context.Context) ([]Model, error)
	// GetModel returns information for a specific model.
	GetModel(ctx context.Context, modelID string) (*Model, error)
	// Chat sends a chat completion request to the provider.
	Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)
	// ChatStream sends a streaming chat completion request.
	ChatStream(ctx context.Context, req ChatRequest) (ChatResponseStream, error)
}

type ResponseFormat struct {
	// Type is the response format type, e.g., "json_object".
	Type string `json:"type"`
}

type Role string

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

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

type TokenUsage struct {
	// PromptTokens is the number of tokens in the prompt.
	PromptTokens int
	// CompletionTokens is the number of tokens in the completion.
	CompletionTokens int
	// TotalTokens is the total number of tokens used.
	TotalTokens int
}

type Tool struct {
	// Type is the type of the tool.
	Type string `json:"type"`
	// Function is the function definition if Type is "function".
	Function Function `json:"function"`
}

type ToolCall struct {
	// ID uniquely identifies this tool call.
	ID string `json:"id"`
	// Type is the type of tool being called.
	Type string `json:"type"`
	// Function contains details about the function call if Type is "function".
	Function ToolCallFunction `json:"function"`
}

type ToolCallFunction struct {
	// Name is the name of the function to call.
	Name string `json:"name"`
	// Arguments is a JSON string containing the function arguments.
	Arguments string `json:"arguments"`
	// IsComplete indicates if the arguments field contains complete valid JSON.
	// This is particularly important during streaming where arguments may come in fragments.
	IsComplete bool `json:"-"`
}

type ToolChoice struct {
	// Type is the tool choice type ("none", "auto", or "function").
	Type string `json:"type"`
	// Function is required if Type is "function".
	Function *ToolChoiceFunction `json:"function,omitempty"`
}

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

type ToolExecutor interface {
	// Execute executes a tool call and returns the result
	Execute(toolCall ToolCall) (string, error)
}

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

type ToolRegistryOption func(*ToolRegistry)

type ToolResult struct {
	// ID is the unique identifier of the tool call this result corresponds to.
	ID string `json:"id"`

	// ToolName is the name of the tool that was called.
	// While the LLM knows this from the original ToolCall, including it can be useful for logging and consistency.
	ToolName string `json:"tool_name"`

	// Content is the result of the tool's execution, typically a string (e.g., JSON output).
	Content string `json:"content"`

	// IsError indicates whether the tool execution resulted in an error.
	// If true, Content might contain an error message or a serialized error object.
	IsError bool `json:"is_error,omitempty"`
}