hoops_ai.ml.embeddings.VectorStore

class hoops_ai.ml.embeddings.VectorStore

Bases: ABC

INTERFACE vector storage supporting CRUD operations and filtering.

Implementations should provide efficient storage and retrieval of high-dimensional vectors with support for similarity search, metadata filtering, and CRUD operations.

abstract close()

Close the vector store and release resources.

Return type:

None

abstract count()

Return total number of vectors in the store.

Returns:

Number of stored vectors

Return type:

int

abstract delete(ids)

Delete vectors by their ids.

Parameters:

ids (Sequence[str]) – Sequence of vector ids to delete

Return type:

None

abstract get_ids()

Return list of all indexed vector IDs.

Returns:

List of all vector IDs currently in the store

Return type:

List[str]

abstract iter_metadata()

Yield the metadata dict for every stored record.

Return type:

Iterator[Dict[str, Any]]

abstract classmethod load(path)

Load a persisted vector store from disk or restore connection.

For local stores (e.g., FAISS): Deserializes index and metadata from file. For cloud stores (e.g., Weaviate, Qdrant): Restores connection to existing index.

Parameters:

path (str) – File path for local stores, or identifier for cloud stores

Returns:

Restored vector store instance

Return type:

VectorStore

abstract query(query_vector, top_k=10, filters=None, include_metadata=True)

Search for similar vectors.

Parameters:

  • query_vector (np.ndarray) – Query vector of shape (dim,), typically from Embedding.values

  • top_k (int) – Maximum number of results to return

  • filters (Optional[Dict[str, Any]]) – Optional metadata filters (key-value pairs)

  • include_metadata (bool) – Whether to include metadata in results

Returns:

List of VectorHit objects sorted by similarity score (descending)

Return type:

List[VectorHit]

abstract save(path)

Persist the vector store to disk or save connection configuration.

For local stores (e.g., FAISS): Serializes index and metadata to a file. For cloud stores (e.g., Weaviate, Qdrant): May save connection config or be a no-op.

Parameters:

path (str) – File path for local stores, or identifier for cloud stores

Return type:

None

abstract update_record_metadata(record_id, updates)

Merge updates into the metadata dict of an existing record.

Returns True if the record exists and was updated, False if not found.

Parameters:
Return type:

bool

abstract upsert(records)

Insert or update vector records.

Parameters:

records (Sequence[VectorRecord]) – Sequence of VectorRecord objects to store

Return type:

None

abstract property dim: int

Dimensionality of vectors stored in this vector store.

Returns:

Vector dimension

Return type:

int