{"record":{"id":"bc92f09bda81d116","repo":"headroomlabs-ai/headroom","slug":"langchain-is-required-for-this-integration-instal-bc92f0","errorCode":null,"errorMessage":"LangChain is required for this integration. Install with: pip install headroom[langchain] or: pip install langchain-core","messagePattern":"LangChain is required for this integration\\. Install with: pip install headroom\\[langchain\\] or: pip install langchain-core","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/integrations/langchain/retriever.py","lineNumber":84,"sourceCode":"                    def compress_documents(\n                        self, documents: Sequence[Any], query: str, callbacks: Any = None\n                    ) -> Sequence[Any]:\n                        raise NotImplementedError\n\n        LANGCHAIN_AVAILABLE = True\n    except ImportError:\n        LANGCHAIN_AVAILABLE = False\n        BaseDocumentCompressor = object  # type: ignore[misc,assignment]\n        Document = object  # type: ignore[misc,assignment]\n        Callbacks = None  # type: ignore[misc,assignment]\n\nlogger = logging.getLogger(__name__)\n\n\ndef _check_langchain_available() -> None:\n    \"\"\"Raise ImportError if LangChain is not installed.\"\"\"\n    if not LANGCHAIN_AVAILABLE:\n        raise ImportError(\n            \"LangChain is required for this integration. \"\n            \"Install with: pip install headroom[langchain] \"\n            \"or: pip install langchain-core\"\n        )\n\n\n@dataclass\nclass CompressionMetrics:\n    \"\"\"Metrics from document compression.\"\"\"\n\n    documents_before: int\n    documents_after: int\n    documents_removed: int\n    relevance_scores: list[float]\n\n\nclass HeadroomDocumentCompressor(BaseDocumentCompressor):\n    \"\"\"Compresses retrieved documents based on relevance to query.","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/langchain/retriever.py#L66-L102","documentation":"Raised by _check_langchain_available() in the LangChain retriever/document-compressor integration when langchain-core is missing (BaseDocumentCompressor, Document, and Callbacks all failed to import and were stubbed). It guards the Headroom document compressor class that exposes CompressionMetrics (documents_before/documents_after) for RAG pipelines.","triggerScenarios":"Instantiating or invoking the Headroom document compressor (compress_documents / acontextualize calls) inside a LangChain retrieval chain when langchain-core is not importable in the runtime environment.","commonSituations":"RAG pipelines assembled in a fresh environment with only `pip install headroom`; container images trimmed of optional extras; local dev works (global site-packages has langchain) but the Docker build omits it.","solutions":["Install `pip install 'headroom[langchain]'` (or `pip install langchain-core`)","Add the extra to your deployment image/requirements: `headroom[langchain]` in requirements.txt or pyproject dependencies","Smoke-test the import inside the actual runtime container, not just locally"],"exampleFix":"# before\ncompressor = HeadroomDocumentCompressor(...)\ndocs = compressor.compress_documents(docs, 'query', callbacks)\n\n# after\n# requirements.txt: headroom[langchain]\ncompressor = HeadroomDocumentCompressor(...)\ndocs = compressor.compress_documents(docs, 'query', callbacks)","handlingStrategy":"validation","validationCode":"import importlib.util\nassert importlib.util.find_spec('langchain_core'), 'langchain-core required for the retriever compressor'","typeGuard":"def retriever_compressor_ready() -> bool:\n    from headroom.integrations.langchain import retriever\n    return retriever.LANGCHAIN_AVAILABLE","tryCatchPattern":"try:\n    docs = compressor.compress_documents(docs, query, callbacks)\nexcept ImportError as e:\n    logger.warning('Compression skipped, returning raw docs: %s', e)\n    docs = docs","preventionTips":["Add headroom[langchain] to the RAG service image","Test the retrieval chain inside the actual container, not just locally","Degrade gracefully: uncompressed retrieval still answers, just costs more tokens"],"tags":["retriever","rag","langchain","import-error"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}