interfaces

type AgentEventType string

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 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 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)

	// 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)
}

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)

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

type MCPTool struct {
	Name        string
	Description string
	Schema      interface{}
}

type MCPToolResponse struct {
	Content interface{}
	IsError bool
}

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 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 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
}