{"record":{"id":"20d379f1f4a24ff6","repo":"JuliusBrussee/caveman","slug":"install-caveman-middleware-llama-index-to-use-the-llamaindex","errorCode":null,"errorMessage":"Install caveman-middleware[llama-index] to use the LlamaIndex adapter","messagePattern":"Install caveman-middleware\\[llama-index\\] to use the LlamaIndex adapter","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"packages/middleware/python/caveman_middleware/llama_index.py","lineNumber":27,"sourceCode":"from contextlib import contextmanager\nfrom dataclasses import dataclass\nfrom importlib.metadata import version\nfrom typing import Any\n\ntry:\n    from llama_index.core.agent.workflow import FunctionAgent\n    from llama_index.core.base.llms.types import ChatMessage, MessageRole, TextBlock, ToolCallBlock\n    from llama_index.core.llms import LLM\n    from llama_index.core.llms.llm import ToolSelection\n    from llama_index.core.llms.function_calling import FunctionCallingLLM\n    from llama_index.core.postprocessor.types import BaseNodePostprocessor\n    from llama_index.core.schema import NodeWithScore, TextNode\n    from llama_index.core.tools import FunctionTool, ToolMetadata, ToolOutput\n    from llama_index.core.workflow import Context\n    from pydantic import Field\n    from pydantic_core import PydanticSerializationError\nexcept ModuleNotFoundError as error:\n    raise ImportError(\"Install caveman-middleware[llama-index] to use the LlamaIndex adapter\") from error\n\nfrom caveman_cloud.middleware import Adapter, Candidate, MiddlewareError, MiddlewareRuntime, RecoveryBinding, Scope\nfrom caveman_cloud.middleware.runtime import RECOVERY_DESCRIPTION, RECOVERY_SCHEMA\nfrom ._native import Attempt, manifest, owner\nfrom ._usage import usage\nfrom ._versions import matches_framework, supports_framework\n\nADAPTER = Adapter(\"llama-index\", \"0.1.0\", \"0.14.24\", \"llama-index-message-v1\")\nRAG_ADAPTER = Adapter(\"llama-index-rag\", \"0.1.0\", \"0.14.24\", \"llama-index-node-v1\")\n\n\ndef _check_version(runtime):\n    return supports_framework(runtime, (\"llama-index-core\", \"0.14\", \"0.15\"))\n\n\ndef _scope(source, context=None):\n    result = source if isinstance(source, Scope) else source(context)\n    if not isinstance(result, Scope):","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/middleware/python/caveman_middleware/llama_index.py#L9-L45","documentation":"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.","triggerScenarios":"Any import of caveman_middleware.llama_index while llama-index-core (or pydantic/pydantic_core) is absent from the environment.","commonSituations":"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.","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"],"exampleFix":"// before\nfrom caveman_middleware.llama_index import CavemanLlamaIndex\n# ImportError: Install caveman-middleware[llama-index] ...\n\n// after\n# shell: pip install \"caveman-middleware[llama-index]\"\nfrom caveman_middleware.llama_index import CavemanLlamaIndex","handlingStrategy":"try-catch","validationCode":"import importlib.util\nmissing = [m for m in (\"llama_index.core\", \"pydantic\", \"pydantic_core\") if importlib.util.find_spec(m) is None]\nif missing:\n    raise SystemExit('Install with: pip install \"caveman-middleware[llama-index]\" (missing: %s)' % missing)","typeGuard":"def llama_index_available() -> bool:\n    return importlib.util.find_spec(\"llama_index.core\") is not None","tryCatchPattern":"try:\n    from caveman_middleware.llama_index import CavemanLlamaIndex\nexcept ImportError as e:\n    logger.error(\"LlamaIndex adapter unavailable: %s\", e)\n    CavemanLlamaIndex = None  # or fall back to another adapter","preventionTips":["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"],"tags":["python","import-error","optional-dependency","llama-index"],"backgroundTag":"missing-optional-dependency","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}