llm

type Chunk struct {
	// Content is the incremental text delta.
	Content string

	// ToolCalls contains incremental tool call deltas.
	ToolCalls []ToolCall

	// FinishReason is set on the final chunk.
	FinishReason string

	// Native is the whole reply in the provider's own format. A client sets
	// it on the final chunk only.
	Native *NativeContent `json:"Native,omitempty"`
}

type Client interface {
	// Complete sends a synchronous completion request and returns the full response.
	Complete(ctx context.Context, req *Request) (*Response, error)

	// CompleteStream sends a streaming completion request and returns a stream
	// that yields incremental chunks.
	CompleteStream(ctx context.Context, req *Request) (Stream, error)
}

type Message struct {
	// Role is the message author: "user", "assistant", or "tool".
	Role string

	// Content is the text content of the message.
	Content string

	// ToolCalls contains tool invocations requested by the assistant.
	ToolCalls []ToolCall

	// ToolCallID identifies which tool call this message is responding to (role=tool).
	ToolCallID string

	// Native is the provider's own form of an assistant message, carried
	// back to the model that produced it. Nil for every other message.
	Native *NativeContent `json:"Native,omitempty"`
}

type MockClient struct {
	// TokenDelay is the delay between each streamed character. Default: 20ms.
	TokenDelay time.Duration
}

type NativeContent struct {
	// Provider names the provider whose format Content is in.
	Provider string `json:"provider"`
	// Model is the model that produced the reply.
	Model string `json:"model"`
	// Content is the reply's raw content blocks, thinking signatures
	// included.
	Content json.RawMessage `json:"content"`
}

type Request struct {
	// Model is the model identifier (e.g. "gpt-4o", "claude-sonnet-4-20250514", "smart").
	Model string

	// System is the system prompt injected before the conversation.
	System string

	// Messages is the conversation history.
	Messages []Message

	// Tools is the set of tools available for the LLM to call.
	Tools []Tool

	// MaxTokens limits the maximum output tokens.
	MaxTokens int

	// Temperature controls sampling randomness. Nil means provider default.
	Temperature *float64

	// ToolChoice constrains whether and which tool the model calls. Nil
	// leaves it to the model. The engine never sets it.
	ToolChoice *ToolChoice `json:"ToolChoice,omitempty"`

	// Metadata labels the request for the client's usage records, for
	// example with MetadataRun and MetadataAgent. The engine sets it. It is
	// kept out of the request's JSON, so request digests do not depend on
	// it.
	Metadata map[string]string `json:"-"`
}

type Response struct {
	// Content is the assistant's text response.
	Content string

	// ToolCalls contains any tool invocations requested by the assistant.
	ToolCalls []ToolCall

	// Usage tracks token consumption.
	Usage Usage

	// Model is the actual model used (may differ from request if aliased).
	Model string

	// FinishReason indicates why generation stopped: "stop", "tool_calls", "length", etc.
	FinishReason string

	// Native is the reply in the provider's own format, when the client
	// has it.
	Native *NativeContent `json:"Native,omitempty"`
}

type Stream interface {
	// Next returns the next chunk. Returns io.EOF when the stream is complete.
	Next(ctx context.Context) (*Chunk, error)

	// Close releases stream resources.
	Close() error

	// Usage returns the final token usage after the stream completes.
	// May return nil if usage is not yet available.
	Usage() *Usage
}

type Tool struct {
	// Name is the tool's unique identifier.
	Name string

	// Description explains what the tool does.
	Description string

	// Parameters is a JSON Schema describing the tool's input parameters.
	Parameters any
}

type ToolCall struct {
	// ID uniquely identifies this tool call (used to match tool results).
	ID string

	// Name is the name of the tool to invoke.
	Name string

	// Arguments is the JSON-encoded arguments for the tool.
	Arguments string
}

type ToolChoice struct {
	// Mode is "auto", "none", "required" or "function".
	Mode string
	// Function names the tool to call when Mode is "function".
	Function string
}

type Usage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}