llm

type APIError struct {
	// Provider is the name of the provider that returned the error.
	Provider string
	// StatusCode is the HTTP status code returned.
	StatusCode int
	// Message is the error message from the API.
	Message string
	// Retryable indicates whether the request can be retried.
	Retryable bool
	// Err is the underlying error, if any.
	Err error
}

type ChatRequest struct {
	// Model is the identifier of the model to use.
	Model string
	// Messages is the conversation history to send to the model.
	Messages []Message
	// Temperature controls randomness in the response (0.0 to 2.0).
	// Lower values make output more deterministic.
	Temperature *float64
	// MaxTokens is the maximum number of tokens to generate.
	MaxTokens *int
	// TopP is the nucleus sampling parameter (0.0 to 1.0).
	TopP *float64
	// Stop is a list of sequences where the model will stop generating.
	Stop []string
	// Thinking enables extended thinking/reasoning mode.
	// Provider-specific handling in each provider implementation.
	Thinking *ThinkingRequest
}

type ChatResponse struct {
	// Content is the generated text content.
	Content string
	// FinishReason indicates why the model stopped generating.
	// Common values: "stop", "length", "content_filter".
	FinishReason string
	// Usage contains token usage statistics.
	Usage Usage
}

type Config struct {
	// APIKey is the authentication key for the provider.
	APIKey string
	// BaseURL is the API endpoint URL. If empty, the provider's default is used.
	BaseURL string
	// Timeout is the maximum time to wait for a response.
	// Default is 60 seconds if not specified.
	Timeout time.Duration

	// Retry configuration
	// MaxRetries is the maximum number of retry attempts for transient errors.
	// Default is 3 if not specified.
	MaxRetries int
	// InitialInterval is the initial backoff interval before the first retry.
	// Default is 1 second if not specified.
	InitialInterval time.Duration
	// MaxInterval is the maximum backoff interval between retries.
	// Default is 30 seconds if not specified.
	MaxInterval time.Duration
	// Multiplier is the factor by which the interval increases after each retry.
	// Default is 2.0 if not specified.
	Multiplier float64
}

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

type Message struct {
	// Role identifies who sent the message (system, user, assistant, or tool).
	Role Role `json:"role"`
	// Content is the text content of the message.
	Content string `json:"content"`
	// Name is an optional identifier for the message sender.
	// Useful in multi-agent scenarios or for tool messages.
	Name string `json:"name,omitempty"`
	// ToolCallID is the ID of the tool call this message is responding to.
	// Required when Role is "tool".
	ToolCallID string `json:"tool_call_id,omitempty"`
}

type Option func(*Config)

type Provider interface {
	// Chat sends messages and returns the complete response.
	Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)

	// ChatStream sends messages and streams the response.
	// Returns a channel that receives StreamEvents until Done is true or an error occurs.
	ChatStream(ctx context.Context, req *ChatRequest) (<-chan StreamEvent, error)

	// Name returns the provider name for logging and error messages.
	Name() string
}

type ProviderFactory func(cfg Config) (Provider, error)

type ProviderType string

type RequestOption func(*ChatRequest)

type Role string

type StreamEvent struct {
	// Delta is the incremental content received in this event.
	Delta string
	// Done indicates whether the stream has completed.
	Done bool
	// Error contains any error that occurred during streaming.
	Error error
	// Usage contains token usage statistics (only set when Done is true).
	Usage *Usage
}

type ThinkingEffort string

type ThinkingRequest struct {
	// Enabled activates thinking mode.
	Enabled bool
	// Effort controls reasoning depth: low, medium, high, xhigh.
	Effort ThinkingEffort
	// BudgetTokens sets explicit token budget (provider-specific).
	BudgetTokens *int
	// IncludeInOutput includes thinking blocks in the response content.
	IncludeInOutput bool
}

type Usage struct {
	// PromptTokens is the number of tokens in the prompt.
	PromptTokens int `json:"prompt_tokens"`
	// CompletionTokens is the number of tokens in the completion.
	CompletionTokens int `json:"completion_tokens"`
	// TotalTokens is the sum of prompt and completion tokens.
	TotalTokens int `json:"total_tokens"`
}