sdk

type ActionSpec struct {
	// Name is the identifier for this action (e.g., "get_tides").
	Name string

	// Description explains what this action does.
	Description string

	// Input is the JSON schema for the action's input parameters.
	Input Schema

	// Output is the JSON schema for the action's response.
	Output Schema
}

type AgentDiscoveryConfig struct {
	// Enabled activates agent discovery in the loop.
	Enabled bool

	// MaxAgents is the maximum number of agents to discover per iteration (default: 3).
	MaxAgents int

	// MinScore is the minimum similarity score for agent inclusion (default: 0.5).
	MinScore float64

	// ShareContext sends caller conversation context to delegates.
	ShareContext bool

	// Budget limits resource consumption for each delegation.
	Budget *TaskBudget

	// AgentFilter excludes agents from discovery.
	// Called for each discovered agent; return false to exclude.
	AgentFilter func(agent AgentMatch) bool

	// OnDelegateEvent is called for each streaming event during agent delegation.
	// When set, the loop uses DelegateToAgentStream instead of DelegateToAgent,
	// enabling real-time visibility into the sub-agent's internal activity.
	// The agentName parameter identifies which agent produced the event.
	OnDelegateEvent func(agentName string, event DelegateEvent)
}

type AgentInfo struct {
	// Name is the agent's unique identifier.
	Name string

	// Description explains what the agent does.
	Description string

	// Capabilities lists the agent's capability tags.
	Capabilities []string

	// Actions lists available actions.
	Actions []ActionSpec

	// Stats contains performance statistics.
	Stats AgentStats
}

type AgentInstance interface {
	// Handle processes an incoming message and returns a response.
	// This is the main entry point for agentic logic.
	Handle(ctx context.Context, msg Message) (Response, error)

	// Start is called when the app instance is initialized.
	// Use this for any setup that needs to happen before handling messages.
	Start() error

	// Stop is called when the app instance is being shut down.
	// Use this for cleanup operations.
	Stop() error
}

type AgentMatch struct {
	// Agent contains the agent information.
	AgentInfo

	// Score is the semantic similarity score (0.0-1.0, higher is more relevant).
	Score float64
}

type AgentModeSpec struct {
	// Instruction describes what this agent does when delegated to.
	// Shown to calling LLMs for routing decisions.
	Instruction string

	// Skills are discrete capabilities the agent offers for delegation.
	Skills []AgentSkill

	// AcceptsContext signals that this agent uses caller conversation context.
	AcceptsContext bool

	// Streaming signals that this agent streams output during processing.
	Streaming bool

	// InputSchema defines optional structured parameters on top of the prompt.
	InputSchema *Schema

	// OutputSchema defines guaranteed output structure (if any).
	OutputSchema *Schema

	// MaxDuration is the estimated maximum processing time.
	MaxDuration time.Duration
}

type AgentPlugin interface {
	// Spec returns the app's specification including name, description,
	// capabilities, and available actions.
	Spec() AgenticAppSpec

	// New creates a new instance of the app with the given platform context.
	// The platform context provides access to LLM, RAG, routing, and logging.
	New(ctx PlatformContext) (AgentInstance, error)
}

type AgentRouter interface {
	// Call invokes another agent by capability or name.
	// The router selects the best available agent based on relevance,
	// reputation, latency, and cost.
	Call(ctx context.Context, query string, content string, opts ...CallOption) (Response, error)

	// CallWithTrace invokes an agent and returns detailed call metadata.
	// Use this when you need to track agent calls for debugging or auditing.
	CallWithTrace(ctx context.Context, query string, content string, opts ...CallOption) (CallResult, error)

	// CallAgent invokes a specific agent by name.
	// Use this when you need a specific agent rather than capability-based routing.
	CallAgent(ctx context.Context, agentName string, msg Message) (Response, error)

	// Discover finds agents matching a capability query.
	// Returns agent information without invoking them.
	Discover(ctx context.Context, query string, opts ...DiscoverOption) ([]AgentInfo, error)

	// Search performs semantic search to find agents matching a natural language query.
	// Uses embeddings to find semantically similar agents based on their description,
	// capabilities, and actions. Returns agents ranked by relevance score.
	Search(ctx context.Context, query string, opts ...DiscoverOption) ([]AgentMatch, error)

	// SearchTools performs semantic search to find tools (agent actions) matching a query.
	// Unlike Search which returns agents, this returns individual tools that can be
	// used for LLM function calling. Tools from multiple agents may be returned.
	SearchTools(ctx context.Context, query string, opts ...DiscoverOption) ([]ToolMatch, error)

	// CallTool invokes a specific tool by its ID (format: "agent_name/action_name").
	// This is used by the agentic loop to execute tool calls from the LLM.
	CallTool(ctx context.Context, toolID string, args map[string]any) (Response, error)

	// Delegate submits a task to the best matching agent.
	// Returns immediately with a Task in "submitted" state.
	// Use Events() or Tasks() to track progress.
	Delegate(ctx context.Context, req DelegateRequest) (*Task, error)

	// DelegateSync submits a task and blocks until completion.
	// Convenience wrapper around Delegate + wait.
	DelegateSync(ctx context.Context, req DelegateRequest) (*Task, error)

	// DelegateToAgent submits a task to a specific agent by name.
	DelegateToAgent(ctx context.Context, agentName string, req DelegateRequest) (*Task, error)

	// DelegateToAgentStream submits a task to a specific agent and streams
	// intermediate events (tool calls, LLM usage) back to the caller via handler.
	// Falls back to DelegateToAgent if the gateway doesn't support streaming.
	DelegateToAgentStream(ctx context.Context, agentName string, req DelegateRequest, handler DelegateEventHandler) (*Task, error)

	// SearchAgents finds agents available for delegation (AgentMode != nil).
	// Uses semantic search over agent instructions and skills.
	SearchAgents(ctx context.Context, query string, opts ...DiscoverOption) ([]AgentMatch, error)

	// RespondToTask sends additional input to a task in "input_needed" state.
	RespondToTask(ctx context.Context, taskID string, input []Part) error

	// CancelTask requests cancellation of a running task.
	CancelTask(ctx context.Context, taskID string) error

	// ReportToolFeedback sends a usage feedback signal for a tool.
	// outcome is "useful" or "irrelevant". This is fire-and-forget;
	// implementations should not block on errors.
	ReportToolFeedback(ctx context.Context, toolID string, outcome string)
}

type AgentSkill struct {
	// Name is a short identifier (e.g., "web-search", "weather-forecast").
	Name string `json:"name"`

	// Description explains what this skill does (shown to LLMs).
	Description string `json:"description"`

	// Tags are optional labels for filtering (e.g., ["search", "web"]).
	Tags []string `json:"tags,omitempty"`
}

type AgentStats struct {
	// SuccessRate is the percentage of successful calls (0.0-1.0).
	SuccessRate float64

	// AvgLatencyMs is the average response time in milliseconds.
	AvgLatencyMs float64

	// AvgCost is the average cost per request (in platform credits).
	AvgCost float64
}

type AgenticAppSpec struct {
	// AppId is the Roobai app instance identifier (e.g., "citron-benet-21").
	// This is set automatically by the platform at runtime and should not be
	// set by the developer. It's used for agent registration and routing.
	AppId string

	// Name is the unique identifier for this app (e.g., "tide-finder").
	Name string

	// Description is a human-readable description of what the app does.
	Description string

	// Version is the semantic version of the app (e.g., "1.0.0").
	Version string

	// Avatar is an emoji that represents this agent (e.g., "🌤️", "📰", "🤖").
	// Must be a single emoji. Used in UIs like PocketChat for visual identification.
	// Use sdk.MustEmoji("🤖") to create, or leave empty for default.
	Avatar Emoji

	// Capabilities is a list of capability tags for discovery (e.g., ["websearch", "weather"]).
	Capabilities []string

	// Actions is the list of actions this app can perform.
	Actions []ActionSpec

	// CustomUI indicates the app provides its own web UI at "/".
	// If false, the platform provides a default landing page.
	CustomUI bool

	// AgentMode declares this agent as available for delegation.
	// When non-nil, the agent appears in delegation searches and can be
	// invoked via router.Delegate* methods. See AgentModeSpec for details.
	// Nil means the agent is tool-only (existing behavior).
	AgentMode *AgentModeSpec
}

type Artifact struct {
	// ID is the platform-assigned artifact identifier.
	ID string `json:"id"`

	// Name is a human-readable name for this artifact (e.g., "market-analysis").
	Name string `json:"name"`

	// Parts is the artifact's content.
	Parts []Part `json:"parts"`

	// Metadata carries additional artifact-level key-value pairs.
	Metadata map[string]string `json:"metadata,omitempty"`

	// TaskID is the ID of the task that produced this artifact.
	TaskID string `json:"taskId"`

	// Index is the artifact's position within the task (0-based).
	Index int `json:"index"`
}

type ArtifactBuilder struct {
	// Name is a human-readable name for the artifact.
	Name string

	// Parts is the artifact's content.
	Parts []Part

	// Metadata carries additional artifact-level key-value pairs.
	Metadata map[string]string
}

type BlobInfo struct {
	// Name is the blob identifier.
	Name string

	// Size is the blob size in bytes.
	Size int64

	// MimeType is the content type (e.g., "image/png").
	MimeType string

	// CreatedAt is when the blob was stored.
	CreatedAt time.Time

	// Metadata carries user-defined key-value pairs.
	Metadata map[string]string
}

type BlobOption func(*BlobOptions)

type BlobOptions struct {
	// MimeType sets the content type of the blob.
	MimeType string

	// TTL sets the time-to-live. Zero means no expiration.
	TTL time.Duration

	// Metadata sets user-defined key-value pairs on the blob.
	Metadata map[string]string
}

type BlobStore interface {
	// Put stores a blob and returns its metadata.
	// The name must be unique within the store.
	Put(ctx context.Context, name string, reader io.Reader, opts ...BlobOption) (*BlobInfo, error)

	// Get retrieves a blob by name.
	// Returns the content reader and metadata.
	// The caller must close the reader when done.
	Get(ctx context.Context, name string) (io.ReadCloser, *BlobInfo, error)

	// Delete removes a blob by name.
	Delete(ctx context.Context, name string) error

	// List returns metadata for all blobs in the store.
	List(ctx context.Context) ([]BlobInfo, error)
}

type CallOption func(*CallOptions)

type CallOptions struct {
	// Action specifies which action to invoke on the target agent.
	Action string

	// MaxLatencyMs sets the maximum acceptable latency for agent selection.
	MaxLatencyMs int

	// MaxCost sets the maximum acceptable cost for agent selection.
	MaxCost float64

	// Timeout overrides the default call timeout.
	TimeoutMs int
}

type CallResult struct {
	// Response is the agent's response.
	Response Response

	// Agent is the name of the agent that handled the request.
	Agent string

	// Query is the query/capability used to route the request.
	Query string

	// Duration is how long the call took.
	Duration time.Duration

	// Request contains the original request parameters.
	Request map[string]any
}

type ChatMessage struct {
	// Role is the message role: "system", "user", "assistant", or "tool".
	Role string

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

	// ToolCalls contains tool invocations when role is "assistant".
	// Only set when the model wants to call tools.
	ToolCalls []ToolCall

	// ToolCallID is set when role is "tool" to link the response to a tool call.
	ToolCallID string

	// Name is set when role is "tool" to identify which tool this response is from.
	Name string
}

type ChatOption func(*ChatOptions)

type ChatOptions struct {
	// Model specifies a preferred model (may be overridden by platform).
	Model string

	// Provider specifies which LLM provider to use (e.g. "copilot", "ovh").
	// If empty, the platform uses the user's configured default provider.
	Provider string

	// MaxTokens limits the response length.
	MaxTokens int

	// Temperature controls randomness (0.0 = deterministic, 1.0 = creative).
	Temperature float64

	// TopP controls nucleus sampling probability.
	TopP float64

	// Stop sequences that will halt generation.
	Stop []string

	// Tools is a list of tools the model can call.
	Tools []Tool

	// ToolChoice controls how the model uses tools.
	// "auto" (default) = model decides, "none" = disable tools, "required" = must use a tool.
	ToolChoice string

	// StreamCallback is called for each chunk during streaming.
	// If set, the Chat method will use streaming mode.
	StreamCallback StreamCallback

	// ResponseFormat controls the format of the LLM's response.
	// Use this to enforce structured output via JSON schema.
	ResponseFormat *ResponseFormat
}

type ChatResponse struct {
	// Content is the assistant's response text.
	// May be empty if the response contains only tool calls.
	Content string

	// ToolCalls contains tool invocations requested by the model.
	// When non-empty, the caller should execute these tools and send results back.
	ToolCalls []ToolCall

	// FinishReason indicates why the response ended.
	// "stop" = normal completion, "tool_calls" = model wants to call tools, "length" = max tokens reached.
	FinishReason string

	// Usage contains token usage statistics.
	Usage TokenUsage
}

type ContentPrefs struct {
	Accept []ContentType `json:"accept,omitempty"`
}

type ContentType string

type DelegateEvent struct {
	Type   DelegateEventType `json:"type"`
	TaskID string            `json:"task_id"`
	Data   map[string]any    `json:"data"`
}

type DelegateEventHandler func(event DelegateEvent)

type DelegateEventType string

type DelegateRequest struct {
	// Prompt is the task description in natural language.
	Prompt string

	// Parts allows multipart input (alternative to Prompt for rich content).
	// If both are set, Prompt is prepended as a text Part.
	Parts []Part

	// ContextID links this task to an existing conversation context.
	ContextID string

	// Params are optional structured parameters (matched against InputSchema).
	Params map[string]any

	// Context provides conversation context from the caller to the delegate.
	Context *DelegationContext

	// ContentPrefs declares which output content types the caller accepts.
	ContentPrefs *ContentPrefs

	// Budget limits the delegate's resource consumption.
	Budget *TaskBudget

	// Async controls whether the task runs asynchronously.
	// When true, Delegate returns immediately with a submitted task.
	// When false (default for DelegateSync), blocks until completion.
	Async bool
}

type DelegationContext struct {
	// Summary of the caller's ongoing conversation.
	Summary string

	// RecentMessages from the caller's conversation.
	RecentMessages []ChatMessage

	// Constraints imposed by the caller.
	Constraints map[string]string
}

type DiscoverOption func(*DiscoverOptions)

type DiscoverOptions struct {
	// Limit is the maximum number of agents to return.
	Limit int

	// Capabilities filters to agents with specific capabilities.
	Capabilities []string

	// Context provides conversation context to enrich the search embedding.
	// When set, the search query is augmented with this context to improve
	// relevance (e.g., the ongoing conversation summary or user intent).
	Context string

	// RecentTools lists tool IDs that were recently used. The search engine
	// uses this to bias results toward complementary tools, avoiding
	// redundant suggestions.
	RecentTools []string

	// ExcludeTools lists tool IDs (or agent: prefixed agent names) to exclude
	// from results. Used to prevent re-discovery of tools already tried in
	// the current loop iteration.
	ExcludeTools []string
}

type Document struct {
	// ID is a unique identifier for the document.
	// If empty, one will be generated.
	ID string

	// Content is the document text to be embedded and searched.
	Content string

	// Metadata contains additional fields for filtering and display.
	Metadata map[string]string
}

type DocumentMeta struct {
	// ID is the document identifier.
	ID string

	// Metadata contains the document's metadata fields.
	Metadata map[string]string

	// CreatedAt is when the document was stored.
	CreatedAt int64
}

type Emoji string

type ErrorHandler struct {
	// MaxConsecutiveErrors stops the loop after N consecutive tool errors.
	// Default: 3
	MaxConsecutiveErrors int

	// FormatError transforms error messages before adding to conversation.
	// If nil, uses default formatting.
	FormatError func(err error) string

	// FallbackResponse is returned if max iterations or errors reached.
	// If empty, returns an error instead.
	FallbackResponse string
}

type Event struct {
	// ID is a unique event identifier.
	ID string `json:"id"`

	// Type identifies the kind of event.
	Type EventType `json:"type"`

	// Source is the agent that produced this event.
	Source string `json:"source"`

	// TaskID is the associated task (empty for agent lifecycle events).
	TaskID string `json:"taskId,omitempty"`

	// Timestamp is the Unix timestamp (seconds) when the event was created.
	Timestamp int64 `json:"timestamp"`

	// Data carries the event-specific payload.
	Data any `json:"data"`
}

type EventType string

type Field struct {
	Key   string
	Value any
}

type FileRef struct {
	// FileID is the platform-assigned file identifier.
	FileID string `json:"fileId"`

	// FileName is the original file name.
	FileName string `json:"fileName,omitempty"`

	// MimeType is the file's MIME type.
	MimeType string `json:"mimeType,omitempty"`

	// Size is the file size in bytes.
	Size int64 `json:"size,omitempty"`
}

type FinishReason string

type FunctionCall struct {
	// Name is the function/tool name to invoke.
	Name string

	// Arguments is a JSON string containing the function arguments.
	Arguments string
}

type FunctionDef struct {
	// Name is the function name (should match action names).
	Name string

	// Description explains what the function does.
	Description string

	// Parameters is the JSON Schema for the function's parameters.
	Parameters map[string]any
}

type InputOption func(*Schema)

type LLMClient interface {
	// Chat sends a conversation to the LLM and returns the response.
	// If [WithStreamCallback] is provided, the response is streamed chunk by chunk.
	Chat(ctx context.Context, messages []ChatMessage, opts ...ChatOption) (ChatResponse, error)

	// ChatStream sends a conversation to the LLM and streams the response.
	// Each chunk of content is passed to the callback as it arrives.
	// Returns the complete response after streaming finishes.
	ChatStream(ctx context.Context, messages []ChatMessage, callback StreamCallback, opts ...ChatOption) (ChatResponse, error)

	// Complete generates a completion for the given prompt.
	// This is a convenience method equivalent to a single-message chat.
	Complete(ctx context.Context, prompt string, opts ...ChatOption) (string, error)

	// Embed generates vector embeddings for the given texts.
	// Useful for semantic search and RAG applications.
	Embed(ctx context.Context, texts []string) ([][]float64, error)
}

type Logger interface {
	// Debug logs a debug-level message.
	Debug(msg string, fields ...Field)

	// Info logs an info-level message.
	Info(msg string, fields ...Field)

	// Warn logs a warning-level message.
	Warn(msg string, fields ...Field)

	// Error logs an error-level message.
	Error(msg string, fields ...Field)

	// With returns a logger with the given fields added to all messages.
	With(fields ...Field) Logger
}

type LoopCallbacks interface {
	// OnLoopStart is called when the loop begins.
	OnLoopStart(ctx context.Context, input string, tools []Tool)

	// OnLoopEnd is called when the loop completes (success or failure).
	OnLoopEnd(ctx context.Context, result *LoopResult, err error)

	// OnIteration is called at the start of each loop iteration.
	OnIteration(ctx context.Context, iteration int, steps []Step)

	// OnToolStart is called before executing a tool.
	OnToolStart(ctx context.Context, action ToolAction)

	// OnToolEnd is called after a tool completes (success or failure).
	OnToolEnd(ctx context.Context, action ToolAction, result string, err error, duration time.Duration)

	// OnLLMStart is called before sending messages to the LLM.
	OnLLMStart(ctx context.Context, messages []ChatMessage)

	// OnLLMEnd is called after receiving an LLM response.
	OnLLMEnd(ctx context.Context, response string, usage TokenUsage)

	// OnStreamChunk is called for each streaming chunk from the LLM.
	// Return an error to abort streaming.
	OnStreamChunk(ctx context.Context, chunk []byte) error
}

type LoopConfig struct {
	// SystemPrompt sets the system instructions for the LLM.
	// Tool instructions will be appended automatically.
	SystemPrompt string

	// Tools are the tools available for the LLM to call.
	// If empty, tools are discovered via semantic search using the prompt.
	Tools []Tool

	// MaxIterations limits the number of loop iterations (default: 10).
	// Each iteration may include multiple tool calls.
	MaxIterations int

	// MaxTokens limits the response length per LLM call.
	MaxTokens int

	// Temperature controls LLM randomness (0.0 = deterministic, 1.0 = creative).
	Temperature float64

	// ToolSearchQuery is used to discover tools if Tools is empty.
	// If empty, the user prompt is used for tool discovery.
	ToolSearchQuery string

	// MinToolScore filters tools below this similarity threshold (default: 0.3).
	MinToolScore float64

	// Model specifies which LLM model to use.
	// If empty, the gateway applies its configured default (see /v1/preferences).
	Model string

	// Memory for conversation persistence.
	// If provided, previous messages are loaded and new messages are saved.
	Memory Memory

	// MaxHistoryMessages limits how many history messages to load (default: 10 pairs).
	// Only used when Memory is provided.
	MaxHistoryMessages int

	// ToolFilter excludes tools from discovery.
	// Called for each discovered tool; return false to exclude.
	// Useful for excluding the agent's own tools to prevent recursion.
	ToolFilter ToolFilter

	// Callbacks for observability and streaming.
	Callbacks LoopCallbacks

	// ErrorHandler for graceful error recovery.
	ErrorHandler *ErrorHandler

	// ParallelToolCalls enables concurrent tool execution (default: true).
	ParallelToolCalls *bool

	// MaxParallelCalls limits concurrent tool executions (default: 5).
	MaxParallelCalls int

	// ReturnIntermediateSteps includes Steps in result.
	ReturnIntermediateSteps bool

	// Stream enables streaming mode for LLM responses.
	// When enabled, chunks are passed to Callbacks.OnStreamChunk as they arrive.
	Stream bool

	// ConfidenceThreshold is the minimum confidence (0-100) required to end the loop
	// with a final response. If the LLM's confidence is below this and no tool calls
	// are made, the loop will prompt the LLM to use tools.
	// Default: 80
	ConfidenceThreshold int

	// AgentDiscovery configures discovery and delegation of other agents
	// within the agentic loop. When enabled, discovered agents are presented
	// to the LLM as callable functions alongside tools.
	// Nil means tool-only discovery (existing behavior).
	AgentDiscovery *AgentDiscoveryConfig
}

type LoopResult struct {
	// Content is the final response from the LLM.
	Content string

	// ToolCalls records all tool invocations during the loop.
	ToolCalls []ToolCallResult

	// Iterations is the number of loop iterations executed.
	Iterations int

	// Usage contains aggregated token usage across all LLM calls.
	Usage TokenUsage

	// Duration is the total time spent in the loop.
	Duration time.Duration

	// Steps contains all intermediate steps (if ReturnIntermediateSteps=true).
	Steps []Step

	// FinishReason indicates why the loop ended.
	FinishReason FinishReason
}

type Memory interface {
	// LoadMessages returns previous conversation messages.
	LoadMessages(ctx context.Context) ([]ChatMessage, error)

	// SaveMessages appends new messages to memory.
	SaveMessages(ctx context.Context, messages []ChatMessage) error

	// Clear resets the memory.
	Clear(ctx context.Context) error
}

type Message struct {
	// ID is a unique identifier for this message.
	ID string

	// Action is the name of the action being invoked (from ActionSpec.Name).
	// May be empty for general messages.
	Action string

	// Content is the main payload of the message.
	Content string

	// Params contains structured input parameters (JSON-decoded from Input schema).
	Params map[string]any

	// Metadata contains additional context about the message.
	Metadata map[string]string

	// Parts carries rich, typed content. When non-empty, this is the
	// primary content and Content is ignored. When empty, Content is
	// treated as a single text Part for backward compatibility.
	Parts []Part
}

type MessageBus interface {
	// Request sends a message and waits for a single reply.
	// Used for synchronous RPC (tool calls, discovery, delegation).
	// Returns ErrTimeout if no reply arrives within timeout.
	Request(ctx context.Context, subject string, data []byte, timeout time.Duration) ([]byte, error)

	// Publish sends a fire-and-forget message to a subject.
	// Used for events, signals, and notifications.
	Publish(ctx context.Context, subject string, data []byte) error

	// Subscribe listens for messages on a subject pattern.
	// Supports NATS wildcards: * (single token), > (multiple tokens).
	Subscribe(ctx context.Context, subject string, handler MsgHandler) (Subscription, error)

	// QueueSubscribe listens with load balancing across a named group.
	// Only one subscriber in the queue group receives each message.
	// Used by agents to distribute incoming RPC across instances.
	QueueSubscribe(ctx context.Context, subject string, queue string, handler MsgHandler) (Subscription, error)
}

type Msg struct {
	// Subject the message was published to.
	Subject string

	// Data is the raw payload.
	Data []byte

	// Reply is the reply subject for request/reply patterns.
	// Empty for pub/sub messages.
	Reply string

	// Header carries metadata (trace IDs, caller identity, etc.).
	Header map[string][]string
}

type MsgHandler func(msg Msg)

type NoopCallbacks struct{}

type Part struct {
	// Type identifies the kind of content this part carries.
	Type ContentType `json:"type"`

	// MimeType is the MIME type of the content (e.g., "application/json", "image/png").
	MimeType string `json:"mimeType,omitempty"`

	// Text is the content for text parts.
	Text string `json:"text,omitempty"`

	// Data is structured content for json parts.
	Data map[string]any `json:"data,omitempty"`

	// FileRef references a platform-stored file.
	FileRef *FileRef `json:"fileRef,omitempty"`

	// Inline carries small binary content (e.g., small images) as raw bytes.
	// JSON-encoded as base64.
	Inline []byte `json:"inline,omitempty"`

	// Metadata carries additional key-value pairs about the content.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type PlatformContext interface {
	// LLM returns a client for interacting with language models.
	LLM() LLMClient

	// RAG returns a client for retrieval-augmented generation storage.
	RAG() RAGClient

	// Router returns a client for calling other agents.
	Router() AgentRouter

	// Logger returns a structured logger for the agent.
	Logger() Logger

	// Config returns configuration values set for this agent.
	Config() map[string]string

	// App returns the PocketBase app instance for direct database/route access.
	// Use this to create collections, register custom routes, and query data.
	// Returns nil if not running in PocketBase context.
	App() any

	// SDK returns the SDK instance for high-level agentic functionality.
	// Use this for RunLoop, memory creation, and other SDK utilities.
	SDK() SDK

	// MessageBus returns the NATS message bus for inter-agent communication,
	// events, and request/reply patterns. This is the unified transport for
	// all internal platform messaging.
	MessageBus() MessageBus

	// Blobs returns the blob store for transferring large binary objects
	// (files, images, audio) between agents via NATS Object Store.
	Blobs() BlobStore

	// Tasks returns the task store for querying task history.
	// Backed by the agent's PocketBase database.
	Tasks() TaskStore
}

type Progress struct {
	// Stage is a short label for the current stage (e.g., "searching", "analyzing").
	Stage string `json:"stage"`

	// Percent is the completion percentage (0.0–1.0).
	Percent float64 `json:"percent,omitempty"`

	// Message is a human-readable progress description.
	Message string `json:"message,omitempty"`
}

type PropertyOption func(*propertyBuilder)

type QueryOption func(*QueryOptions)

type QueryOptions struct {
	// Limit is the maximum number of results to return.
	Limit int

	// MinScore filters out results below this similarity threshold.
	MinScore float64

	// Filter restricts results to documents matching these metadata fields.
	Filter map[string]string
}

type RAGClient interface {
	// Store adds a document to the RAG store.
	// The document will be automatically chunked and embedded.
	Store(ctx context.Context, doc Document) error

	// Query performs a semantic search and returns relevant documents.
	// Results are ordered by relevance (most relevant first).
	Query(ctx context.Context, query string, opts ...QueryOption) ([]SearchResult, error)

	// Delete removes a document by ID.
	Delete(ctx context.Context, id string) error

	// List returns all documents (without content, for indexing purposes).
	List(ctx context.Context) ([]DocumentMeta, error)
}

type Response struct {
	// Content is the main response payload.
	Content string

	// Data contains structured response data (will be JSON-encoded).
	Data map[string]any

	// Metadata contains additional context about the response.
	Metadata map[string]string

	// Error is set if the agent encountered an error processing the message.
	// When set, Content and Data may be empty.
	Error string

	// Parts carries rich, typed output content. When non-empty, this is
	// the primary output and Content is ignored. When empty, Content is
	// treated as a single text Part for backward compatibility.
	Parts []Part

	// Artifacts are named outputs produced during handling.
	Artifacts []Artifact
}

type ResponseFormat struct {
	// Type is the response format type.
	// - "text": Default, plain text response
	// - "json_object": Basic JSON mode (any valid JSON)
	// - "json_schema": Strict schema-enforced JSON
	Type string `json:"type"`

	// JSONSchema is required when Type is "json_schema".
	// Defines the exact structure the LLM must output.
	JSONSchema *ResponseFormatJSONSchema `json:"json_schema,omitempty"`
}

type ResponseFormatJSONSchema struct {
	// Name is a unique identifier for the schema.
	Name string `json:"name"`

	// Strict enables strict schema enforcement.
	// When true, the output MUST match the schema exactly.
	Strict bool `json:"strict"`

	// Schema is the JSON Schema definition.
	Schema map[string]any `json:"schema"`

	// Description provides context about what this schema represents.
	Description string `json:"description,omitempty"`
}

type SDK interface {
	// RunLoop executes an agentic tool-use loop.
	//
	// The loop orchestrates LLM calls and tool execution:
	//  1. Discovers tools via semantic search (if not provided in config)
	//  2. Sends prompt to LLM with tool descriptions
	//  3. Parses tool calls from LLM response
	//  4. Executes tools (parallel or sequential)
	//  5. Sends results back to LLM
	//  6. Repeats until LLM provides final response or max iterations
	//
	// Example:
	//
	//	result, err := pctx.SDK().RunLoop(ctx, sdk.LoopConfig{
	//	    SystemPrompt:  "You are a helpful assistant.",
	//	    MaxIterations: 5,
	//	    Model:         "", // uses gateway default
	//	}, userMessage)
	RunLoop(ctx context.Context, config LoopConfig, userPrompt string) (LoopResult, error)

	// NewSimpleMemory creates an in-memory message store.
	// Messages are kept until explicitly cleared.
	NewSimpleMemory() Memory

	// NewWindowMemory creates a windowed memory that keeps the last N message pairs.
	// Older messages are discarded when the window is exceeded.
	NewWindowMemory(windowSize int) Memory

	// NewSummaryBufferMemory creates a hybrid memory that keeps recent messages
	// in full and summarizes older messages via LLM.
	// Returns [SummaryMemory] which has additional methods for summary access.
	NewSummaryBufferMemory(config SummaryBufferConfig) SummaryMemory

	// NewLoggingCallbacks creates callbacks that log loop events to the provided logger.
	// Useful for debugging and development.
	NewLoggingCallbacks(logger Logger) LoopCallbacks

	// NewSessionMemory creates a session-scoped memory store.
	//
	// When running inside PocketBase, messages are persisted to
	// agentic_conversations + agentic_messages collections and survive
	// app restarts. When PocketBase is not available, falls back to
	// in-memory storage (same as NewSimpleMemory).
	//
	// The sessionID groups messages into a conversation. Use a stable
	// identifier (e.g., user ID, chat thread ID) so the same session
	// can be resumed across requests.
	NewSessionMemory(sessionID string) Memory

	// NewSessionWindowMemory creates a session-scoped windowed memory.
	//
	// Like NewSessionMemory but only loads the last windowSize message
	// pairs (user + assistant). Older messages are still persisted but
	// not returned by LoadMessages.
	NewSessionWindowMemory(sessionID string, windowSize int) Memory

	// NewSessionSummaryMemory creates a session-scoped summary buffer memory.
	//
	// Combines persistence with LLM-powered summarization. Recent messages
	// are kept in full, older messages are summarized. Both the summary
	// and recent messages are persisted across restarts.
	NewSessionSummaryMemory(sessionID string, config SummaryBufferConfig) SummaryMemory
}

type Schema struct {
	// Type is the JSON Schema type (e.g., "object", "string", "number", "array", "boolean", "integer").
	Type string `json:"type,omitempty"`

	// Title provides a short title for the schema.
	Title string `json:"title,omitempty"`

	// Description provides human-readable documentation for the schema.
	Description string `json:"description,omitempty"`

	// Properties defines the fields for object types.
	// Keys are property names, values are their schemas.
	Properties map[string]Schema `json:"properties,omitempty"`

	// Required lists the names of required properties for object types.
	Required []string `json:"required,omitempty"`

	// Items defines the schema for array element types.
	Items *Schema `json:"items,omitempty"`

	// Enum restricts the value to one of the specified options.
	Enum []any `json:"enum,omitempty"`

	// Default specifies the default value for this schema.
	Default any `json:"default,omitempty"`

	// Pattern is a regex pattern for string validation.
	Pattern string `json:"pattern,omitempty"`

	// MinLength is the minimum string length.
	MinLength *int `json:"minLength,omitempty"`

	// MaxLength is the maximum string length.
	MaxLength *int `json:"maxLength,omitempty"`

	// Minimum is the minimum numeric value (inclusive).
	Minimum *float64 `json:"minimum,omitempty"`

	// Maximum is the maximum numeric value (inclusive).
	Maximum *float64 `json:"maximum,omitempty"`

	// ExclusiveMinimum is the exclusive minimum numeric value.
	ExclusiveMinimum *float64 `json:"exclusiveMinimum,omitempty"`

	// ExclusiveMaximum is the exclusive maximum numeric value.
	ExclusiveMaximum *float64 `json:"exclusiveMaximum,omitempty"`

	// MinItems is the minimum number of array items.
	MinItems *int `json:"minItems,omitempty"`

	// MaxItems is the maximum number of array items.
	MaxItems *int `json:"maxItems,omitempty"`

	// UniqueItems requires all array items to be unique.
	UniqueItems bool `json:"uniqueItems,omitempty"`

	// Format specifies semantic validation (e.g., "email", "uri", "date-time").
	Format string `json:"format,omitempty"`

	// AdditionalProperties controls whether extra properties are allowed in objects.
	// nil = not specified, true = allowed, false = not allowed
	AdditionalProperties *bool `json:"additionalProperties,omitempty"`
}

type SearchResult struct {
	// Document is the matching document.
	Document Document

	// Score is the similarity score (higher = more relevant).
	Score float64

	// Chunk is the specific text chunk that matched, if chunking was used.
	Chunk string
}

type Step struct {
	Action      ToolAction    // What the LLM wanted to do
	Observation string        // What happened (result)
	Error       string        // Error message if failed
	Duration    time.Duration // How long the tool call took
}

type StreamCallback func(chunk string) error

type Subscription interface {
	// Unsubscribe stops receiving messages and releases resources.
	Unsubscribe() error
}

type SummaryBufferConfig struct {
	// WindowSize is the number of recent conversation turns to keep in full.
	// A turn is a user+assistant message pair.
	// Default: 3 (keeps last 6 messages)
	WindowSize int

	// Model to use for summarization.
	// Default: "gpt-4o-mini" (fast and cost-effective)
	Model string

	// InitialSummary allows starting with an existing conversation summary.
	// Useful for resuming conversations from persistent storage.
	InitialSummary string
}

type SummaryMemory interface {
	Memory

	// GetSummary returns the current conversation summary.
	GetSummary() string

	// SetSummary sets the conversation summary.
	SetSummary(summary string)

	// SetMessages replaces all messages (useful for initializing from existing conversation).
	SetMessages(messages []ChatMessage)
}

type Task struct {
	// ID is the unique task identifier.
	ID string `json:"id"`

	// ContextID groups related tasks into a conversation.
	// Optional; when empty, the task is standalone.
	ContextID string `json:"contextId,omitempty"`

	// CallerAgent is the name of the agent (or "user") that created this task.
	CallerAgent string `json:"callerAgent"`

	// TargetAgent is the name of the agent executing this task.
	TargetAgent string `json:"targetAgent"`

	// Status is the current task status.
	Status TaskStatus `json:"status"`

	// Input is the task's input content.
	Input []Part `json:"input"`

	// Output is the task's output content (set on completion).
	Output []Part `json:"output,omitempty"`

	// Artifacts are named outputs produced during execution.
	Artifacts []Artifact `json:"artifacts,omitempty"`

	// Metadata carries additional task-level key-value pairs.
	Metadata map[string]string `json:"metadata,omitempty"`

	// DelegationChain is the ordered list of agent names in the delegation path.
	// Used for cycle detection.
	DelegationChain []string `json:"delegationChain,omitempty"`

	// DelegationDepth is the current depth in the delegation chain.
	DelegationDepth int `json:"delegationDepth,omitempty"`

	// CreatedAt is the Unix timestamp (seconds) when the task was created.
	CreatedAt int64 `json:"createdAt"`

	// UpdatedAt is the Unix timestamp (seconds) of the last status change.
	UpdatedAt int64 `json:"updatedAt"`

	// CompletedAt is the Unix timestamp (seconds) when the task reached a terminal state.
	CompletedAt *int64 `json:"completedAt,omitempty"`
}

type TaskBudget struct {
	// MaxTokens limits total LLM tokens the delegate may consume.
	MaxTokens int `json:"maxTokens,omitempty"`

	// MaxCredits limits platform credits the delegate may spend.
	MaxCredits float64 `json:"maxCredits,omitempty"`

	// MaxCalls limits the number of sub-calls (tool or delegation) the delegate may make.
	MaxCalls int `json:"maxCalls,omitempty"`

	// TimeoutMs is the maximum wall-clock time in milliseconds.
	TimeoutMs int `json:"timeoutMs,omitempty"`
}

type TaskContext interface {
	// SetProgress updates the task's progress. Publishes a task.progress event.
	SetProgress(stage string, percent float64, message string) error

	// RequestInput transitions the task to input_needed and sends a prompt
	// to the caller. Use WaitForInput to block until the caller responds.
	RequestInput(prompt []Part) error

	// WaitForInput blocks until the caller provides additional input
	// (after the task was set to input_needed via RequestInput).
	WaitForInput(ctx context.Context) ([]Part, error)

	// StreamOutput sends incremental output parts to subscribers.
	// Publishes a task.output event. The final output is set when
	// HandleTask returns without error.
	StreamOutput(parts []Part) error

	// EmitArtifact stores an artifact and publishes a task.artifact event.
	// Returns the platform-assigned artifact ID.
	EmitArtifact(artifact ArtifactBuilder) (string, error)

	// TaskID returns the current task's ID.
	TaskID() string

	// ContextID returns the conversation context ID (may be empty).
	ContextID() string

	// CallerAgent returns the name of the agent that created this task.
	CallerAgent() string

	// DelegationChain returns the ordered list of agent names
	// in the delegation path leading to this task.
	DelegationChain() []string

	// RemainingBudget returns the remaining budget for this task, if any.
	RemainingBudget() *TaskBudget

	// DelegationCallbacks returns LoopCallbacks that should be composed
	// into any RunLoop executed during HandleTask. This enables the caller
	// to observe the sub-agent's internal loop events (tool calls, LLM usage).
	// Returns nil when no external observer is attached.
	DelegationCallbacks() LoopCallbacks
}

type TaskFilter struct {
	// ContextID filters by conversation context.
	ContextID string

	// CallerAgent filters by who created the task.
	CallerAgent string

	// TargetAgent filters by who executed the task.
	TargetAgent string

	// State filters by current state. Nil means any state.
	State *TaskState

	// Limit is the maximum number of tasks to return.
	Limit int

	// Before filters to tasks created before this Unix timestamp (for pagination).
	Before *int64
}

type TaskHandler interface {
	// HandleTask processes an asynchronous task with full lifecycle control.
	// The TaskContext provides methods to update status, emit artifacts,
	// stream output, and request input from the caller.
	HandleTask(ctx context.Context, task Task, tc TaskContext) error
}

type TaskState string

type TaskStatus struct {
	// State is the current lifecycle state.
	State TaskState `json:"state"`

	// Message is an optional human-readable status message.
	Message string `json:"message,omitempty"`

	// Progress is optional progress information.
	Progress *Progress `json:"progress,omitempty"`
}

type TaskStore interface {
	// Get retrieves a task by ID.
	Get(ctx context.Context, taskID string) (*Task, error)

	// List returns tasks matching the given filter.
	List(ctx context.Context, filter TaskFilter) ([]Task, error)

	// GetArtifacts returns all artifacts for a task.
	GetArtifacts(ctx context.Context, taskID string) ([]Artifact, error)

	// GetArtifact returns a specific artifact by ID.
	GetArtifact(ctx context.Context, artifactID string) (*Artifact, error)
}

type TokenUsage struct {
	// PromptTokens is the number of tokens in the prompt.
	PromptTokens int

	// CompletionTokens is the number of tokens in the response.
	CompletionTokens int

	// TotalTokens is the sum of prompt and completion tokens.
	TotalTokens int
}

type Tool struct {
	// Type is always "function" for function tools.
	Type string

	// Function contains the function definition.
	Function FunctionDef
}

type ToolAction struct {
	ToolID    string         // Tool identifier (format: "agent/action")
	Arguments map[string]any // Arguments to pass to the tool
	Thought   string         // LLM's reasoning (for debugging)
}

type ToolCall struct {
	// ID is a unique identifier for this tool call (used to match tool responses).
	ID string

	// Type is always "function" for function calls.
	Type string

	// Function contains the function name and arguments.
	Function FunctionCall
}

type ToolCallResult struct {
	// ToolID is the tool identifier (format: "agent_name/action_name").
	ToolID string

	// Arguments is the parsed JSON arguments passed to the tool.
	Arguments map[string]any

	// Result is the tool's response content.
	Result string

	// Error is set if the tool call failed.
	Error string

	// Duration is how long the tool call took.
	Duration time.Duration
}

type ToolFilter func(toolID string, score float64) bool

type ToolMatch struct {
	// ToolID is the unique identifier (format: "agent_name/action_name").
	ToolID string

	// AgentName is the name of the agent that provides this tool.
	AgentName string

	// AgentAvatar is the emoji avatar of the agent (e.g., "🤖", "🌤️").
	AgentAvatar string

	// ActionName is the name of the action/tool.
	ActionName string

	// Description explains what this tool does.
	Description string

	// InputSchema is the JSON Schema for the tool's parameters.
	InputSchema map[string]any

	// Score is the semantic similarity score (0.0-1.0, higher is more relevant).
	Score float64
}