RyanCodrai/turbovec · error · ImportError

agno is required to use turbovec.agno. Install with: pip ins

Error message

agno is required to use turbovec.agno. Install with: pip install turbovec[agno]

What it means

turbovec.agno is an optional integration module that imports agno's VectorDb/Embedder/Reranker base classes at import time. If the agno package is not installed, the ImportError is re-raised as ImportError with instructions to install the extra. This is a standard optional-dependency guard.

Source

Thrown at turbovec-python/python/turbovec/agno.py:49

from pathlib import Path
from typing import Any, Dict, Iterable, List, Optional, Set, Union

import numpy as np

from ._persist import check_persisted_handles, check_schema_version
from ._similarity import l2_normalize_rows
from ._turbovec import IdMapIndex
from ._persist import atomic_save  # isort:skip

try:
    from agno.knowledge.document import Document
    from agno.knowledge.embedder import Embedder
    from agno.knowledge.reranker.base import Reranker
    from agno.vectordb.base import VectorDb
    from agno.vectordb.distance import Distance
    from agno.vectordb.search import SearchType
except ImportError as exc:
    raise ImportError(
        "agno is required to use turbovec.agno. "
        "Install with: pip install turbovec[agno]"
    ) from exc


_INDEX_FILENAME = "index.tvim"
_STORE_FILENAME = "docstore.json"
# Bump when docstore.json shape changes; loader accepts the current
# version plus any older versions whose missing fields we know how to
# reconstruct (v1 predates the `distance` field — those stores hold raw,
# unnormalized vectors, so they load as Distance.max_inner_product,
# which is exactly the scoring they were written under).
_DOCSTORE_SCHEMA_VERSION = 2
_DOCSTORE_SCHEMA_COMPAT = (1, 2)


def _embedder_has_async(embedder: "Embedder") -> bool:
    """True when this embedder really implements the async single-embed

View on GitHub (pinned to ccab9f325e)

Solutions

1. Install the optional extra: pip install turbovec[agno].
2. Add 'turbovec[agno]' to requirements/pyproject dependencies for projects that use the agno integration.
3. Guard the import in your code if agno integration is optional for you, and fall back to another vector DB backend.

Example fix

# before
pip install turbovec
import turbovec.agno  # ImportError
# after
pip install 'turbovec[agno]'
import turbovec.agno  # works

import importlib.util
if importlib.util.find_spec("agno") is None:
    raise SystemExit("Install with: pip install turbovec[agno]")

try:
    import turbovec.agno
except ImportError:
    turbovec_agno = None  # fall back to another vector backend

When it happens

Trigger: Importing turbovec.agno (or anything that imports it) in an environment where the `agno` distribution is not installed.

Common situations: Deploying to a fresh environment where only the base package was installed (pip install turbovec), running tests/CI without the extra, or a requirements file that dropped the agno extra.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

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