Skip to content

Use langchain_core.__version__ instead of requiring the langchain umbrella package as a version sentinel in CallbackHandler #13651

@walterosc

Description

@walterosc

Describe the bug / enhancement

langfuse/langchain/CallbackHandler.py (lines 40-85 in 4.5.1 and 4.6.1) requires import langchain purely as a version sentinel:

try:
    import langchain

    if langchain.__version__.startswith("1"):
        # Langchain v1 — all imports below are from langchain_core
        from langchain_core.agents import AgentAction, AgentFinish
        from langchain_core.callbacks import (
            BaseCallbackHandler as LangchainBaseCallbackHandler,
        )
        from langchain_core.documents import Document
        from langchain_core.messages import (
            AIMessage, BaseMessage, ChatMessage, FunctionMessage,
            HumanMessage, SystemMessage, ToolMessage,
        )
        from langchain_core.outputs import ChatGeneration, LLMResult
    else:
        # Langchain v0 — uses some langchain.* imports
        ...
except ImportError:
    raise ModuleNotFoundError(
        "Please install langchain to use the Langfuse langchain integration: 'pip install langchain'"
    )

In the v1 branch, none of the actual imports come from the langchain umbrella — they all come from langchain_core, which is already a required dependency for anyone using LangGraph or any langchain-* provider package (e.g., langchain-anthropic, langchain-openai).

Why this matters

Users who only depend on langgraph + langchain-core + langchain-anthropic (the modern minimal stack) are forced to install the entire langchain umbrella package just to satisfy a version check. The umbrella brings in additional transitive deps and increases install size with no functional benefit.

Suggested fix

Replace the umbrella version sentinel with a langchain_core one:

import langchain_core

if langchain_core.__version__.startswith("1"):
    # langchain v1 imports
    from langchain_core.agents import AgentAction, AgentFinish
    from langchain_core.callbacks import (
        BaseCallbackHandler as LangchainBaseCallbackHandler,
    )
    # ... etc, all from langchain_core
else:
    # langchain v0 imports — still need the umbrella package
    try:
        from langchain.callbacks.base import (
            BaseCallbackHandler as LangchainBaseCallbackHandler,
        )
        from langchain.schema.agent import AgentAction, AgentFinish
        from langchain.schema.document import Document
        # ...
    except ImportError:
        raise ModuleNotFoundError(
            "Please install langchain<1.0 to use the legacy Langfuse "
            "langchain integration"
        )

This way:

  • v1 users only need langchain_core (which they already have)
  • v0 users still get a clear error message asking for the umbrella

Steps to reproduce

pip install langfuse langchain-core langchain-anthropic
python -c "from langfuse.langchain import CallbackHandler"
# → ModuleNotFoundError: Please install langchain to use the Langfuse langchain integration: 'pip install langchain'

Environment

  • Langfuse: 4.5.1 and 4.6.1 (latest as of 2026-05-15)
  • LangChain Core: 1.3.3
  • Python: 3.11
  • OS: Linux (Docker)

Prior art

Are you interested in contributing a fix for this bug?

Open to it — the change is minimal and isolated to one file. Will open a PR if a maintainer signals interest.

Metadata

Metadata

Assignees

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions