model

type Content struct {
	// Parts contains the content parts (text, data, files).
	Parts []a2a.Part

	// Role identifies the sender (agent/user).
	Role a2a.MessageRole
}

type FinishReason string

type GenerateConfig struct {
	// Temperature controls randomness (0-2).
	Temperature *float64

	// MaxTokens limits the response length.
	MaxTokens *int

	// TopP controls nucleus sampling.
	TopP *float64

	// TopK controls top-k sampling.
	TopK *int

	// StopSequences terminates generation.
	StopSequences []string

	// ResponseMIMEType for structured output (e.g., "application/json").
	ResponseMIMEType string

	// ResponseSchema for structured output.
	ResponseSchema map[string]any

	// ResponseSchemaName identifies the schema for providers that require it.
	// Used by OpenAI's json_schema format.
	// Default: "response"
	ResponseSchemaName string

	// ResponseSchemaStrict enables strict schema validation.
	// When true, the LLM is constrained to only output valid schema conforming JSON.
	// Default: true (nil means true)
	ResponseSchemaStrict *bool

	// EnableThinking enables extended thinking (model-specific).
	EnableThinking bool

	// ThinkingBudget limits thinking tokens (model-specific).
	ThinkingBudget int

	// Metadata contains additional key-value pairs for LLM providers.
	// Used for authentication tokens, custom headers, etc.
	Metadata map[string]string
}

type LLM interface {
	// Name returns the model identifier.
	Name() string

	// Provider returns the provider type (e.g., "openai", "anthropic", "gemini").
	// Used for model-specific message formatting and content processing.
	Provider() Provider

	// GenerateContent produces responses for the given request.
	//
	// When stream=false:
	//   - Yields exactly one Response with complete content
	//   - Response.Partial will be false
	//
	// When stream=true:
	//   - Yields multiple partial Responses with Partial=true
	//   - Finally yields aggregated Response with Partial=false and full content
	//   - The aggregated response is for session persistence
	//   - Partial responses are for real-time UI updates
	GenerateContent(ctx context.Context, req *Request, stream bool) iter.Seq2[*Response, error]

	// Close releases any resources held by the LLM.
	Close() error
}

type Provider string

type Request struct {
	// Messages is the conversation history.
	Messages []*a2a.Message

	// Tools available for the model to call.
	Tools []tool.Definition

	// Config contains generation configuration.
	Config *GenerateConfig

	// SystemInstruction is prepended to the conversation.
	SystemInstruction string
}

type Response struct {
	// Content is the generated content (text, tool calls, etc.)
	Content *Content

	// Partial indicates whether this is a streaming chunk (true) or final response (false).
	// In streaming mode:
	//   - Partial=true: This is a delta chunk for real-time display
	//   - Partial=false: This is the aggregated final response for persistence
	Partial bool

	// TurnComplete indicates whether the model has finished its turn.
	TurnComplete bool

	// ToolCalls requested by the model.
	ToolCalls []tool.ToolCall

	// Usage statistics.
	Usage *Usage

	// Thinking contains the model's reasoning (if enabled).
	Thinking *ThinkingBlock

	// FinishReason indicates why generation stopped.
	FinishReason FinishReason

	// ErrorCode for provider-specific errors.
	ErrorCode string

	// ErrorMessage for provider-specific error messages.
	ErrorMessage string
}

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

type ThinkingBlock struct {
	// ID uniquely identifies this thinking block in the conversation.
	// Generated by the LLM provider or assigned during aggregation.
	ID string

	// Content is the thinking/reasoning text.
	Content string

	// Signature is used for multi-turn verification (e.g., Anthropic).
	Signature string
}

type Usage struct {
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
	ThinkingTokens   int
}