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 CacheConfig struct {
	// CacheSystemMessage marks the system message for caching
	CacheSystemMessage bool
	// CacheTools marks all tool definitions for caching (cache_control on last tool)
	CacheTools bool
	// CacheConversation marks conversation history for caching (cache_control on last message)
	// Each new turn just appends to the cached prefix
	CacheConversation bool
	// CacheTTL sets the cache duration: "5m" (default) or "1h"
	CacheTTL string
}

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 Entity struct {
	// ID is the unique identifier for the entity
	ID string `json:"id"`

	// Name is the human-readable name of the entity
	Name string `json:"name"`

	// Type categorizes the entity (e.g., "Person", "Organization", "Concept")
	Type string `json:"type"`

	// Description provides detailed information about the entity
	Description string `json:"description"`

	// Embedding is the vector representation of the entity
	Embedding []float32 `json:"embedding,omitempty"`

	// Properties contains additional key-value attributes
	Properties map[string]interface{} `json:"properties,omitempty"`

	// OrgID is the organization ID for multi-tenancy
	OrgID string `json:"org_id,omitempty"`

	// CreatedAt is the creation timestamp
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt is the last update timestamp
	UpdatedAt time.Time `json:"updated_at"`
}

type EntityTypeSchema struct {
	// Name is the type name (e.g., "Person")
	Name string `json:"name"`

	// Description describes the entity type
	Description string `json:"description"`

	// Properties defines the expected properties
	Properties []PropertySchema `json:"properties,omitempty"`
}

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

type ExtractionOption func(*ExtractionOptions)

type ExtractionOptions struct {
	// SchemaGuided indicates whether to use schema-guided extraction
	SchemaGuided bool

	// EntityTypes limits extraction to specific entity types
	EntityTypes []string

	// RelationshipTypes limits extraction to specific relationship types
	RelationshipTypes []string

	// MinConfidence filters entities/relationships by minimum confidence
	MinConfidence float32

	// MaxEntities limits the number of entities to extract
	MaxEntities int

	// DedupThreshold is the embedding similarity threshold for deduplication
	DedupThreshold float32
}

type ExtractionResult struct {
	// Entities are the extracted entities
	Entities []Entity `json:"entities"`

	// Relationships are the extracted relationships
	Relationships []Relationship `json:"relationships"`

	// SourceText is the original text
	SourceText string `json:"source_text"`

	// Confidence is the overall extraction confidence (0-1)
	Confidence float32 `json:"confidence"`
}

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
	CacheConfig    *CacheConfig    // Optional prompt caching configuration (Anthropic only)
}

type GeneratedImage struct {
	// Data contains the raw image bytes
	Data []byte

	// Base64 contains the base64-encoded image data
	Base64 string

	// MimeType is the MIME type of the image (e.g., "image/png", "image/jpeg")
	MimeType string

	// URL is the storage URL (populated after upload to storage)
	URL string

	// RevisedPrompt is the prompt actually used by the model (may differ from input)
	RevisedPrompt string

	// FinishReason indicates why generation stopped
	FinishReason string
}

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 GraphContext struct {
	// CentralEntity is the starting point of the traversal
	CentralEntity Entity `json:"central_entity"`

	// Entities are all entities discovered within the traversal depth
	Entities []Entity `json:"entities"`

	// Relationships are all relationships discovered in the traversal
	Relationships []Relationship `json:"relationships"`

	// Depth is the actual traversal depth reached
	Depth int `json:"depth"`
}

type GraphPath struct {
	// Source is the starting entity
	Source Entity `json:"source"`

	// Target is the destination entity
	Target Entity `json:"target"`

	// Entities are intermediate entities (ordered)
	Entities []Entity `json:"entities"`

	// Relationships are relationships connecting the entities (ordered)
	Relationships []Relationship `json:"relationships"`

	// Length is the number of hops
	Length int `json:"length"`
}

type GraphRAGStore interface {
	// Entity CRUD operations
	StoreEntities(ctx context.Context, entities []Entity, options ...GraphStoreOption) error
	GetEntity(ctx context.Context, id string, options ...GraphStoreOption) (*Entity, error)
	UpdateEntity(ctx context.Context, entity Entity, options ...GraphStoreOption) error
	DeleteEntity(ctx context.Context, id string, options ...GraphStoreOption) error

	// Relationship CRUD operations
	StoreRelationships(ctx context.Context, relationships []Relationship, options ...GraphStoreOption) error
	GetRelationships(ctx context.Context, entityID string, direction RelationshipDirection, options ...GraphSearchOption) ([]Relationship, error)
	DeleteRelationship(ctx context.Context, id string, options ...GraphStoreOption) error

	// Search operations
	Search(ctx context.Context, query string, limit int, options ...GraphSearchOption) ([]GraphSearchResult, error)
	LocalSearch(ctx context.Context, query string, entityID string, depth int, options ...GraphSearchOption) ([]GraphSearchResult, error)
	GlobalSearch(ctx context.Context, query string, communityLevel int, options ...GraphSearchOption) ([]GraphSearchResult, error)

	// Graph traversal
	TraverseFrom(ctx context.Context, entityID string, depth int, options ...GraphSearchOption) (*GraphContext, error)
	ShortestPath(ctx context.Context, sourceID, targetID string, options ...GraphSearchOption) (*GraphPath, error)

	// Entity/Relationship extraction (requires LLM)
	ExtractFromText(ctx context.Context, text string, llm LLM, options ...ExtractionOption) (*ExtractionResult, error)

	// Schema management
	ApplySchema(ctx context.Context, schema GraphSchema) error
	DiscoverSchema(ctx context.Context) (*GraphSchema, error)

	// Multi-tenancy
	SetTenant(tenant string)
	GetTenant() string

	// Lifecycle
	Close() error
}

type GraphSchema struct {
	// EntityTypes are the allowed entity type definitions
	EntityTypes []EntityTypeSchema `json:"entity_types"`

	// RelationshipTypes are the allowed relationship type definitions
	RelationshipTypes []RelationshipTypeSchema `json:"relationship_types"`
}

type GraphSearchMode string

type GraphSearchOption func(*GraphSearchOptions)

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

	// EntityTypes filters by entity types
	EntityTypes []string

	// RelationshipTypes filters by relationship types
	RelationshipTypes []string

	// MaxDepth limits traversal depth (default: 2)
	MaxDepth int

	// IncludeRelationships includes relationships in search results
	IncludeRelationships bool

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

	// SearchMode specifies the search mode
	SearchMode GraphSearchMode
}

type GraphSearchResult struct {
	// Entity is the found entity
	Entity Entity `json:"entity"`

	// Score is the relevance score (0-1, higher is more relevant)
	Score float32 `json:"score"`

	// Context contains related entities from graph traversal
	Context []Entity `json:"context,omitempty"`

	// Path represents the relationship path to this entity (for local search)
	Path []Relationship `json:"path,omitempty"`

	// CommunityID is the community identifier (for global search)
	CommunityID string `json:"community_id,omitempty"`
}

type GraphStoreOption func(*GraphStoreOptions)

type GraphStoreOptions struct {
	// BatchSize is the number of items to store in each batch
	BatchSize int

	// GenerateEmbeddings indicates whether to generate embeddings
	GenerateEmbeddings bool

	// Tenant is the tenant name for native multi-tenancy
	Tenant 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 ImageData struct {
	// Data contains raw image bytes
	Data []byte

	// Base64 contains base64-encoded image data
	Base64 string

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

	// URL is a URL to fetch the image from
	URL string
}

type ImageGenerationOption func(*ImageGenerationOptions)

type ImageGenerationOptions struct {
	// NumberOfImages specifies how many images to generate (default: 1)
	NumberOfImages int

	// AspectRatio controls the image dimensions (e.g., "1:1", "16:9", "9:16", "4:3", "3:4")
	AspectRatio string

	// OutputFormat specifies the desired output format ("png", "jpeg")
	OutputFormat string

	// SafetyFilterLevel controls content filtering ("none", "low", "medium", "high")
	SafetyFilterLevel string
}

type ImageGenerationRequest struct {
	// Prompt is the text description of the image to generate (required)
	Prompt string

	// ReferenceImage is an optional input image for image-to-image generation
	ReferenceImage *ImageData

	// Options contains generation configuration
	Options *ImageGenerationOptions
}

type ImageGenerationResponse struct {
	// Images contains the generated images
	Images []GeneratedImage

	// Usage contains token/cost information if available
	Usage *ImageUsage

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

type ImageGenerator interface {
	// GenerateImage generates one or more images from a text prompt
	GenerateImage(ctx context.Context, request ImageGenerationRequest) (*ImageGenerationResponse, error)

	// SupportsImageGeneration returns true if this LLM supports image generation
	SupportsImageGeneration() bool

	// SupportedImageFormats returns the output formats supported (e.g., "png", "jpeg")
	SupportedImageFormats() []string
}

type ImageReference struct {
	// URL is the storage URL of the generated image
	URL string

	// MimeType is the image MIME type
	MimeType string

	// Prompt is the original prompt used to generate the image
	Prompt string

	// CreatedAt is the timestamp when the image was generated
	CreatedAt time.Time
}

type ImageUsage struct {
	// InputTokens used for the prompt
	InputTokens int

	// OutputTokens used for generation
	OutputTokens int

	// ImagesGenerated is the number of images produced
	ImagesGenerated int
}

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 PropertySchema struct {
	// Name is the property name
	Name string `json:"name"`

	// Type is the data type: "string", "number", "boolean", "datetime"
	Type string `json:"type"`

	// Required indicates whether the property is required
	Required bool `json:"required"`

	// Description describes the property
	Description string `json:"description"`

	// Default is the default value (optional)
	Default interface{} `json:"default,omitempty"`
}

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 Relationship struct {
	// ID is the unique identifier for the relationship
	ID string `json:"id"`

	// SourceID is the ID of the source entity
	SourceID string `json:"source_id"`

	// TargetID is the ID of the target entity
	TargetID string `json:"target_id"`

	// Type describes the relationship (e.g., "WORKS_ON", "MANAGES", "LOCATED_IN")
	Type string `json:"type"`

	// Description provides context about the relationship
	Description string `json:"description"`

	// Strength indicates the relationship strength (0.0 to 1.0, default 1.0)
	Strength float32 `json:"strength"`

	// Properties contains additional attributes
	Properties map[string]interface{} `json:"properties,omitempty"`

	// OrgID is the organization ID for multi-tenancy
	OrgID string `json:"org_id,omitempty"`

	// CreatedAt is the creation timestamp
	CreatedAt time.Time `json:"created_at"`
}

type RelationshipDirection string

type RelationshipTypeSchema struct {
	// Name is the relationship type name (e.g., "WORKS_ON")
	Name string `json:"name"`

	// Description describes the relationship type
	Description string `json:"description"`

	// SourceTypes are the allowed source entity types
	SourceTypes []string `json:"source_types,omitempty"`

	// TargetTypes are the allowed target entity types
	TargetTypes []string `json:"target_types,omitempty"`

	// Properties defines the expected properties
	Properties []PropertySchema `json:"properties,omitempty"`
}

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

	// CacheCreationInputTokens is the number of tokens written to cache (Anthropic only)
	CacheCreationInputTokens int

	// CacheReadInputTokens is the number of tokens read from cache (Anthropic only)
	CacheReadInputTokens 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
}