opaque

type ClusterStats struct {
	NumClusters   int     // Number of clusters
	MinSize       int     // Smallest cluster size
	MaxSize       int     // Largest cluster size
	AvgSize       float64 // Average cluster size
	EmptyClusters int     // Number of empty clusters (should be 0)
	Iterations    int     // K-means iterations until convergence
}

type Config struct {
	// Dimension is the length of each vector. Required.
	// All vectors added to the DB must have exactly this many elements.
	Dimension int

	// NumClusters is the number of k-means clusters used to partition vectors.
	// More clusters means faster search (fewer vectors per cluster) but weaker
	// privacy (smaller anonymity sets per cluster). Must be >= 2.
	// Default: 64.
	NumClusters int

	// TopClusters is the number of clusters probed during each search.
	// Higher values improve recall at the cost of more computation, bandwidth,
	// and weaker access pattern privacy (more clusters probed = easier to infer intent).
	// Must be <= NumClusters.
	// Default: max(NumClusters / 16, 4). For 64 clusters this is 4 (~6% of data).
	TopClusters int

	// NumDecoys is the number of extra clusters fetched per search to hide
	// which clusters are actually relevant. Higher values provide better
	// access pattern privacy at the cost of additional bandwidth.
	// Default: 8.
	NumDecoys int

	// WorkerPoolSize is the number of parallel CKKS homomorphic encryption engines.
	// Each engine consumes ~50MB of memory but enables parallel centroid scoring.
	// Set to 0 for automatic sizing (min(NumCPU, 8)).
	// Default: 0 (automatic).
	WorkerPoolSize int

	// Storage selects the backend for encrypted blob storage.
	// Default: Memory.
	Storage StorageBackend

	// StoragePath is the directory for file-backed storage.
	// Required when Storage is [File], ignored otherwise.
	StoragePath string

	// ProbeThreshold controls multi-probe cluster selection during search.
	// Clusters scoring within this fraction of the top cluster score are also probed,
	// beyond the TopClusters limit. For example, 0.95 means clusters within 5% of
	// the best score are included.
	// Set to 1.0 to disable multi-probe (strict top-K only).
	// Default: 0.95.
	ProbeThreshold float64

	// RedundantAssignments assigns each vector to multiple clusters during indexing.
	// Improves recall for vectors near cluster boundaries at the cost of increased storage.
	// A value of 2 means each vector is stored in its 2 nearest clusters.
	// Default: 1 (no redundancy).
	RedundantAssignments int

	// PCADimension enables optional PCA dimensionality reduction.
	// When set to a positive value, vectors are projected to this dimension
	// before clustering and encryption, reducing latency and bandwidth.
	// The PCA transform is applied client-side, so it has no privacy impact.
	// Must be less than Dimension. Set to 0 to disable (default).
	// Default: 0 (disabled).
	PCADimension int

	// NumKMeansInit is the number of k-means clustering initializations to run.
	// Multiple runs with different seeds are executed in parallel, and the result
	// with the lowest inertia (best cluster quality) is kept.
	// Higher values improve cluster quality at the cost of more CPU during Build.
	// Default: 1 (single initialization).
	NumKMeansInit int

	// NormalizedStorage stores vectors pre-normalized during Build, skipping
	// per-vector normalization during Search. This reduces local scoring latency
	// by 10-15%. Stored vectors lose original magnitudes (direction is preserved).
	// Default: true for new databases.
	NormalizedStorage *bool

	// ProbeStrategy selects the cluster probing method during search.
	// "threshold" (default) uses ProbeThreshold ratio to include nearby clusters.
	// "gap" uses adaptive score-gap detection to find natural breaks in the score distribution.
	// Default: "" (uses "threshold").
	ProbeStrategy string

	// GapMultiplier controls gap-based probing sensitivity when ProbeStrategy is "gap".
	// Expansion stops when the gap between consecutive cluster scores exceeds
	// GapMultiplier times the median gap. Lower values probe fewer clusters.
	// Default: 2.0.
	GapMultiplier float64

	// OnBuildProgress is called during [DB.Build] and [DB.Rebuild] to report progress.
	// The phase parameter identifies the current step, and pct is a value between 0 and 1
	// indicating completion within that phase.
	//
	// Phases reported (in order):
	//   - "pca": PCA fitting and dimensionality reduction (only if PCADimension > 0)
	//   - "clustering": k-means clustering of vectors
	//   - "encrypting": AES-256-GCM encryption of vectors
	//   - "indexing": blob storage and HE engine initialization
	//
	// The callback is invoked synchronously from the Build goroutine. Keep it fast.
	// A nil callback disables progress reporting (default).
	OnBuildProgress func(phase string, pct float64) `json:"-"`
}

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

type DBStats struct {
	// TotalVectors is the total number of vectors (pending + indexed).
	TotalVectors int

	// IndexedVectors is the number of vectors in the built index.
	// Zero if the index has not been built.
	IndexedVectors int

	// PendingVectors is the number of vectors buffered but not yet indexed.
	PendingVectors int

	// ClusterStats contains k-means clustering statistics (zero if not built).
	ClusterStats ClusterStats

	// StorageBackend is the storage backend in use.
	StorageBackend StorageBackend

	// HasPCA is true if PCA dimensionality reduction is enabled.
	HasPCA bool

	// IsReady is true if the index is built and ready for search.
	IsReady bool
}

type Filter struct {
	// Where contains exact-match conditions. A result must match ALL conditions.
	// Supported value types: string, int, float64, bool.
	Where map[string]any
}

type Metadata map[string]any

type Result struct {
	// ID is the identifier passed to [DB.Add] when the vector was indexed.
	ID string

	// Score is the cosine similarity between the query and this vector.
	// Higher is more similar. Range: [-1, 1] for normalized vectors.
	Score float64
}

type StorageBackend int