{"record":{"id":"f31a26c990060fca","repo":"headroomlabs-ai/headroom","slug":"langchain-is-required-for-this-integration-instal-f31a26","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/memory.py","lineNumber":54,"sourceCode":"        ToolMessage,\n    )\n\n    LANGCHAIN_AVAILABLE = True\nexcept ImportError:\n    LANGCHAIN_AVAILABLE = False\n    BaseChatMessageHistory = object  # type: ignore[misc,assignment]\n\nfrom headroom import HeadroomConfig\nfrom headroom.providers import OpenAIProvider\nfrom headroom.transforms import TransformPipeline\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\nclass HeadroomChatMessageHistory(BaseChatMessageHistory):\n    \"\"\"Wraps any LangChain chat message history with automatic compression.\n\n    When conversation history exceeds the token threshold, automatically\n    applies live-zone block compression (per-block content compression on\n    the live zone, never dropping messages — that's what the live-zone\n    refactor in PR-B1+ replaces the old RollingWindow strategy with).\n\n    This works with ANY memory type because it wraps at the storage layer:\n    - ConversationBufferMemory\n    - ConversationSummaryMemory\n    - ConversationBufferWindowMemory","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/langchain/memory.py#L36-L72","documentation":"Raised by _check_langchain_available() in the LangChain memory integration when langchain-core is missing. It guards HeadroomChatMessageHistory, a wrapper around any BaseChatMessageHistory that applies live-zone block compression (SmartCrusher-style per-block compression that never drops messages) once history exceeds the token threshold. When the import fails, BaseChatMessageHistory is stubbed to `object`, so instantiation is impossible anyway; this guard gives an actionable message.","triggerScenarios":"Constructing HeadroomChatMessageHistory(session_id=..., ...) or calling its methods (add_message, get_messages) when `from langchain_core... import BaseChatMessageHistory` failed at module import time.","commonSituations":"Adding headroom history compression to a chat app whose environment lacks langchain-core; deploying with a lockfile that excluded optional extras; upgrading LangChain versions where the import path moved so LANGCHAIN_AVAILABLE silently became False even though some langchain package exists.","solutions":["Install `pip install 'headroom[langchain]'` or `pip install langchain-core`","If langchain-core IS installed, check the module's import block for the specific symbols it imports and verify your langchain-core version still provides them (a version mismatch flips LANGCHAIN_AVAILABLE to False)","Pin known-good versions in requirements.txt"],"exampleFix":"# before\nhistory = HeadroomChatMessageHistory(session_id='s1', wrapped=redis_history)\n\n# after\n# pip install 'headroom[langchain]'\nhistory = HeadroomChatMessageHistory(session_id='s1', wrapped=redis_history)","handlingStrategy":"validation","validationCode":"import importlib.util\nassert importlib.util.find_spec('langchain_core'), 'langchain-core required for HeadroomChatMessageHistory'","typeGuard":"def history_wrapper_ready() -> bool:\n    from headroom.integrations.langchain import memory\n    return memory.LANGCHAIN_AVAILABLE","tryCatchPattern":"try:\n    history = HeadroomChatMessageHistory(session_id=sid, wrapped=inner)\nexcept ImportError as e:\n    if 'langchain' in str(e):\n        history = inner  # fall back to the raw store without compression\n    else:\n        raise","preventionTips":["List headroom[langchain] in the chat app's dependencies","Fall back to the unwrapped BaseChatMessageHistory when compression is optional","Bump langchain-core deliberately and re-run integration tests — moved imports silently disable the wrapper"],"tags":["memory","langchain","import-error","chat-history"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}