{"record":{"id":"1d8e23c2650b8b1e","repo":"JuliusBrussee/caveman","slug":"install-caveman-middleware-openai-to-use-the-openai-adapter","errorCode":null,"errorMessage":"Install caveman-middleware[openai] to use the OpenAI adapter","messagePattern":"Install caveman-middleware\\[openai\\] to use the OpenAI adapter","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"packages/middleware/python/caveman_middleware/openai.py","lineNumber":15,"sourceCode":"\"\"\"Instance-scoped integration through OpenAI's public client post method.\"\"\"\nfrom __future__ import annotations\n\nimport functools\nimport asyncio\nimport copy\nimport json\nfrom dataclasses import dataclass\nfrom types import MappingProxyType\nfrom urllib.parse import urlsplit\n\ntry:\n    from openai import OpenAI, AsyncOpenAI, Stream, AsyncStream, __version__\nexcept ModuleNotFoundError as error:\n    raise ImportError(\"Install caveman-middleware[openai] to use the OpenAI adapter\") from error\n\nfrom caveman_cloud.middleware import MiddlewareRuntime, AsyncMiddlewareRuntime\nfrom ._httpx2 import observe_response, OpenAICall, CavemanOpenAITransport, CavemanAsyncOpenAITransport\nfrom ._usage import usage\nfrom ._native import NativeSession, owner, plain\nfrom ._versions import in_range\n\n\ndef with_caveman_openai(client, *, runtime, scope, transport=None):\n    \"\"\"Return the same native client class with native resources and helpers.\n\n    Python's pinned SDK has no Chat Completions tool runner. This model-only\n    integration therefore uses recovery-free transformations. Native agent\n    integrations can own recovery above it without a second optimization pass.\n    Supply the same CavemanOpenAITransport/CavemanAsyncOpenAITransport used by\n    the client's public http_client to observe physical SDK retries. Without\n    that explicit seam, receipts describe one native operation.\n    \"\"\"","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/middleware/python/caveman_middleware/openai.py#L1-L33","documentation":"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.","triggerScenarios":"Importing caveman_middleware.openai (directly or via with_caveman_openai / with_caveman_openai_tools) in an environment where the `openai` pip package is absent.","commonSituations":"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.","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"],"exampleFix":"// before\npip install caveman-middleware\n// after\npip install \"caveman-middleware[openai]\"","handlingStrategy":"fallback","validationCode":"import importlib.util\nif importlib.util.find_spec(\"openai\") is None:\n    raise SystemExit(\"Install caveman-middleware[openai]\")","typeGuard":"def openai_installed(): return importlib.util.find_spec(\"openai\") is not None","tryCatchPattern":"try:\n    from caveman_middleware.openai import with_caveman_openai\nexcept ImportError as e:\n    if \"caveman-middleware[openai]\" in str(e):\n        raise SystemExit(\"pip install 'caveman-middleware[openai]'\") from e\n    raise","preventionTips":["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"],"tags":["python","dependencies","import"],"backgroundTag":"missing-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"}