vectorstore

type BatchConfig struct {
	// BatchSize is the number of documents to process per batch.
	// Default: 100
	BatchSize int

	// Parallelism is the number of concurrent batches.
	// Default: 1 (sequential)
	Parallelism int

	// ContinueOnError controls whether to continue on individual document errors.
	// If false, the entire batch fails on first error.
	// If true, failed documents are collected in UpsertResult.Errors.
	// Default: true
	ContinueOnError bool

	// ProgressCallback is called after each batch completes.
	// Receives (processed, total) counts.
	ProgressCallback func(processed, total int)

	// ValidateBeforeBatch validates all documents before starting batch.
	// If true, invalid documents cause immediate failure.
	// If false, validation happens per-batch.
	// Default: false
	ValidateBeforeBatch bool

	// RetryOnError enables retry for failed batches.
	// Default: false
	RetryOnError bool

	// MaxRetries is the maximum number of retries per batch.
	// Only meaningful if RetryOnError is true.
	// Default: 3
	MaxRetries int

	// RetryDelay is the delay between retries.
	// Default: 1 second
	RetryDelay time.Duration
}

type BatchOption func(*BatchConfig)

type Collection interface {
	// Name returns the collection name.
	Name() string

	// Upsert inserts or updates documents in the collection.
	// If a document with the same ID exists, it is updated. Otherwise, a new document is created.
	//
	// Documents are validated before insertion. Invalid documents cause the entire
	// operation to fail (all-or-nothing semantics).
	//
	// For large batches, consider using UpsertBatch for better performance.
	//
	// Example:
	//
	//	doc := &Document{
	//	    ID: "doc1",
	//	    Content: NewTextContent("Hello world"),
	//	    Embedding: NewEmbedding([]float32{0.1, 0.2, 0.3}, "text-embedding-3-small"),
	//	    Tags: []string{"greeting", "english"},
	//	}
	//	result, err := coll.Upsert(ctx, doc)
	Upsert(ctx context.Context, documents ...*Document) (*UpsertResult, error)

	// UpsertBatch performs batch upsert with progress tracking and error handling.
	// This is optimized for inserting large numbers of documents.
	//
	// Options can control batch size, parallelism, and progress callbacks.
	//
	// Example:
	//
	//	result, err := coll.UpsertBatch(ctx, documents,
	//	    WithBatchSize(100),
	//	    WithProgressCallback(func(processed, total int) {
	//	        log.Printf("Progress: %d/%d", processed, total)
	//	    }),
	//	)
	UpsertBatch(ctx context.Context, documents []*Document, opts ...BatchOption) (*UpsertResult, error)

	// Query performs similarity search and returns matching documents.
	// The query can include vector similarity, metadata filters, temporal constraints,
	// scope filters, and more.
	//
	// Example:
	//
	//	results, err := coll.Query(ctx, &Query{
	//	    Embedding: queryEmbedding,
	//	    Limit: 10,
	//	    Filters: And(
	//	        TagFilter("category", "product"),
	//	        ScoreFilter(GreaterThan(0.8)),
	//	    ),
	//	})
	Query(ctx context.Context, query *Query) (*QueryResult, error)

	// QueryStream performs similarity search and streams results via an iterator.
	// This is useful for processing large result sets without loading everything into memory.
	//
	// The iterator must be closed when done to release resources.
	//
	// Example:
	//
	//	iter, err := coll.QueryStream(ctx, query)
	//	if err != nil {
	//	    log.Fatal(err)
	//	}
	//	defer iter.Close()
	//
	//	for iter.Next() {
	//	    match := iter.Match()
	//	    fmt.Printf("Score: %.4f, Content: %s\n", match.Score, match.Document.Content)
	//	}
	//	if err := iter.Err(); err != nil {
	//	    log.Fatal(err)
	//	}
	QueryStream(ctx context.Context, query *Query) (ResultIterator, error)

	// Get retrieves documents by their IDs.
	// Documents that don't exist are omitted from the result (no error is returned).
	//
	// The order of returned documents may not match the order of requested IDs.
	//
	// Example:
	//
	//	docs, err := coll.Get(ctx, "doc1", "doc2", "doc3")
	Get(ctx context.Context, ids ...string) ([]*Document, error)

	// Delete removes documents by their IDs.
	// IDs that don't exist are silently ignored (no error is returned).
	//
	// Example:
	//
	//	result, err := coll.Delete(ctx, "doc1", "doc2")
	//	fmt.Printf("Deleted %d documents\n", result.Deleted)
	Delete(ctx context.Context, ids ...string) (*DeleteResult, error)

	// DeleteByFilter removes all documents matching the filter.
	// This is useful for bulk deletion based on criteria.
	//
	// WARNING: This can delete many documents. Use with caution.
	//
	// Example:
	//
	//	// Delete all expired documents
	//	result, err := coll.DeleteByFilter(ctx,
	//	    TimeFilter(Before(time.Now())),
	//	)
	DeleteByFilter(ctx context.Context, filter Filter) (*DeleteResult, error)

	// Count returns the number of documents in the collection.
	// If a filter is provided, only documents matching the filter are counted.
	//
	// Example:
	//
	//	total, err := coll.Count(ctx, nil) // All documents
	//	active, err := coll.Count(ctx, TagFilter("status", "active"))
	Count(ctx context.Context, filter Filter) (int64, error)

	// Stats returns statistics about the collection.
	// This includes document count, storage size, index info, etc.
	Stats(ctx context.Context) (*CollectionStats, error)

	// Clear removes all documents from the collection.
	// This is primarily useful for testing.
	//
	// WARNING: This permanently deletes all data in the collection.
	Clear(ctx context.Context) error
}

type CollectionConfig struct {
	// TTL specifies the time-to-live for documents in this collection.
	// Documents are automatically deleted after TTL expires.
	// Zero means no TTL (documents never expire).
	TTL time.Duration

	// EnableDeduplication enables content-based deduplication.
	// When enabled, documents with identical embeddings (or content hashes)
	// are deduplicated automatically.
	EnableDeduplication bool

	// DeduplicationThreshold is the similarity threshold for deduplication (0.0-1.0).
	// Documents with similarity >= threshold are considered duplicates.
	// Default: 0.99 (nearly identical)
	DeduplicationThreshold float32

	// IndexType specifies the vector index type.
	// Examples: "flat", "hnsw", "ivf"
	IndexType IndexType

	// EmbeddingDimensions is the expected dimensionality of embeddings.
	// If set, documents with different dimensions will be rejected.
	// Zero means no dimension validation.
	EmbeddingDimensions int

	// AutoGenerateEmbeddings enables automatic embedding generation.
	// When enabled, documents without embeddings will have them generated
	// using the specified embedding function.
	AutoGenerateEmbeddings bool

	// EmbeddingFunction is the function to generate embeddings.
	// Only used if AutoGenerateEmbeddings is true.
	EmbeddingFunction EmbeddingFunction

	// ScopeRequired specifies required scope fields.
	// Documents without these scope fields will be rejected.
	ScopeRequired []string

	// MaxDocuments limits the number of documents in the collection.
	// Oldest documents are removed when limit is exceeded (FIFO).
	// Zero means no limit.
	MaxDocuments int64

	// EnableVersioning enables document versioning.
	// Previous versions are retained and can be queried.
	EnableVersioning bool

	// MaxVersions limits the number of versions per document.
	// Only meaningful if EnableVersioning is true.
	// Zero means unlimited versions.
	MaxVersions int

	// EnableAuditLog enables audit logging for all operations.
	EnableAuditLog bool

	// Metadata contains additional provider-specific configuration.
	Metadata map[string]any
}

type CollectionOption func(*CollectionConfig)

type CollectionStats struct {
	// Name is the collection name
	Name string

	// Documents is the number of documents in the collection
	Documents int64

	// StorageBytes is the storage used by this collection in bytes
	StorageBytes int64

	// EmbeddingDimensions is the dimensionality of embeddings in this collection
	EmbeddingDimensions int

	// IndexType is the index type used (e.g., "flat", "hnsw", "ivf")
	IndexType string

	// CreatedAt is when the collection was created
	CreatedAt *TimestampValue

	// UpdatedAt is when the collection was last modified
	UpdatedAt *TimestampValue

	// Extra contains provider-specific statistics
	Extra map[string]any
}

type Content struct {
	// Type indicates the content type
	Type ContentType

	// Text is the text content (for ContentTypeText)
	Text string

	// Data is the binary data (for images, audio, video)
	// Stored as base64-encoded string for JSON serialization
	Data []byte

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

	// URL is an optional external URL for the content
	// Useful for referencing large media without storing it inline
	URL string

	// Chunks contains text chunks for long documents
	// Useful for document splitting and retrieval
	Chunks []string
}

type ContentType string

type DeleteResult struct {
	// Deleted is the number of documents actually deleted
	Deleted int64

	// NotFound is the number of IDs that were not found
	NotFound int64

	// NotFoundIDs contains the IDs that were not found
	NotFoundIDs []string

	// Timing contains operation timing information
	Timing *OperationTiming
}

type DistanceMetric string

type Document struct {
	// ID is the unique identifier for the document.
	// Must be unique within a collection.
	// IDs should be URL-safe strings (alphanumeric, hyphens, underscores).
	ID string

	// Content is the multi-modal content of the document.
	// Supports text, images, audio, video.
	Content *Content

	// Embedding is the vector representation of the content.
	// Can be nil if embeddings are generated server-side.
	Embedding *Embedding

	// Scope defines hierarchical context for the document.
	// Useful for multi-tenancy, user isolation, session tracking.
	// Example: {Tenant: "acme", User: "user123", Session: "sess456"}
	Scope *Scope

	// Temporal contains time-related information for the document.
	// Useful for TTL, time-based queries, event ordering.
	Temporal *Temporal

	// Tags are indexed labels for efficient filtering.
	// Unlike metadata, tags are optimized for equality queries.
	// Examples: ["product", "electronics", "featured"]
	Tags []string

	// Metadata contains additional free-form information.
	// Use this for data that doesn't fit into typed fields.
	// Keys should be alphanumeric with underscores (no special chars).
	Metadata map[string]any

	// Score is the similarity score (populated during queries).
	// Not stored, only returned in query results.
	Score float32 `json:"-"`

	// Distance is the raw distance metric (populated during queries).
	// Not stored, only returned in query results.
	Distance float32 `json:"-"`
}

type Embedding struct {
	// Vector is the embedding vector
	Vector []float32

	// Model is the name of the model that generated this embedding
	// Examples: "text-embedding-3-small", "clip-vit-base-patch32"
	Model string

	// Dimensions is the dimensionality of the vector
	// Automatically set from len(Vector)
	Dimensions int

	// Normalized indicates whether the vector is normalized (unit length)
	// Many distance metrics work better with normalized vectors
	Normalized bool
}

type EmbeddingFunction func(content *Content) (*Embedding, error)

type ExplainStep struct {
	// Name is the step name
	Name string

	// Duration is how long this step took
	Duration time.Duration

	// Details contains step-specific information
	Details map[string]any
}

type Filter interface {
	// contains filtered or unexported methods
}

type FilterOperator string

type IndexType string

type Match struct {
	// Document is the matched document
	Document *Document

	// Score is the similarity score (higher is more similar)
	// For cosine similarity: -1 (opposite) to 1 (identical)
	// For euclidean: normalized to 0-1 range
	Score float32

	// Distance is the raw distance metric (optional)
	// The interpretation depends on the distance metric used
	Distance float32

	// Rank is the result rank (1-based)
	// Useful for hybrid ranking scenarios
	Rank int
}

type OperationTiming struct {
	// Total is the total operation time
	Total time.Duration

	// Validation is the time spent validating documents
	Validation time.Duration

	// Storage is the time spent writing to storage
	Storage time.Duration

	// IndexUpdate is the time spent updating indexes
	IndexUpdate time.Duration
}

type Query struct {
	// Embedding is the query vector for similarity search.
	// If nil, performs a pure metadata/filter query without vector similarity.
	Embedding *Embedding

	// Filters specifies conditions that documents must match.
	// Can be combined using And(), Or(), Not() for complex queries.
	Filters Filter

	// Limit is the maximum number of results to return.
	// Default: 10. Maximum: 10000.
	Limit int

	// Offset is the number of results to skip (for pagination).
	// Default: 0.
	Offset int

	// MinScore is the minimum similarity score (0.0-1.0).
	// Documents with lower scores are excluded.
	// Default: 0 (no minimum).
	MinScore float32

	// Metric specifies how to calculate vector similarity.
	// Default: Cosine similarity.
	Metric DistanceMetric

	// IncludeEmbeddings controls whether to return embeddings in results.
	// Default: false (embeddings are large and often not needed).
	IncludeEmbeddings bool

	// IncludeContent controls whether to return document content in results.
	// Default: true. Set to false to only get metadata/scores.
	IncludeContent bool

	// SortBy specifies additional sorting criteria (after similarity).
	// Useful for hybrid ranking (e.g., similarity + recency).
	SortBy []SortBy

	// Explain requests query execution details (for debugging/optimization).
	// Default: false.
	Explain bool
}

type QueryExplain struct {
	// Strategy describes the query execution strategy
	// Examples: "brute_force", "hnsw_index", "ivf_index"
	Strategy string

	// IndexUsed indicates which index was used (if any)
	IndexUsed string

	// ScannedDocuments is the number of documents scanned
	ScannedDocuments int64

	// FilteredDocuments is the number of documents after filtering
	FilteredDocuments int64

	// VectorComparisons is the number of vector similarity comparisons
	VectorComparisons int64

	// CacheHit indicates if results were served from cache
	CacheHit bool

	// Steps contains detailed execution steps
	Steps []ExplainStep
}

type QueryResult struct {
	// Matches are the matching documents with their scores
	Matches []*Match

	// Total is the total number of matches (before limit/offset)
	// Useful for pagination
	Total int64

	// Offset is the offset that was applied
	Offset int

	// Limit is the limit that was applied
	Limit int

	// Timing contains query execution timing information
	Timing *QueryTiming

	// Explain contains query execution details (if requested)
	Explain *QueryExplain
}

type QueryTiming struct {
	// Total is the total query execution time
	Total time.Duration

	// VectorSearch is the time spent on vector similarity search
	VectorSearch time.Duration

	// FilterApplication is the time spent applying filters
	FilterApplication time.Duration

	// Retrieval is the time spent retrieving full documents
	Retrieval time.Duration

	// Scoring is the time spent calculating similarity scores
	Scoring time.Duration
}

type ResultIterator interface {
	// Next advances to the next result.
	// Returns true if there is a result, false if iteration is complete or an error occurred.
	//
	// Always check Err() after Next returns false to distinguish between
	// normal completion and errors.
	Next() bool

	// Match returns the current search match.
	// Only valid after Next returns true.
	Match() *Match

	// Err returns any error that occurred during iteration.
	// Should be checked after Next returns false.
	Err() error

	// Close releases resources associated with the iterator.
	// Always call Close when done, typically via defer.
	Close() error
}

type Scope struct {
	// Tenant is the top-level scope (organization, workspace, team)
	Tenant string

	// User is the user identifier
	User string

	// Session is the session identifier
	Session string

	// Agent is the agent identifier (for multi-agent systems)
	Agent string

	// Thread is the conversation thread identifier
	Thread string

	// Custom contains additional custom scope dimensions
	// Use this for domain-specific scoping needs
	Custom map[string]string
}

type SortBy struct {
	// Field is the field name to sort by
	// Can be a metadata field, score, or temporal field
	Field string

	// Descending indicates descending order (default is ascending)
	Descending bool
}

type StoreStats struct {
	// Collections is the total number of collections
	Collections int64

	// Documents is the total number of documents across all collections
	Documents int64

	// StorageBytes is the total storage used in bytes
	StorageBytes int64

	// Provider is the vector store provider name (e.g., "memory", "firestore", "qdrant")
	Provider string

	// Version is the provider version
	Version string

	// Extra contains provider-specific statistics
	Extra map[string]any
}

type Temporal struct {
	// CreatedAt is when the document was created
	CreatedAt time.Time

	// UpdatedAt is when the document was last updated
	UpdatedAt time.Time

	// ExpiresAt is when the document should expire (optional)
	// Used for automatic cleanup in caching scenarios
	ExpiresAt *time.Time

	// EventTime is the time of the event this document represents (optional)
	// Used for time-series data and event ordering
	EventTime *time.Time

	// ValidFrom is when this document becomes valid (optional)
	// Used for future-dated content
	ValidFrom *time.Time

	// ValidUntil is when this document stops being valid (optional)
	// Different from ExpiresAt - this is semantic validity, not storage
	ValidUntil *time.Time
}

type TimeField string

type TimestampValue struct {
	time.Time
}

type UpsertResult struct {
	// Inserted is the number of new documents inserted
	Inserted int64

	// Updated is the number of existing documents updated
	Updated int64

	// Failed is the number of documents that failed validation/insertion
	Failed int64

	// FailedIDs contains the IDs of documents that failed (if any)
	FailedIDs []string

	// Errors contains errors for failed documents (parallel to FailedIDs)
	Errors []error

	// Timing contains operation timing information
	Timing *OperationTiming

	// Deduplicated is the number of documents that were deduplicated
	// Only set if deduplication is enabled
	Deduplicated int64

	// DeduplicatedIDs contains the IDs of deduplicated documents
	DeduplicatedIDs []string
}

type VectorStore interface {
	// Collection returns a Collection with the specified name and options.
	// Collections provide isolated namespaces for documents and embeddings.
	//
	// The name must be a valid collection identifier (alphanumeric, hyphens, underscores).
	// Options configure behavior like TTL, deduplication, indexing, etc.
	//
	// Collections are created lazily on first use. Calling Collection multiple times
	// with the same name returns the same logical collection.
	//
	// Example:
	//
	//	cache := store.Collection("cache", WithTTL(5*time.Minute))
	//	docs := store.Collection("documents", WithIndexing(IndexTypeHNSW))
	Collection(name string, opts ...CollectionOption) Collection

	// ListCollections returns the names of all collections in this store.
	// This is useful for administration and debugging.
	ListCollections(ctx context.Context) ([]string, error)

	// DeleteCollection permanently deletes a collection and all its documents.
	// This operation cannot be undone.
	//
	// Returns an error if the collection doesn't exist or cannot be deleted.
	DeleteCollection(ctx context.Context, name string) error

	// Stats returns statistics about the vector store.
	// This includes total collections, documents, storage size, etc.
	Stats(ctx context.Context) (*StoreStats, error)

	// Close closes the connection to the vector database and releases resources.
	// After Close is called, the VectorStore should not be used.
	Close() error
}