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, media ...Media) 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, media ...Media) 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, media ...Media) (string, error)
	// Usage returns the cumulative token usage across every provider
	// round-trip made by this client instance since construction. A single
	// Chat/Ask/StreamChat call may make multiple round-trips (one per ReAct
	// step) and all are summed. Providers that do not report token counts
	// (e.g. ProviderClaudeLocal) contribute a zero, Known == false Usage.
	// Wire Config.UsageObserver to observe usage per round-trip instead.
	Usage() Usage
}

type ClaudeLocal struct {
	UsageTracker
	// 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
	// Credentials carries provider-specific credential config resolved by the
	// host application. Token still wins when both are set.
	Credentials CredentialConfig `json:"-"`
	// 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
	// RequestTimeout bounds a single HTTP request to the provider. Zero falls
	// back to the ai.request_timeout config key, then DefaultChatRequestTimeout.
	// Bounded on purpose so a stuck model fails rather than hanging forever.
	RequestTimeout time.Duration
	// HTTPClient, when non-nil, is used verbatim for provider API calls. The
	// host injects a hardened transport here (go-tool-base supplies pkg/http's);
	// nil ⇒ the module builds a plain bounded client from RequestTimeout.
	HTTPClient *http.Client `json:"-"`
	// 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

	// Seed, when non-nil, requests deterministic sampling from providers
	// that support a seed parameter (currently OpenAI / OpenAI-compatible).
	// Nil — the default — omits the seed entirely so the provider samples
	// normally. A previous build hardcoded seed=0, silently pinning every
	// OpenAI request to one sampling path; set this only when you need
	// reproducible-ish completions.
	Seed *int64

	// ExecLookPath overrides exec.LookPath for the ClaudeLocal provider.
	// Nil means use the real exec.LookPath.
	ExecLookPath func(string) (string, error) `json:"-"`
	// ExecCommand overrides exec.CommandContext for the ClaudeLocal provider
	// and the update command's config re-init.
	// Nil means use the real exec.CommandContext.
	ExecCommand func(context.Context, string, ...string) *exec.Cmd `json:"-"`
	// GenaiNewClient overrides the Gemini client constructor for testing.
	// Must be func(context.Context, *genai.ClientConfig) (*genai.Client, error).
	// Nil means use the real genai.NewClient.
	GenaiNewClient any `json:"-"`

	// UsageObserver, when non-nil, is invoked once per provider round-trip
	// with that round-trip's token usage. A ReAct tool-calling loop fires it
	// once per step. This is the opt-in hook for emitting a telemetry event,
	// metric, or log line; the chat client never depends on a telemetry
	// collector. Providers that do not report usage still fire the observer
	// with a Known == false Usage. The callback runs synchronously on the
	// calling goroutine, so keep it fast and non-blocking.
	UsageObserver func(Usage) `json:"-"`

	// AllowInsecureBaseURL permits HTTP (non-HTTPS) BaseURLs. This is
	// exclusively for tests that point at an httptest.Server. Production
	// callers must leave this false. The field is tagged json:"-" so
	// config files cannot enable it.
	AllowInsecureBaseURL bool `json:"-"`
}

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 CredentialConfig struct {
	Env      string `mapstructure:"env"`
	Keychain string `mapstructure:"keychain"`
	Key      string `mapstructure:"key"`
	// Lookup resolves the Keychain reference. Injected by the host (nil ⇒ the
	// keychain step is skipped); never decoded from config.
	Lookup KeychainLookup `mapstructure:"-" json:"-"`
}

type FailoverDecision int

type FailoverPolicy interface {
	Classify(err error) FailoverDecision
}

type FallbackConfig struct {
	Enabled   bool       `mapstructure:"enabled"`
	Providers []Provider `mapstructure:"providers"`
}

type FallbackOption func(*fallbackConfig)

type FileStoreOption func(*fileStoreConfig)

type HTTPStatusExtractor func(err error) (status int, ok bool)

type KeychainLookup func(ctx context.Context, service, account string) (string, error)

type Media struct {
	MIMEType string
	Data     []byte
}

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, settings Settings) (ChatClient, error)

type ResolvedMedia struct {
	MIMEType string
	Data     []byte
}

type RuntimeConfig struct {
	Provider       Provider       `mapstructure:"provider"`
	RequestTimeout time.Duration  `mapstructure:"request_timeout"`
	Fallback       FallbackConfig `mapstructure:"fallback"`
}

type Settings struct {
	Config Config
	Logger *slog.Logger
}

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, media ...Media) (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"`
}

type Usage struct {
	// InputTokens is the number of prompt/input tokens consumed.
	InputTokens int
	// OutputTokens is the number of completion/output tokens produced.
	OutputTokens int
	// TotalTokens is the sum of input and output tokens. When a provider
	// supplies its own total it is preserved; otherwise it is computed as
	// InputTokens + OutputTokens.
	TotalTokens int
	// CachedTokens is the number of input tokens served from a provider-side
	// prompt cache, when reported. Zero when the provider does not expose it.
	CachedTokens int
	// ReasoningTokens is the number of tokens spent on internal reasoning
	// ("thinking") output, when reported. Zero when not exposed.
	ReasoningTokens int
	// Known reports whether the provider supplied token counts for this call.
	// False indicates the counts are not authoritative (e.g. ProviderClaudeLocal).
	Known bool
}

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