goagent

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

type CompletionRequest struct {
	// Model is the exact model identifier forwarded to the provider
	// (e.g. "llama3", "qwen3"). Interpretation is provider-specific;
	// the framework passes it through without validation.
	Model string

	// SystemPrompt is the system-level instruction for the model.
	// Providers must forward it using their native mechanism — for
	// OpenAI-compatible APIs this means prepending a system message;
	// for Anthropic it maps to the top-level "system" field.
	// Empty string means no system prompt.
	SystemPrompt string

	// Messages is the conversation history to send, in chronological order.
	// The slice is never nil when sent by Agent, but Provider implementations
	// must handle a nil or empty slice without panicking.
	Messages []Message

	// Tools is the list of tools the model may call during this completion.
	// Nil or empty means no tool use is available for this request.
	// Providers must not error when this field is nil.
	Tools []ToolDefinition

	// Thinking configures extended thinking for this request.
	// nil means thinking is disabled (default behaviour).
	// Providers that do not support thinking must ignore this field.
	Thinking *ThinkingConfig

	// Effort controls the overall effort the model puts into its response,
	// affecting text, tool calls, and thinking (when enabled).
	// Valid values: "high", "medium", "low". Empty string means the model's
	// default (equivalent to "high"). Thinking and Effort are orthogonal —
	// each can be set independently.
	// Providers that do not support effort must ignore this field.
	Effort string
}

type CompletionResponse struct {
	// Message is the model's reply. Role is always RoleAssistant.
	// Content may be empty if the model produced only tool calls.
	// ToolCalls is non-empty when StopReason is StopReasonToolUse.
	Message Message

	// StopReason indicates why the model stopped generating.
	StopReason StopReason

	// Usage reports token consumption for this completion.
	// Providers should populate this when the API returns it;
	// zero values are valid if the backend does not expose token counts.
	Usage Usage
}

type ContentBlock struct {
	Type     ContentType
	Text     string
	Image    *ImageData
	Document *DocumentData
	Thinking *ThinkingData
}

type ContentType string

type DocumentData struct {
	MediaType string // MIME type: "application/pdf", "text/plain"
	Data      []byte // raw document content
	Title     string // optional — gives the model context about the document
}

type Embedder interface {
	Embed(ctx context.Context, content []ContentBlock) ([]float32, error)
}

type Hooks struct {
	// OnIterationStart se invoca al inicio de cada iteración del loop ReAct,
	// antes de llamar al provider.
	// iteration es 0-indexed: la primera iteración es 0.
	OnIterationStart func(iteration int)

	// OnThinking se invoca cuando el modelo produce un bloque de thinking.
	// text es el contenido del razonamiento — puede ser un resumen en Claude 4+
	// o el razonamiento completo en modelos locales y Claude Sonnet 3.7.
	//
	// Se invoca una vez por cada thinking block en la respuesta del modelo.
	// Si la respuesta tiene múltiples thinking blocks (interleaved thinking),
	// se invoca una vez por cada uno, en orden.
	//
	// Solo se invoca si el agente tiene thinking habilitado (WithThinking,
	// WithAdaptiveThinking) o si el modelo local produce thinking.
	OnThinking func(text string)

	// OnToolCall se invoca cuando el modelo solicita ejecutar una herramienta,
	// antes de que el dispatcher la ejecute.
	// Se invoca una vez por cada tool call en la respuesta del modelo.
	// Si el modelo pide N tools en paralelo, se invoca N veces antes del dispatch.
	OnToolCall func(name string, args map[string]any)

	// OnToolResult se invoca después de que una herramienta termina de ejecutarse.
	// content es el resultado que se devolverá al modelo.
	// duration es el tiempo que tardó la ejecución.
	// err es nil si la tool ejecutó exitosamente, o el error si falló.
	//
	// Se invoca incluso cuando la tool falla — err contiene el error.
	// Se invoca una vez por cada tool call, después de que todas terminan.
	OnToolResult func(name string, content []ContentBlock, duration time.Duration, err error)

	// OnResponse se invoca cuando el modelo produce la respuesta final,
	// justo antes de que Run/RunBlocks retorne al caller.
	// text es la respuesta textual extraída (sin thinking blocks).
	// iterations es la cantidad total de iteraciones que usó el loop (1-indexed).
	//
	// También se invoca cuando el loop se agota (MaxIterationsError) —
	// text puede ser "" si la última iteración terminó en tool use.
	OnResponse func(text string, iterations int)

	// OnShortTermLoad se invoca después de que el agente carga el historial de la
	// memoria de corto plazo al inicio de cada Run, tanto en éxito como en error.
	// results es la cantidad de mensajes cargados (0 si err != nil).
	// duration es el tiempo que tardó la operación.
	// err es nil si la carga fue exitosa.
	//
	// Solo se invoca si el agente tiene una ShortTermMemory configurada.
	OnShortTermLoad func(results int, duration time.Duration, err error)

	// OnShortTermAppend se invoca después de que el agente persiste el turno en
	// la memoria de corto plazo al finalizar cada Run, tanto en éxito como en error.
	// msgs es la cantidad de mensajes que se intentó almacenar.
	// duration es el tiempo que tardó la operación.
	// err es nil si el almacenamiento fue exitoso.
	//
	// Solo se invoca si el agente tiene una ShortTermMemory configurada.
	OnShortTermAppend func(msgs int, duration time.Duration, err error)

	// OnLongTermRetrieve se invoca después de que el agente consulta la memoria
	// de largo plazo al inicio de cada Run, tanto en caso de éxito como de error.
	// results es la cantidad de mensajes recuperados (0 si err != nil).
	// duration es el tiempo que tardó la operación de recuperación.
	// err es nil si la recuperación fue exitosa.
	//
	// Solo se invoca si el agente tiene una LongTermMemory configurada.
	OnLongTermRetrieve func(results int, duration time.Duration, err error)

	// OnLongTermStore se invoca después de que el agente persiste un turno en la
	// memoria de largo plazo al finalizar cada Run, tanto en caso de éxito como
	// de error.
	// msgs es la cantidad de mensajes que se intentó almacenar.
	// duration es el tiempo que tardó la operación de almacenamiento.
	// err es nil si el almacenamiento fue exitoso.
	//
	// Solo se invoca si el agente tiene una LongTermMemory configurada y la
	// WritePolicy decidió persistir el turno. No se invoca si la política
	// descarta el turno.
	OnLongTermStore func(msgs int, duration time.Duration, err error)
}

type ImageData struct {
	MediaType string // MIME type: "image/jpeg", "image/png", "image/gif", "image/webp"
	Data      []byte // raw image content
}

type LongTermMemory interface {
	// Store persists msgs for future retrieval.
	Store(ctx context.Context, msgs ...Message) error

	// Retrieve returns the topK messages most semantically similar to the
	// given content. The full []ContentBlock is passed so that embedder
	// implementations that support vision or documents can build a meaningful
	// query vector even when the prompt contains no text.
	Retrieve(ctx context.Context, query []ContentBlock, topK int) ([]Message, error)
}

type MCPConnectorFn func(ctx context.Context, logger *slog.Logger) ([]Tool, io.Closer, error)

type MaxIterationsError struct {
	// Iterations is the budget that was exhausted (set by WithMaxIterations).
	Iterations int

	// LastThought is the text content of the model's last assistant message
	// before the budget ran out. It is empty if the model's last turn
	// produced only tool calls with no accompanying text. Useful for
	// debugging runaway loops or surfacing a partial answer to the user.
	LastThought string
}

type Message struct {
	Role    Role
	Content []ContentBlock

	// ToolCalls is non-empty when the model requests one or more tool
	// invocations. Only set on assistant messages (Role == RoleAssistant).
	ToolCalls []ToolCall

	// ToolCallID is the ID of the ToolCall this message is a result for.
	// Must be set — and must exactly match ToolCall.ID — when Role == RoleTool.
	// The Agent sets this automatically when building tool result messages;
	// Provider implementations must populate ToolCall.ID for the correlation
	// to work correctly.
	ToolCallID string
}

type Option func(*options)

type Provider interface {
	Complete(ctx context.Context, req CompletionRequest) (CompletionResponse, error)
}

type ProviderError struct {
	Provider string
	Cause    error
}

type Role string

type ShortTermMemory interface {
	// Messages returns the messages to include in the next provider request,
	// with the configured read policy applied (e.g. FixedWindow, TokenWindow).
	// The returned slice is a defensive copy; callers may modify it freely.
	Messages(ctx context.Context) ([]Message, error)

	// Append adds msgs to the store in the order provided.
	// Filtering occurs at read time (Messages), never at write time.
	Append(ctx context.Context, msgs ...Message) error
}

type StopReason int

type ThinkingConfig struct {
	Enabled      bool
	BudgetTokens int
}

type ThinkingData struct {
	Thinking  string
	Signature string
}

type Tool interface {
	Definition() ToolDefinition
	Execute(ctx context.Context, args map[string]any) ([]ContentBlock, error)
}

type ToolCall struct {
	// ID is the opaque identifier assigned by the model to this tool call.
	// It must be echoed back in Message.ToolCallID of the corresponding
	// tool result message so the model can correlate the result with the
	// request. Provider implementations must populate this field; leaving
	// it empty will cause the next completion to fail on APIs that enforce
	// the tool call / tool result pairing (e.g. Anthropic, OpenAI).
	ID string

	// Name is the tool name the model wants to invoke, matching the
	// Name field of a registered ToolDefinition.
	Name string

	// Arguments contains the arguments the model supplied for this call,
	// decoded from the provider's JSON payload. Keys match the parameter
	// names defined in ToolDefinition.Parameters.
	Arguments map[string]any
}

type ToolDefinition struct {
	Name        string
	Description string
	Parameters  map[string]any
}

type ToolExecutionError struct {
	ToolName string
	Args     map[string]any
	Cause    error
}

type ToolResult struct {
	ToolCallID string
	Name       string
	Content    []ContentBlock
	Err        error
	// Duration is how long Execute took. It is zero when the tool was not
	// found (ErrToolNotFound) — no execution occurred in that case.
	Duration time.Duration
}

type UnsupportedContentError struct {
	ContentType ContentType
	Provider    string
	Reason      string
}

type Usage struct {
	// InputTokens is the number of tokens in the prompt (including history).
	InputTokens int

	// OutputTokens is the number of tokens in the model's response.
	OutputTokens int
}

type VectorStore interface {
	// Upsert stores or updates a message with its embedding vector.
	// id must be a stable identifier for the message (e.g. content hash).
	Upsert(ctx context.Context, id string, vector []float32, msg Message) error

	// Search returns the topK messages most similar to the given vector.
	Search(ctx context.Context, vector []float32, topK int) ([]Message, error)
}

type WritePolicy func(prompt, response Message) []Message