ResidualSnapIndex

ResidualSnapIndex

ResidualSnapIndex(dim: int, b1: int = 3, b2: int = 3, seed: int = 0, normalized: bool = False)

Bases: FreezableIndex

Two-stage Lloyd-Max TurboQuant index.

Parameters:

Name	Type	Description	Default
dim	int	Embedding dimension.	required
b1	int	Coarse-stage bits per coordinate. Must be in {2, 3, 4}.	3
b2	int	Residual-stage bits per coordinate. Must be in {2, 3, 4}.	3
seed	int	RHT rotation seed. Must match across build and query.	0
normalized	bool	When True, inputs are assumed unit-length and the per-vector norm is not computed or stored.	False

Notes

Bit-packing is not applied in this version — each stage stores one uint8 per coordinate. A 6-bit combined rate thus takes ~16 B/coord pre-pack; tight packing would bring it to 6/8 B/coord.

search

search(query: NDArray[float32], k: int = 10, rerank_M: int | None = None) -> list[tuple[Any, float]]

Approximate cosine top-k.

Parameters:

Name	Type	Description	Default
query	NDArray[float32]	Query vector (need not be normalized).	required
k	int	Number of results to return.	10
rerank_M	int | None	When set to an int, do a coarse pass (b1 bits) over the full corpus to select top-M candidates, then rerank those using the full (b1 + b2) reconstruction. When None, use full reconstruction over the whole corpus. M = 100 is sufficient for convergence at k ≤ 10 on the tested datasets.	None