headroomlabs-ai/headroom · error · ImportError

LangChain is required for this integration. Install with: pi

Error message

LangChain is required for this integration. Install with: pip install headroom[langchain] or: pip install langchain-core

What it means

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.

Source

Thrown at headroom/integrations/langchain/retriever.py:84

                    def compress_documents(
                        self, documents: Sequence[Any], query: str, callbacks: Any = None
                    ) -> Sequence[Any]:
                        raise NotImplementedError

        LANGCHAIN_AVAILABLE = True
    except ImportError:
        LANGCHAIN_AVAILABLE = False
        BaseDocumentCompressor = object  # type: ignore[misc,assignment]
        Document = object  # type: ignore[misc,assignment]
        Callbacks = None  # type: ignore[misc,assignment]

logger = logging.getLogger(__name__)


def _check_langchain_available() -> None:
    """Raise ImportError if LangChain is not installed."""
    if not LANGCHAIN_AVAILABLE:
        raise ImportError(
            "LangChain is required for this integration. "
            "Install with: pip install headroom[langchain] "
            "or: pip install langchain-core"
        )


@dataclass
class CompressionMetrics:
    """Metrics from document compression."""

    documents_before: int
    documents_after: int
    documents_removed: int
    relevance_scores: list[float]


class HeadroomDocumentCompressor(BaseDocumentCompressor):
    """Compresses retrieved documents based on relevance to query.

View on GitHub (pinned to 322425c43b)

Solutions

  1. Install `pip install 'headroom[langchain]'` (or `pip install langchain-core`)
  2. Add the extra to your deployment image/requirements: `headroom[langchain]` in requirements.txt or pyproject dependencies
  3. Smoke-test the import inside the actual runtime container, not just locally

Example fix

# before
compressor = HeadroomDocumentCompressor(...)
docs = compressor.compress_documents(docs, 'query', callbacks)

# after
# requirements.txt: headroom[langchain]
compressor = HeadroomDocumentCompressor(...)
docs = compressor.compress_documents(docs, 'query', callbacks)
Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
assert importlib.util.find_spec('langchain_core'), 'langchain-core required for the retriever compressor'

Type guard

def retriever_compressor_ready() -> bool:
    from headroom.integrations.langchain import retriever
    return retriever.LANGCHAIN_AVAILABLE

Try / catch

try:
    docs = compressor.compress_documents(docs, query, callbacks)
except ImportError as e:
    logger.warning('Compression skipped, returning raw docs: %s', e)
    docs = docs

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/bc92f09bda81d116. Report an issue: GitHub.