vector

type Backend string

type ChromaConfig struct {
	// BaseURL is the root URL of the Chroma server, e.g. "http://localhost:8000".
	BaseURL string

	// APIKey is sent as "Authorization: Bearer <key>" when non-empty.
	APIKey string

	// Tenant and Database are used by the v2 API.
	// Defaults: "default_tenant" / "default_database".
	Tenant   string
	Database string
}

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

type Config struct {
	// Backend selects the implementation.
	Backend Backend

	// DB is used by the SQLite and pgvector backends.
	// For SQLite:   must be a SQLite DB (DriverSQLite).
	// For pgvector: must be a Postgres DB (DriverPostgres).
	DB *dbpkg.DB

	// Dim is the vector dimension required by pgvector and Qdrant when
	// creating a new collection/table. Defaults to 1536 (OpenAI ada-002).
	Dim int

	// PgVectorCreateExtension controls whether the pgvector extension is created
	// automatically at store initialization time.
	PgVectorCreateExtension *bool

	// PgVectorIndexMethod selects the ANN index type for pgvector. Supported:
	// "hnsw" and "ivfflat". Empty defaults to "hnsw".
	PgVectorIndexMethod string

	// PgVectorHNSWM tunes HNSW index creation when PgVectorIndexMethod=hnsw.
	PgVectorHNSWM int

	// PgVectorHNSWEfConstruction tunes HNSW ef_construction.
	PgVectorHNSWEfConstruction int

	// PgVectorIVFFlatLists tunes IVFFlat index creation when
	// PgVectorIndexMethod=ivfflat.
	PgVectorIVFFlatLists int

	// QdrantHost / QdrantPort / QdrantAPIKey for the Qdrant gRPC client.
	QdrantHost   string
	QdrantPort   int // defaults to 6334 (gRPC)
	QdrantAPIKey string

	// QdrantPrefix is prepended to every collection name (useful for
	// multi-tenant deployments sharing one Qdrant instance).
	QdrantPrefix string

	// ChromaURL is the base URL of the Chroma HTTP API (e.g. "http://localhost:8000").
	ChromaURL string

	// ChromaAPIKey is sent as "Authorization: Bearer <key>" when non-empty.
	ChromaAPIKey string

	// ChromaTenant and ChromaDatabase are used with the Chroma v2 API.
	// Defaults to "default_tenant" / "default_database".
	ChromaTenant   string
	ChromaDatabase string

	// HNSWDir is the directory where HNSW index files are stored.
	// Each namespace gets its own pair of files (<slug>.hnsw + <slug>.meta.json).
	// Defaults to <runtime_root>/data/hnsw when not set.
	HNSWDir string
}

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

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

type PgVectorOptions struct {
	Dim                int
	CreateExtension    bool
	IndexMethod        string
	HNSWM              int
	HNSWEfConstruction int
	IVFFlatLists       int
}

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

type QdrantConfig struct {
	Host       string
	Port       int
	APIKey     string
	CollPrefix string // prefix prepended to every collection name
	DefaultDim int    // vector dimension used when creating new collections
}

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

type Query struct {
	Namespace string
	// Vector is the query embedding. Leave empty (nil) for a "vectorless"
	// query - pure keyword/BM25 ranking via QueryText, no embedding call
	// needed at all. Requires QueryText to be set. SQLite and Memory
	// support this directly; HNSW falls back to a coarser keyword-overlap
	// score; Chroma/Qdrant/pgvector return an error (not yet implemented -
	// none of them are wired into the CLI today, unlike SQLite/HNSW).
	// When Vector is non-empty, HybridWeight controls how much (if any)
	// keyword scoring blends in on top of it; when Vector is empty,
	// HybridWeight is ignored (scoring is 100% keyword either way).
	Vector []float32
	TopK   int
	Filter map[string]any // optional; nil = no filter

	// HybridWeight blends BM25 keyword search with vector similarity.
	//   0   (default) → pure vector
	//   1             → pure BM25
	//   0 < w < 1    → linear blend: (1-w)*vector + w*bm25
	// Only the SQLite and pgvector backends implement BM25; others ignore it.
	// Meaningless when Vector is empty - see the Vector field doc.
	HybridWeight float32

	// QueryText is the raw query string used for BM25/keyword scoring.
	// Must be non-empty when HybridWeight > 0, or when Vector is empty.
	QueryText string
}

type Record struct {
	Namespace string            `json:"namespace"`
	Key       string            `json:"key"`
	Text      string            `json:"text,omitempty"`
	Vector    []float32         `json:"vector"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

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

type SearchResult struct {
	Record Record  `json:"record"`
	Score  float32 `json:"score"`
}

type Store interface {
	// Upsert inserts or replaces records (namespace + key = primary key).
	Upsert(ctx context.Context, records []Record) error

	// Search performs vector similarity search within a namespace.
	// Query.Filter is applied as an AND predicate on record metadata.
	Search(ctx context.Context, query Query) ([]SearchResult, error)

	// Get retrieves records by key. If keys is nil or empty, all records in
	// the namespace are returned.
	Get(ctx context.Context, namespace string, keys []string) ([]Record, error)

	// HasNamespace reports whether the namespace contains at least one record.
	HasNamespace(ctx context.Context, namespace string) (bool, error)

	// DeleteNamespace removes all records for a namespace.
	DeleteNamespace(ctx context.Context, namespace string) error

	// DeleteKeys removes specific records within a namespace.
	DeleteKeys(ctx context.Context, namespace string, keys []string) error
}