core

type AdaptPolicy int

type AdvancedSearchOptions struct {
	SearchOptions
	PreFilter     *FilterExpression // Applied before vector search
	PostFilter    *FilterExpression // Applied after vector search
	ArraySupport  bool              // Enable array field filtering
	NumericRanges bool              // Enable numeric range optimization
}

type AggregationMethod string

type AggregationRequest struct {
	Type       AggregationType        `json:"type"`
	Field      string                 `json:"field"`      // Metadata field to aggregate
	GroupBy    []string               `json:"group_by"`   // Fields to group by
	Filters    map[string]interface{} `json:"filters"`    // Optional filters
	Collection string                 `json:"collection"` // Optional collection filter
	Having     map[string]interface{} `json:"having"`     // Post-aggregation filters
	OrderBy    string                 `json:"order_by"`   // Field to order results by
	Limit      int                    `json:"limit"`      // Max results
}

type AggregationResponse struct {
	Request AggregationRequest  `json:"request"`
	Results []AggregationResult `json:"results"`
	Total   int                 `json:"total"`
}

type AggregationResult struct {
	GroupKeys map[string]interface{} `json:"group_keys"` // Group by field values
	Value     interface{}            `json:"value"`      // Aggregated value
	Count     int                    `json:"count"`      // Number of items in group
}

type AggregationType string

type AutoSaveConfig struct {
	Enabled     bool          `json:"enabled"`     // Enable auto-save (default: true)
	Interval    time.Duration `json:"interval"`    // Save interval (default: 5 minutes)
	SaveOnClose bool          `json:"saveOnClose"` // Save on database close (default: true)
	MinChanges  int           `json:"minChanges"`  // Minimum changes before saving (default: 100)
}

type Collection struct {
	ID          int                    `json:"id"`
	Name        string                 `json:"name"`
	Dimensions  int                    `json:"dimensions"`
	Description string                 `json:"description,omitempty"`
	Metadata    map[string]interface{} `json:"metadata,omitempty"`
	CreatedAt   time.Time              `json:"created_at"`
	UpdatedAt   time.Time              `json:"updated_at"`
}

type CollectionStats struct {
	Name           string    `json:"name"`
	Count          int64     `json:"count"`
	Dimensions     int       `json:"dimensions"`
	Size           int64     `json:"size"`
	CreatedAt      time.Time `json:"created_at"`
	LastInsertedAt time.Time `json:"last_inserted_at,omitempty"`
}

type Config struct {
	Path           string               `json:"path"`                     // Database file path
	VectorDim      int                  `json:"vectorDim"`                // Expected vector dimension, 0 = auto-detect
	AutoDimAdapt   AdaptPolicy          `json:"autoDimAdapt"`             // How to handle dimension mismatches
	SimilarityFn   SimilarityFunc       `json:"-"`                        // Similarity function
	IndexType      IndexType            `json:"indexType"`                // Index type to use
	HNSW           HNSWConfig           `json:"hnsw,omitempty"`           // HNSW index configuration
	IVF            IVFConfig            `json:"ivf,omitempty"`            // IVF index configuration
	TextSimilarity TextSimilarityConfig `json:"textSimilarity,omitempty"` // Text similarity configuration
	Quantization   QuantizationConfig   `json:"quantization,omitempty"`   // Quantization configuration
	Logger         Logger               `json:"-"`                        // Logger instance (defaults to nop logger)
	AutoSave       AutoSaveConfig       `json:"autoSave,omitempty"`       // Auto-save configuration
}

type CustomReranker struct {
	// ScoreFunc computes a custom score for each result
	ScoreFunc func(ctx context.Context, query string, result ScoredEmbedding) float64
}

type DimensionAdapter struct {
	// contains filtered or unexported fields
}

type DimensionAnalysis struct {
	PrimaryDim     int         `json:"primaryDim"`     // Most common dimension
	PrimaryCount   int         `json:"primaryCount"`   // Count of primary dimension
	Dimensions     map[int]int `json:"dimensions"`     // Map of dimension -> count
	TotalVectors   int         `json:"totalVectors"`   // Total number of vectors
	NeedsMigration bool        `json:"needsMigration"` // Whether migration is recommended
}

type DiversityMethod string

type DiversityReranker struct {
	// Lambda controls the diversity vs relevance trade-off
	// 0.0 = maximum diversity, 1.0 = maximum relevance
	Lambda float64
	// SimilarityFunc computes similarity between two embeddings
	SimilarityFunc SimilarityFunc
}

type DiversitySearchOptions struct {
	// Lambda parameter for MMR (0 = max diversity, 1 = max relevance)
	Lambda float32

	// Diversity method
	Method DiversityMethod

	// Minimum distance between results
	MinDistance float32

	// Base search options
	SearchOptions
}

type Document struct {
	ID        string                 `json:"id"`
	Title     string                 `json:"title"`
	SourceURL string                 `json:"source_url,omitempty"`
	Content   string                 `json:"content,omitempty"` // Full document content
	Version   int                    `json:"version"`
	Author    string                 `json:"author,omitempty"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
	ACL       []string               `json:"acl,omitempty"` // Allowed user IDs or groups
	CreatedAt time.Time              `json:"created_at"`
	UpdatedAt time.Time              `json:"updated_at"`
}

type DocumentInfo struct {
	DocID          string  `json:"docId"`
	EmbeddingCount int     `json:"embeddingCount"`
	FirstCreated   *string `json:"firstCreated,omitempty"`
	LastUpdated    *string `json:"lastUpdated,omitempty"`
}

type DumpFormat string

type DumpOptions struct {
	Format         DumpFormat      // Export format
	IncludeVectors bool            // Include vector data (can be large)
	IncludeIndex   bool            // Include index data (HNSW, IVF)
	Filter         *MetadataFilter // Optional filter for selective export
	BatchSize      int             // Batch size for export (default: 1000)
}

type DumpStats struct {
	TotalEmbeddings  int   `json:"total_embeddings"`
	TotalDocuments   int   `json:"total_documents"`
	TotalCollections int   `json:"total_collections"`
	BytesWritten     int64 `json:"bytes_written"`
}

type Embedding struct {
	ID           string            `json:"id"`
	CollectionID int               `json:"collection_id,omitempty"`
	Collection   string            `json:"collection,omitempty"`
	Vector       []float32         `json:"vector"`
	Content      string            `json:"content"`
	DocID        string            `json:"docId,omitempty"`
	Metadata     map[string]string `json:"metadata,omitempty"`
	ACL          []string          `json:"acl,omitempty"` // Allowed user IDs or groups
}

type ExportMetadata struct {
	Version    string `json:"version"`
	Dimensions int    `json:"dimensions"`
	Count      int    `json:"count"`
	ExportedAt string `json:"exported_at"`
	Config     Config `json:"config"`
}

type FacetFilter struct {
	// Type of filter
	Type FacetFilterType

	// Values for equality/inclusion filters
	Values []interface{}

	// Range for numeric filters
	Min interface{}
	Max interface{}

	// Pattern for text filters
	Pattern string

	// Nested filters for complex conditions
	Nested []FacetFilter

	// Logical operator for nested filters
	Operator LogicalOperator
}

type FacetFilterType string

type FacetResult struct {
	Field  string
	Values map[string]int
	Total  int
}

type FacetedSearchOptions struct {
	SearchOptions

	// Facets to filter by
	Facets map[string]FacetFilter

	// Whether to return facet counts
	ReturnFacets bool

	// Maximum number of facet values to return
	MaxFacetValues int
}

type FilterExpression struct {
	Operator FilterOperator
	Field    string
	Value    interface{}
	Children []*FilterExpression
}

type FilterOperator string

type HNSWConfig struct {
	Enabled        bool `json:"enabled"`
	M              int  `json:"m"`              // Maximum connections per node (default: 16)
	EfConstruction int  `json:"efConstruction"` // Candidates during construction (default: 64)
	EfSearch       int  `json:"efSearch"`       // Candidates during search (default: 50)
	NumWorkers     int  `json:"numWorkers"`     // Number of parallel workers for index building (default: 4)
	Incremental    bool `json:"incremental"`    // Enable incremental indexing (default: true)
}

type HybridReranker struct {
	Rerankers []Reranker
	Weights   []float64
}

type HybridSearchOptions struct {
	SearchOptions
	// Fusion parameter for RRF (default 60)
	RRFK float64
}

type IVFConfig struct {
	Enabled    bool `json:"enabled"`
	NCentroids int  `json:"nCentroids"` // Number of centroids (default: 100)
	NProbe     int  `json:"nProbe"`     // Number of clusters to search (default: 10)
}

type ImportStats struct {
	TotalEmbeddings int `json:"total_embeddings"`
	TotalDocuments  int `json:"total_documents"`
	FailedCount     int `json:"failed_count"`
	SkippedCount    int `json:"skipped_count"`
}

type IncrementalIndex struct {
	// contains filtered or unexported fields
}

type IndexType int

type KeywordMatchReranker struct {
	// Boost is the score multiplier for keyword matches
	Boost float64
	// CaseSensitive enables case-sensitive matching
	CaseSensitive bool
}

type LoadOptions struct {
	Format       DumpFormat // Import format
	SkipExisting bool       // Skip existing embeddings (by ID)
	Replace      bool       // Replace existing embeddings
	BatchSize    int        // Batch size for import (default: 100)
	Upsert       bool       // Use upsert instead of insert
}

type LogLevel int

type Logger interface {
	// Debug logs a debug message
	Debug(msg string, keyvals ...any)
	// Info logs an informational message
	Info(msg string, keyvals ...any)
	// Warn logs a warning message
	Warn(msg string, keyvals ...any)
	// Error logs an error message
	Error(msg string, keyvals ...any)
	// With returns a new logger with additional key-value pairs
	With(keyvals ...any) Logger
}

type LogicalOperator string

type Message struct {
	ID        string                 `json:"id"`
	SessionID string                 `json:"session_id"`
	Role      string                 `json:"role"` // 'user', 'assistant', 'system'
	Content   string                 `json:"content"`
	Vector    []float32              `json:"vector,omitempty"` // Embedding for long-term memory
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
	CreatedAt time.Time              `json:"created_at"`
}

type MetadataFilter struct {
	// contains filtered or unexported fields
}

type MultiVectorEntity struct {
	// Entity ID
	ID string

	// Vectors associated with this entity
	Vectors map[string][]float32

	// Metadata for the entity
	Metadata map[string]interface{}

	// Content/text for the entity
	Content string
}

type MultiVectorSearchOptions struct {
	// Which vector fields to search
	VectorFields []string

	// Weights for each vector field
	FieldWeights map[string]float32

	// Aggregation method for combining scores
	Aggregation AggregationMethod

	// Standard search options
	SearchOptions
}

type NegativeSearchOptions struct {
	// Positive examples (find similar to these)
	PositiveVectors [][]float32

	// Negative examples (avoid similar to these)
	NegativeVectors [][]float32

	// Weight for negative examples (higher = stronger avoidance)
	NegativeWeight float32

	// Base search options
	SearchOptions
}

type QuantizationConfig struct {
	Enabled bool   `json:"enabled"` // Enable quantization
	Type    string `json:"type"`    // "scalar" (SQ8) or "binary" (BQ)
	NBits   int    `json:"nBits"`   // Bits per component (default 8 for SQ8)
}

type ReciprocalRankFusionReranker struct {
	// K is the RRF constant (typically 60)
	K float64
	// VectorWeight is the weight for vector similarity scores
	VectorWeight float64
	// TextWeight is the weight for text match scores
	TextWeight float64
}

type RerankOptions struct {
	// TopK is the number of results to return after reranking
	TopK int
	// Threshold is the minimum score threshold after reranking
	Threshold float64
	// PreserveOriginalScore keeps the original vector similarity score
	// If false, the score is replaced by the reranker's score
	PreserveOriginalScore bool
}

type Reranker interface {
	// Rerank reorders the scored embeddings based on the query
	// Returns a new slice with the same embeddings, but potentially different scores/order
	Rerank(ctx context.Context, query string, results []ScoredEmbedding) ([]ScoredEmbedding, error)
}

type RerankerFunc func(ctx context.Context, query string, results []ScoredEmbedding) ([]ScoredEmbedding, error)

type SQLiteStore struct {
	// contains filtered or unexported fields
}

type ScoreNormalizationReranker struct {
	MinScore float64
	MaxScore float64
}

type ScoredEmbedding struct {
	Embedding
	Score float64 `json:"score"`
}

type SearchOptions struct {
	Collection string            `json:"collection,omitempty"` // Collection name to search in
	TopK       int               `json:"topK"`
	Filter     map[string]string `json:"filter,omitempty"`
	Threshold  float64           `json:"threshold,omitempty"`
	QueryText  string            `json:"queryText,omitempty"`  // Optional query text for enhanced matching
	TextWeight float64           `json:"textWeight,omitempty"` // Weight for text similarity (0.0-1.0, default 0.3)
}

type Session struct {
	ID        string                 `json:"id"`
	UserID    string                 `json:"user_id"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
	CreatedAt time.Time              `json:"created_at"`
	UpdatedAt time.Time              `json:"updated_at"`
}

type SimilarityFunc func(a, b []float32) float64

type Store interface {
	// Init initializes the store, creates necessary tables, and builds/loads indexes.
	// It must be called before any other operation.
	Init(ctx context.Context) error

	// Upsert inserts or updates a single embedding.
	// If the vector dimension doesn't match the store's dimension, it applies the adaptation policy.
	Upsert(ctx context.Context, emb *Embedding) error

	// UpsertBatch inserts or updates multiple embeddings in a single database transaction.
	// This is significantly faster than calling Upsert multiple times.
	UpsertBatch(ctx context.Context, embs []*Embedding) error

	// Search performs a vector similarity search.
	// It uses the configured index (HNSW or IVF) if available, otherwise falls back to linear search.
	Search(ctx context.Context, query []float32, opts SearchOptions) ([]ScoredEmbedding, error)

	// RangeSearch finds all vectors within a specified distance (radius) from the query.
	RangeSearch(ctx context.Context, query []float32, radius float32, opts SearchOptions) ([]ScoredEmbedding, error)

	// Delete removes an embedding by its unique ID.
	Delete(ctx context.Context, id string) error

	// DeleteByDocID removes all embeddings associated with a specific document ID.
	DeleteByDocID(ctx context.Context, docID string) error

	// DeleteBatch removes multiple embeddings by their IDs in a single operation.
	DeleteBatch(ctx context.Context, ids []string) error

	// DeleteByFilter removes embeddings matching the given metadata filter criteria.
	DeleteByFilter(ctx context.Context, filter *MetadataFilter) error

	// Close closes the store, releases database connections, and persists memory indexes.
	Close() error

	// Stats returns global statistics about the vector store (count, dimensions, size).
	Stats(ctx context.Context) (StoreStats, error)

	// CreateCollection creates a new named collection for multi-tenant isolation.
	CreateCollection(ctx context.Context, name string, dimensions int) (*Collection, error)
	// GetCollection retrieves collection information by name.
	GetCollection(ctx context.Context, name string) (*Collection, error)
	// ListCollections lists all available collections.
	ListCollections(ctx context.Context) ([]*Collection, error)
	// DeleteCollection deletes a collection and all its associated data.
	DeleteCollection(ctx context.Context, name string) error
	// GetCollectionStats returns statistics for a specific collection.
	GetCollectionStats(ctx context.Context, name string) (*CollectionStats, error)

	// TrainIndex learns cluster centroids for IVF indexes from existing data.
	TrainIndex(ctx context.Context, numCentroids int) error
	// TrainQuantizer learns value ranges for scalar quantization from existing data.
	TrainQuantizer(ctx context.Context) error

	// CreateDocument creates a document record for source tracking and versioning.
	CreateDocument(ctx context.Context, doc *Document) error
	// GetDocument retrieves a document record by its ID.
	GetDocument(ctx context.Context, id string) (*Document, error)
	// DeleteDocument deletes a document and all its linked embeddings (cascading).
	DeleteDocument(ctx context.Context, id string) error
	// ListDocumentsWithFilter lists documents matching specific criteria like author.
	ListDocumentsWithFilter(ctx context.Context, author string, limit int) ([]*Document, error)

	// CreateSession starts a new conversation thread for chat memory.
	CreateSession(ctx context.Context, session *Session) error
	// GetSession retrieves a chat session by its ID.
	GetSession(ctx context.Context, id string) (*Session, error)
	// AddMessage appends a new message (user or assistant) to a session.
	AddMessage(ctx context.Context, msg *Message) error
	// GetSessionHistory returns the chronological message history for a session.
	GetSessionHistory(ctx context.Context, sessionID string, limit int) ([]*Message, error)
	// SearchChatHistory performs semantic search over previous messages in a session.
	SearchChatHistory(ctx context.Context, queryVec []float32, sessionID string, limit int) ([]*Message, error)

	// SearchWithACL performs vector search while enforcing access control rules.
	SearchWithACL(ctx context.Context, query []float32, acl []string, opts SearchOptions) ([]ScoredEmbedding, error)
	// HybridSearch combines vector similarity with FTS5 keyword matching using RRF fusion.
	HybridSearch(ctx context.Context, vectorQuery []float32, textQuery string, opts HybridSearchOptions) ([]ScoredEmbedding, error)
	// SearchWithAdvancedFilter performs vector search with complex boolean and range metadata filters.
	SearchWithAdvancedFilter(ctx context.Context, query []float32, opts AdvancedSearchOptions) ([]ScoredEmbedding, error)
}

type StoreError struct {
	Op  string // Operation name
	Err error  // Underlying error
}

type StoreStats struct {
	Count      int64 `json:"count"`
	Dimensions int   `json:"dimensions"`
	Size       int64 `json:"size"`
}

type StreamingOptions struct {
	SearchOptions
	BatchSize        int                        // Number of vectors to process per batch
	MaxLatency       time.Duration              // Maximum time to wait before sending partial results
	EarlyTerminate   bool                       // Stop when enough good results are found
	QualityThreshold float64                    // Score threshold for early termination
	ProgressCallback func(processed, total int) // Optional progress reporting
}

type StreamingResult struct {
	ScoredEmbedding
	Timestamp time.Time
	BatchID   int
}

type TextSimilarity interface {
	CalculateSimilarity(query, text string) float64
}

type TextSimilarityConfig struct {
	Enabled       bool    `json:"enabled"`       // Enable text similarity matching
	DefaultWeight float64 `json:"defaultWeight"` // Default weight for text similarity (0.0-1.0)
}