ann_router.backends.turbovec_backend module

turbovec backend — the dynamic-corpus specialist.

turbovec (Rust + PyO3, ships wheels on PyPI incl. Apple Silicon) is the engine the router reaches for when the corpus changes constantly: it supports O(1) add_with_ids and remove(id) with no index rebuild, and its TurboQuant 2-4 bit quantisation gives ~16x compression while keeping recall above FAISS-PQ. That combination — mutable and compact and fast on Apple Silicon — is what earns it the “frequent updates” branch of the policy, ahead of the graph indexes whose deletes rot the structure.

This is the extracted, packaged form of the brute-force → turbovec routing that already ships inside the roitelet prototype’s core/personal.py.

Consumes: turbovec (optional, pip install 'ann-router[turbovec]'). Produces: TurboVecIndex.

Author: Warith Harchaoui <warith.harchaoui@deraison.ai>

class ann_router.backends.turbovec_backend.TurboVecIndex(dim, metric='cosine', **kwargs)

Bases: ANNIndex

turbovec IdMapIndex: mutable, quantised, id-native.

turbovec is id-native (add_with_ids / remove(id)) and returns (distances, ids) from search — this adapter flips that to the package’s (ids, distances) order. Vectors are normalised for cosine so the quantiser’s inner product matches cosine similarity.

Parameters:

• dim (int) – Embedding dimensionality.

• metric ({"cosine", "l2", "ip"}, optional) – Distance metric. Defaults to "cosine". turbovec is inner-product / cosine oriented; L2 is approximated on normalised vectors.

• bit_width (int, optional) – TurboQuant bit width (2 or 4). Defaults to 4 — the recall/size sweet spot measured in the roitelet study.

• kwargs (object)

Examples

>>> TurboVecIndex.capabilities().supports_remove
True

add(vectors)

Append vectors with the next contiguous ids.

Parameters:

vectors (numpy.ndarray) – Shape (m, dim).

Return type:

None

add_with_ids(vectors, ids)

Append vectors with explicit ids (O(1), no rebuild).

Parameters:

• vectors (numpy.ndarray) – Shape (m, dim).

• ids (numpy.ndarray) – Shape (m,) integer ids.

Return type:

None

build(vectors, ids=None)

Create the index and insert the initial corpus.

Parameters:

• vectors (numpy.ndarray) – Shape (n, dim).

• ids (numpy.ndarray, optional) – Shape (n,); defaults to range(n).

Returns:

self.

Return type:

TurboVecIndex

classmethod capabilities()

Return the turbovec capability descriptor (fully mutable).

Return type:

Capabilities

classmethod is_available()

Return True if turbovec is importable.

Examples

>>> isinstance(TurboVecIndex.is_available(), bool)
True

Return type:

bool

load(path)

Load an index written by save().

Parameters:

path (str) – Source path produced by save().

Returns:

self, populated from disk.

Return type:

TurboVecIndex

remove(ids)

Delete vectors by id — O(1) each, no structural degradation.

Parameters:

ids (numpy.ndarray) – Shape (m,) integer ids to drop.

Return type:

None

save(path)

Persist via turbovec’s native write.

Parameters:

path (str) – Destination file path.

Return type:

None

search(queries, k)

Return approximate top-k neighbours per query.

Parameters:

• queries (numpy.ndarray) – Shape (q, dim).

• k (int) – Neighbours per query.

Returns:

• ids (numpy.ndarray) – Shape (q, k) neighbour ids.

• distances (numpy.ndarray) – Shape (q, k) distances under the index metric.

Return type:

tuple[ndarray, ndarray]