chat

type ChatClient interface {
	// Add appends a user message to the conversation history without
	// triggering a completion. The message persists for subsequent
	// Chat() or Ask() calls.
	Add(ctx context.Context, prompt string) error
	// Ask sends a question and unmarshals the structured response into
	// target. If Config.ResponseSchema was set during construction, the
	// provider enforces that schema. If no schema is set, the provider
	// returns the raw text content unmarshalled into target (which must
	// be a *string or implement json.Unmarshaler).
	Ask(ctx context.Context, question string, target any) error
	// SetTools configures the tools available to the AI. This replaces
	// (not appends to) any previously set tools.
	SetTools(tools []Tool) error
	// Chat sends a message and returns the response content. If tools
	// are configured, the provider handles tool calls internally via a
	// ReAct loop bounded by Config.MaxSteps (default 20).
	Chat(ctx context.Context, prompt string) (string, error)
}

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

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

type Config struct {
	// Provider is the AI service provider to use.
	Provider Provider
	// Model is the specific model to use (e.g., "gpt-4o", "claude-3-5-sonnet").
	Model string
	// Token is the API key or token for the service.
	Token string
	// BaseURL overrides the API endpoint. Required when using ProviderOpenAICompatible.
	// Example: "http://localhost:11434/v1" for Ollama, "https://api.groq.com/openai/v1" for Groq.
	BaseURL string
	// SystemPrompt is the initial system prompt to set the context for the AI.
	SystemPrompt string
	// ResponseSchema is the JSON schema used to force a structured output from the AI.
	ResponseSchema any
	// SchemaName is the name of the response schema (e.g., "error_analysis").
	SchemaName string
	// SchemaDescription is a description of the response schema.
	SchemaDescription string
	// MaxSteps limits the number of ReAct loop iterations in Chat().
	// Zero means use the default (DefaultMaxSteps = 20).
	MaxSteps int
	// MaxTokens sets the maximum tokens per response.
	// Zero means use the provider default (OpenAI: 4096, Claude: 8192, Gemini: 8192).
	MaxTokens int
	// ParallelTools enables concurrent execution of multiple tool calls
	// within a single ReAct step. Disabled by default.
	ParallelTools bool
	// MaxParallelTools limits the number of tools executing concurrently.
	// Zero means use the default (5). Only effective when ParallelTools is true.
	MaxParallelTools int
}

type ConversationStore interface {
	// Save writes a snapshot to the store.
	Save(ctx context.Context, snapshot *Snapshot) error
	// Load retrieves a snapshot by ID.
	Load(ctx context.Context, id string) (*Snapshot, error)
	// List returns summaries of all stored snapshots.
	List(ctx context.Context) ([]SnapshotSummary, error)
	// Delete removes a snapshot by ID.
	Delete(ctx context.Context, id string) error
}

type FileStoreOption func(*fileStoreConfig)

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

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

type PersistentChatClient interface {
	ChatClient
	// Save captures the current conversation state as an immutable snapshot.
	// The snapshot includes provider-specific messages as opaque JSON, tool
	// metadata (without handlers), and configuration. Tokens are never saved.
	Save() (*Snapshot, error)
	// Restore replaces the current conversation state with a previously saved
	// snapshot. The snapshot's Provider must match the client's provider.
	// After restore, tools must be re-registered via SetTools with live handlers.
	Restore(snapshot *Snapshot) error
}

type Provider string

type ProviderFactory func(ctx context.Context, p *props.Props, cfg Config) (ChatClient, error)

type Snapshot struct {
	// ID uniquely identifies this snapshot.
	ID string `json:"id"`
	// Provider identifies which chat provider created this snapshot.
	Provider Provider `json:"provider"`
	// Model is the AI model used in the conversation.
	Model string `json:"model"`
	// SystemPrompt is the system instruction active at snapshot time.
	SystemPrompt string `json:"system_prompt,omitempty"`
	// Messages contains provider-specific message history as opaque JSON.
	// The format varies by provider — do not parse or modify directly.
	Messages json.RawMessage `json:"messages"`
	// Tools captures tool metadata (name, description, parameters) without
	// handlers. After restoring, call SetTools to re-register live handlers.
	Tools []ToolSnapshot `json:"tools,omitempty"`
	// Metadata holds arbitrary key-value pairs for consumer use.
	Metadata map[string]string `json:"metadata,omitempty"`
	// CreatedAt is when this snapshot was taken.
	CreatedAt time.Time `json:"created_at"`
	// Version is the snapshot format version for forward compatibility.
	Version int `json:"version"`
}

type SnapshotSummary struct {
	ID           string    `json:"id"`
	Provider     Provider  `json:"provider"`
	Model        string    `json:"model"`
	CreatedAt    time.Time `json:"created_at"`
	MessageCount int       `json:"message_count"`
}

type StreamCallback func(event StreamEvent) error

type StreamEvent struct {
	// Type indicates the kind of event.
	Type StreamEventType

	// Delta contains the text fragment for EventTextDelta events.
	Delta string

	// ToolCall contains tool call information for EventToolCallStart/EventToolCallEnd events.
	ToolCall *StreamToolCall

	// Error contains error information for EventError events.
	Error error
}

type StreamEventType int

type StreamToolCall struct {
	// ID is the provider-assigned identifier for the tool call.
	ID string
	// Name is the tool name.
	Name string
	// Arguments is the complete JSON argument payload (only populated on EventToolCallEnd).
	Arguments string
	// Result is the tool execution result (only populated on EventToolCallEnd).
	Result string
}

type StreamingChatClient interface {
	ChatClient

	// StreamChat sends a message and streams the response via callback.
	// The callback is invoked for each event in the stream. If the callback
	// returns a non-nil error, the stream is cancelled and that error is returned.
	// The return value is the complete assembled response text (concatenation of
	// all EventTextDelta fragments) or an error if streaming failed.
	// Tool calls are handled internally via the same ReAct loop as Chat(). If
	// Config.ParallelTools is enabled, multiple tool calls are executed concurrently.
	StreamChat(ctx context.Context, prompt string, callback StreamCallback) (string, error)
}

type Tool struct {
	Name        string                                                       `json:"name"`
	Description string                                                       `json:"description"`
	Parameters  *jsonschema.Schema                                           `json:"parameters"`
	Handler     func(ctx context.Context, args json.RawMessage) (any, error) `json:"-"`
}

type ToolCall struct {
	Name  string
	Input json.RawMessage
}

type ToolResult struct {
	Name   string
	Result string
}

type ToolSnapshot struct {
	Name        string             `json:"name"`
	Description string             `json:"description"`
	Parameters  *jsonschema.Schema `json:"parameters,omitempty"`
}