{"record":{"id":"1d563667f3b1238d","repo":"RyanCodrai/turbovec","slug":"turboquantvectordb-supports-distance-distance-cosi","errorCode":null,"errorMessage":"TurboQuantVectorDb supports distance=Distance.cosine or distance=Distance.max_inner_product; got {distance}. L2 distance is not supported by the underlying inner-product kernel.","messagePattern":"TurboQuantVectorDb supports distance=Distance\\.cosine or distance=Distance\\.max_inner_product; got (.+?)\\. L2 distance is not supported by the underlying inner-product kernel\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"turbovec-python/python/turbovec/agno.py","lineNumber":198,"sourceCode":"            similarity_threshold=similarity_threshold,\n        )\n        if embedder is None:\n            raise ValueError(\n                \"`embedder` is required; turbovec needs the embedder's \"\n                \"`dimensions` to size the underlying index.\"\n            )\n        if embedder.dimensions is None:\n            raise ValueError(\"Embedder.dimensions must be set.\")\n        if bit_width not in (2, 3, 4):\n            raise ValueError(f\"bit_width must be 2, 3, or 4, got {bit_width}\")\n        if search_type != SearchType.vector:\n            raise ValueError(\n                f\"TurboQuantVectorDb only supports search_type=SearchType.vector; \"\n                f\"got {search_type}. Use LanceDb / Chroma / etc. for keyword \"\n                f\"or hybrid search.\"\n            )\n        if distance not in (Distance.cosine, Distance.max_inner_product):\n            raise ValueError(\n                f\"TurboQuantVectorDb supports distance=Distance.cosine or \"\n                f\"distance=Distance.max_inner_product; got {distance}. \"\n                f\"L2 distance is not supported by the underlying \"\n                f\"inner-product kernel.\"\n            )\n\n        self.embedder: Embedder = embedder\n        self.dimensions: int = embedder.dimensions\n        self.bit_width = bit_width\n        # Assigned through the validating property below, so the guard\n        # applies to runtime mutation as well as construction.\n        self.search_type = search_type\n        self.distance = distance\n        self.reranker = reranker\n        self.path: Optional[str] = path\n\n        # Lazy: the underlying IdMapIndex is created by `create()`, not\n        # in __init__. This matches LanceDb's `exists()` contract: a","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/RyanCodrai/turbovec/blob/ccab9f325e6ce2a270a87daf01ae4e443bcf2d49/turbovec-python/python/turbovec/agno.py#L180-L216","documentation":"The underlying quantized kernel computes inner products, so TurboQuantVectorDb supports only Distance.cosine and Distance.max_inner_product. L2 (euclidean) distance cannot be served correctly and raises a ValueError at construction.","triggerScenarios":"TurboQuantVectorDb(..., distance=Distance.l2) or any distance value other than cosine / max_inner_product.","commonSituations":"Reusing a distance enum copied from LanceDb/Milvus configs that default to L2; assuming euclidean distance is universally supported; porting pipelines tuned for L2-normalized-with-L2 setups.","solutions":["Set distance=Distance.cosine (most common for text embeddings).","Use distance=Distance.max_inner_product if your scores are inner-product-like (e.g. MIPS).","If L2 is mandatory, choose a backend whose kernel supports euclidean distance."],"exampleFix":"// before\nTurboQuantVectorDb(embedder=e, distance=Distance.l2)\n// after\nTurboQuantVectorDb(embedder=e, distance=Distance.cosine)","handlingStrategy":"validation","validationCode":"from agno.vectordb.distance import Distance\nif distance not in (Distance.cosine, Distance.max_inner_product):\n    distance = Distance.cosine","typeGuard":null,"tryCatchPattern":"try:\n    db = TurboQuantVectorDb(embedder=e, distance=d)\nexcept ValueError:\n    db = TurboQuantVectorDb(embedder=e, distance=Distance.cosine)","preventionTips":["Default to Distance.cosine for text-embedding workloads.","Do not copy distance settings from L2-based backends (Milvus/LanceDb defaults).","Centralize backend construction so distance is set per-backend, not globally."],"tags":["distance-metric","unsupported","configuration"],"backgroundTag":"unsupported-enum-value","analyzedSha":"ccab9f325e6ce2a270a87daf01ae4e443bcf2d49","analyzedAt":"2026-09-06T08:39:18.516Z","contentChangedAt":"2026-09-06T08:39:18.516Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}