VectorIndexBackend#

class scikitplot.corpus.VectorIndexBackend[source]#

Uniform contract for a dense vector index.

Subclasses build an index from a 2-D embedding matrix and answer top-k cosine-similarity queries. Every subclass guarantees the unified score contract described in the module docstring.

Attributes:

namestr: Stable backend identifier (e.g. "annoy").

build(embeddings)[source]#

Build the index from an (n_docs, dim) embedding matrix.

Parameters:

embeddingsnumpy.ndarray: Row-major float32 matrix. Rows are not required to be unit-normalised; each backend normalises internally as needed for cosine similarity.

Parameters:

embeddings (Any)

Return type:

None

capabilities()[source]#

Return every declared capability as a mapping.

Returns:

dict: Suitable for a capability report or a build manifest.

Return type:

dict[str, Any]

dependency_modules: ClassVar[str | tuple[str, ...] | None] = None#

property dimension: int | None#: Vector length this index was built with, None before build.

dtype: str = 'float32'#: Element type of the indexed vectors.

classmethod is_available()[source]#

Return whether this backend’s optional dependencies are discoverable.

Return type:: bool

memory_profile: str = 'in_memory'#: "in_memory", "mmap" or "hybrid".

metric: str = 'cosine'#: Distance/similarity metric this backend computes.

name: ClassVar[str] = 'base'#

query(vector, k)[source]#

Return up to k (row_index, cosine_score) pairs.

Results are sorted by descending cosine_score in [-1, 1] with deterministic, index-ascending tie breaking. A zero-norm query returns an empty list (cosine is undefined). Non-finite queries raise.

Parameters:

vector (Any)
k (int)

Return type:

list[tuple[int, float]]

score_semantics: str = 'cosine_similarity'#

Meaning of the score in query results.

"cosine_similarity" – range [-1, 1], higher is better. "bounded_inverse_distance" – range (0, 1], higher is better, but not a similarity: it is 1 / (1 + d) and is not comparable with a cosine score. Declaring this is what lets a threshold be validated against the scale it will actually be applied to (finding F-R06-02).

supports_persistence: bool = True#

Whether this backend’s index can be persisted and reloaded.

True since ANNIndexArtifact landed: an artifact writes the native payload alongside a versioned ordinal->doc_id sidecar and the embedding manifest, so a reloaded index can prove its rows still name the documents they named at write time. Before that, R06 found zero persistence surface in this module and the declaration was False – accurately.

thread_safety: str = 'concurrent_read'#: "single_thread", "concurrent_read" or "full".