JuliusBrussee/caveman · error · ImportError

Install caveman-middleware[openai] to use the OpenAI adapter

Error message

Install caveman-middleware[openai] to use the OpenAI adapter

What it means

The OpenAI adapter module imports the official `openai` SDK at module load time; if it is not installed the import fails and the library re-raises it as an ImportError telling you to install the optional extra `caveman-middleware[openai]`. The openai package is an optional dependency, not a hard requirement of caveman-middleware.

Solutions

Run `pip install "caveman-middleware[openai]"`
Or install the openai SDK separately: `pip install openai`
Verify with `pip show openai` in the same interpreter/venv your app runs in
Re-run after adding the extra to requirements.txt/pyproject dependencies

Example fix

// before
pip install caveman-middleware
// after
pip install "caveman-middleware[openai]"

Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
if importlib.util.find_spec("openai") is None:
    raise SystemExit("Install caveman-middleware[openai]")

Type guard

def openai_installed(): return importlib.util.find_spec("openai") is not None

Try / catch

try:
    from caveman_middleware.openai import with_caveman_openai
except ImportError as e:
    if "caveman-middleware[openai]" in str(e):
        raise SystemExit("pip install 'caveman-middleware[openai]'") from e
    raise

Prevention

Declare the extra in requirements: caveman-middleware[openai]
Pin extras in pyproject/CI so fresh environments install them
Verify deps in CI with the same interpreter as production

When it happens

Trigger: Importing caveman_middleware.openai (directly or via with_caveman_openai / with_caveman_openai_tools) in an environment where the `openai` pip package is absent.

Common situations: Fresh virtualenv or CI container that installed only `pip install caveman-middleware`; the extras bracket was dropped when pinning requirements; a different Python interpreter is active than the one where openai was installed.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at packages/middleware/python/caveman_middleware/openai.py:15

"""Instance-scoped integration through OpenAI's public client post method."""
from __future__ import annotations

import functools
import asyncio
import copy
import json
from dataclasses import dataclass
from types import MappingProxyType
from urllib.parse import urlsplit

try:
    from openai import OpenAI, AsyncOpenAI, Stream, AsyncStream, __version__
except ModuleNotFoundError as error:
    raise ImportError("Install caveman-middleware[openai] to use the OpenAI adapter") from error

from caveman_cloud.middleware import MiddlewareRuntime, AsyncMiddlewareRuntime
from ._httpx2 import observe_response, OpenAICall, CavemanOpenAITransport, CavemanAsyncOpenAITransport
from ._usage import usage
from ._native import NativeSession, owner, plain
from ._versions import in_range


def with_caveman_openai(client, *, runtime, scope, transport=None):
    """Return the same native client class with native resources and helpers.

    Python's pinned SDK has no Chat Completions tool runner. This model-only
    integration therefore uses recovery-free transformations. Native agent
    integrations can own recovery above it without a second optimization pass.
    Supply the same CavemanOpenAITransport/CavemanAsyncOpenAITransport used by
    the client's public http_client to observe physical SDK retries. Without
    that explicit seam, receipts describe one native operation.
    """

View on GitHub (pinned to 3ee70a1026)