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).

Raises:

RuntimeError – If called on an index that was populated via load() with no subsequent build()/add_with_ids() call in this process — the high-water mark can’t be recovered from disk (see load()’s docstring), so guessing 0 here would silently collide with ids already on disk instead of failing loudly. Call add_with_ids() with explicit ids instead.

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

Notes

turbovec’s native IdMapIndex exposes no way to enumerate or count the ids it holds, so the id high-water mark add() relies on cannot be recovered here. _next_id is set to None — a sentinel add() checks for and refuses to guess past, raising a clear error rather than silently restarting id assignment at 0 and colliding with ids already in the loaded index. Use add_with_ids() with explicit ids after loading.

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]