ai

type Agent interface {
	// Run executes the agent synchronously with the given input.
	Run(ctx context.Context, input string, opts ...Option) (*Message, error)
	// Stream executes the agent and returns a streaming response.
	Stream(ctx context.Context, input string, opts ...Option) (MessageStream, error)
}

type AgentBuilder interface {
	// WithModel sets the chat model for the agent.
	WithModel(model ToolableChatModel) AgentBuilder
	// WithTools adds tools to the agent.
	WithTools(tools ...Tool) AgentBuilder
	// WithSystemPrompt sets the system prompt.
	WithSystemPrompt(prompt string) AgentBuilder
	// WithMaxIterations sets the maximum number of iterations.
	WithMaxIterations(n int) AgentBuilder
	// Build creates the agent instance.
	Build(ctx context.Context) (Agent, error)
}

type AgentConfig struct {
	// Model is the chat model to use for reasoning.
	Model ToolableChatModel
	// Tools are the tools available to the agent.
	Tools []Tool
	// SystemPrompt is the system prompt that guides the agent's behavior.
	SystemPrompt string
	// MaxIterations limits the maximum number of reasoning iterations.
	MaxIterations int
}

type AgentFactory interface {
	// Name returns the agent type name.
	Name() string
	// CreateBuilder creates a new agent builder.
	CreateBuilder() AgentBuilder
}

type ChatModel interface {
	// Generate produces a response from the given messages synchronously.
	Generate(ctx context.Context, messages []*Message, opts ...Option) (*Message, error)
	// Stream produces a streaming response from the given messages.
	Stream(ctx context.Context, messages []*Message, opts ...Option) (MessageStream, error)
}

type Message struct {
	// Role indicates who sent this message.
	Role Role
	// Content is the text content of the message.
	Content string
	// ToolCalls contains tool invocation requests (only for Assistant role).
	ToolCalls []ToolCall
	// ToolResult contains tool execution result (only for Tool role).
	ToolResult *ToolResult
	// Usage contains token usage statistics (only for response messages).
	Usage *TokenUsage
}

type MessageChunk struct {
	// Content is the incremental text content.
	Content string
	// ToolCalls contains tool calls (may be partial in streaming).
	ToolCalls []ToolCall
	// Done indicates whether the stream is complete.
	Done bool
}

type MessageStream interface {
	io.Closer

	// Recv receives the next message chunk from the stream.
	// Returns io.EOF when the stream is exhausted.
	Recv() (*MessageChunk, error)
	// Collect collects all chunks and merges them into a complete message.
	Collect() (*Message, error)
}

type ModelConfig struct {
	// Provider is the name of the model provider.
	Provider string
	// Model is the name of the model to use.
	Model string
	// APIKey is the API key for authentication.
	APIKey string
	// BaseURL is the base URL for the API endpoint.
	BaseURL string
	// Temperature controls randomness (0.0 to 1.0).
	Temperature float64
	// MaxTokens limits the maximum tokens in the response.
	MaxTokens int
	// Timeout is the request timeout duration.
	Timeout time.Duration
}

type ModelError struct {
	Provider   string
	StatusCode int
	Message    string
}

type ModelInfo struct {
	// Provider is the name of the model provider.
	Provider string
	// Model is the name of the model.
	Model string
	// MaxTokens is the maximum context length.
	MaxTokens int
	// Temperature is the default temperature setting.
	Temperature float64
}

type ModelProvider interface {
	// Name returns the provider's unique identifier.
	Name() string
	// CreateModel creates a new chat model instance.
	CreateModel(ctx context.Context, cfg *ModelConfig) (ToolableChatModel, error)
}

type Option func(*Options)

type Options struct {
	// Temperature controls randomness in the output.
	Temperature *float64
	// MaxTokens limits the maximum number of tokens to generate.
	MaxTokens *int
	// StopSequences specifies sequences that stop generation.
	StopSequences []string
	// Meta contains additional key-value pairs.
	Meta map[string]string
}

type ParameterSchema struct {
	// Type is the schema type, typically "object".
	Type string
	// Properties defines the parameter properties.
	Properties map[string]*PropertySchema
	// Required lists the required parameter names.
	Required []string
}

type PropertySchema struct {
	// Type is the property type: string, number, integer, boolean, array, object.
	Type string
	// Description explains what this parameter is for.
	Description string
	// Enum lists allowed values if this is an enumeration.
	Enum []string
	// Items defines the schema for array items (only for array type).
	Items *PropertySchema
}

type Role string

type StreamableTool interface {
	Tool

	// InvokeStream executes the tool and returns a streaming result.
	InvokeStream(ctx context.Context, arguments string) (StringStream, error)
}

type StringStream interface {
	io.Closer

	// Recv receives the next string chunk from the stream.
	// Returns io.EOF when the stream is exhausted.
	Recv() (string, error)
	// Collect collects all chunks and concatenates them.
	Collect() (string, error)
}

type TokenUsage struct {
	// PromptTokens is the number of tokens in the prompt.
	PromptTokens int
	// CompletionTokens is the number of tokens in the completion.
	CompletionTokens int
	// TotalTokens is the total number of tokens used.
	TotalTokens int
}

type Tool interface {
	// Info returns the tool's metadata.
	Info() *ToolInfo
	// Invoke executes the tool with the given JSON-encoded arguments.
	// Returns the result as a string.
	Invoke(ctx context.Context, arguments string) (string, error)
}

type ToolCall struct {
	// ID is the unique identifier for this tool call.
	ID string
	// Name is the name of the tool to invoke.
	Name string
	// Arguments contains the JSON-encoded arguments for the tool.
	Arguments string
}

type ToolError struct {
	ToolName string
	Err      error
}

type ToolInfo struct {
	// Name is the unique identifier of the tool.
	Name string
	// Description explains what the tool does.
	Description string
	// Parameters defines the input schema for the tool.
	Parameters *ParameterSchema
}

type ToolResult struct {
	// CallID is the identifier of the corresponding ToolCall.
	CallID string
	// Content is the result content from the tool execution.
	Content string
}

type ToolableChatModel interface {
	ChatModel

	// WithTools returns a new model instance with the specified tools bound.
	// This follows the immutable pattern - it does not modify the current instance.
	WithTools(tools ...Tool) ToolableChatModel
}