{"record":{"id":"060a4a318b06e9c5","repo":"JuliusBrussee/caveman","slug":"install-caveman-middleware-litellm-to-use-the-litellm","errorCode":null,"errorMessage":"Install caveman-middleware[litellm] to use the LiteLLM adapter","messagePattern":"Install caveman-middleware\\[litellm\\] to use the LiteLLM adapter","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"packages/middleware/python/caveman_middleware/litellm.py","lineNumber":21,"sourceCode":"Install the callback after original-content policy hooks. A proxy scope resolver\nreceives the authenticated UserAPIKeyAuth object, never a model-supplied identity.\nLiteLLM remains the sole inference hop and owns retries, fallbacks and streams.\n\"\"\"\nfrom __future__ import annotations\n\nimport contextlib\nimport contextvars\nimport threading\nimport time\nimport uuid\nfrom collections import OrderedDict\nfrom dataclasses import dataclass\n\ntry:\n    import litellm as native\n    from litellm.integrations.custom_logger import CustomLogger\nexcept ModuleNotFoundError as error:\n    raise ImportError(\"Install caveman-middleware[litellm] to use the LiteLLM adapter\") from error\n\nfrom caveman_cloud.middleware import MiddlewareError, MiddlewareRuntime, Scope\nfrom ._native import Attempt, NativeSession, owner, plain\nfrom ._versions import matches_framework\nfrom ._usage import usage\n\n_active = contextvars.ContextVar(\"caveman_litellm_request\", default=None)\n_sync_router = contextvars.ContextVar(\"caveman_litellm_sync_router\", default=None)\n_prepared_sync = contextvars.ContextVar(\"caveman_litellm_prepared_sync\", default=None)\n_registration_lock = threading.RLock()\n_KEY = \"caveman_middleware_registration\"\n\n\n@dataclass\nclass _Request:\n    scope: Scope\n    logical_id: str\n    expires: float","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/middleware/python/caveman_middleware/litellm.py#L3-L39","documentation":"Importing the LiteLLM adapter requires the optional 'litellm' package (plus litellm.integrations.custom_logger). When the import fails with ModuleNotFoundError, the adapter re-raises it as ImportError with this message, chaining the original error. The adapter is shipped as an extra so the core package stays dependency-light.","triggerScenarios":"Any import of caveman_middleware.litellm (or use of the adapter entry point) while the 'litellm' distribution is not installed in the current Python environment.","commonSituations":"Installed caveman-middleware without the [litellm] extra; using a different virtualenv/interpreter than the one that has litellm; deploying to a container where extras were pruned; litellm broken/unimportable so its import also raises ModuleNotFoundError.","solutions":["Run pip install \"caveman-middleware[litellm]\" in the active environment","Verify with `which python` / `pip show litellm` that you are in the same environment that runs your app","If litellm is installed but fails to import, fix or reinstall litellm itself (pip install --force-reinstall litellm)","Pin a litellm version compatible with your Python if the install itself fails"],"exampleFix":"// before\nfrom caveman_middleware.litellm import CavemanLiteLLM\n# ImportError: Install caveman-middleware[litellm] ...\n\n// after\n# shell: pip install \"caveman-middleware[litellm]\"\nfrom caveman_middleware.litellm import CavemanLiteLLM","handlingStrategy":"try-catch","validationCode":"import importlib.util\nif importlib.util.find_spec(\"litellm\") is None:\n    raise SystemExit('Install with: pip install \"caveman-middleware[litellm]\"')","typeGuard":"def litellm_available() -> bool:\n    return importlib.util.find_spec(\"litellm\") is not None","tryCatchPattern":"try:\n    from caveman_middleware.litellm import CavemanLiteLLM\nexcept ImportError as e:\n    logger.error(\"LiteLLM adapter unavailable: %s\", e)\n    CavemanLiteLLM = None  # or fall back to another adapter","preventionTips":["Install framework adapters with extras: caveman-middleware[litellm]","Declare the extra in your project's dependencies/requirements","Import adapters at startup (fail fast) rather than lazily at request time","Run the app with the same interpreter/venv you pip-install into"],"tags":["python","import-error","optional-dependency","litellm"],"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"}