core

type APIEndpoint string

type AgentCompleteEvent struct {
	Iterations     int
	TotalToolCalls int
	TotalDuration  time.Duration
	TotalTokens    TokenUsage
	StopReason     AgentStopReason
	FinalResponse  *ChatResponse
}

type AgentConfig struct {
	// MaxIterations is the maximum number of LLM calls before stopping.
	// Each iteration may execute multiple tools.
	// Default: 10. Set to 0 for unlimited (use with caution).
	MaxIterations int

	// MaxToolCalls is the maximum total tool calls across all iterations.
	// Default: 50. Set to 0 for unlimited.
	MaxToolCalls int

	// IterationTimeout is the timeout for each individual LLM call.
	// Does not include tool execution time.
	// Default: 30s.
	IterationTimeout time.Duration

	// ToolTimeout is the timeout for each individual tool execution.
	// Default: 60s.
	ToolTimeout time.Duration

	// ParallelTools enables concurrent execution of tools within an iteration.
	// When false, tools execute sequentially in order.
	// Default: true.
	ParallelTools bool

	// MaxParallelTools limits concurrent tool executions.
	// Only applies when ParallelTools is true.
	// Default: 5. Set to 0 for unlimited.
	MaxParallelTools int

	// ContinueOnToolError determines behavior when a tool fails.
	// If true, the error is passed to the model as a tool result.
	// If false, the agent loop returns immediately with the error.
	// Default: true (pass errors to model).
	ContinueOnToolError bool

	// StopSequences are additional strings that stop the agent.
	// If the model's output contains any of these, the loop terminates.
	// Default: empty.
	StopSequences []string

	// ToolFilter optionally filters which tools can be executed.
	// Return false to skip a tool (error sent to model).
	// Default: nil (all tools allowed).
	ToolFilter func(call ToolCall) bool

	// Hooks for observability and control.
	Hooks AgentHooks

	// Memory configures conversation memory management with auto-summarization.
	// If nil, no memory management is performed (may hit context limits).
	Memory *MemoryConfig
}

type AgentHooks struct {
	// OnIterationStart is called at the start of each LLM call.
	// Return an error to abort the agent loop.
	OnIterationStart func(ctx context.Context, e IterationStartEvent) error

	// OnIterationEnd is called after each LLM response.
	OnIterationEnd func(ctx context.Context, e IterationEndEvent)

	// OnToolCallStart is called before executing each tool.
	// Return an error to skip this tool (error sent to model).
	OnToolCallStart func(ctx context.Context, e ToolCallStartEvent) error

	// OnToolCallEnd is called after each tool execution.
	OnToolCallEnd func(ctx context.Context, e ToolCallEndEvent)

	// OnAgentComplete is called when the agent loop finishes.
	OnAgentComplete func(ctx context.Context, e AgentCompleteEvent)

	// OnTextDelta is called for each text chunk during streaming.
	// Only used with RunStream.
	OnTextDelta func(ctx context.Context, delta string)
}

type AgentResult struct {
	// FinalResponse is the last response from the model.
	FinalResponse *ChatResponse

	// Iterations is the number of LLM calls made.
	Iterations int

	// ToolHistory contains all tool executions in order.
	ToolHistory []ToolExecution

	// TotalTokens is the sum of tokens across all iterations.
	TotalTokens TokenUsage

	// Duration is the total time from start to finish.
	Duration time.Duration

	// StopReason indicates why the agent stopped.
	StopReason AgentStopReason

	// Error is set if the agent stopped due to an error.
	// May be nil even if StopReason is StopReasonError.
	Error error
}

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

type AgentSnapshot struct {
	// Version for forward compatibility
	Version string `json:"version"`

	// Conversation state
	Messages []Message `json:"messages"`

	// Execution progress
	Iteration      int             `json:"iteration"`
	TotalToolCalls int             `json:"total_tool_calls"`
	ToolHistory    []ToolExecution `json:"tool_history"`

	// Timing (for metrics continuity)
	StartTime   time.Time     `json:"start_time"`
	ElapsedTime time.Duration `json:"elapsed_time"`
	TotalTokens TokenUsage    `json:"total_tokens"`

	// Configuration hash for validation on restore
	ConfigHash string `json:"config_hash"`

	// Last response (if paused mid-iteration)
	PendingToolCalls []ToolCall `json:"pending_tool_calls,omitempty"`
}

type AgentStopReason string

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

	// 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"`
}

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"`

	// 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 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 IterationEndEvent struct {
	Iteration  int
	Response   *ChatResponse
	ToolCalls  []ToolCall
	Duration   time.Duration
	TokensUsed TokenUsage
}

type IterationStartEvent struct {
	Iteration    int
	MessageCount int
	ToolCount    int // Tools executed so far
}

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

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

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

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

	// Clear removes all messages from the conversation.
	Clear()

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

	// SetMessages replaces the entire conversation history.
	SetMessages(msgs []Message)
}

type MemoryConfig struct {
	// MaxTokens is the target maximum tokens for the conversation.
	// When exceeded, auto-summarization is triggered.
	// Default: 0 (no limit - use provider's context window)
	MaxTokens int

	// SummarizationThreshold triggers summarization when token count
	// exceeds MaxTokens * SummarizationThreshold.
	// Default: 0.8 (summarize when 80% full)
	SummarizationThreshold float64

	// SummarizationPrompt is the system prompt used for summarization.
	// Default: built-in prompt optimized for agent context preservation
	SummarizationPrompt string

	// PreserveLastN keeps the N most recent messages unsummarized.
	// Default: 4 (keep last 2 turns)
	PreserveLastN int

	// OnSummarize is called when summarization occurs.
	OnSummarize func(ctx context.Context, e SummarizationEvent)
}

type Message struct {
	Role        Role          `json:"role"`
	Content     string        `json:"content,omitempty"`
	Parts       []ContentPart `json:"-"`                      // Multimodal content parts (Responses API only)
	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
	Err       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 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.
	NextDelay(attempt int, err error) (delay time.Duration, ok bool)
}

type Role string

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

type SummarizationEvent struct {
	OriginalTokens   int
	SummarizedTokens int
	MessagesRemoved  int
	Summary          string
}

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 TokenUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

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

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

type ToolCallEndEvent struct {
	Iteration int
	ToolCall  ToolCall
	Result    any
	Error     error
	Duration  time.Duration
}

type ToolCallStartEvent struct {
	Iteration int
	ToolCall  ToolCall
	Index     int // Index within this iteration's tool calls
	Total     int // Total tool calls in this iteration
}

type ToolExecution struct {
	Iteration int
	Call      ToolCall
	Result    any
	Error     error
	Duration  time.Duration
	Timestamp time.Time
}

type ToolExecutor interface {
	// Execute finds a tool by name and calls it with the given arguments.
	Execute(ctx context.Context, name string, args json.RawMessage) (any, error)
}

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 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
}