ago

type AgentConfig interface {
	GetName() string
	GetModel() string
	GetLLM() LLM
	GetTools() []Tool
	GetMaxIterations() int
	GetGenerateConfig() *GenerateConfig
	GetSystemInstruction() *Content
}

type Blob struct {
	// MIMEType identifies the data format (e.g. "image/png", "audio/mp3").
	MIMEType string `json:"mimeType,omitempty"`

	// Data is the raw binary content.
	Data []byte `json:"data,omitempty"`
}

type Candidate struct {
	// Content is the generated message (text, tool calls, or both).
	Content *Content `json:"content,omitempty"`

	// FinishReason explains why the model stopped generating this candidate.
	FinishReason FinishReason `json:"finishReason,omitempty"`

	// Index is the candidate's position when multiple candidates are returned (usually 0).
	Index int `json:"index,omitempty"`

	// TokenCount is the number of tokens in this specific candidate (backend-dependent).
	TokenCount int32 `json:"tokenCount,omitempty"`

	// FinishMessage is an optional human-readable message about why generation stopped.
	FinishMessage string `json:"finishMessage,omitempty"`
}

type CodeExecutionResult struct {
	// Outcome indicates whether execution succeeded, failed, or timed out.
	Outcome CodeOutcome `json:"outcome,omitempty"`

	// Output is the stdout/stderr captured during execution.
	Output string `json:"output,omitempty"`
}

type CodeLanguage string

type CodeOutcome string

type Content struct {
	// Role identifies who produced this content (user, model, system, or tool).
	Role Role `json:"role,omitempty"`

	// Parts holds the payload segments. A single Content can have multiple parts,
	// for example a model response with both text and a tool call, or a user message
	// with text and an image.
	Parts []*Part `json:"parts,omitempty"`
}

type ExecutableCode struct {
	// Code is the source code the model generated.
	Code string `json:"code,omitempty"`

	// Language identifies the programming language (e.g. CodeLanguagePython).
	Language CodeLanguage `json:"language,omitempty"`
}

type ExecutorResult struct {
	Response *Response  // final LLM response (or synthetic response for SkipSynthesis)
	History  []*Content // full conversation including tool calls/responses
}

type FileData struct {
	// MIMEType identifies the file format (e.g. "application/pdf", "image/jpeg").
	MIMEType string `json:"mimeType,omitempty"`

	// FileURI is the URI where the file can be accessed (e.g. "gs://bucket/file.pdf").
	FileURI string `json:"fileUri,omitempty"`

	// DisplayName is a human-readable label for the file (optional).
	DisplayName string `json:"displayName,omitempty"`
}

type FinishReason string

type FunctionCall struct {
	// ID is a backend-assigned identifier for this tool call (used by OpenAI to match
	// tool calls with their responses; may be empty for other backends).
	ID string `json:"id,omitempty"`

	// Name is the tool/function name the model wants to invoke. Must match a registered
	// Tool's Name() return value.
	Name string `json:"name,omitempty"`

	// Args is the map of argument name to value that the model wants to pass to the tool.
	// Values are JSON-decoded: strings, float64 for numbers, bools, nested maps/slices.
	Args map[string]any `json:"args,omitempty"`
}

type FunctionDeclaration struct {
	// Name is the unique identifier for this tool. The model uses this name when requesting
	// a tool call, and the executor uses it to look up the Tool implementation.
	Name string

	// Description tells the model what this tool does and when to use it.
	// Be specific: "Calculate mathematical expressions" is better than "Math tool".
	Description string

	// Parameters defines the arguments this tool accepts as a JSON Schema.
	// Use TypeObject with Properties and Required to define named parameters.
	// Set to nil or an empty object schema if the tool takes no arguments.
	Parameters *Schema
}

type FunctionResponse struct {
	// ID matches the FunctionCall.ID this response is for (required by OpenAI, optional elsewhere).
	ID string `json:"id,omitempty"`

	// Name is the tool name this response is for (matches the original FunctionCall.Name).
	Name string `json:"name,omitempty"`

	// Response is the tool's output as a key-value map. On success, this is whatever the
	// tool returned. On tool-level errors, this is {"error": "message"} and the loop continues.
	Response map[string]any `json:"response,omitempty"`
}

type GenerateConfig struct {
	// MaxOutputTokens caps the number of tokens the model can generate in one response.
	// 0 means use the backend's default limit.
	MaxOutputTokens int

	// Temperature controls randomness in generation. Higher values (e.g. 0.8) make output
	// more random; lower values (e.g. 0.2) make it more deterministic. nil = backend default.
	Temperature *float64

	// TopP controls nucleus sampling: only tokens with cumulative probability <= TopP are
	// considered. nil = backend default (usually 1.0).
	TopP *float64

	// TopK limits sampling to the top K most likely tokens. nil = backend default.
	// Note: not all backends support TopK (OpenAI does not).
	TopK *float64

	// StopSequences is a list of strings that, when generated, cause the model to stop.
	// Empty means no custom stop sequences.
	StopSequences []string

	// ResponseMIMEType constrains the response format (e.g. "application/json" for JSON mode).
	// Empty means no constraint (default text).
	ResponseMIMEType string

	// ResponseSchema defines the expected JSON structure when ResponseMIMEType is "application/json".
	// The model will attempt to produce output matching this schema.
	ResponseSchema *Schema

	// ThinkingConfig enables and configures extended reasoning/thinking tokens.
	// Set Enabled=true and Budget to the max thinking tokens. nil = thinking disabled.
	ThinkingConfig *ThinkingConfig

	// Seed sets a deterministic seed for reproducible generation. nil = non-deterministic.
	// Note: reproducibility is best-effort and not guaranteed by all backends.
	Seed *int

	// PresencePenalty penalizes tokens that have already appeared in the output, encouraging
	// the model to talk about new topics. Range: typically -2.0 to 2.0. nil = no penalty.
	PresencePenalty *float64

	// FrequencyPenalty penalizes tokens proportional to how often they've appeared, reducing
	// repetition. Range: typically -2.0 to 2.0. nil = no penalty.
	FrequencyPenalty *float64
}

type GenerateParams struct {
	// Contents is the conversation history: a sequence of user messages, model responses,
	// tool calls, and tool results that form the context for this generation.
	Contents []*Content

	// Config holds sampling parameters (temperature, max tokens, penalties, etc.).
	// May be nil to use backend defaults.
	Config *GenerateConfig

	// SystemInstruction is the system prompt as a Content value.
	// Set by the executor from Agent.SystemPrompt. Backends inject this into their
	// native system-message mechanism (e.g. OpenAI system message, GenAI config field).
	SystemInstruction *Content

	// Tools is the list of tool declarations available to the model for this request.
	// Set by the executor from Agent.Tools. The model can choose to call any of these.
	Tools []*FunctionDeclaration
}

type LLM interface {
	// Name returns a stable identifier for this backend (e.g. "openai", "genai").
	Name() string

	// Generate performs a single non-streaming completion request.
	// The model name, conversation history, system instruction, tools, and sampling config
	// are all provided via the GenerateParams struct.
	// Returns the full response with candidates and usage, or an error.
	Generate(ctx context.Context, model string, params *GenerateParams) (*Response, error)

	// GenerateStream performs a streaming completion request, yielding chunks as they arrive.
	// Each yielded StreamChunk may contain partial text or tool calls. The final chunk has
	// Complete=true with definitive candidates and usage data.
	// Iterate the returned sequence with a range loop; break early to cancel.
	GenerateStream(ctx context.Context, model string, params *GenerateParams) iter.Seq2[*StreamChunk, error]

	// Close releases any resources (connections, clients) held by the backend.
	// Call this when the LLM is no longer needed. Safe to call multiple times.
	Close() error
}

type ModalityTokenCount struct {
	// Modality is the content type (e.g. "TEXT", "IMAGE").
	Modality string `json:"modality,omitempty"`

	// TokenCount is the number of tokens for this modality.
	TokenCount int32 `json:"tokenCount,omitempty"`
}

type Part struct {
	// Text holds plain text content. Non-empty for text messages, empty otherwise.
	Text string `json:"text,omitempty"`

	// FunctionCall is set when the model requests a tool invocation.
	// Contains the tool name and arguments. The executor uses this to dispatch to the
	// matching Tool implementation.
	FunctionCall *FunctionCall `json:"functionCall,omitempty"`

	// FunctionResponse is set when returning a tool's result to the model.
	// Contains the tool name and the response data (key-value map). The executor
	// builds these automatically after executing tools.
	FunctionResponse *FunctionResponse `json:"functionResponse,omitempty"`

	// InlineData holds binary data (e.g. images, audio clips) embedded directly in the
	// message, along with its MIME type. Use BlobPart() to create these.
	InlineData *Blob `json:"inlineData,omitempty"`

	// FileData references external data by URI (e.g. a GCS path or uploaded file URL).
	// Use FileDataPart() to create these.
	FileData *FileData `json:"fileData,omitempty"`

	// ExecutableCode holds code the model produced for execution (used in code-execution
	// flows where the model can write and run code).
	ExecutableCode *ExecutableCode `json:"executableCode,omitempty"`

	// CodeExecutionResult holds the outcome and output of running model-generated code.
	CodeExecutionResult *CodeExecutionResult `json:"codeExecutionResult,omitempty"`

	// VideoMetadata provides timing and FPS info for video content in InlineData or FileData.
	VideoMetadata *VideoMetadata `json:"videoMetadata,omitempty"`

	// Thought is true when this part contains model reasoning/thinking tokens.
	// These are typically passed through opaquely and not displayed to the end user.
	Thought bool `json:"thought,omitempty"`

	// ThoughtSignature is an opaque signature for thought tokens, used by some backends
	// to validate or reference thinking content across turns.
	ThoughtSignature []byte `json:"thoughtSignature,omitempty"`
}

type Response struct {
	// Candidates holds the generated completions. Typically contains one candidate.
	Candidates []*Candidate

	// Usage reports token consumption for this request.
	Usage TokenUsage

	// ModelVersion is the specific model version string returned by the backend
	// (e.g. "gpt-4o-2024-05-13" or "gemini-1.5-pro-001").
	ModelVersion string
}

type Role string

type Schema struct {
	// Type is the JSON Schema type (string, number, integer, boolean, array, object).
	Type SchemaType

	// Description explains what this value represents. Shown to the model to guide
	// argument generation — be specific and helpful.
	Description string

	// Enum restricts the value to one of the listed strings (only for TypeString).
	Enum []string

	// Properties defines the fields of an object schema (only for TypeObject).
	// Each key is a field name; the value is the field's schema.
	Properties map[string]*Schema

	// Required lists the field names that must be present (only for TypeObject).
	Required []string

	// Items defines the element schema for array types (only for TypeArray).
	Items *Schema

	// Format is an optional format hint (e.g. "date-time", "email", "uri").
	Format string

	// Nullable indicates the value may be null.
	Nullable bool
}

type SchemaType string

type StreamChunk struct {
	// Candidates holds partial or complete candidate data for this chunk.
	Candidates []*Candidate `json:"candidates,omitempty"`

	// Usage is populated on the final chunk with complete token usage statistics.
	Usage *TokenUsage `json:"usageMetadata,omitempty"`

	// Complete is true only on the final chunk, indicating the response is fully received.
	// The final chunk's Candidates and Usage are the source of truth.
	Complete bool `json:"complete,omitempty"`

	// ErrorMessage is set if the stream encountered an error.
	ErrorMessage string `json:"error,omitempty"`
}

type ThinkingConfig struct {
	// Enabled turns on thinking/reasoning mode.
	Enabled bool

	// Budget is the maximum number of thinking tokens the model may use.
	Budget int
}

type TokenUsage struct {
	// PromptTokenCount is the total number of tokens in the input (prompt + history).
	PromptTokenCount int32 `json:"promptTokenCount,omitempty"`

	// CandidatesTokenCount is the total tokens in the model's output (completion).
	CandidatesTokenCount int32 `json:"candidatesTokenCount,omitempty"`

	// TotalTokenCount is PromptTokenCount + CandidatesTokenCount.
	TotalTokenCount int32 `json:"totalTokenCount,omitempty"`

	// CachedContentTokenCount is the number of prompt tokens served from cache.
	CachedContentTokenCount int32 `json:"cachedContentTokenCount,omitempty"`

	// ThoughtsTokenCount is the number of tokens consumed by model reasoning/thinking.
	ThoughtsTokenCount int32 `json:"thoughtsTokenCount,omitempty"`

	// ToolUsePromptTokenCount is the number of prompt tokens attributed to tool definitions.
	ToolUsePromptTokenCount int32 `json:"toolUsePromptTokenCount,omitempty"`

	// TrafficType is a backend-specific traffic classification string.
	TrafficType string `json:"trafficType,omitempty"`

	// CacheTokensDetails breaks down cached tokens by modality.
	CacheTokensDetails []*ModalityTokenCount `json:"cacheTokensDetails,omitempty"`

	// CandidatesTokensDetails breaks down completion tokens by modality.
	CandidatesTokensDetails []*ModalityTokenCount `json:"candidatesTokensDetails,omitempty"`

	// PromptTokensDetails breaks down prompt tokens by modality.
	PromptTokensDetails []*ModalityTokenCount `json:"promptTokensDetails,omitempty"`

	// ToolUsePromptTokensDetails breaks down tool-definition tokens by modality.
	ToolUsePromptTokensDetails []*ModalityTokenCount `json:"toolUsePromptTokensDetails,omitempty"`
}

type Tool interface {
	Name() string
	Declaration() *FunctionDeclaration
	Execute(ctx context.Context, args map[string]any) (*ToolResult, error)
	Options() ToolOptions
}

type ToolOptions struct {
	// SkipSynthesis, when true, causes the executor to return the tool result
	// directly without an additional LLM synthesis turn.
	SkipSynthesis bool
}

type ToolResult struct {
	Response map[string]any
	Error    error
}

type VideoMetadata struct {
	// StartOffset is the start time of the video segment.
	StartOffset time.Duration `json:"startOffset,omitempty"`

	// EndOffset is the end time of the video segment.
	EndOffset time.Duration `json:"endOffset,omitempty"`

	// FPS is the frames-per-second of the video (nil if unspecified).
	FPS *float64 `json:"fps,omitempty"`
}