interfaces

type AgentToolApprovalPolicy interface {
	RequiresApproval(tool Tool) bool
}

type Conversation interface {
	// AddMessage adds a message to the conversation identified by id. Id is passed at runtime (e.g. from Run input, workflow).
	AddMessage(ctx context.Context, id string, msg Message) error

	// ListMessages returns messages for the conversation identified by id.
	ListMessages(ctx context.Context, id string, opts ...ListMessagesOption) ([]Message, error)

	// Clear removes all messages for the conversation identified by id. Called by the user when ending a session.
	Clear(ctx context.Context, id string) error

	// IsDistributed returns true if the implementation uses distributed storage (Redis, Postgres, etc.).
	// In-memory implementations return false. Use distributed implementations when using remote workers.
	IsDistributed() bool
}

type JSONSchema map[string]any

type LLMClient interface {
	// Generate generates a response from the LLM.
	Generate(ctx context.Context, request *LLMRequest) (*LLMResponse, error)
	// GenerateStream generates a response from the LLM using streaming.
	GenerateStream(ctx context.Context, request *LLMRequest) (LLMStream, error)
	// GetModel returns the model name.
	GetModel() string
	// GetProvider returns the provider name.
	GetProvider() LLMProvider
	// IsStreamSupported returns true if the client supports streaming (e.g. OpenAI, Anthropic).
	IsStreamSupported() bool
}

type LLMProvider string

type LLMReasoning struct {
	// Enabled requests reasoning/thinking where the provider supports it.
	// Anthropic: if true and BudgetTokens is 0, uses the minimum extended-thinking budget (1024 tokens).
	// OpenAI: does not infer reasoning_effort from Enabled alone (standard models reject that param).
	// Gemini: contributes to turning on thought output with IncludeThoughts.
	Enabled bool

	// Effort is a generic reasoning intensity: "none", "minimal", "low", "medium", "high", "xhigh".
	// OpenAI: sent as reasoning_effort only when non-empty; use only with reasoning-capable models.
	// Gemini: mapped to ThinkingLevel when recognized (low/medium/high/minimal), unless BudgetTokens > 0.
	// Anthropic: not used (use Enabled and BudgetTokens for extended thinking).
	Effort string

	// BudgetTokens is the token budget for internal reasoning / extended thinking.
	// Anthropic: extended thinking; must be >= 1024 when non-zero (values below are clamped).
	// Gemini: ThinkingBudget. If non-zero, Effort is not mapped to ThinkingLevel (API allows only one).
	// OpenAI: not used.
	BudgetTokens int
}

type LLMRequest struct {
	SystemMessage  string
	ResponseFormat *ResponseFormat
	Tools          []ToolSpec // Tool specs for the LLM to choose from
	// Messages is the conversation history. For first turn, use one user message.
	// For continuation after tool use: append assistant (with ToolCalls) + tool result messages.
	Messages []Message

	// Sampling (per-request; typically set from agent config). nil/0 = provider default.
	Temperature *float64 // 0-2 OpenAI, 0-1 Anthropic; also Gemini
	MaxTokens   int      // 0 = provider default
	TopP        *float64 // 0-1; OpenAI and Gemini (Anthropic client does not set TopP)
	TopK        *int     // Anthropic only

	// Reasoning configures generic reasoning/thinking when non-nil; each LLM client maps fields to its API.
	Reasoning *LLMReasoning
}

type LLMResponse struct {
	Content  string
	Metadata map[string]any
	// Usage is set when the provider returns token usage for this completion (non-stream and stream).
	Usage *LLMUsage
	// ToolCalls contains any tool invocations the LLM chose; empty when none.
	ToolCalls []*ToolCall
}

type LLMStream interface {
	Next() bool
	Current() *LLMStreamChunk
	Err() error
	// GetResult returns the accumulated content and tool calls after streaming completes.
	// Call after the Next loop; returns nil if streaming failed or was not completed.
	GetResult() *LLMResponse
}

type LLMStreamChunk struct {
	ContentDelta  string      // partial text content
	ThinkingDelta string      // Anthropic extended thinking (optional)
	ToolCalls     []*ToolCall // set on final chunk when tool calls are present
}

type LLMUsage struct {
	PromptTokens       int64 `json:"prompt_tokens,omitempty"`
	CompletionTokens   int64 `json:"completion_tokens,omitempty"`
	TotalTokens        int64 `json:"total_tokens,omitempty"`
	CachedPromptTokens int64 `json:"cached_prompt_tokens,omitempty"`
	ReasoningTokens    int64 `json:"reasoning_tokens,omitempty"`
}

type ListMessagesOption func(*ListMessagesOptions)

type ListMessagesOptions struct {
	// Limit is the maximum number of messages to retrieve from recent. -1 = all.
	Limit int

	// Offset is the number of most recent messages to skip. -1 = 0 (default).
	Offset int

	// Roles filters messages by role
	Roles []MessageRole
}

type Message struct {
	Role    MessageRole `json:"role"`
	Content string      `json:"content"`

	ToolName   string      `json:"tool_name"`
	ToolCallID string      `json:"tool_call_id"`
	ToolCalls  []*ToolCall `json:"tool_calls"`

	Metadata  map[string]any `json:"metadata"`
	CreatedAt time.Time      `json:"created_at"`
}

type MessageRole string

type ResponseFormat struct {
	Type   ResponseFormatType
	Name   string
	Schema JSONSchema
}

type ResponseFormatType string

type Tool interface {
	// Name returns the tool identifier (e.g. "search", "calculator"). Used by the LLM in tool calls.
	Name() string

	// Description describes when and how to use this tool. Shown to the LLM for tool selection.
	Description() string

	// Parameters returns the JSON schema for the tool's input. The LLM produces args matching this schema.
	// Use tools.Params with tools.ParamString, ParamInteger, etc. for type-safe construction.
	Parameters() JSONSchema

	// Execute runs the tool with the given args. Args match the Parameters schema.
	// Called by the agent when the LLM returns a tool call for this tool.
	Execute(ctx context.Context, args map[string]any) (any, error)
}

type ToolApproval interface {
	ApprovalRequired() bool
}

type ToolCall struct {
	ToolCallID string         `json:"tool_call_id"` // from API; needed to match tool results
	ToolName   string         `json:"tool_name"`
	Args       map[string]any `json:"args"`
}

type ToolRegistry interface {
	// Register adds a tool. Overwrites if a tool with the same name exists.
	Register(tool Tool)

	// Get returns the tool by name, or (nil, false) if not found.
	Get(name string) (Tool, bool)

	// Tools returns all registered tools in registration order.
	Tools() []Tool
}

type ToolSpec struct {
	Name        string     `json:"name"`
	Description string     `json:"description"`
	Parameters  JSONSchema `json:"parameters"`
}