JuliusBrussee/caveman · error · ImportError

Install caveman-middleware[llama-index] to use the…

Error message

Install caveman-middleware[llama-index] to use the LlamaIndex adapter

What it means

The LlamaIndex adapter needs llama-index-core (schema, tools, workflow) plus pydantic/pydantic_core; these are optional extras. On ModuleNotFoundError the module raises ImportError telling you to install caveman-middleware[llama-index], chaining the original error.

Solutions

Run pip install "caveman-middleware[llama-index]" in the active environment
Confirm the running interpreter sees the package: python -c "import llama_index.core"
If llama-index is installed but broken, reinstall it (pip install --force-reinstall llama-index-core)
Verify pydantic/pydantic_core are installed and version-compatible with llama-index-core

Example fix

// before
from caveman_middleware.llama_index import CavemanLlamaIndex
# ImportError: Install caveman-middleware[llama-index] ...

// after
# shell: pip install "caveman-middleware[llama-index]"
from caveman_middleware.llama_index import CavemanLlamaIndex

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util
missing = [m for m in ("llama_index.core", "pydantic", "pydantic_core") if importlib.util.find_spec(m) is None]
if missing:
    raise SystemExit('Install with: pip install "caveman-middleware[llama-index]" (missing: %s)' % missing)

Type guard

def llama_index_available() -> bool:
    return importlib.util.find_spec("llama_index.core") is not None

Try / catch

try:
    from caveman_middleware.llama_index import CavemanLlamaIndex
except ImportError as e:
    logger.error("LlamaIndex adapter unavailable: %s", e)
    CavemanLlamaIndex = None  # or fall back to another adapter

Prevention

Install with the extra: caveman-middleware[llama-index]
List the extra in your project dependencies for reproducible environments
Import the adapter during app startup to fail fast, not at first tool call
Verify llama-index-core and pydantic versions stay mutually compatible

When it happens

Trigger: Any import of caveman_middleware.llama_index while llama-index-core (or pydantic/pydantic_core) is absent from the environment.

Common situations: Installed caveman-middleware without the [llama-index] extra; running under a different venv/interpreter than the one with llama-index; a slim deployment image without the extras; a broken llama-index install that also fails to import.

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.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/20d379f1f4a24ff6. Report an issue: GitHub.

Appendix: source

Thrown at packages/middleware/python/caveman_middleware/llama_index.py:27

from contextlib import contextmanager
from dataclasses import dataclass
from importlib.metadata import version
from typing import Any

try:
    from llama_index.core.agent.workflow import FunctionAgent
    from llama_index.core.base.llms.types import ChatMessage, MessageRole, TextBlock, ToolCallBlock
    from llama_index.core.llms import LLM
    from llama_index.core.llms.llm import ToolSelection
    from llama_index.core.llms.function_calling import FunctionCallingLLM
    from llama_index.core.postprocessor.types import BaseNodePostprocessor
    from llama_index.core.schema import NodeWithScore, TextNode
    from llama_index.core.tools import FunctionTool, ToolMetadata, ToolOutput
    from llama_index.core.workflow import Context
    from pydantic import Field
    from pydantic_core import PydanticSerializationError
except ModuleNotFoundError as error:
    raise ImportError("Install caveman-middleware[llama-index] to use the LlamaIndex adapter") from error

from caveman_cloud.middleware import Adapter, Candidate, MiddlewareError, MiddlewareRuntime, RecoveryBinding, Scope
from caveman_cloud.middleware.runtime import RECOVERY_DESCRIPTION, RECOVERY_SCHEMA
from ._native import Attempt, manifest, owner
from ._usage import usage
from ._versions import matches_framework, supports_framework

ADAPTER = Adapter("llama-index", "0.1.0", "0.14.24", "llama-index-message-v1")
RAG_ADAPTER = Adapter("llama-index-rag", "0.1.0", "0.14.24", "llama-index-node-v1")


def _check_version(runtime):
    return supports_framework(runtime, ("llama-index-core", "0.14", "0.15"))


def _scope(source, context=None):
    result = source if isinstance(source, Scope) else source(context)
    if not isinstance(result, Scope):

View on GitHub (pinned to 3ee70a1026)