interfaces

type Agent interface {
	Runnable

	// Name 返回智能体的标识符
	Name() string

	// Description 返回智能体的功能描述
	Description() string

	// Capabilities 返回智能体的能力列表
	// 描述智能体可以执行的任务或操作
	// 示例：["search", "analyze", "summarize"]
	Capabilities() []string

	// Plan 为给定输入生成执行计划
	// 这是可选的，如果智能体不支持规划可能返回 nil
	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 是对话历史或输入消息
	Messages []Message `json:"messages"`

	// State 是持久状态数据
	// 可以存储任意键值对用于状态管理
	State State `json:"state"`

	// Config 包含运行时配置选项
	// 可以包括模型设置、工具设置等
	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 标识消息发送者（user、assistant、system、function）
	Role string `json:"role"`

	// Content 是消息的文本内容
	Content string `json:"content"`

	// Name 是发送者的可选名称（用于函数/工具消息）
	Name string `json:"name,omitempty"`
}

type Output struct {
	// Messages 是生成或修改的消息
	Messages []Message `json:"messages"`

	// State 是更新的状态数据
	State State `json:"state"`

	// Metadata 包含关于执行的额外信息
	// 可以包括时序、模型信息、工具调用等
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type Plan struct {
	// Steps 是要执行的有序动作列表
	Steps []Step `json:"steps"`

	// Metadata 包含规划元数据（置信度、推理等）
	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 使用给定输入执行 runnable
	// 这是用于同步处理的主要执行方法
	//
	// 参数：
	//   - ctx: 用于取消和超时控制的上下文
	//   - input: runnable 的输入数据
	//
	// 返回：
	//   - output: 执行结果
	//   - error: 执行失败时的错误
	Invoke(ctx context.Context, input *Input) (*Output, error)

	// Stream 使用流式输出支持执行
	// 允许在输出可用时进行处理
	//
	// 参数：
	//   - ctx: 用于取消和超时控制的上下文
	//   - input: runnable 的输入数据
	//
	// 返回：
	//   - chan: 流式数据块通道
	//   - error: 流设置失败时的错误
	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 是要执行的动作（例如 "search"、"analyze"、"format"）
	Action string `json:"action"`

	// Input 包含动作的参数
	Input map[string]interface{} `json:"input"`

	// ToolName 是要调用的工具（如果这是工具调用步骤）
	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 是数据块内容（可以是部分输出）
	Content string `json:"content"`

	// Metadata 包含关于数据块的上下文信息
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// Done 指示这是否是最后一个数据块
	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 返回工具标识符
	//
	// 名称应在工具注册表中唯一，并遵循命名约定
	// （小写字母，下划线分隔）
	Name() string

	// Description 返回工具的功能描述
	//
	// 此描述供 LLM 理解何时以及如何使用工具
	// 应当清晰简洁
	Description() string

	// Invoke 使用给定输入执行工具
	//
	// 工具应处理输入参数并返回结果
	// 如果执行失败则返回错误
	Invoke(ctx context.Context, input *ToolInput) (*ToolOutput, error)

	// ArgsSchema 返回工具的输入模式（JSON Schema 格式）
	//
	// 此模式定义工具接受的参数结构
	// LLM 使用它生成有效的工具调用
	//
	// 示例模式：
	//   {
	//     "type": "object",
	//     "properties": {
	//       "query": {"type": "string", "description": "搜索查询"}
	//     },
	//     "required": ["query"]
	//   }
	ArgsSchema() string
}

type ToolCall struct {
	// ID 是此工具调用的唯一标识符
	//
	// 用于在日志和追踪中关联调用
	ID string `json:"id"`

	// ToolName 是被调用工具的名称
	ToolName string `json:"tool_name"`

	// Args 是传递给工具的参数
	Args map[string]interface{} `json:"args"`

	// Result 是工具的输出
	//
	// 如果调用仍在进行中可能为 nil
	Result *ToolOutput `json:"result,omitempty"`

	// Error 包含调用失败时的错误信息
	//
	// 调用成功时为空字符串
	Error string `json:"error,omitempty"`

	// StartTime 是工具调用开始的时间（Unix 时间戳）
	StartTime int64 `json:"start_time"`

	// EndTime 是工具调用完成的时间（Unix 时间戳）
	//
	// 如果调用仍在进行中则为零
	EndTime int64 `json:"end_time,omitempty"`

	// Metadata 包含关于调用的额外上下文
	//
	// 可能包括调用者信息、追踪 ID 等
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ToolExecutor interface {
	// ExecuteTool 按名称使用给定参数执行工具
	//
	// 执行器负责：
	//   - 按名称查找工具
	//   - 验证参数是否符合工具模式
	//   - 执行工具
	//   - 处理错误和超时
	ExecuteTool(ctx context.Context, toolName string, args map[string]interface{}) (*ToolResult, error)

	// ListTools 返回所有可用工具
	//
	// 这对于需要发现可用工具的智能体很有用
	ListTools() []Tool
}

type ToolInput struct {
	// Args 包含工具的输入参数
	//
	// Args 的结构应与工具的 ArgsSchema 匹配
	Args map[string]interface{} `json:"args"`

	// Context 是执行上下文（不序列化）
	//
	// 用于取消、超时和传递请求范围的值
	Context context.Context `json:"-"`

	// CallerID 标识调用工具的身份
	//
	// 可选，用于授权和审计
	CallerID string `json:"caller_id,omitempty"`

	// TraceID 用于分布式追踪
	//
	// 可选，帮助跨系统跟踪工具执行
	TraceID string `json:"trace_id,omitempty"`
}

type ToolOutput struct {
	// Result 包含工具的输出数据
	//
	// 类型取决于具体工具，常见类型：
	//   - string: 文本输出
	//   - map[string]interface{}: 结构化数据
	//   - []byte: 二进制数据
	Result interface{} `json:"result"`

	// Success 指示工具是否成功执行
	//
	// 如果工具无错误完成则为 true，否则为 false
	Success bool `json:"success"`

	// Error 包含错误消息（当 Success 为 false 时）
	//
	// 当 Success 为 true 时为空字符串
	Error string `json:"error,omitempty"`

	// Metadata 包含关于执行的额外信息
	//
	// 可选，可能包括：
	//   - execution_time: 工具运行时长
	//   - retries: 重试次数
	//   - cost: API 调用成本（对于外部服务）
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ToolResult struct {
	// ToolName 是被执行工具的名称
	ToolName string `json:"tool_name"`

	// Output 包含工具的执行输出
	Output *ToolOutput `json:"output"`

	// ExecutionTime 是工具执行时长（毫秒）
	//
	// 可选，用于性能监控
	ExecutionTime int64 `json:"execution_time,omitempty"`
}

type ValidatableTool interface {
	Tool

	// Validate 在执行前验证工具输入
	//
	// 如果输入无效则返回错误，错误消息应清楚描述输入的问题
	Validate(ctx context.Context, input *ToolInput) error
}

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
}