agent

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

type CacheControl struct {
	Type string `json:"type"` // Type of cache control (e.g. "ephemeral")
}

type Content []MessageContent

type ContentType string

type FakeLLMClient struct {

	// RequestHistory stores all requests made to this client
	RequestHistory []MessagesRequest

	// ResponseDelay adds artificial delay to simulate network latency
	ResponseDelay time.Duration

	// DefaultResponse is used when responses slice is exhausted
	DefaultResponse *MessagesResponse

	// DefaultError is used when errors slice is exhausted (after DefaultResponse)
	DefaultError error

	// TokenCounter function for custom token counting logic
	TokenCounter func(req MessagesRequest) int

	// OnRequest is called for each request, allowing custom behavior
	OnRequest func(ctx context.Context, req MessagesRequest) (*MessagesResponse, error)
	// contains filtered or unexported fields
}

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

type Hooks struct {
	// BeforeRequest is called just before sending a request to the LLM.
	// It can be used to modify or log the request, or to cancel the request by returning an error.
	BeforeRequest func(ctx context.Context, mr MessagesRequest) error

	// OnResponse is called immediately after receiving a response from the LLM,
	// before any tool calls are processed.
	// It can be used to log responses or modify them before further processing.
	OnResponse func(ctx context.Context, resp MessagesResponse) error

	// OnStreamingResponse is called during streaming responses with incremental updates.
	// It receives the full accumulated response for each update during streaming.
	OnStreamingResponse func(ctx context.Context, resp MessagesResponse)

	// BeforeToolRun is called just before executing a tool.
	// It can be used to validate or log tool calls, or to prevent execution by returning an error.
	// If an error is returned, the tool will not be executed and the error will be returned to the agent.
	BeforeToolRun func(ctx context.Context, toolID, toolName string, inputJSON json.RawMessage) error

	// AfterToolRun is called after a tool has been executed, with the result or error.
	// It can be used to log or modify tool results before they're sent back to the LLM.
	AfterToolRun func(ctx context.Context, toolID, toolName string, inputJSON json.RawMessage, output string, other []MessageContent, outErr error) error

	// OnToolResponse is called after a tool has been executed, with the result or error.
	// It can be used to log or modify tool results before they're sent back to the LLM.
	OnToolResponse func(ctx context.Context, toolResponse *Message, err error) error
}

type LLMClient interface {
	// CreateMessages sends a request to the LLM and returns the response.
	// It must handle rate limiting, context cancellation, and other errors
	// as specified above. All provider-specific errors must be wrapped using
	// the appropriate error types defined in this package.
	//
	// If onUpdate is provided, it will be called with incremental updates as the
	// response is generated (streaming). The callback receives the full accumulated
	// response for each update. If nil, the method behaves non-streaming.
	CreateMessages(ctx context.Context, req MessagesRequest, onUpdate func(MessagesResponse)) (MessagesResponse, error)
}

type Message struct {
	Role    Role    `json:"role"`    // Role of the message sender (e.g. "user", "assistant")
	Content Content `json:"content"` // Content blocks for the message
}

type MessageContent struct {
	// Type indicates the kind of content (text, tool_use, tool_result, thinking, etc.)
	Type ContentType `json:"type"`

	// Thinking contains the reasoning/thinking content when Type is ContentTypeThinking
	// This is primarily used with Claude Sonnet and other models supporting thinking chains
	Thinking string `json:"thinking,omitempty"`

	// Signature contains a cryptographic signature for the thinking block when used
	Signature string `json:"signature,omitempty"`

	// MediaType is used to specify what type of image is being sent.
	// Available types are "image/png", "image/jpeg", "image/webp", and "image/gif".
	MediaType string `json:"media_type,omitempty"`

	// Data contains base64 encoded data when Type is ContentTypeImage.
	Data json.RawMessage `json:"data,omitempty"`

	// RedactedThinking contains the redacted thinking content when Type is ContentTypeRedactedThinking
	RedactedThinking string `json:"redacted_thinking,omitempty"`

	// Text contains the plain text content when Type is ContentTypeText
	Text string `json:"text,omitempty"`

	// ToolUse contains tool use information when Type is ContentTypeToolUse
	ToolUse *ToolUse `json:"tool_use,omitempty"`

	// ToolResults contains tool execution results when Type is ContentTypeToolResult
	ToolResults *ToolResult `json:"tool_results,omitempty"`

	// CacheControl contains optional caching directives for this content
	CacheControl *CacheControl `json:"cache_control,omitempty"`
}

type MessagesRequest struct {
	// System is the system prompt that guides the LLM's behavior.
	// This provides high-level instructions to the model about its role and constraints.
	System string `json:"system"`

	// MaxTokens limits the number of tokens the LLM can generate in its response.
	// A value of 0 means the default model limit will be used.
	MaxTokens int `json:"max_tokens"`

	// Messages contains the conversation history in chronological order.
	// This includes previous user messages, assistant responses, and tool interactions.
	Messages []Message `json:"messages"`

	// Tools defines the tools available for the LLM to use in its response.
	// These are presented to the model as capabilities it can invoke.
	Tools []ToolDefinition `json:"tools"`

	// ToolChoice specifies how tools should be chosen:
	// - If nil or Type="auto": Let the LLM decide which tool to use (if any)
	// - If Type="tool" and Name is set: Force the LLM to use that specific tool
	// - If Type="any": Force the LLM to use any tool (implementation-specific)
	ToolChoice *ToolChoice `json:"tool_choice,omitempty"`

	// ThinkingMode enables the LLM to show its reasoning process.
	// This is only supported by certain models (e.g., Claude Sonnet).
	// The provider should ignore this field if it does not support it.
	ThinkingMode bool `json:"thinking_mode,omitempty"`

	// ThinkingTokens specifies how many tokens to allocate for thinking/reasoning.
	// Only applies when ThinkingMode is true. A value of 0 means the default (typically 1024).
	// The provider should ignore this field if it does not support ThinkingMode.
	ThinkingTokens int `json:"thinking_tokens,omitempty"`
}

type MessagesResponse struct {
	// ID is the ID of the response.
	ID string `json:"id"`

	// StopReason is the reason the LLM stopped generating content.
	StopReason string `json:"stop_reason"`

	// Content contains the actual response content from the LLM,
	// which may include text, tool calls, or other content types.
	// The format of this content matches the MessageContent struct and can
	// contain multiple types of responses in a single message.
	Content Content `json:"content"`

	// Usage provides statistics about token consumption and caching metrics
	// from the LLM service, including input, output, and cache-related tokens.
	Usage Usage `json:"usage"`

	// TimeToFirstToken is the time it took for the first token to be generated.
	TimeToFirstToken time.Duration `json:"time_to_first_token"`

	// ResponseTime is the total time it took for the response to be generated.
	ResponseTime time.Duration `json:"response_time"`
}

type Opts struct {
	// Name is the unique identifier for this agent instance.
	// It is only used for logging and metrics.
	Name string

	// SystemPrompt is the system instruction that guides the LLM's behavior.
	// Required - must be non-empty.
	SystemPrompt string

	// Client is the LLM service implementation to use for generating responses.
	// Required - must be a valid implementation of the LLMClient interface.
	Client LLMClient

	// Hooks provides optional callback functions for customizing agent behavior
	// at various points in the conversation lifecycle.
	Hooks Hooks

	// ToolProvider is an optional function that provides tools dynamically on each request.
	// If set, it will be called before each LLM request to get the current list of tools.
	// The tools returned by this function will be merged with the Tools list.
	ToolProvider func() []*Tool

	// Logf is the logging function to use. If nil, defaults to log.Printf.
	// Can be used to integrate with custom logging systems.
	Logf logger.Logf

	// ThinkingTokens specifies how many tokens to allocate for thinking/reasoning.
	// Only applies when ThinkingMode is true. A value of 0 means to use the default value.
	ThinkingTokens int

	// ForceTools restricts the agent to only using tools.
	// When true, the agent will not use the LLM to generate responses.
	ForceTools bool

	// MaxTokens limits the number of tokens in the LLM's response.
	// A value of 0 means to use the default value.
	MaxTokens int

	// MaxContextSize limits how large the agent's context can get before a loop is terminated.
	// If 0, no limit is applied.
	MaxContextSize int

	// MaxToolIterations is the maximum number of iterations for a call to
	// [Agent.Loop]. If 0, no limit is applied.
	MaxToolIterations int
}

type RateLimitError struct {
	// RetryAfter indicates how long to wait before retrying the request
	RetryAfter time.Duration
	// Err is the underlying error, typically wrapping ErrRateLimit
	Err error
}

type Role string

type TokenCounter interface {
	// CountTokens analyzes the request and returns the estimated number of tokens it would use.
	// This is useful for:
	// 1. Estimating costs before making expensive API calls
	// 2. Preventing requests that would exceed token limits
	// 3. Optimizing prompts by analyzing token usage
	//
	// If the implementation cannot count tokens accurately, it should return an error.
	CountTokens(ctx context.Context, req MessagesRequest) (int, error)
}

type Tool struct {
	// Name is the name of the tool.
	Name string
	// Desc is the description of the tool.
	Desc string

	// Schema is the JSON schema for the tool's input.
	Schema string

	// Handler is the function that will be called when the tool is used. It
	// must be set.
	Handler toolUseHandler
	// contains filtered or unexported fields
}

type ToolChoice struct {
	// Type determines the tool selection strategy:
	// - "auto": Let the LLM decide which tool to use (if any)
	// - "tool": Force the LLM to use the specific tool named in the Name field
	// - "any": Force the LLM to use any tool (implementation-specific behavior)
	Type string `json:"type"`

	// Name is the specific tool name to use when Type is "tool".
	// This field is required when Type is "tool" and ignored otherwise.
	Name string `json:"name"`
}

type ToolDefinition struct {
	Name        string          `json:"name"`         // Name of the tool
	Description string          `json:"description"`  // Human-readable description of what the tool does
	InputSchema json.RawMessage `json:"input_schema"` // JSON schema describing the input parameters
}

type ToolHandler[Req any] func(ctx context.Context, req Req) (string, []MessageContent, error)

type ToolResult struct {
	Name       string `json:"tool_name"`    // Name of the tool
	ToolCallID string `json:"tool_call_id"` // ID of the tool call these results are for
	Output     string `json:"output"`       // Output from the tool
	Error      bool   `json:"error"`        // Whether this output represents an error
}

type ToolSpec[T any] struct {
	Name        string              // Name of the tool
	Description string              // Full description for the LLM
	Summary     func(args T) string // Function to generate a summary of the tool invocation
	Handler     ToolHandler[T]      // The handler function for the tool
}

type ToolUse struct {
	ID    string          `json:"id"`    // Unique identifier for this tool use
	Name  string          `json:"name"`  // Name of the tool
	Input json.RawMessage `json:"input"` // Input parameters for the tool
}

type Usage struct {
	InputTokens              int `json:"input_tokens"`
	OutputTokens             int `json:"output_tokens"`
	CacheCreationInputTokens int `json:"cache_creation_input_tokens"`
	CacheReadInputTokens     int `json:"cache_read_input_tokens"`
}