RyanCodrai/turbovec · error · ImportError

haystack-ai is required to use turbovec.haystack. Install wi

Error message

haystack-ai is required to use turbovec.haystack. Install with: pip install turbovec[haystack]

What it means

Module-level ImportError raised when turbovec.haystack is imported without haystack-ai installed. The try/except around the haystack imports converts the raw ModuleNotFoundError into a named error with the correct extra-install command, so users learn at import time which optional dependency is missing.

Source

Thrown at turbovec-python/python/turbovec/haystack.py:42

from numbers import Real
from pathlib import Path
from typing import Any, Dict, Iterable, List, Literal, Optional, Tuple

import numpy as np

from ._persist import atomic_save, check_persisted_handles, check_schema_version
from ._similarity import l2_normalize_rows, validate_similarity
from ._turbovec import IdMapIndex

try:
    from haystack import Document
    from haystack.dataclasses import ByteStream
    from haystack.dataclasses.sparse_embedding import SparseEmbedding
    from haystack.document_stores.errors import DuplicateDocumentError
    from haystack.document_stores.types import DuplicatePolicy
    from haystack.utils.filters import document_matches_filter
except ImportError as exc:
    raise ImportError(
        "haystack-ai is required to use turbovec.haystack. "
        "Install with: pip install turbovec[haystack]"
    ) from exc


class TurboQuantDocumentStore:
    """Haystack DocumentStore backed by a :class:`~turbovec.IdMapIndex`.

    Vectors are quantized to 2–4 bits per dimension. Full-precision
    embeddings are dropped after quantization — callers requesting
    ``return_embedding=True`` on retrieval will see ``None`` on the
    returned documents' ``embedding`` field regardless of the flag.

    **Similarity modes.** ``embedding_similarity_function="cosine"``
    (default) L2-normalizes document embeddings at write time and query
    embeddings at retrieval time, so raw scores are cosine similarity in
    ``[-1, 1]``, ranking matches ``InMemoryDocumentStore``'s cosine
    branch for embeddings of any magnitude, and ``scale_score=True``

View on GitHub (pinned to ccab9f325e)

Solutions

1. Install the extra: pip install turbovec[haystack].
2. Or install haystack-ai directly into the environment.
3. Avoid importing turbovec.haystack in environments that do not need Haystack integration.

When it happens

Trigger: Thrown at turbovec-python/python/turbovec/haystack.py:42 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of RyanCodrai/turbovec@ccab9f325e (2026-09-06). Data as JSON: /api/errors/1415e00fbec80420. Report an issue: GitHub.