interfaces

type Agent interface {
	Runnable

	// Name returns the agent's identifier.
	Name() string

	// Description returns what the agent does.
	Description() string

	// Plan generates an execution plan for the given input.
	// This is optional and may return nil if the agent doesn't support planning.
	Plan(ctx context.Context, input *Input) (*Plan, error)
}

type Case struct {
	// ID is a unique identifier for this case.
	//
	// May be auto-generated by the storage implementation.
	ID string `json:"id"`

	// Title is a brief summary of the case.
	//
	// Should be descriptive but concise (1-2 sentences).
	Title string `json:"title"`

	// Description provides more detail about the case.
	//
	// This can be a longer explanation of the context and scenario.
	Description string `json:"description"`

	// Problem describes the issue that was encountered.
	//
	// This should be detailed enough to match similar future problems.
	Problem string `json:"problem"`

	// Solution describes how the problem was resolved.
	//
	// This should include actionable steps and outcomes.
	Solution string `json:"solution"`

	// Category groups related cases.
	//
	// Examples: "infrastructure", "security", "performance", "bug-fix"
	Category string `json:"category"`

	// Tags are keywords for filtering and searching.
	//
	// Examples: ["database", "timeout", "postgres"]
	Tags []string `json:"tags,omitempty"`

	// Embedding is the semantic vector representation of this case.
	//
	// This is used for similarity search. Typically computed by
	// embedding the concatenation of Title + Problem + Solution.
	//
	// The dimension should match the embedding model being used
	// (e.g., 1536 for OpenAI text-embedding-ada-002).
	Embedding []float64 `json:"embedding,omitempty"`

	// Similarity is the similarity score (0.0-1.0) when this case
	// is returned from a search.
	//
	// Only populated in search results. Higher values indicate
	// greater similarity to the query.
	//
	// Not persisted in storage.
	Similarity float64 `json:"similarity,omitempty"`

	// CreatedAt is when the case was first added.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when the case was last modified.
	//
	// Useful for tracking case evolution and versioning.
	UpdatedAt time.Time `json:"updated_at"`

	// Metadata contains additional information about the case.
	//
	// Optional. May include:
	//   - source: Where this case came from
	//   - author: Who created the case
	//   - success_rate: How often this solution works
	//   - related_cases: IDs of related cases
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type Checkpoint struct {
	// ID is the unique checkpoint identifier.
	// Format: "ckpt-{uuid}" or implementation-specific format
	ID string `json:"id"`

	// ThreadID is the thread/session identifier.
	// All checkpoints with the same ThreadID belong to the same conversation.
	ThreadID string `json:"thread_id"`

	// State is the agent state at checkpoint time.
	// Contains all data needed to resume execution from this point.
	State State `json:"state"`

	// Metadata contains additional checkpoint information.
	// Common metadata keys:
	//   - "agent_name": Name of the agent that created the checkpoint
	//   - "checkpoint_reason": Why this checkpoint was created (e.g., "user_request", "step_complete")
	//   - "parent_checkpoint_id": ID of the previous checkpoint (for history traversal)
	//   - "tags": Array of tags for categorization
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// CreatedAt is when the checkpoint was created.
	CreatedAt time.Time `json:"created_at"`
}

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

	// ThreadID is the thread/session identifier.
	ThreadID string `json:"thread_id"`

	// CreatedAt is when the checkpoint was created.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is when the checkpoint was last updated.
	UpdatedAt time.Time `json:"updated_at"`

	// Metadata holds additional checkpoint information.
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// Size is the approximate size in bytes of the checkpoint data.
	// Useful for storage management and cleanup decisions.
	Size int64 `json:"size"`
}

type Checkpointer interface {
	// SaveCheckpoint persists a checkpoint.
	//
	// The checkpoint contains the complete agent state at a point in time,
	// allowing resumption of execution from that state.
	//
	// Parameters:
	//   - ctx: Context for cancellation and deadlines
	//   - checkpoint: The checkpoint to save (must have ID and ThreadID)
	//
	// Returns:
	//   - error: SaveError if persistence fails
	SaveCheckpoint(ctx context.Context, checkpoint *Checkpoint) error

	// LoadCheckpoint retrieves a checkpoint by ID.
	//
	// Returns the complete checkpoint including state and metadata.
	//
	// Parameters:
	//   - ctx: Context for cancellation and deadlines
	//   - checkpointID: The unique checkpoint identifier
	//
	// Returns:
	//   - *Checkpoint: The loaded checkpoint
	//   - error: NotFoundError if checkpoint doesn't exist, LoadError for other failures
	LoadCheckpoint(ctx context.Context, checkpointID string) (*Checkpoint, error)

	// ListCheckpoints lists checkpoints for a thread.
	//
	// Returns metadata for the most recent checkpoints, useful for:
	//   - Displaying checkpoint history to users
	//   - Finding the latest checkpoint to resume from
	//   - Analyzing checkpoint patterns
	//
	// Parameters:
	//   - ctx: Context for cancellation and deadlines
	//   - threadID: The thread/session identifier
	//   - limit: Maximum number of checkpoints to return (0 = all)
	//
	// Returns:
	//   - []*CheckpointMetadata: List of checkpoint metadata, ordered by creation time (newest first)
	//   - error: QueryError if listing fails
	ListCheckpoints(ctx context.Context, threadID string, limit int) ([]*CheckpointMetadata, error)

	// DeleteCheckpoint removes a checkpoint.
	//
	// Permanently deletes a checkpoint and its associated state.
	// This operation cannot be undone.
	//
	// Parameters:
	//   - ctx: Context for cancellation and deadlines
	//   - checkpointID: The unique checkpoint identifier
	//
	// Returns:
	//   - error: DeleteError if removal fails (not an error if checkpoint doesn't exist)
	DeleteCheckpoint(ctx context.Context, checkpointID string) error
}

type Conversation struct {
	// ID is a unique identifier for this conversation turn.
	//
	// May be auto-generated by the storage implementation.
	ID string `json:"id"`

	// SessionID groups related conversation turns.
	//
	// All conversations with the same SessionID are part of the
	// same dialogue session.
	SessionID string `json:"session_id"`

	// Role indicates who sent the message.
	//
	// Common values:
	//   - "user": Message from the user
	//   - "assistant": Message from the AI agent
	//   - "system": System message (e.g., instructions)
	Role string `json:"role"`

	// Content is the message content.
	//
	// This is typically text, but may include formatted content
	// depending on the implementation.
	Content string `json:"content"`

	// Timestamp is when the conversation occurred.
	//
	// Used for ordering and filtering conversations.
	Timestamp time.Time `json:"timestamp"`

	// Metadata contains additional context about the conversation.
	//
	// Optional. May include:
	//   - model: Which LLM model generated the response
	//   - tokens: Token count for this turn
	//   - language: Detected language
	//   - sentiment: Sentiment analysis results
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ConversationMemory interface {
	// Add adds a conversation to storage.
	Add(ctx context.Context, conv *Conversation) error

	// Get retrieves conversation history.
	Get(ctx context.Context, sessionID string, limit int) ([]*Conversation, error)

	// Clear clears conversation history for a session.
	Clear(ctx context.Context, sessionID string) error

	// Count returns the number of conversations in a session.
	Count(ctx context.Context, sessionID string) (int, error)
}

type DependencyAware interface {
	// Dependencies returns the names of components this component depends on.
	// The LifecycleManager will ensure dependencies are started first.
	Dependencies() []string
}

type Document struct {
	// ID is the unique identifier for the document.
	//
	// If not provided when creating a document, implementations should
	// generate a unique ID automatically.
	ID string `json:"id"`

	// PageContent is the main text content of the document.
	//
	// This is the primary searchable text that embeddings are generated from.
	PageContent string `json:"page_content"`

	// Metadata contains additional structured information about the document.
	//
	// Common metadata fields:
	//   - "source": Document source (file path, URL, etc.)
	//   - "title": Document title
	//   - "author": Document author
	//   - "created_at": Creation timestamp
	//   - "tags": Document tags/categories
	//
	// Metadata can be used for filtering and enriching search results.
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// Embedding is the vector representation of the document.
	//
	// This field may be nil if embeddings haven't been generated yet.
	// VectorStore implementations should generate embeddings if missing.
	Embedding []float64 `json:"embedding,omitempty"`

	// Score represents the similarity or relevance score.
	//
	// This field is populated by search operations:
	//   - SimilaritySearch: Cosine similarity (typically 0.0 to 1.0)
	//   - Reranking: Relevance score from reranker
	//   - BM25: BM25 score
	//
	// Higher scores indicate better matches.
	Score float64 `json:"score,omitempty"`
}

type HealthState string

type HealthStatus struct {
	// State is the overall health state
	State HealthState `json:"state"`

	// Message provides additional context about the health state
	Message string `json:"message,omitempty"`

	// Details contains component-specific health information
	Details map[string]interface{} `json:"details,omitempty"`

	// LastChecked is when this status was determined
	LastChecked time.Time `json:"last_checked"`

	// ComponentName identifies the component
	ComponentName string `json:"component_name,omitempty"`
}

type Input struct {
	// Messages is the conversation history or input messages.
	Messages []Message `json:"messages"`

	// State is the persistent state data.
	// Can store arbitrary key-value pairs for state management.
	State State `json:"state"`

	// Config contains runtime configuration options.
	// Can include model settings, tool settings, etc.
	Config map[string]interface{} `json:"config,omitempty"`
}

type Lifecycle interface {
	// Init initializes the component with configuration.
	// This is called once before Start and should set up resources.
	// Config can be nil if no configuration is needed.
	Init(ctx context.Context, config interface{}) error

	// Start begins the component's active operation.
	// Called after Init succeeds. Component should be ready to serve.
	Start(ctx context.Context) error

	// Stop gracefully stops the component.
	// Should release resources and complete pending operations.
	// Context may have a deadline for forced shutdown.
	Stop(ctx context.Context) error

	// HealthCheck returns the component's current health status.
	// Should be non-blocking and return quickly.
	HealthCheck(ctx context.Context) HealthStatus
}

type LifecycleAware interface {
	// OnInit is called during initialization
	OnInit(ctx context.Context) error

	// OnShutdown is called during shutdown
	OnShutdown(ctx context.Context) error
}

type LifecycleManager interface {
	// Register adds a component to be managed.
	// Name must be unique. Priority determines startup/shutdown order.
	Register(name string, component Lifecycle, priority int) error

	// Unregister removes a component from management.
	Unregister(name string) error

	// InitAll initializes all registered components in priority order.
	InitAll(ctx context.Context) error

	// StartAll starts all initialized components in priority order.
	StartAll(ctx context.Context) error

	// StopAll stops all running components in reverse priority order.
	StopAll(ctx context.Context) error

	// HealthCheckAll returns aggregated health of all components.
	HealthCheckAll(ctx context.Context) map[string]HealthStatus

	// GetState returns the current state of a component.
	GetState(name string) (LifecycleState, error)

	// WaitForShutdown blocks until all components are stopped.
	WaitForShutdown(ctx context.Context) error
}

type LifecycleState string

type MemoryManager interface {
	// AddConversation stores a conversation turn.
	//
	// This is used to maintain conversation history for context-aware
	// agent interactions. Each conversation turn is associated with
	// a session ID for grouping related conversations.
	//
	// Example:
	//   conv := &Conversation{
	//     SessionID: "session-123",
	//     Role:      "user",
	//     Content:   "Hello, how are you?",
	//     Timestamp: time.Now(),
	//   }
	//   err := manager.AddConversation(ctx, conv)
	AddConversation(ctx context.Context, conv *Conversation) error

	// GetConversationHistory retrieves conversation history for a session.
	//
	// Returns the most recent conversations up to the specified limit.
	// Conversations are typically returned in chronological order.
	//
	// Parameters:
	//   - sessionID: The session identifier
	//   - limit: Maximum number of conversations to return (0 or negative for all)
	//
	// Returns:
	//   - Conversation slice (may be empty if no history exists)
	//   - Error if retrieval fails
	GetConversationHistory(ctx context.Context, sessionID string, limit int) ([]*Conversation, error)

	// ClearConversation removes conversation history for a session.
	//
	// This is useful for starting fresh conversations or implementing
	// privacy features like "forget this conversation".
	//
	// Parameters:
	//   - sessionID: The session identifier to clear
	//
	// Returns:
	//   - Error if clearing fails (returns nil if session doesn't exist)
	ClearConversation(ctx context.Context, sessionID string) error

	// AddCase stores a case for case-based reasoning.
	//
	// Cases are examples of problems and solutions that agents can
	// reference when handling similar situations. This supports
	// learning from past experiences.
	//
	// The case's embedding vector should be pre-computed and included
	// in the Case struct for efficient similarity search.
	//
	// Example:
	//   case := &Case{
	//     Title:       "Database connection timeout",
	//     Problem:     "App fails to connect to database",
	//     Solution:    "Increase connection timeout to 30s",
	//     Category:    "infrastructure",
	//     Tags:        []string{"database", "timeout"},
	//     Embedding:   embeddings,  // Pre-computed vector
	//   }
	//   err := manager.AddCase(ctx, case)
	AddCase(ctx context.Context, caseMemory *Case) error

	// SearchSimilarCases finds similar cases using semantic search.
	//
	// This uses vector similarity (typically cosine similarity) to find
	// cases that are semantically similar to the query. The query is
	// embedded and compared against stored case embeddings.
	//
	// Parameters:
	//   - query: Natural language query describing the problem
	//   - limit: Maximum number of similar cases to return
	//
	// Returns:
	//   - Case slice ordered by similarity (highest first)
	//   - Each case includes a Similarity score (0.0-1.0)
	//   - Error if search fails
	//
	// Example:
	//   cases, err := manager.SearchSimilarCases(ctx, "database timeout issue", 3)
	//   for _, c := range cases {
	//     fmt.Printf("Similar case (%.2f): %s\n", c.Similarity, c.Title)
	//   }
	SearchSimilarCases(ctx context.Context, query string, limit int) ([]*Case, error)

	// Store persists arbitrary key-value data.
	//
	// This provides a general-purpose storage mechanism for agent state
	// or other data that doesn't fit into conversation or case memory.
	//
	// The value will be serialized internally, so it must be serializable.
	//
	// Parameters:
	//   - key: Unique identifier for the data
	//   - value: Data to store (must be serializable)
	//
	// Returns:
	//   - Error if storage fails
	Store(ctx context.Context, key string, value interface{}) error

	// Retrieve fetches stored data by key.
	//
	// Returns the stored value or an error if the key doesn't exist.
	// The caller is responsible for type assertion.
	//
	// Parameters:
	//   - key: The key to retrieve
	//
	// Returns:
	//   - The stored value (requires type assertion)
	//   - Error if key doesn't exist or retrieval fails
	//
	// Example:
	//   val, err := manager.Retrieve(ctx, "user_preferences")
	//   if err != nil {
	//     // Handle error
	//   }
	//   prefs, ok := val.(map[string]interface{})
	Retrieve(ctx context.Context, key string) (interface{}, error)

	// Delete removes stored data by key.
	//
	// This is idempotent - deleting a non-existent key is not an error.
	//
	// Parameters:
	//   - key: The key to delete
	//
	// Returns:
	//   - Error if deletion fails (returns nil if key doesn't exist)
	Delete(ctx context.Context, key string) error

	// Clear removes all memory.
	//
	// This is a destructive operation that clears:
	//   - All conversation history
	//   - All cases
	//   - All key-value storage
	//
	// Use with caution! This is typically used for:
	//   - Testing and development
	//   - Complete system resets
	//   - Data privacy compliance (e.g., GDPR right to be forgotten)
	//
	// Returns:
	//   - Error if clearing fails
	Clear(ctx context.Context) error
}

type Message struct {
	// Role identifies the message sender (user, assistant, system, function).
	Role string `json:"role"`

	// Content is the message text content.
	Content string `json:"content"`

	// Name is the optional name of the sender (for function/tool messages).
	Name string `json:"name,omitempty"`
}

type Output struct {
	// Messages is the generated or modified messages.
	Messages []Message `json:"messages"`

	// State is the updated state data.
	State State `json:"state"`

	// Metadata contains additional information about the execution.
	// Can include timing, model info, tool calls, etc.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type Plan struct {
	// Steps is the ordered list of actions to execute.
	Steps []Step `json:"steps"`

	// Metadata contains planning metadata (confidence, reasoning, etc.).
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ProgramCode struct {
	// Language of the code (e.g., "python", "javascript")
	Language string `json:"language"`

	// Code content
	Code string `json:"code"`

	// ExecutionResult after running the code
	ExecutionResult interface{} `json:"execution_result,omitempty"`

	// Error if execution failed
	Error string `json:"error,omitempty"`
}

type ReasoningChunk struct {
	// Step is a partial or complete reasoning step
	Step *ReasoningStep `json:"step,omitempty"`

	// PartialAnswer is incremental answer content
	PartialAnswer string `json:"partial_answer,omitempty"`

	// Done indicates if reasoning is complete
	Done bool `json:"done"`

	// Error if something went wrong
	Error error `json:"error,omitempty"`
}

type ReasoningInput struct {
	// Query is the main question or task to reason about
	Query string `json:"query"`

	// Context provides additional information for reasoning
	Context map[string]interface{} `json:"context,omitempty"`

	// Tools available for the reasoning process
	Tools []Tool `json:"tools,omitempty"`

	// Config contains pattern-specific configuration
	Config map[string]interface{} `json:"config,omitempty"`

	// History of previous reasoning steps (for iterative patterns)
	History []ReasoningStep `json:"history,omitempty"`
}

type ReasoningOutput struct {
	// Answer is the final answer or conclusion
	Answer string `json:"answer"`

	// Steps contains the reasoning steps taken
	Steps []ReasoningStep `json:"steps"`

	// Confidence score (0-1) in the answer
	Confidence float64 `json:"confidence,omitempty"`

	// Metadata contains pattern-specific output data
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// ToolCalls made during reasoning
	ToolCalls []ReasoningToolCall `json:"tool_calls,omitempty"`
}

type ReasoningPattern interface {
	// Name returns the name of the reasoning pattern.
	Name() string

	// Description returns a description of the reasoning pattern.
	Description() string

	// Process executes the reasoning pattern on the given input.
	Process(ctx context.Context, input *ReasoningInput) (*ReasoningOutput, error)

	// Stream processes with streaming support for incremental results.
	Stream(ctx context.Context, input *ReasoningInput) (<-chan *ReasoningChunk, error)
}

type ReasoningStep struct {
	// StepID uniquely identifies this step
	StepID string `json:"step_id"`

	// Type of reasoning step (e.g., "thought", "action", "observation", "branch")
	Type string `json:"type"`

	// Content of the reasoning step
	Content string `json:"content"`

	// Score or evaluation of this step (for search-based patterns)
	Score float64 `json:"score,omitempty"`

	// ParentID links to the parent step (for tree/graph patterns)
	ParentID string `json:"parent_id,omitempty"`

	// ChildrenIDs links to child steps (for tree/graph patterns)
	ChildrenIDs []string `json:"children_ids,omitempty"`

	// Metadata for step-specific data
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ReasoningStrategy string

type ReasoningToolCall struct {
	// ToolName identifies the tool
	ToolName string `json:"tool_name"`

	// Input parameters for the tool
	Input map[string]interface{} `json:"input"`

	// Output from the tool execution
	Output interface{} `json:"output,omitempty"`

	// Error if tool execution failed
	Error string `json:"error,omitempty"`

	// ReasoningStepID links this call to a specific reasoning step
	ReasoningStepID string `json:"reasoning_step_id,omitempty"`
}

type Reloadable interface {
	// Reload reloads configuration without stopping the component.
	// Returns error if reload fails (component continues with old config).
	Reload(ctx context.Context, config interface{}) error
}

type Runnable interface {
	// Invoke executes the runnable with the given input.
	// This is the primary execution method for synchronous processing.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - input: Input data for the runnable
	//
	// Returns:
	//   - output: Result of the execution
	//   - error: Error if execution fails
	Invoke(ctx context.Context, input *Input) (*Output, error)

	// Stream executes with streaming output support.
	// Allows processing output as it becomes available.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control
	//   - input: Input data for the runnable
	//
	// Returns:
	//   - chan: Channel of stream chunks
	//   - error: Error if stream setup fails
	Stream(ctx context.Context, input *Input) (<-chan *StreamChunk, error)
}

type SkeletonPoint struct {
	// ID uniquely identifies this skeleton point
	ID string `json:"id"`

	// Question or sub-problem to solve
	Question string `json:"question"`

	// Answer to this skeleton point
	Answer string `json:"answer,omitempty"`

	// Dependencies on other skeleton points
	Dependencies []string `json:"dependencies,omitempty"`

	// Status of this point ("pending", "processing", "completed")
	Status string `json:"status"`
}

type State map[string]interface{}

type Step struct {
	// Action is the action to perform (e.g., "search", "analyze", "format").
	Action string `json:"action"`

	// Input contains parameters for the action.
	Input map[string]interface{} `json:"input"`

	// ToolName is the tool to invoke (if this is a tool call step).
	ToolName string `json:"tool_name,omitempty"`
}

type Store interface {
	// Get retrieves a value by key.
	//
	// Returns:
	//   - The stored value
	//   - An error if the key doesn't exist or retrieval fails
	Get(ctx context.Context, key string) (interface{}, error)

	// Set stores a key-value pair.
	//
	// If the key already exists, its value is replaced.
	Set(ctx context.Context, key string, value interface{}) error

	// Delete removes a key and its associated value.
	//
	// Returns no error if the key doesn't exist (idempotent operation).
	Delete(ctx context.Context, key string) error

	// Clear removes all keys from the store.
	//
	// Use with caution - this operation is typically irreversible.
	Clear(ctx context.Context) error
}

type StreamChunk struct {
	// Content is the chunk data (can be partial output).
	Content string `json:"content"`

	// Metadata contains contextual information about the chunk.
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// Done indicates if this is the final chunk.
	Done bool `json:"done"`
}

type ThoughtNode struct {
	// ID uniquely identifies this node
	ID string `json:"id"`

	// Thought content at this node
	Thought string `json:"thought"`

	// Score or evaluation of this thought
	Score float64 `json:"score"`

	// State at this node (for stateful reasoning)
	State map[string]interface{} `json:"state,omitempty"`

	// Parent node reference
	Parent *ThoughtNode `json:"-"`

	// Children nodes
	Children []*ThoughtNode `json:"-"`

	// Visited flag for graph traversal
	Visited bool `json:"visited"`

	// Depth in the tree/graph
	Depth int `json:"depth"`
}

type TokenUsage struct {
	// PromptTokens is the number of tokens in the input/prompt.
	PromptTokens int `json:"prompt_tokens"`

	// CompletionTokens is the number of tokens in the generated output.
	CompletionTokens int `json:"completion_tokens"`

	// TotalTokens is the total number of tokens used.
	// Usually equals PromptTokens + CompletionTokens.
	TotalTokens int `json:"total_tokens"`

	// CachedTokens is the number of tokens served from cache (if applicable).
	// Not all LLM providers support this field.
	CachedTokens int `json:"cached_tokens,omitempty"`
}

type Tool interface {
	// Name returns the tool identifier.
	//
	// The name should be unique within a tool registry and follow
	// naming conventions (lowercase, underscores for separators).
	Name() string

	// Description returns what the tool does.
	//
	// This description is used by LLMs to understand when and how
	// to use the tool. It should be clear and concise.
	Description() string

	// Invoke executes the tool with given input.
	//
	// The tool should process the input arguments and return results
	// or an error if execution fails.
	Invoke(ctx context.Context, input *ToolInput) (*ToolOutput, error)

	// ArgsSchema returns the tool's input schema (JSON Schema format).
	//
	// This schema defines the structure of arguments the tool accepts.
	// It's used by LLMs to generate valid tool calls.
	//
	// Example schema:
	//   {
	//     "type": "object",
	//     "properties": {
	//       "query": {"type": "string", "description": "Search query"}
	//     },
	//     "required": ["query"]
	//   }
	ArgsSchema() string
}

type ToolCall struct {
	// ID is a unique identifier for this tool call.
	//
	// Useful for correlating calls across logs and traces.
	ID string `json:"id"`

	// ToolName is the name of the tool that was called.
	ToolName string `json:"tool_name"`

	// Args are the arguments passed to the tool.
	Args map[string]interface{} `json:"args"`

	// Result is the output from the tool.
	//
	// May be nil if the call is still in progress.
	Result *ToolOutput `json:"result,omitempty"`

	// Error contains error information if the call failed.
	//
	// Empty string if the call succeeded.
	Error string `json:"error,omitempty"`

	// StartTime is when the tool call started (Unix timestamp).
	StartTime int64 `json:"start_time"`

	// EndTime is when the tool call completed (Unix timestamp).
	//
	// Zero if the call is still in progress.
	EndTime int64 `json:"end_time,omitempty"`

	// Metadata contains additional context about the call.
	//
	// May include caller information, trace IDs, etc.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ToolExecutor interface {
	// ExecuteTool executes a tool by name with the given arguments.
	//
	// The executor is responsible for:
	//   - Looking up the tool by name
	//   - Validating arguments against the tool's schema
	//   - Executing the tool
	//   - Handling errors and timeouts
	ExecuteTool(ctx context.Context, toolName string, args map[string]interface{}) (*ToolResult, error)

	// ListTools returns all available tools.
	//
	// This is useful for agents that need to discover what tools
	// they can use.
	ListTools() []Tool
}

type ToolInput struct {
	// Args contains the tool's input parameters.
	//
	// The structure of Args should match the tool's ArgsSchema.
	Args map[string]interface{} `json:"args"`

	// Context is the execution context (not serialized).
	//
	// This is used for cancellation, timeouts, and passing
	// request-scoped values.
	Context context.Context `json:"-"`

	// CallerID identifies who is invoking the tool.
	//
	// Optional. Used for authorization and auditing.
	CallerID string `json:"caller_id,omitempty"`

	// TraceID is used for distributed tracing.
	//
	// Optional. Helps track tool execution across systems.
	TraceID string `json:"trace_id,omitempty"`
}

type ToolOutput struct {
	// Result contains the tool's output data.
	//
	// The type depends on the specific tool. Common types:
	//   - string: Text output
	//   - map[string]interface{}: Structured data
	//   - []byte: Binary data
	Result interface{} `json:"result"`

	// Success indicates whether the tool executed successfully.
	//
	// True if the tool completed without errors, false otherwise.
	Success bool `json:"success"`

	// Error contains the error message if Success is false.
	//
	// Empty string if Success is true.
	Error string `json:"error,omitempty"`

	// Metadata contains additional information about execution.
	//
	// Optional. May include:
	//   - execution_time: How long the tool took to run
	//   - retries: Number of retry attempts
	//   - cost: API call cost (for external services)
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ToolResult struct {
	// ToolName is the name of the tool that was executed.
	ToolName string `json:"tool_name"`

	// Output contains the tool's execution output.
	Output *ToolOutput `json:"output"`

	// ExecutionTime is how long the tool took to execute (in milliseconds).
	//
	// Optional. Useful for performance monitoring.
	ExecutionTime int64 `json:"execution_time,omitempty"`
}

type VectorStore interface {
	// SimilaritySearch performs vector similarity search and returns the most similar documents.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeouts
	//   - query: The query string to search for
	//   - topK: Maximum number of results to return
	//
	// Returns documents sorted by similarity (most similar first).
	SimilaritySearch(ctx context.Context, query string, topK int) ([]*Document, error)

	// SimilaritySearchWithScore returns documents with their similarity scores.
	//
	// This is useful when you need to filter results based on a score threshold
	// or display confidence levels to users.
	//
	// The Score field in each returned Document will be populated.
	SimilaritySearchWithScore(ctx context.Context, query string, topK int) ([]*Document, error)

	// AddDocuments adds new documents to the vector store.
	//
	// The implementation should:
	//   - Generate embeddings for documents without them
	//   - Store the document content and metadata
	//   - Index the vectors for efficient similarity search
	AddDocuments(ctx context.Context, docs []*Document) error

	// Delete removes documents by their IDs.
	//
	// This is useful for:
	//   - Removing outdated information
	//   - GDPR/data deletion compliance
	//   - Managing store size
	Delete(ctx context.Context, ids []string) error
}