{"record":{"id":"b9014145b61b3378","repo":"headroomlabs-ai/headroom","slug":"langchain-is-required-for-this-integration-instal-b90141","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/streaming.py","lineNumber":46,"sourceCode":"try:\n    from langchain_core.messages import AIMessageChunk\n    from langchain_core.outputs import ChatGenerationChunk\n\n    LANGCHAIN_AVAILABLE = True\nexcept ImportError:\n    LANGCHAIN_AVAILABLE = False\n    AIMessageChunk = object  # type: ignore[misc,assignment]\n    ChatGenerationChunk = object  # type: ignore[misc,assignment]\n\nfrom headroom.providers import OpenAIProvider\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 StreamingMetrics:\n    \"\"\"Metrics from a streaming response.\"\"\"\n\n    output_tokens: int\n    chunk_count: int\n    content_length: int\n    start_time: datetime\n    end_time: datetime | None\n    duration_ms: float | None\n\n    def to_dict(self) -> dict[str, Any]:","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/langchain/streaming.py#L28-L64","documentation":"Raised by _check_langchain_available() in the LangChain streaming integration when langchain-core is missing (AIMessageChunk and ChatGenerationChunk failed to import and were stubbed to `object`). It guards the streaming wrapper that produces StreamingMetrics (output_tokens, chunk_count) around token streams from an OpenAIProvider.","triggerScenarios":"Starting or consuming a headroom-wrapped streaming response (any API on this module that builds AIMessageChunk/ChatGenerationChunk objects) when langchain-core is absent.","commonSituations":"An app that previously used non-streaming headroom calls adds streaming via the LangChain integration without adding the dependency; notebooks where the kernel was started before installing langchain-core (module cached with LANGCHAIN_AVAILABLE=False — needs kernel restart even after pip install).","solutions":["Install `pip install 'headroom[langchain]'`","If you installed it mid-session in a notebook, restart the kernel/process — LANGCHAIN_AVAILABLE is evaluated once at import time","Verify with `python -c \"from headroom.integrations.langchain import streaming\"`"],"exampleFix":"# before\nstream = headroom_stream(provider, messages)  # ImportError raised by guard\n\n# after\n# pip install 'headroom[langchain]'; restart process\nstream = headroom_stream(provider, messages)","handlingStrategy":"validation","validationCode":"import importlib.util\nassert importlib.util.find_spec('langchain_core'), 'langchain-core required for the streaming integration'","typeGuard":"def streaming_wrapper_ready() -> bool:\n    from headroom.integrations.langchain import streaming\n    return streaming.LANGCHAIN_AVAILABLE","tryCatchPattern":"try:\n    for chunk in headroom_stream(...):\n        yield chunk\nexcept ImportError as e:\n    if 'langchain' in str(e):\n        yield from raw_stream(...)  # bypass the LangChain chunk wrappers\n    else:\n        raise","preventionTips":["Restart kernels/processes after installing langchain-core (flag cached at import)","Prefer the non-LangChain streaming path if you don't need AIMessageChunk types","Add an integration import check to the app's health endpoint"],"tags":["streaming","langchain","import-error","notebook-pitfall"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}