vectorstore

type AddOptions struct {
	// Namespace partitions the store.
	Namespace string

	// Upsert controls whether to update existing documents. Default: true
	Upsert bool
}

type Document struct {
	// ID is the unique identifier. If empty on Add, one will be generated.
	ID string

	// Content is the original text content.
	Content string

	// Embedding is the vector representation.
	Embedding embedding.Vector

	// Metadata contains arbitrary key-value pairs for filtering.
	Metadata Metadata

	// Score is the similarity score (populated on search results).
	Score float64

	// Timestamp is when this document was added/updated.
	Timestamp time.Time
}

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

type Filter map[string]any

type FusionAlgorithm string

type HybridSearchOptions struct {
	SearchOptions

	// Alpha controls the balance between keyword and vector search.
	// 0.0 = pure keyword (BM25/sparse), 1.0 = pure vector (dense).
	// Default: 0.5 (equal weighting)
	Alpha float64

	// FusionAlgorithm specifies how to combine results.
	// Default: RRF (Reciprocal Rank Fusion)
	FusionAlgorithm FusionAlgorithm
}

type Indexer interface {
	VectorStore

	// CreateIndex creates a new index/collection.
	CreateIndex(ctx context.Context, name string, dims int, metric embedding.Metric) error

	// DeleteIndex removes an index and all its data.
	DeleteIndex(ctx context.Context, name string) error

	// ListIndexes returns all available indexes.
	ListIndexes(ctx context.Context) ([]string, error)
}

type Metadata = map[string]any

type SearchOptions struct {
	// K is the maximum number of results to return. Default: 10
	K int

	// MinScore filters results below this similarity threshold (0.0-1.0).
	MinScore float64

	// Filter applies metadata-based filtering.
	Filter Filter

	// IncludeEmbeddings controls whether embeddings are returned in results.
	IncludeEmbeddings bool

	// Namespace partitions the store (for multi-tenant scenarios).
	Namespace string
}

type Stats struct {
	DocumentCount int64
	IndexSize     int64 // bytes
	Dimensions    int
}

type StatsProvider interface {
	Stats(ctx context.Context, namespace string) (Stats, error)
}

type TextSearcher interface {
	VectorStore

	// SearchHybrid combines keyword and vector search.
	// The alpha parameter in HybridSearchOptions controls the balance:
	// 0.0 = pure keyword search, 1.0 = pure vector search.
	SearchHybrid(ctx context.Context, query string, embedding embedding.Vector, opts HybridSearchOptions) ([]Document, error)
}

type VectorStore interface {
	// Add inserts or updates documents in the store.
	Add(ctx context.Context, docs []Document, opts ...func(*AddOptions)) error

	// Search finds documents similar to the query embedding.
	Search(ctx context.Context, embedding embedding.Vector, opts SearchOptions) ([]Document, error)

	// Delete removes documents by ID.
	Delete(ctx context.Context, ids []string, namespace string) error

	// Close releases resources.
	Close() error
}