core

type APIEndpoint string

type BatchError struct {
	// Code is the error code (e.g., "rate_limit_exceeded").
	Code string `json:"code"`
	// Message is a human-readable error description.
	Message string `json:"message"`
}

type BatchID string

type BatchInfo struct {
	// ID is the unique identifier for this batch.
	ID BatchID `json:"id"`
	// Status is the current processing state.
	Status BatchStatus `json:"status"`
	// Total is the total number of requests in the batch.
	Total int `json:"total"`
	// Completed is the number of successfully completed requests.
	Completed int `json:"completed"`
	// Failed is the number of failed requests.
	Failed int `json:"failed"`
	// CreatedAt is when the batch was created.
	CreatedAt int64 `json:"created_at"`
	// CompletedAt is when the batch finished (nil if still processing).
	CompletedAt *int64 `json:"completed_at,omitempty"`
	// ExpiresAt is when the batch will expire if not completed.
	ExpiresAt *int64 `json:"expires_at,omitempty"`
	// Endpoint is the API endpoint used for this batch.
	Endpoint string `json:"endpoint,omitempty"`
	// ErrorFileID contains error details if the batch failed.
	ErrorFileID string `json:"error_file_id,omitempty"`
	// OutputFileID contains results when the batch completes.
	OutputFileID string `json:"output_file_id,omitempty"`
}

type BatchProvider interface {
	// CreateBatch submits requests for asynchronous batch processing.
	// Returns a BatchID that can be used to track progress and retrieve results.
	// Each request's CustomID must be unique within the batch.
	CreateBatch(ctx context.Context, requests []BatchRequest) (BatchID, error)

	// GetBatchStatus returns the current status of a batch.
	// Poll this method to check if the batch has completed processing.
	GetBatchStatus(ctx context.Context, id BatchID) (*BatchInfo, error)

	// GetBatchResults retrieves completed batch results.
	// Should only be called after GetBatchStatus indicates completion.
	// Returns results for all requests, including failures.
	GetBatchResults(ctx context.Context, id BatchID) ([]BatchResult, error)

	// CancelBatch cancels a pending or in-progress batch.
	// Already completed requests may still return results.
	CancelBatch(ctx context.Context, id BatchID) error

	// ListBatches returns all batches for the account.
	// Use limit to control pagination (0 for default).
	ListBatches(ctx context.Context, limit int) ([]BatchInfo, error)
}

type BatchRequest struct {
	// CustomID is a user-provided identifier for correlating results.
	// Must be unique within a batch and 64 characters or fewer.
	CustomID string `json:"custom_id"`
	// Request is the chat request to process.
	Request ChatRequest `json:"request"`
}

type BatchResult struct {
	// CustomID is the user-provided identifier from the request.
	CustomID string `json:"custom_id"`
	// Response is the chat response (nil if request failed).
	Response *ChatResponse `json:"response,omitempty"`
	// Error contains error details if the request failed.
	Error *BatchError `json:"error,omitempty"`
}

type BatchStatus string

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

type BuiltInTool struct {
	Type string `json:"type"` // "web_search", "file_search", "code_interpreter"
}

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

type ChatChunk struct {
	Delta string `json:"delta"`
}

type ChatRequest struct {
	Model       ModelID   `json:"model"`
	Messages    []Message `json:"messages"`
	Temperature *float32  `json:"temperature,omitempty"`
	MaxTokens   *int      `json:"max_tokens,omitempty"`
	Tools       []Tool    `json:"-"` // Tools are handled separately by providers

	// Structured output fields
	ResponseFormat ResponseFormat        `json:"response_format,omitempty"`
	JSONSchema     *JSONSchemaDefinition `json:"json_schema,omitempty"`

	// Responses API fields (ignored for Chat Completions API)
	Instructions       string          `json:"instructions,omitempty"`
	ReasoningEffort    ReasoningEffort `json:"reasoning_effort,omitempty"`
	BuiltInTools       []BuiltInTool   `json:"builtin_tools,omitempty"`
	PreviousResponseID string          `json:"previous_response_id,omitempty"`
	Truncation         string          `json:"truncation,omitempty"`
	ToolResources      *ToolResources  `json:"tool_resources,omitempty"`

	// Web-search grounding options for providers that support
	// FeatureWebSearch (currently Perplexity). Requests carrying search
	// options against a provider without the capability are rejected by the
	// builder with ErrSearchUnsupported before any HTTP call is made.
	SearchOptions *SearchOptions `json:"search_options,omitempty"`
}

type ChatResponse struct {
	ID        string     `json:"id"`
	Model     ModelID    `json:"model"`
	Output    string     `json:"output"`
	Usage     TokenUsage `json:"usage"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`

	// Citations contains the source URLs consulted by search-grounded
	// providers (currently Perplexity). Empty for providers without search.
	Citations []string `json:"citations,omitempty"`

	// Responses API fields
	Reasoning *ReasoningOutput `json:"reasoning,omitempty"`
	Status    string           `json:"status,omitempty"`
}

type ChatStream struct {
	// Ch emits text deltas in order. Closed when stream ends.
	Ch <-chan ChatChunk

	// Err emits at most one error. MUST be closed when stream ends.
	// If error occurs after setup, send on Err then close all channels.
	Err <-chan error

	// Final sent exactly once (or zero if setup fails) after stream completion.
	// Includes usage and tool calls if available.
	// Providers may send partial ChatResponse with Output empty.
	Final <-chan *ChatResponse
}

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

type ClientOption func(*Client)

type ContentPart interface {
	// ContentType returns the type identifier for this content part.
	ContentType() string
}

type ContentPartSupporter interface {
	SupportsContentPart(model ModelID, role Role, part ContentPart) bool
}

type ContextualTelemetryHook interface {
	TelemetryHook

	// OnRequestStartWithContext is called when a request to a provider begins.
	// Returns a new context that should be used for the request.
	// The returned context may contain span information for propagation.
	OnRequestStartWithContext(ctx context.Context, e RequestStartEvent) context.Context

	// OnRequestEndWithContext is called when a request to a provider completes.
	OnRequestEndWithContext(ctx context.Context, e RequestEndEvent)
}

type ContextualizedEmbeddingProvider interface {
	// CreateContextualizedEmbeddings generates context-aware embeddings for document chunks.
	// Each inner slice in Inputs represents chunks from a single document.
	CreateContextualizedEmbeddings(ctx context.Context, req *ContextualizedEmbeddingRequest) (*ContextualizedEmbeddingResponse, error)
}

type ContextualizedEmbeddingRequest struct {
	// Model specifies the embedding model to use.
	Model ModelID `json:"model"`

	// Inputs is a list of documents, where each document is a list of chunks.
	// Chunks within the same document are encoded with awareness of each other.
	Inputs [][]string `json:"inputs"`

	// InputType specifies whether inputs are queries or documents.
	InputType InputType `json:"input_type,omitempty"`

	// OutputDimension specifies the number of dimensions for output embeddings.
	OutputDimension *int `json:"output_dimension,omitempty"`

	// OutputDType specifies the data type for embeddings (float, int8, etc.).
	OutputDType OutputDType `json:"output_dtype,omitempty"`

	// EncodingFormat specifies the encoding format (float array or base64).
	EncodingFormat EncodingFormat `json:"encoding_format,omitempty"`
}

type ContextualizedEmbeddingResponse struct {
	// Embeddings contains the vectors grouped by document, then by chunk.
	// embeddings[i][j] is the embedding for chunk j of document i.
	Embeddings [][]EmbeddingVector `json:"embeddings"`

	// Model is the model that generated the embeddings.
	Model ModelID `json:"model"`

	// Usage contains token consumption information.
	Usage EmbeddingUsage `json:"usage"`
}

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

type ConversationOption func(*Conversation)

type EmbeddingInput struct {
	Text     string            `json:"text"`
	ID       string            `json:"id,omitempty"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

type EmbeddingProvider interface {
	// CreateEmbeddings generates embeddings for the given input texts.
	CreateEmbeddings(ctx context.Context, req *EmbeddingRequest) (*EmbeddingResponse, error)
}

type EmbeddingRequest struct {
	Model          ModelID          `json:"model"`
	Input          []EmbeddingInput `json:"input"`
	EncodingFormat EncodingFormat   `json:"encoding_format,omitempty"`
	Dimensions     *int             `json:"dimensions,omitempty"`
	User           string           `json:"user,omitempty"`
	InputType      InputType        `json:"input_type,omitempty"`
	OutputDType    OutputDType      `json:"output_dtype,omitempty"`
	Truncation     *bool            `json:"truncation,omitempty"`
}

type EmbeddingResponse struct {
	Vectors []EmbeddingVector `json:"vectors"`
	Model   ModelID           `json:"model"`
	Usage   EmbeddingUsage    `json:"usage"`
}

type EmbeddingUsage struct {
	PromptTokens int `json:"prompt_tokens"`
	TotalTokens  int `json:"total_tokens"`
}

type EmbeddingVector struct {
	Index     int               `json:"index"`
	ID        string            `json:"id,omitempty"`
	Vector    []float32         `json:"vector,omitempty"`
	VectorB64 string            `json:"vector_b64,omitempty"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

type EncodingFormat string

type Feature string

type FileSearchResources struct {
	VectorStoreIDs []string `json:"vector_store_ids"`
}

type ImageAction string

type ImageBackground string

type ImageChunk struct {
	PartialImageIndex int    `json:"partial_image_index"`
	B64JSON           string `json:"b64_json"`
}

type ImageData struct {
	B64JSON       string `json:"b64_json,omitempty"`
	URL           string `json:"url,omitempty"`
	RevisedPrompt string `json:"revised_prompt,omitempty"`
}

type ImageDetail string

type ImageEditRequest struct {
	Model  ModelID `json:"model"`
	Prompt string  `json:"prompt"`

	// Image inputs - at least one required
	Images []ImageInput `json:"-"` // Handled separately for multipart

	// Optional mask for inpainting
	Mask *ImageInput `json:"-"`

	// Optional parameters
	N             int                `json:"n,omitempty"`
	Size          ImageSize          `json:"size,omitempty"`
	Quality       ImageQuality       `json:"quality,omitempty"`
	Format        ImageFormat        `json:"output_format,omitempty"`
	Compression   *int               `json:"output_compression,omitempty"`
	Background    ImageBackground    `json:"background,omitempty"`
	InputFidelity ImageInputFidelity `json:"input_fidelity,omitempty"`
	User          string             `json:"user,omitempty"`
}

type ImageFormat string

type ImageGenerateRequest struct {
	Model  ModelID `json:"model"`
	Prompt string  `json:"prompt"`

	// Optional parameters
	N              int             `json:"n,omitempty"`                  // Number of images to generate (default 1)
	Size           ImageSize       `json:"size,omitempty"`               // Image dimensions
	Quality        ImageQuality    `json:"quality,omitempty"`            // Rendering quality
	Format         ImageFormat     `json:"output_format,omitempty"`      // Output format
	Compression    *int            `json:"output_compression,omitempty"` // 0-100 for jpeg/webp
	Background     ImageBackground `json:"background,omitempty"`         // Transparency setting
	Moderation     string          `json:"moderation,omitempty"`         // "auto" or "low"
	User           string          `json:"user,omitempty"`               // User identifier
	ResponseFormat string          `json:"response_format,omitempty"`    // "b64_json" or "url"
	PartialImages  int             `json:"partial_images,omitempty"`     // For streaming (0-3)
}

type ImageGenerator interface {
	// GenerateImage generates images from a text prompt.
	GenerateImage(ctx context.Context, req *ImageGenerateRequest) (*ImageResponse, error)

	// EditImage edits existing images using a prompt and optional mask.
	EditImage(ctx context.Context, req *ImageEditRequest) (*ImageResponse, error)

	// StreamImage generates images with streaming partial results.
	// Not all providers support streaming.
	StreamImage(ctx context.Context, req *ImageGenerateRequest) (*ImageStream, error)
}

type ImageInput struct {
	// One of these must be set
	Data     []byte // Raw image bytes
	Base64   string // Base64-encoded image
	URL      string // URL to fetch image from (Responses API only)
	FileID   string // File ID from Files API (Responses API only)
	Filename string // Optional filename hint
}

type ImageInputFidelity string

type ImageQuality string

type ImageResponse struct {
	Created int64       `json:"created"`
	Data    []ImageData `json:"data"`
	Usage   *ImageUsage `json:"usage,omitempty"`
}

type ImageSize string

type ImageStream struct {
	Ch    <-chan ImageChunk     // Partial images
	Err   <-chan error          // At most one error
	Final <-chan *ImageResponse // Complete response
}

type ImageUsage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	TotalTokens  int `json:"total_tokens"`
}

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

type InputFile struct {
	// FileID is a file ID from the Files API.
	FileID string
	// FileURL is an HTTPS URL to the file.
	FileURL string
	// FileData contains base64-encoded file bytes.
	FileData string
	// Filename is the recommended filename when using FileData.
	Filename string
}

type InputImage struct {
	// ImageURL is an HTTPS URL or data URL (data:image/jpeg;base64,...).
	ImageURL string
	// FileID is a file ID from the Files API.
	FileID string
	// Detail specifies the level of detail for image processing.
	Detail ImageDetail
}

type InputText struct {
	// Text is the text content.
	Text string
}

type InputType string

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

type JSONSchemaDefinition struct {
	// Name is a required identifier for the schema (used by some providers).
	Name string `json:"name"`
	// Description explains what the schema represents (optional).
	Description string `json:"description,omitempty"`
	// Schema is the JSON Schema definition.
	Schema json.RawMessage `json:"schema"`
	// Strict enables strict schema validation (recommended).
	// When true, the model will always output valid JSON matching the schema.
	// The tag omits omitempty so an explicit false is still marshaled.
	Strict bool `json:"strict"`
}

type Memory interface {
	// AddMessage appends a message to the conversation history.
	AddMessage(ctx context.Context, msg Message)

	// AddMessages appends multiple messages to the conversation history.
	AddMessages(ctx context.Context, msgs []Message)

	// GetHistory returns all messages in the conversation.
	GetHistory(ctx context.Context) []Message

	// GetLastN returns the last N messages in the conversation.
	GetLastN(ctx context.Context, n int) []Message

	// Clear removes all messages from the conversation.
	Clear(ctx context.Context)

	// Len returns the number of messages in the conversation.
	Len(ctx context.Context) int

	// SetMessages replaces the entire conversation history.
	SetMessages(ctx context.Context, msgs []Message)
}

type Message struct {
	Role        Role          `json:"role"`
	Content     string        `json:"content,omitempty"`
	Parts       []ContentPart `json:"-"`                      // Provider-mapped multimodal content parts
	ToolCalls   []ToolCall    `json:"tool_calls,omitempty"`   // For assistant messages requesting tools
	ToolResults []ToolResult  `json:"tool_results,omitempty"` // For tool result messages (RoleTool)
}

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

type ModelID string

type ModelInfo struct {
	ID           ModelID     `json:"id"`
	DisplayName  string      `json:"display_name"`
	Capabilities []Feature   `json:"capabilities"`
	APIEndpoint  APIEndpoint `json:"api_endpoint,omitempty"` // defaults to completions
}

type NoopTelemetryHook struct{}

type OutputDType string

type Provider interface {
	// ID returns the provider identifier (e.g., "openai", "anthropic").
	ID() string

	// Models returns the list of models available from this provider.
	Models() []ModelInfo

	// Supports reports whether the provider supports the given feature.
	Supports(feature Feature) bool

	// Chat sends a non-streaming chat request.
	Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)

	// StreamChat sends a streaming chat request.
	StreamChat(ctx context.Context, req *ChatRequest) (*ChatStream, error)
}

type ProviderError struct {
	Provider   string
	Status     int
	RequestID  string
	Code       string
	Message    string
	Body       string        // raw response body (truncated); preserved when Message lacks detail
	RetryAfter time.Duration // server-advised minimum delay before retrying
	Err        error
}

type ProviderUnwrapper interface {
	Unwrap() Provider
}

type RateLimiter interface {
	Wait(ctx context.Context) error
}

type RateLimiterFunc func(context.Context) error

type ReasoningEffort string

type ReasoningOutput struct {
	ID      string   `json:"id"`
	Summary []string `json:"summary,omitempty"`
}

type RequestEndEvent struct {
	Provider string     // Provider identifier
	Model    ModelID    // Model that was called
	Start    time.Time  // When the request started
	End      time.Time  // When the request completed
	Usage    TokenUsage // Token consumption
	Err      error      // Error if request failed, nil on success
}

type RequestStartEvent struct {
	Provider string    // Provider identifier (e.g., "openai", "anthropic")
	Model    ModelID   // Model being called
	Start    time.Time // When the request started
}

type RerankRequest struct {
	// Model specifies the reranker model to use.
	Model ModelID `json:"model"`

	// Query is the search query to rank documents against.
	Query string `json:"query"`

	// Documents is the list of documents to rerank.
	Documents []string `json:"documents"`

	// TopK limits the number of results to return. If nil, returns all.
	TopK *int `json:"top_k,omitempty"`

	// ReturnDocuments includes document text in the response if true.
	ReturnDocuments bool `json:"return_documents,omitempty"`

	// Truncation controls whether to truncate inputs exceeding context length.
	// Defaults to true.
	Truncation *bool `json:"truncation,omitempty"`
}

type RerankResponse struct {
	// Results contains the reranked documents sorted by descending relevance.
	Results []RerankResult `json:"results"`

	// Model is the model that performed the reranking.
	Model ModelID `json:"model"`

	// Usage contains token consumption information.
	Usage RerankUsage `json:"usage"`
}

type RerankResult struct {
	// Index is the original position in the input documents slice.
	Index int `json:"index"`

	// RelevanceScore is the relevance score (higher is more relevant).
	RelevanceScore float64 `json:"relevance_score"`

	// Document contains the document text if ReturnDocuments was true.
	Document string `json:"document,omitempty"`
}

type RerankUsage struct {
	// TotalTokens is the total number of tokens used.
	TotalTokens int `json:"total_tokens"`
}

type RerankerProvider interface {
	// Rerank scores and sorts documents by relevance to the query.
	// Results are returned in descending order of relevance.
	Rerank(ctx context.Context, req *RerankRequest) (*RerankResponse, error)
}

type ResponseFormat string

type RetryConfig struct {
	MaxRetries int           // Maximum number of retry attempts (default: 3)
	BaseDelay  time.Duration // Initial delay before first retry (default: 1s)
	MaxDelay   time.Duration // Maximum delay cap (default: 30s)
	Jitter     float64       // Jitter factor 0.0-1.0 (default: 0.2)
}

type RetryPolicy interface {
	// NextDelay returns the delay before the next retry attempt and whether to retry.
	// If ok is false, no more retries should be attempted.
	// attempt starts at 0 for the first retry after the initial failure.
	// The default policy retries only errors explicitly classified as transient;
	// custom policies may opt into retrying additional error types.
	NextDelay(attempt int, err error) (delay time.Duration, ok bool)
}

type Role string

type SearchMode string

type SearchOptions struct {
	// SearchDomainFilter restricts results to the listed domains. A domain
	// prefixed with "-" is excluded instead of included (e.g. "-example.com").
	SearchDomainFilter []string `json:"search_domain_filter,omitempty"`

	// Recency limits results by freshness (hour, day, week, month, year).
	Recency SearchRecencyFilter `json:"search_recency_filter,omitempty"`

	// Mode selects the search corpus: web (default), academic, or sec.
	Mode SearchMode `json:"search_mode,omitempty"`
}

type SearchRecencyFilter string

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

type TelemetryHook interface {
	// OnRequestStart is called when a request to a provider begins.
	OnRequestStart(e RequestStartEvent)

	// OnRequestEnd is called when a request to a provider completes.
	OnRequestEnd(e RequestEndEvent)
}

type TokenCountResponse struct {
	InputTokens int `json:"input_tokens"`
}

type TokenCounter interface {
	CountTokens(ctx context.Context, req *ChatRequest) (*TokenCountResponse, error)
}

type TokenUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type Tool interface {
	Name() string
	Description() string
	Schema() ToolSchema
}

type ToolCall struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

type ToolResources struct {
	FileSearch *FileSearchResources `json:"file_search,omitempty"`
}

type ToolResult struct {
	CallID  string `json:"call_id"`  // Must match ToolCall.ID from the response
	Content any    `json:"content"`  // Result data (will be JSON marshaled)
	IsError bool   `json:"is_error"` // True if this represents an error
}

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

type ToolSchema struct {
	// JSONSchema is a valid JSON Schema object describing the tool's
	// parameters. Example:
	//   {"type": "object", "properties": {"location": {"type": "string"}}}
	JSONSchema json.RawMessage `json:"json_schema"`
}

type TypedToolResult[T any] struct {
	CallID  string `json:"call_id"`
	Content T      `json:"content"`
	IsError bool   `json:"is_error"`
}

type TypedToolResultBuilder[T any] struct {
	// contains filtered or unexported fields
}

type WarningHandler func(message string)