ai

type APIClient interface {
	// ClientType returns the API client type identifier.
	// Examples: "openai-completions", "anthropic-messages", "google-genai".
	ClientType() string

	// Stream starts a streaming LLM call.
	// The endpoint provides base URL and resolved API key.
	// The model provides model-specific config (ID, compat flags, etc.).
	Stream(ctx context.Context, endpoint ProviderEndpoint, model Model,
		llmCtx Context, opts StreamOptions) *EventStream

	// StreamSimple is the high-level API that maps ThinkingLevel to
	// provider-specific params.
	StreamSimple(ctx context.Context, endpoint ProviderEndpoint, model Model,
		llmCtx Context, opts SimpleStreamOptions) *EventStream
}

type AssistantMessage struct {
	Content      []ContentBlock // TextContent | ThinkingContent | ToolCall
	API          string
	Provider     string
	Model        string
	Usage        Usage
	StopReason   StopReason
	ErrorMessage string
	Timestamp    int64
}

type AssistantMessageEvent struct {
	Type         EventType
	ContentIndex int
	Delta        string
	Content      string
	ToolCall     *ToolCall
	Partial      *AssistantMessage
	Message      *AssistantMessage
	Error        *AssistantMessage
	Reason       StopReason
}

type CacheRetention string

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

type ContentType string

type Context struct {
	SystemPrompt string
	Messages     []Message
	Tools        []Tool
}

type CustomModelOpts struct {
	Name          string
	Reasoning     bool
	Input         []string
	Cost          ModelCost
	PricingKnown  bool // false by default; set to true if pricing is known
	ContextWindow int
	MaxTokens     int
	Compat        *ModelCompat
}

type CustomProviderConfig struct {
	ProviderConfig

	// APIKey is a directly-provided API key. If set, takes precedence
	// over KeyEnvVars during resolution.
	APIKey string
}

type EmbedFunc func(ctx context.Context, endpoint ProviderEndpoint, model EmbeddingModel, req EmbeddingRequest) (*EmbeddingResponse, error)

type Embedding struct {
	Index  int
	Values []float32
	Raw    any
}

type EmbeddingAPIClient interface {
	// ClientType returns the embedding API client type identifier.
	// Examples: "openai-embeddings", "google-embeddings", "cohere-embeddings".
	ClientType() string

	// Embed generates embeddings for the given texts.
	Embed(ctx context.Context, endpoint ProviderEndpoint, model EmbeddingModel,
		req EmbeddingRequest) (*EmbeddingResponse, error)
}

type EmbeddingCost struct {
	PerMTok float64 `json:"perMTok"`
}

type EmbeddingEncoding string

type EmbeddingModel struct {
	ID               string              `json:"id"`
	Name             string              `json:"name"`
	API              string              `json:"api"`
	Provider         string              `json:"provider"`
	MaxInputTokens   int                 `json:"maxInputTokens"`
	DefaultDims      int                 `json:"defaultDims"`
	MaxDims          int                 `json:"maxDims,omitempty"`
	MinDims          int                 `json:"minDims,omitempty"`
	MaxBatchSize     int                 `json:"maxBatchSize"`
	SupportsDimCtrl  bool                `json:"supportsDimCtrl"`
	SupportsTaskType bool                `json:"supportsTaskType"`
	Headers          map[string][]string `json:"headers,omitempty"`
	Cost             EmbeddingCost       `json:"cost"`
	PricingKnown     bool                `json:"pricingKnown"`
}

type EmbeddingRequest struct {
	Texts      []string
	TaskType   EmbeddingTaskType
	Dimensions int
	Encoding   EmbeddingEncoding
	OnProgress func(completed, total int)
}

type EmbeddingResponse struct {
	Embeddings []Embedding
	Model      string
	Usage      EmbeddingUsage
}

type EmbeddingTaskType string

type EmbeddingUsage struct {
	Tokens int
	Cost   float64
}

type EventStream struct {
	C <-chan AssistantMessageEvent
	// contains filtered or unexported fields
}

type EventType string

type ImageContent struct {
	Data     string // base64 encoded
	MimeType string // e.g. image/jpeg
}

type Message interface {
	GetTimestamp() int64
	// contains filtered or unexported methods
}

type Model struct {
	ID            string              `json:"id"`
	Name          string              `json:"name"`
	API           string              `json:"api"`
	Provider      string              `json:"provider"`
	Reasoning     bool                `json:"reasoning"`
	Input         []string            `json:"input"`
	Cost          ModelCost           `json:"cost"`
	PricingKnown  bool                `json:"pricingKnown"`
	ContextWindow int                 `json:"contextWindow"`
	MaxTokens     int                 `json:"maxTokens"`
	Headers       map[string][]string `json:"headers,omitempty"`
	Compat        *ModelCompat        `json:"compat,omitempty"`
}

type ModelCompat struct {
	SupportsStore                    *bool             `json:"supportsStore,omitempty"`
	SupportsDeveloperRole            *bool             `json:"supportsDeveloperRole,omitempty"`
	SupportsReasoningEffort          *bool             `json:"supportsReasoningEffort,omitempty"`
	ReasoningEffortMap               map[string]string `json:"reasoningEffortMap,omitempty"`
	SupportsUsageInStreaming         *bool             `json:"supportsUsageInStreaming,omitempty"`
	MaxTokensField                   string            `json:"maxTokensField,omitempty"`
	RequiresToolResultName           *bool             `json:"requiresToolResultName,omitempty"`
	RequiresAssistantAfterToolResult *bool             `json:"requiresAssistantAfterToolResult,omitempty"`
	RequiresThinkingAsText           *bool             `json:"requiresThinkingAsText,omitempty"`
	RequiresMistralToolIDs           *bool             `json:"requiresMistralToolIds,omitempty"`
	ThinkingFormat                   string            `json:"thinkingFormat,omitempty"`
	SupportsStrictMode               *bool             `json:"supportsStrictMode,omitempty"`
}

type ModelCost struct {
	Input      float64 `json:"input"`
	Output     float64 `json:"output"`
	CacheRead  float64 `json:"cacheRead"`
	CacheWrite float64 `json:"cacheWrite"`
}

type ProviderConfig struct {
	// Name is the unique provider identifier.
	// Examples: "openai", "anthropic", "openrouter".
	Name string `json:"name"`

	// APIClientType is the protocol to use for chat completions with this provider.
	// Must match a registered APIClient's ClientType() return value.
	// Examples: "openai-completions", "anthropic-messages", "google-genai".
	// Note: embedding models use a separate client type -- see EmbeddingAPIClientType.
	APIClientType string `json:"apiClientType"`

	// EmbeddingAPIClientType is the protocol to use for embeddings with this provider.
	// Must match a registered EmbeddingAPIClient's ClientType() return value.
	// Optional: only needed if this provider offers embedding models.
	EmbeddingAPIClientType string `json:"embeddingApiClientType,omitempty"`

	// BaseURL is the base URL for the API endpoint.
	// Examples: "https://api.openai.com/v1", "https://openrouter.ai/api/v1".
	BaseURL string `json:"baseUrl"`

	// KeyEnvVars is the ordered list of environment variable names to check
	// for the API key. The first non-empty value wins.
	KeyEnvVars []string `json:"keyEnvVars,omitempty"`

	// Headers are extra HTTP headers sent with every request to this provider.
	// Multi-valued headers use multiple values in the slice.
	Headers map[string][]string `json:"headers,omitempty"`

	// ProviderSpecific holds provider-level config that API client
	// implementations may need. Examples: Anthropic API version,
	// Google API version path segment.
	ProviderSpecific map[string]string `json:"providerSpecific,omitempty"`
}

type ProviderEndpoint struct {
	// ProviderName is the provider identifier (for error messages, telemetry).
	ProviderName string

	// BaseURL is the resolved base URL.
	BaseURL string

	// APIKey is the resolved API key (from env var or StreamOptions override).
	// May be empty if the provider doesn't require authentication (e.g., local).
	APIKey string

	// Headers are merged provider-level + call-level headers.
	Headers map[string][]string

	// ProviderSpecific passes through from ProviderConfig.
	ProviderSpecific map[string]string
}

type ProviderError struct {
	Code       ProviderErrorCode
	Message    string
	StatusCode int
	Provider   string
	RetryAfter time.Duration
}

type ProviderErrorCode string

type Role string

type SimpleStreamOptions struct {
	StreamOptions
	Reasoning       ThinkingLevel
	ThinkingBudgets *ThinkingBudgets
}

type StopReason string

type StreamOptions struct {
	Temperature     *float64
	TopP            *float64
	TopK            *int
	MaxTokens       *int
	APIKey          string
	SessionID       string
	CacheRetention  CacheRetention
	Headers         map[string][]string
	MaxRetryDelayMs int
	Metadata        map[string]any
	OnPayload       func(payload any)
}

type TextContent struct {
	Text          string
	TextSignature string // optional, provider-specific
}

type ThinkingBudgets struct {
	Minimal *int
	Low     *int
	Medium  *int
	High    *int
}

type ThinkingContent struct {
	Thinking          string
	ThinkingSignature string // optional, provider-specific
	Redacted          bool   // true if redacted by safety filters
}

type ThinkingLevel string

type Tool struct {
	Name        string
	Description string
	Parameters  json.RawMessage // JSON Schema object
}

type ToolCall struct {
	ID               string
	Name             string
	Arguments        map[string]any
	ThoughtSignature string // optional, Google-specific
}

type ToolCallIDNormalizer func(id string, model Model, source *AssistantMessage) string

type ToolResultMessage struct {
	ToolCallID string
	ToolName   string
	Content    []ContentBlock // TextContent | ImageContent
	IsError    bool
	Timestamp  int64
}

type Usage struct {
	Input       int
	Output      int
	CacheRead   int
	CacheWrite  int
	TotalTokens int
	Cost        UsageCost
}

type UsageCost struct {
	Input      float64
	Output     float64
	CacheRead  float64
	CacheWrite float64
	Total      float64
}

type UserMessage struct {
	Content   []ContentBlock // TextContent | ImageContent
	Timestamp int64          // Unix milliseconds
}