interfaces

type AdminConversationMemory interface {
	ConversationMemory

	// GetAllConversationsAcrossOrgs returns all conversation IDs from all organizations
	GetAllConversationsAcrossOrgs() (map[string][]string, error) // map[orgID][]conversationID

	// GetConversationMessagesAcrossOrgs finds conversation in any org and returns messages
	GetConversationMessagesAcrossOrgs(conversationID string) ([]Message, string, error) // messages, orgID, error

	// GetMemoryStatisticsAcrossOrgs returns memory statistics across all organizations
	GetMemoryStatisticsAcrossOrgs() (totalConversations, totalMessages int, err error)
}

type AgentEventType string

type AgentResponse struct {
	Content          string
	Usage            *TokenUsage
	AgentName        string
	Model            string
	ExecutionSummary ExecutionSummary
	Metadata         map[string]interface{}
}

type AgentStreamEvent struct {
	Type         AgentEventType         `json:"type"`
	Content      string                 `json:"content,omitempty"`
	ToolCall     *ToolCallEvent         `json:"tool_call,omitempty"`
	ThinkingStep string                 `json:"thinking_step,omitempty"`
	Error        error                  `json:"error,omitempty"`
	Metadata     map[string]interface{} `json:"metadata,omitempty"`
	Timestamp    time.Time              `json:"timestamp"`
}

type AgentTaskServiceInterface[AgentTask any, AgentCreateRequest any, AgentApproveRequest any, AgentTaskUpdate any] interface {
	// CreateTask creates a new task
	CreateTask(ctx context.Context, req AgentCreateRequest) (AgentTask, error)

	// GetTask gets a task by ID
	GetTask(ctx context.Context, taskID string) (AgentTask, error)

	// ListTasks returns all tasks for a user
	ListTasks(ctx context.Context, userID string) ([]AgentTask, error)

	// ApproveTaskPlan approves or rejects a task plan
	ApproveTaskPlan(ctx context.Context, taskID string, req AgentApproveRequest) (AgentTask, error)

	// UpdateTask updates an existing task with new steps or modifications
	UpdateTask(ctx context.Context, taskID string, conversationID string, updates []AgentTaskUpdate) (AgentTask, error)

	// AddTaskLog adds a log entry to a task
	AddTaskLog(ctx context.Context, taskID string, message string, level string) error
}

type CollectionRef interface {
	// Insert inserts a document into the collection
	Insert(ctx context.Context, data map[string]interface{}) (string, error)

	// Get retrieves a document by ID
	Get(ctx context.Context, id string) (map[string]interface{}, error)

	// Update updates a document by ID
	Update(ctx context.Context, id string, data map[string]interface{}) error

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

	// Query queries documents in the collection
	Query(ctx context.Context, filter map[string]interface{}, options ...QueryOption) ([]map[string]interface{}, error)
}

type ConversationMemory interface {
	Memory

	// GetAllConversations returns all conversation IDs for current org
	GetAllConversations(ctx context.Context) ([]string, error)

	// GetConversationMessages gets all messages for a specific conversation in current org
	GetConversationMessages(ctx context.Context, conversationID string) ([]Message, error)

	// GetMemoryStatistics returns basic memory statistics for current org
	GetMemoryStatistics(ctx context.Context) (totalConversations, totalMessages int, err error)
}

type DataStore interface {
	// Collection returns a reference to a specific collection/table
	Collection(name string) CollectionRef

	// Transaction executes multiple operations in a transaction
	Transaction(ctx context.Context, fn func(tx Transaction) error) error

	// Close closes the database connection
	Close() error
}

type DeleteOption func(*DeleteOptions)

type DeleteOptions struct {
	// Class is the class/collection name to delete from
	Class string

	// Tenant is the tenant name for native multi-tenancy
	Tenant string
}

type Document struct {
	// ID is the unique identifier for the document
	ID string

	// Content is the text content of the document
	Content string

	// Vector is the embedding vector for the document
	// If nil, the vector store will generate it
	Vector []float32

	// Metadata contains additional information about the document
	Metadata map[string]interface{}
}

type Embedder interface {
	// Embed generates an embedding for the given text
	Embed(ctx context.Context, text string) ([]float32, error)

	// EmbedBatch generates embeddings for multiple texts
	EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)

	// CalculateSimilarity calculates the similarity between two embeddings
	CalculateSimilarity(vec1, vec2 []float32, metric string) (float32, error)
}

type ExecutionSummary struct {
	LLMCalls        int
	ToolCalls       int
	SubAgentCalls   int
	ExecutionTimeMs int64
	UsedTools       []string
	UsedSubAgents   []string
}

type GenerateOption func(options *GenerateOptions)

type GenerateOptions struct {
	LLMConfig      *LLMConfig      // LLM config for the generation
	OrgID          string          // For multi-tenancy
	SystemMessage  string          // System message for chat models
	ResponseFormat *ResponseFormat // Optional expected response format
	MaxIterations  int             // Maximum number of tool-calling iterations (0 = use default)
	Memory         Memory          // Optional memory for storing tool calls and results
	StreamConfig   *StreamConfig   // Optional streaming configuration
}

type GetMessagesOption func(*GetMessagesOptions)

type GetMessagesOptions struct {
	// Limit is the maximum number of messages to retrieve
	Limit int

	// Roles filters messages by role
	Roles []string

	// Query is a search query for relevant messages
	Query string
}

type Guardrails interface {
	// ProcessInput processes user input before sending to the LLM
	ProcessInput(ctx context.Context, input string) (string, error)

	// ProcessOutput processes LLM output before returning to the user
	ProcessOutput(ctx context.Context, output string) (string, error)
}

type InternalTool interface {
	// Internal returns true if this tool's usage should be hidden from users
	// This can be used to filter tool calls in OnToolCall or other display contexts
	Internal() bool
}

type JSONSchema map[string]interface{}

type LLM interface {
	// Generate generates text based on the provided prompt
	Generate(ctx context.Context, prompt string, options ...GenerateOption) (string, error)

	// GenerateWithTools generates text and can use tools
	GenerateWithTools(ctx context.Context, prompt string, tools []Tool, options ...GenerateOption) (string, error)

	// GenerateDetailed generates text and returns detailed response information including token usage
	GenerateDetailed(ctx context.Context, prompt string, options ...GenerateOption) (*LLMResponse, error)

	// GenerateWithToolsDetailed generates text with tools and returns detailed response information including token usage
	GenerateWithToolsDetailed(ctx context.Context, prompt string, tools []Tool, options ...GenerateOption) (*LLMResponse, error)

	// Name returns the name of the LLM provider
	Name() string

	// SupportsStreaming returns true if this LLM supports streaming
	SupportsStreaming() bool
}

type LLMConfig struct {
	Temperature      float64  // Temperature for the generation
	TopP             float64  // Top P for the generation
	FrequencyPenalty float64  // Frequency penalty for the generation
	PresencePenalty  float64  // Presence penalty for the generation
	StopSequences    []string // Stop sequences for the generation
	Reasoning        string   // Reasoning mode (minimal, low, medium, high) to control reasoning effort
	EnableReasoning  bool     // Enable native reasoning tokens (Anthropic thinking/OpenAI o1)
	ReasoningBudget  int      // Optional token budget for reasoning (Anthropic only), minimum 1024
}

type LLMResponse struct {
	// Content is the generated text response
	Content string

	// Usage contains token usage information (nil if not available)
	Usage *TokenUsage

	// Model indicates which model was used for generation
	Model string

	// StopReason indicates why the generation stopped (optional)
	StopReason string

	// Metadata contains provider-specific additional information
	Metadata map[string]interface{}
}

type MCPContent struct {
	Type     string `json:"type"`
	Text     string `json:"text,omitempty"`
	Data     string `json:"data,omitempty"` // base64 encoded for images/audio
	MimeType string `json:"mimeType,omitempty"`
}

type MCPMessage struct {
	Role    string     `json:"role"`
	Content MCPContent `json:"content"`
	Name    string     `json:"name,omitempty"`
}

type MCPModelHint struct {
	Name string `json:"name"`
}

type MCPModelPreferences struct {
	// Model hints (optional suggestions)
	Hints []MCPModelHint `json:"hints,omitempty"`

	// Priority values (0.0 to 1.0)
	CostPriority         float64 `json:"costPriority,omitempty"`
	SpeedPriority        float64 `json:"speedPriority,omitempty"`
	IntelligencePriority float64 `json:"intelligencePriority,omitempty"`
}

type MCPPrompt struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description,omitempty"`
	Arguments   []MCPPromptArgument    `json:"arguments,omitempty"`
	Schema      map[string]interface{} `json:"schema,omitempty"`
	Metadata    map[string]string      `json:"metadata,omitempty"`
}

type MCPPromptArgument struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	Required    bool        `json:"required,omitempty"`
	Type        string      `json:"type,omitempty"`
	Default     interface{} `json:"default,omitempty"`
}

type MCPPromptCapabilities struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

type MCPPromptMessage struct {
	Role    string                 `json:"role"`
	Content string                 `json:"content"`
	Name    string                 `json:"name,omitempty"`
	Meta    map[string]interface{} `json:"meta,omitempty"`
}

type MCPPromptResult struct {
	Prompt    string                 `json:"prompt"`
	Messages  []MCPPromptMessage     `json:"messages,omitempty"`
	Variables map[string]interface{} `json:"variables,omitempty"`
	Metadata  map[string]string      `json:"metadata,omitempty"`
}

type MCPResource struct {
	URI         string            `json:"uri"`
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	MimeType    string            `json:"mimeType,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

type MCPResourceCapabilities struct {
	Subscribe   bool `json:"subscribe,omitempty"`
	ListChanged bool `json:"listChanged,omitempty"`
}

type MCPResourceContent struct {
	URI      string            `json:"uri"`
	MimeType string            `json:"mimeType"`
	Text     string            `json:"text,omitempty"`
	Blob     []byte            `json:"blob,omitempty"`
	Reader   io.Reader         `json:"-"` // For streaming content
	Metadata map[string]string `json:"metadata,omitempty"`
}

type MCPResourceType string

type MCPResourceUpdate struct {
	URI       string                `json:"uri"`
	Type      MCPResourceUpdateType `json:"type"`
	Content   *MCPResourceContent   `json:"content,omitempty"`
	Timestamp time.Time             `json:"timestamp"`
	Error     error                 `json:"error,omitempty"`
}

type MCPResourceUpdateType string

type MCPSamplingRequest struct {
	Messages         []MCPMessage           `json:"messages"`
	ModelPreferences *MCPModelPreferences   `json:"modelPreferences,omitempty"`
	SystemPrompt     string                 `json:"systemPrompt,omitempty"`
	IncludeContext   string                 `json:"includeContext,omitempty"`
	Temperature      *float64               `json:"temperature,omitempty"`
	MaxTokens        *int                   `json:"maxTokens,omitempty"`
	StopSequences    []string               `json:"stopSequences,omitempty"`
	Metadata         map[string]interface{} `json:"metadata,omitempty"`
}

type MCPSamplingResponse struct {
	Role       string                 `json:"role"`
	Content    MCPContent             `json:"content"`
	Model      string                 `json:"model"`
	StopReason string                 `json:"stopReason,omitempty"`
	Usage      *MCPTokenUsage         `json:"usage,omitempty"`
	Metadata   map[string]interface{} `json:"metadata,omitempty"`
}

type MCPServer interface {
	// Initialize initializes the connection to the MCP server
	Initialize(ctx context.Context) error

	// ListTools lists the tools available on the MCP server
	ListTools(ctx context.Context) ([]MCPTool, error)

	// CallTool calls a tool on the MCP server
	CallTool(ctx context.Context, name string, args interface{}) (*MCPToolResponse, error)

	// ListResources lists the resources available on the MCP server
	ListResources(ctx context.Context) ([]MCPResource, error)

	// GetResource retrieves a specific resource by URI
	GetResource(ctx context.Context, uri string) (*MCPResourceContent, error)

	// WatchResource watches for changes to a resource (if supported)
	WatchResource(ctx context.Context, uri string) (<-chan MCPResourceUpdate, error)

	// ListPrompts lists the prompts available on the MCP server
	ListPrompts(ctx context.Context) ([]MCPPrompt, error)

	// GetPrompt retrieves a specific prompt with variables
	GetPrompt(ctx context.Context, name string, variables map[string]interface{}) (*MCPPromptResult, error)

	// Sampling Methods (if supported by client)
	// CreateMessage requests the client to generate a completion using its LLM
	CreateMessage(ctx context.Context, request *MCPSamplingRequest) (*MCPSamplingResponse, error)

	// Metadata discovery methods
	// GetServerInfo returns the server metadata discovered during initialization
	GetServerInfo() (*MCPServerInfo, error)

	// GetCapabilities returns the server capabilities discovered during initialization
	GetCapabilities() (*MCPServerCapabilities, error)

	// Close closes the connection to the MCP server
	Close() error
}

type MCPServerCapabilities struct {
	Tools     *MCPToolCapabilities     `json:"tools,omitempty"`
	Resources *MCPResourceCapabilities `json:"resources,omitempty"`
	Prompts   *MCPPromptCapabilities   `json:"prompts,omitempty"`
}

type MCPServerInfo struct {
	Name    string `json:"name"`              // Required: server identifier
	Title   string `json:"title,omitempty"`   // Optional: human-readable title
	Version string `json:"version,omitempty"` // Optional: server version
}

type MCPTokenUsage struct {
	PromptTokens     int `json:"promptTokens,omitempty"`
	CompletionTokens int `json:"completionTokens,omitempty"`
	TotalTokens      int `json:"totalTokens,omitempty"`
}

type MCPTool struct {
	Name         string                 `json:"name"`
	Description  string                 `json:"description"`
	Schema       interface{}            `json:"inputSchema,omitempty"`
	OutputSchema interface{}            `json:"outputSchema,omitempty"`
	Metadata     map[string]interface{} `json:"metadata,omitempty"`
}

type MCPToolCapabilities struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

type MCPToolResponse struct {
	Content           interface{}            `json:"content,omitempty"`
	StructuredContent interface{}            `json:"structuredContent,omitempty"`
	IsError           bool                   `json:"isError,omitempty"`
	Metadata          map[string]interface{} `json:"metadata,omitempty"`
}

type Memory interface {
	// AddMessage adds a message to memory
	AddMessage(ctx context.Context, message Message) error

	// GetMessages retrieves messages from memory
	GetMessages(ctx context.Context, options ...GetMessagesOption) ([]Message, error)

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

type Message struct {
	// Role is the role of the message sender
	Role MessageRole

	// Content is the content of the message
	Content string

	// Metadata contains additional information about the message
	Metadata map[string]interface{}

	// ToolCallID is used for tool messages to reference the tool call
	ToolCallID string

	// ToolCalls contains tool call information for assistant messages
	ToolCalls []ToolCall
}

type MessageRole string

type ParameterSpec struct {
	// Type is the data type of the parameter (string, number, boolean, etc.)
	Type string

	// Description describes what the parameter is for
	Description string

	// Required indicates if the parameter is required
	Required bool

	// Default is the default value for the parameter
	Default interface{}

	// Enum is a list of possible values for the parameter
	Enum []interface{}

	// Items is the type of the items in the parameter
	Items *ParameterSpec
}

type QueryOption func(*QueryOptions)

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

	// Offset is the number of documents to skip
	Offset int

	// OrderBy specifies the field to order by
	OrderBy string

	// OrderDirection specifies the order direction (asc or desc)
	OrderDirection string
}

type ResponseFormat struct {
	Type   ResponseFormatType
	Name   string     // The name of the struct/object to be returned
	Schema JSONSchema // JSON schema representation of the struct
}

type ResponseFormatType string

type RetryPolicy struct {
	// MaxRetries is the maximum number of retries
	MaxRetries int
	// InitialBackoff is the initial backoff duration
	InitialBackoff time.Duration
	// MaxBackoff is the maximum backoff duration
	MaxBackoff time.Duration
	// BackoffMultiplier is the multiplier for backoff duration after each retry
	BackoffMultiplier float64
}

type SearchOption func(*SearchOptions)

type SearchOptions struct {
	// MinScore is the minimum similarity score (0-1)
	MinScore float32

	// Filters are metadata filters to apply to the search
	Filters map[string]interface{}

	// Class is the class/collection name to search in
	Class string

	// UseEmbedding indicates whether to use embedding for the search
	UseEmbedding bool

	// UseBM25 indicates whether to use BM25 search instead of vector search
	UseBM25 bool

	// UseNearText indicates whether to use nearText search
	UseNearText bool

	// UseKeyword indicates whether to use keyword search
	UseKeyword bool

	// Tenant is the tenant name for native multi-tenancy
	Tenant string

	// Fields specifies which fields to retrieve. If empty, all fields will be retrieved dynamically
	Fields []string
}

type SearchResult struct {
	// Document is the found document
	Document Document

	// Score is the similarity score (0-1, higher is more similar)
	Score float32
}

type Span interface {
	// End ends the span
	End()

	// AddEvent adds an event to the span
	AddEvent(name string, attributes map[string]interface{})

	// SetAttribute sets an attribute on the span
	SetAttribute(key string, value interface{})

	RecordError(err error)
}

type StoreOption func(*StoreOptions)

type StoreOptions struct {
	// BatchSize is the number of documents to store in each batch
	BatchSize int

	// GenerateVectors indicates whether to generate vectors for documents
	GenerateVectors bool

	// Class is the class/collection name to store documents in
	Class string

	// Tenant is the tenant name for native multi-tenancy
	Tenant string
}

type StreamConfig struct {
	// BufferSize determines the channel buffer size
	BufferSize int

	// IncludeThinking whether to include thinking events
	IncludeThinking bool

	// IncludeToolProgress whether to include tool execution progress
	IncludeToolProgress bool

	// IncludeIntermediateMessages whether to include intermediate messages between tool iterations
	IncludeIntermediateMessages bool
}

type StreamEvent struct {
	Type      StreamEventType        `json:"type"`
	Content   string                 `json:"content,omitempty"`
	ToolCall  *ToolCall              `json:"tool_call,omitempty"`
	Error     error                  `json:"error,omitempty"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
	Timestamp time.Time              `json:"timestamp"`
}

type StreamEventType string

type StreamForwarder func(event AgentStreamEvent)

type StreamingAgent interface {
	// RunStream executes the agent with streaming response
	RunStream(ctx context.Context, input string) (<-chan AgentStreamEvent, error)
}

type StreamingLLM interface {
	LLM

	// GenerateStream generates text with streaming response
	GenerateStream(ctx context.Context, prompt string, options ...GenerateOption) (<-chan StreamEvent, error)

	// GenerateWithToolsStream generates text with tools and streaming response
	GenerateWithToolsStream(ctx context.Context, prompt string, tools []Tool, options ...GenerateOption) (<-chan StreamEvent, error)
}

type TaskExecutor interface {
	// ExecuteSync executes a task synchronously
	ExecuteSync(ctx context.Context, taskName string, params interface{}, opts *TaskOptions) (*TaskResult, error)

	// ExecuteAsync executes a task asynchronously and returns a channel for the result
	ExecuteAsync(ctx context.Context, taskName string, params interface{}, opts *TaskOptions) (<-chan *TaskResult, error)

	// ExecuteWorkflow initiates a temporal workflow
	ExecuteWorkflow(ctx context.Context, workflowName string, params interface{}, opts *TaskOptions) (*TaskResult, error)

	// ExecuteWorkflowAsync initiates a temporal workflow asynchronously
	ExecuteWorkflowAsync(ctx context.Context, workflowName string, params interface{}, opts *TaskOptions) (<-chan *TaskResult, error)

	// CancelTask cancels a running task
	CancelTask(ctx context.Context, taskID string) error

	// GetTaskStatus gets the status of a task
	GetTaskStatus(ctx context.Context, taskID string) (string, error)

	// ExecuteStep executes a single step in a task's plan
	ExecuteStep(ctx context.Context, task interface{}, step interface{}) error

	// ExecuteTask executes all steps in a task's plan
	ExecuteTask(ctx context.Context, task interface{}) error
}

type TaskOptions struct {
	// Timeout specifies the maximum duration for task execution
	Timeout *time.Duration
	// RetryPolicy specifies the retry policy for the task
	RetryPolicy *RetryPolicy
	// Metadata contains additional information for the task execution
	Metadata map[string]interface{}
}

type TaskPlanner interface {
	// CreatePlan creates a plan for a task
	CreatePlan(ctx context.Context, task interface{}) (string, error)
}

type TaskResult struct {
	// Data contains the result data
	Data interface{}
	// Error contains any error that occurred during task execution
	Error error
	// Metadata contains additional information about the task execution
	Metadata map[string]interface{}
}

type TaskService interface {
	// CreateTask creates a new task
	CreateTask(ctx context.Context, req interface{}) (interface{}, error)
	// GetTask gets a task by ID
	GetTask(ctx context.Context, taskID string) (interface{}, error)
	// ListTasks returns tasks filtered by the provided criteria
	ListTasks(ctx context.Context, filter interface{}) ([]interface{}, error)
	// ApproveTaskPlan approves or rejects a task plan
	ApproveTaskPlan(ctx context.Context, taskID string, req interface{}) (interface{}, error)
	// UpdateTask updates an existing task with new steps or modifications
	UpdateTask(ctx context.Context, taskID string, updates interface{}) (interface{}, error)
	// AddTaskLog adds a log entry to a task
	AddTaskLog(ctx context.Context, taskID string, message string, level string) error
}

type TokenUsage struct {
	// InputTokens is the number of tokens in the input/prompt
	InputTokens int

	// OutputTokens is the number of tokens in the generated response
	OutputTokens int

	// TotalTokens is the total number of tokens used (input + output)
	TotalTokens int

	// ReasoningTokens is the number of tokens used for reasoning (optional, for models that support it)
	ReasoningTokens int
}

type Tool interface {
	// Name returns the name of the tool
	Name() string

	// Description returns a description of what the tool does
	Description() string

	// Run executes the tool with the given input
	Run(ctx context.Context, input string) (string, error)

	// Parameters returns the parameters that the tool accepts
	Parameters() map[string]ParameterSpec

	// Execute executes the tool with the given arguments
	Execute(ctx context.Context, args string) (string, error)
}

type ToolCall struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	DisplayName string `json:"display_name,omitempty"`
	Internal    bool   `json:"internal,omitempty"`
	Arguments   string `json:"arguments"`
}

type ToolCallEvent struct {
	ID          string `json:"id,omitempty"`
	Name        string `json:"name"`
	DisplayName string `json:"display_name,omitempty"`
	Internal    bool   `json:"internal,omitempty"`
	Arguments   string `json:"arguments,omitempty"`
	Result      string `json:"result,omitempty"`
	Status      string `json:"status"` // "starting", "executing", "completed", "error"
}

type ToolRegistry interface {
	// Register registers a tool with the registry
	Register(tool Tool)

	// Get returns a tool by name
	Get(name string) (Tool, bool)

	// List returns all registered tools
	List() []Tool
}

type ToolWithDisplayName interface {
	// DisplayName returns a human-friendly name for the tool
	DisplayName() string
}

type Tracer interface {
	// StartSpan starts a new span and returns a new context containing the span
	StartSpan(ctx context.Context, name string) (context.Context, Span)

	// StartTraceSession starts a root trace session for a request with the given contextID
	// This creates a root span that will group all subsequent operations under the same trace
	StartTraceSession(ctx context.Context, contextID string) (context.Context, Span)
}

type Transaction interface {
	// Collection returns a reference to a specific collection/table within the transaction
	Collection(name string) CollectionRef

	// Commit commits the transaction
	Commit() error

	// Rollback rolls back the transaction
	Rollback() error
}

type VectorStore interface {
	Store(ctx context.Context, documents []Document, options ...StoreOption) error
	Get(ctx context.Context, id string, options ...StoreOption) (*Document, error)
	Search(ctx context.Context, query string, limit int, options ...SearchOption) ([]SearchResult, error)
	SearchByVector(ctx context.Context, vector []float32, limit int, options ...SearchOption) ([]SearchResult, error)
	Delete(ctx context.Context, ids []string, options ...DeleteOption) error

	// Global operations for shared data (no tenant context)
	GlobalStore(ctx context.Context, documents []Document, options ...StoreOption) error
	GlobalSearch(ctx context.Context, query string, limit int, options ...SearchOption) ([]SearchResult, error)
	GlobalSearchByVector(ctx context.Context, vector []float32, limit int, options ...SearchOption) ([]SearchResult, error)
	GlobalDelete(ctx context.Context, ids []string, options ...DeleteOption) error

	// Tenant management for native multi-tenancy
	CreateTenant(ctx context.Context, tenantName string) error
	DeleteTenant(ctx context.Context, tenantName string) error
	ListTenants(ctx context.Context) ([]string, error)
}

type VectorStoreConfig struct {
	// Host is the hostname of the vector store server
	Host string

	// APIKey is the authentication key for the vector store
	APIKey string

	// Scheme is the URL scheme (http or https)
	Scheme string

	// ClassPrefix is the default prefix for class/collection names
	ClassPrefix string

	// DistanceMetric is the similarity metric to use (e.g., "cosine", "euclidean", "dot")
	DistanceMetric string
}