sovara-langchain 0.1.0__py3-none-any.whl

sovara_langchain/__init__.py

@@ -0,0 +1,48 @@
+"""Record LangChain and LangGraph model and tool calls, with lessons per model call.
+
+Use one of these per model, not both:
+
+- ``SovaraMiddleware`` for ``create_agent`` (needs ``langchain>=1.1``); it also records tool
+  calls.
+- ``wrap_chat_model(model)`` for any other use of a chat model, such as custom LangGraph
+  nodes, ``with_structured_output`` or prebuilt agents (needs only ``langchain-core``).
+
+Call ``instrument_tools()`` once at startup to also record tool calls that the middleware does not
+own, such as the tools of a LangGraph agent built on a wrapped model. Each export loads on first
+access, so the wrapper does not import ``langchain``.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from sovara_langchain._chat_model import SovaraChatModel, wrap_chat_model
+    from sovara_langchain._middleware import SovaraMiddleware
+
+__all__ = ["SovaraChatModel", "SovaraMiddleware", "instrument_tools", "wrap_chat_model"]
+
+_MODULES = {
+    "SovaraChatModel": "sovara_langchain._chat_model",
+    "wrap_chat_model": "sovara_langchain._chat_model",
+    "SovaraMiddleware": "sovara_langchain._middleware",
+}
+
+
+def instrument_tools() -> None:
+    """Record LangChain tool calls inside Sovara traces; idempotent.
+
+    Patches ``langchain_core`` tool execution. Tool calls the middleware already records are
+    skipped, so using both never records a tool twice.
+    """
+    from sovara_langchain._tool_patch import langchain_patch
+
+    langchain_patch()
+
+
+def __getattr__(name: str) -> Any:
+    module = _MODULES.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    return getattr(import_module(module), name)

sovara_langchain/_chat_model.py

@@ -0,0 +1,346 @@
+"""Wrap a LangChain chat model so every call it makes is recorded with lessons.
+
+``wrap_chat_model(model)`` returns a chat model that records each ``invoke``, ``stream``,
+``batch`` and async call, including calls through ``bind_tools`` and
+``with_structured_output``. Lessons go into one temporary user message on that request
+only; the caller's messages and graph state are never changed. Generation, tool binding,
+structured output and parsing stay with the wrapped model.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Iterator, Mapping, Sequence
+from typing import Any
+
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import BaseMessage
+from langchain_core.outputs import ChatGenerationChunk, ChatResult
+from langchain_core.runnables import (
+    Runnable,
+    RunnableBinding,
+    RunnableParallel,
+    RunnableSequence,
+    RunnableWithFallbacks,
+)
+from langchain_core.runnables.passthrough import RunnableAssign
+from pydantic import PrivateAttr
+
+from sovara import ConversationOutput, Execution, SovaraConfigError, Step
+from sovara import integration as instrumentation
+from sovara_langchain import _messages as convert
+
+__all__ = ["SovaraChatModel", "wrap_chat_model"]
+
+
+def _prepare(
+    model: BaseChatModel, messages: list[BaseMessage], kwargs: dict[str, Any]
+) -> tuple[Step | None, list[BaseMessage], Execution | None]:
+    call = convert.llm_call(model, messages, kwargs.get("tools") or ())
+    step = instrumentation.begin(call, lessons=True) if call is not None else None
+    return _with_lessons(step, messages, kwargs)
+
+
+async def _aprepare(
+    model: BaseChatModel, messages: list[BaseMessage], kwargs: dict[str, Any]
+) -> tuple[Step | None, list[BaseMessage], Execution | None]:
+    call = convert.llm_call(model, messages, kwargs.get("tools") or ())
+    step = await instrumentation.abegin(call, lessons=True) if call is not None else None
+    return _with_lessons(step, messages, kwargs)
+
+
+def _with_lessons(
+    step: Step | None, messages: list[BaseMessage], kwargs: dict[str, Any]
+) -> tuple[Step | None, list[BaseMessage], Execution | None]:
+    context = step.lesson_context if step is not None else None
+    if context is None:
+        return step, messages, None
+    sent = convert.with_lessons(messages, context.text)
+    execution = Execution(
+        input=convert.conversation(sent, kwargs.get("tools") or ()),
+        injected_retrieval_id=context.retrieval_id,
+    )
+    return step, sent, execution
+
+
+def _result_output(result: ChatResult) -> ConversationOutput:
+    if not result.generations:
+        return convert.safe_output(None)
+    generation = result.generations[0]
+    return convert.safe_output(generation.message, generation.generation_info)  # type: ignore[arg-type]
+
+
+def _chunks_output(chunks: ChatGenerationChunk | None) -> ConversationOutput:
+    if chunks is None:
+        return convert.safe_output(None)
+    return convert.safe_output(chunks.message, chunks.generation_info)  # type: ignore[arg-type]
+
+
+def _rebind(node: Any, old: Any, new: Any) -> tuple[Any, bool]:
+    """Return ``node`` with the runnable ``old`` replaced by ``new``, and whether it was found."""
+    if node is old:
+        return new, True
+    if isinstance(node, RunnableBinding):
+        bound, found = _rebind(node.bound, old, new)
+        return (node.model_copy(update={"bound": bound}), True) if found else (node, False)
+    if isinstance(node, RunnableSequence):
+        first, in_first = _rebind(node.first, old, new)
+        middle = [_rebind(step, old, new) for step in node.middle]
+        last, in_last = _rebind(node.last, old, new)
+        found = in_first or in_last or any(hit for _, hit in middle)
+        update = {"first": first, "middle": [step for step, _ in middle], "last": last}
+        return (node.model_copy(update=update), True) if found else (node, False)
+    if isinstance(node, RunnableParallel):
+        steps = {key: _rebind(step, old, new) for key, step in node.steps__.items()}
+        if not any(hit for _, hit in steps.values()):
+            return node, False
+        return node.model_copy(update={"steps__": {k: s for k, (s, _) in steps.items()}}), True
+    if isinstance(node, RunnableWithFallbacks):
+        runnable, in_runnable = _rebind(node.runnable, old, new)
+        fallbacks = [_rebind(step, old, new) for step in node.fallbacks]
+        if not in_runnable and not any(hit for _, hit in fallbacks):
+            return node, False
+        update = {"runnable": runnable, "fallbacks": [step for step, _ in fallbacks]}
+        return node.model_copy(update=update), True
+    if isinstance(node, RunnableAssign):
+        mapper, found = _rebind(node.mapper, old, new)
+        return (node.model_copy(update={"mapper": mapper}), True) if found else (node, False)
+    return node, False
+
+
+class SovaraChatModel(BaseChatModel):
+    """A chat model that records each call of the wrapped model as a Sovara step.
+
+    Create it with ``wrap_chat_model``. Calls go to the wrapped model's own generation and
+    streaming methods; outside a recording they pass through unchanged.
+
+    Public attributes the wrapper does not define, such as ``temperature`` or ``model_name``,
+    are read from and set on the wrapped model. Chat-model settings (callbacks, tags, cache and
+    the other ``BaseChatModel`` fields) are copied when wrapping; setting one later sets it on
+    both models.
+    """
+
+    # Private, because providers such as ChatAnthropic use a public ``model`` field.
+    _model: BaseChatModel = PrivateAttr()
+
+    def __init__(self, model: BaseChatModel, **settings: Any) -> None:
+        """Wrap ``model``; ``settings`` are its ``BaseChatModel`` fields."""
+        super().__init__(**settings)
+        self._model = model
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return super().__getattr__(name)  # type: ignore[misc]
+        except AttributeError:
+            if name.startswith("_"):
+                raise
+            private = self.__pydantic_private__ or {}
+            if "_model" not in private:
+                raise
+            return getattr(private["_model"], name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith("_"):
+            super().__setattr__(name, value)
+        elif name in BaseChatModel.model_fields:
+            super().__setattr__(name, value)
+            setattr(self._model, name, value)
+        else:
+            setattr(self._model, name, value)
+
+    @property
+    def wrapped_model(self) -> BaseChatModel:
+        """Return the model whose calls this wrapper records."""
+        return self._model
+
+    @property
+    def _llm_type(self) -> str:
+        return self._model._llm_type
+
+    @property
+    def _identifying_params(self) -> Mapping[str, Any]:
+        return self._model._identifying_params
+
+    def _get_ls_params(self, stop: list[str] | None = None, **kwargs: Any) -> Any:
+        return self._model._get_ls_params(stop=stop, **kwargs)
+
+    def _should_stream(self, *, async_api: bool, run_manager: Any = None, **kwargs: Any) -> bool:
+        return self._model._should_stream(async_api=async_api, run_manager=run_manager, **kwargs)
+
+    def _generate(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,
+        run_manager: Any = None,
+        **kwargs: Any,
+    ) -> ChatResult:
+        step, sent, execution = _prepare(self._model, messages, kwargs)
+        if step is None:
+            return self._model._generate(messages, stop=stop, run_manager=run_manager, **kwargs)
+        try:
+            with step.activate():
+                result = self._model._generate(sent, stop=stop, run_manager=run_manager, **kwargs)
+        except BaseException as exc:
+            instrumentation.report_raised(step, exc, classify=convert.raised, execution=execution)
+            raise
+        instrumentation.report(step, "finish", _result_output(result), execution=execution)
+        return result
+
+    async def _agenerate(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,
+        run_manager: Any = None,
+        **kwargs: Any,
+    ) -> ChatResult:
+        step, sent, execution = await _aprepare(self._model, messages, kwargs)
+        if step is None:
+            return await self._model._agenerate(
+                messages, stop=stop, run_manager=run_manager, **kwargs
+            )
+        try:
+            with step.activate():
+                result = await self._model._agenerate(
+                    sent, stop=stop, run_manager=run_manager, **kwargs
+                )
+        except BaseException as exc:
+            await instrumentation.areport_raised(
+                step, exc, classify=convert.raised, execution=execution
+            )
+            raise
+        await instrumentation.areport(step, "finish", _result_output(result), execution=execution)
+        return result
+
+    def _stream(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,
+        run_manager: Any = None,
+        **kwargs: Any,
+    ) -> Iterator[ChatGenerationChunk]:
+        step, sent, execution = _prepare(self._model, messages, kwargs)
+        if step is None:
+            yield from self._model._stream(messages, stop=stop, run_manager=run_manager, **kwargs)
+            return
+        chunks: ChatGenerationChunk | None = None
+        iterator = self._model._stream(sent, stop=stop, run_manager=run_manager, **kwargs)
+        try:
+            while True:
+                # Activation covers each pull from the model, never the consumer's code.
+                with step.activate():
+                    chunk = next(iterator, None)
+                if chunk is None:
+                    break
+                chunks = chunk if chunks is None else chunks + chunk
+                yield chunk
+        except BaseException as exc:
+            ending, args = (
+                ("cancel", ("Closed",)) if isinstance(exc, GeneratorExit) else (convert.raised(exc))
+            )
+            instrumentation.report(
+                step,
+                ending,
+                *args,
+                output=_chunks_output(chunks),
+                execution=execution,
+                propagating=True,
+            )
+            close = getattr(iterator, "close", None)
+            if close is not None:
+                close()
+            raise
+        instrumentation.report(step, "finish", _chunks_output(chunks), execution=execution)
+
+    async def _astream(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,
+        run_manager: Any = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[ChatGenerationChunk]:
+        step, sent, execution = await _aprepare(self._model, messages, kwargs)
+        if step is None:
+            async for chunk in self._model._astream(
+                messages, stop=stop, run_manager=run_manager, **kwargs
+            ):
+                yield chunk
+            return
+        chunks: ChatGenerationChunk | None = None
+        iterator = self._model._astream(sent, stop=stop, run_manager=run_manager, **kwargs)
+        try:
+            while True:
+                with step.activate():
+                    chunk = await anext(iterator, None)
+                if chunk is None:
+                    break
+                chunks = chunk if chunks is None else chunks + chunk
+                yield chunk
+        except BaseException as exc:
+            ending, args = (
+                ("cancel", ("Closed",)) if isinstance(exc, GeneratorExit) else (convert.raised(exc))
+            )
+            partial = _chunks_output(chunks)
+            # A closed async generator may still await; a cancelled task must not.
+            if isinstance(exc, (Exception, GeneratorExit)):
+                await instrumentation.areport(
+                    step, ending, *args, output=partial, execution=execution, propagating=True
+                )
+            else:
+                instrumentation.report_in_background(
+                    step, ending, *args, output=partial, execution=execution
+                )
+            aclose = getattr(iterator, "aclose", None)
+            if aclose is not None:
+                await aclose()
+            raise
+        await instrumentation.areport(step, "finish", _chunks_output(chunks), execution=execution)
+
+    def bind_tools(self, tools: Sequence[Any], **kwargs: Any) -> Runnable:
+        """Bind tools with the wrapped model's own implementation, keeping calls recorded.
+
+        Raises:
+            SovaraConfigError: The wrapped model did not return a binding of itself, so its
+                calls could not be recorded.
+        """
+        native = self._model.bind_tools(tools, **kwargs)
+        if not (isinstance(native, RunnableBinding) and native.bound is self._model):
+            raise SovaraConfigError(
+                f"{type(self._model).__name__}.bind_tools did not return a binding of the "
+                "model, so Sovara cannot record its calls."
+            )
+        return native.model_copy(update={"bound": self})
+
+    def with_structured_output(self, schema: Any, **kwargs: Any) -> Runnable:
+        """Use the wrapped model's own structured output, keeping its calls recorded.
+
+        Parsing, ``include_raw`` and errors behave exactly as for the wrapped model.
+
+        Raises:
+            SovaraConfigError: The wrapped model's runnable does not call the model in a form
+                Sovara can redirect.
+        """
+        native = self._model.with_structured_output(schema, **kwargs)
+        rebound, found = _rebind(native, self._model, self)
+        if not found:
+            raise SovaraConfigError(
+                f"{type(self._model).__name__}.with_structured_output returned a runnable "
+                "Sovara cannot record."
+            )
+        return rebound
+
+
+def wrap_chat_model(model: BaseChatModel) -> SovaraChatModel:
+    """Return a chat model that records every call of ``model``; wrapping twice is a no-op.
+
+    The wrapper takes the wrapped model's callbacks, cache, rate limiter and other chat-model
+    settings, since calls go to its generation methods directly. Other attributes are
+    forwarded to ``model``.
+
+    Raises:
+        SovaraConfigError: ``model`` is not a LangChain chat model.
+    """
+    if isinstance(model, SovaraChatModel):
+        return model
+    if not isinstance(model, BaseChatModel):
+        raise SovaraConfigError("wrap_chat_model() needs a LangChain BaseChatModel.")
+    settings = {name: getattr(model, name) for name in BaseChatModel.model_fields}
+    return SovaraChatModel(model=model, **settings)

sovara_langchain/_log.py

@@ -0,0 +1,20 @@
+"""Logging for the LangChain integration: metadata only, never payloads or tokens."""
+
+from __future__ import annotations
+
+import logging
+import threading
+
+logger = logging.getLogger("sovara_langchain")
+
+_warned: set[str] = set()
+_warned_lock = threading.Lock()
+
+
+def warn_once(key: str, message: str) -> None:
+    """Log a warning the first time ``key`` is seen in this process."""
+    with _warned_lock:
+        if key in _warned:
+            return
+        _warned.add(key)
+    logger.warning(message)

sovara_langchain/_messages.py

@@ -0,0 +1,278 @@
+"""Convert LangChain messages, tools and responses into Sovara conversation data.
+
+Content is read through LangChain's standard ``content_blocks``, so provider-specific
+formats are normalized by LangChain. Tool calls come from ``AIMessage.tool_calls``, which
+LangChain keeps authoritative for every provider. Also holds the step helpers the
+middleware and the chat-model wrapper share.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, ToolMessage
+from langchain_core.runnables.config import ensure_config
+from langchain_core.utils.function_calling import convert_to_openai_tool
+
+from sovara import (
+    ContentBlock,
+    ConversationInput,
+    ConversationOutput,
+    LlmCall,
+    MediaBlock,
+    Message,
+    ProviderBlock,
+    ReasoningBlock,
+    TextBlock,
+    ToolCallBlock,
+    ToolResultBlock,
+    ToolSpec,
+    Usage,
+)
+from sovara import integration as instrumentation
+from sovara.integration import Ending, json_value
+from sovara_langchain._log import warn_once
+
+try:
+    from langgraph.errors import GraphBubbleUp as _BUBBLE_UP
+except ImportError:  # LangGraph is optional for the chat-model wrapper.
+    _BUBBLE_UP = None
+
+METADATA = {"framework": "langchain"}
+
+
+def graph_location() -> dict[str, Any]:
+    """Return where in a LangGraph graph the current call runs, or nothing outside one.
+
+    ``langgraph_nodes`` lists the node names from the outermost graph in, so a supervisor's
+    sub-assistant shows as ``["sql_assistant", "agent"]``. ``langgraph_namespace`` also
+    carries LangGraph's task IDs, so it tells repeated or parallel delegations apart.
+    """
+    metadata = ensure_config().get("metadata") or {}
+    namespace = metadata.get("langgraph_checkpoint_ns")
+    if not isinstance(namespace, str) or not namespace:
+        return {}
+    nodes = [part.split(":", 1)[0] for part in namespace.split("|") if part]
+    return {"langgraph_nodes": nodes, "langgraph_namespace": namespace}
+
+
+def step_metadata() -> dict[str, Any]:
+    """Return the metadata of a recorded LangChain model or tool call."""
+    return {**METADATA, **graph_location()}
+
+
+_ROLES = {"system": "system", "human": "user", "ai": "assistant", "tool": "tool"}
+_CHAT_ROLES = {"system", "developer", "user", "assistant", "tool"}
+_MEDIA = {"image", "audio", "video", "file"}
+
+
+def call_id(value: Any) -> str | None:
+    """Return a tool call ID, or None when it is missing or blank."""
+    return (str(value).strip() or None) if value is not None else None
+
+
+def _role(message: BaseMessage) -> Any:
+    # Streamed chunks report types such as "AIMessageChunk".
+    kind = message.type.removesuffix("MessageChunk").lower()
+    if kind == "chat":
+        role = getattr(message, "role", None)
+        return role if role in _CHAT_ROLES else "user"
+    return _ROLES.get(kind, "user")
+
+
+def _provider(block: dict[str, Any]) -> ProviderBlock:
+    return ProviderBlock(format=f"langchain.{block.get('type')}", data=json_value(block))
+
+
+def _media(block: dict[str, Any]) -> ContentBlock:
+    url, data = block.get("url") or None, block.get("base64") or None
+    if (url is None) == (data is None):
+        return _provider(block)
+    kind = block["type"]
+    default = "application/octet-stream" if kind == "file" else f"{kind}/*"
+    return MediaBlock(mime_type=block.get("mime_type") or default, url=url, data=data)
+
+
+def _block(block: Any) -> ContentBlock | None:
+    if not isinstance(block, dict):
+        return TextBlock(text=block) if isinstance(block, str) and block else None
+    kind = block.get("type")
+    if kind == "text":
+        return TextBlock(text=str(block["text"])) if block.get("text") else None
+    if kind == "reasoning":
+        return ReasoningBlock(text=str(block.get("reasoning", "")))
+    if kind == "tool_call":
+        return None
+    if kind in _MEDIA:
+        return _media(block)
+    return _provider(block)
+
+
+def _blocks(message: BaseMessage) -> list[ContentBlock]:
+    return [block for raw in message.content_blocks if (block := _block(raw)) is not None]
+
+
+def message(message: BaseMessage) -> Message:
+    """Convert one LangChain message."""
+    if isinstance(message, ToolMessage):
+        blocks = _blocks(message)
+        texts = [block.text for block in blocks if isinstance(block, TextBlock)]
+        output = "".join(texts) if len(texts) == len(blocks) else json_value(message.content)
+        result = ToolResultBlock(
+            output=output,
+            call_id=call_id(message.tool_call_id),
+            is_error=message.status == "error",
+        )
+        return Message(role="tool", content=(result,))
+    content = _blocks(message)
+    if isinstance(message, AIMessage):
+        content += [
+            ToolCallBlock(
+                name=call["name"],
+                arguments=json_value(call["args"]),
+                call_id=call_id(call.get("id")),
+            )
+            for call in message.tool_calls
+        ]
+    return Message(role=_role(message), content=tuple(content))
+
+
+def _tool(tool: Any) -> ToolSpec:
+    try:
+        function = convert_to_openai_tool(tool)["function"]
+    except Exception:
+        name = tool.get("name") or tool.get("type") if isinstance(tool, dict) else None
+        return ToolSpec(name=str(name or type(tool).__name__))
+    parameters = json_value(function.get("parameters") or {})
+    return ToolSpec(
+        name=function["name"],
+        description=function.get("description"),
+        parameters=parameters if isinstance(parameters, dict) else {},
+    )
+
+
+def conversation(
+    messages: Iterable[BaseMessage], tools: Sequence[Any] = (), system: BaseMessage | None = None
+) -> ConversationInput:
+    """Convert a model request: optional system message, messages and tools."""
+    prefix = [system] if system is not None and system.content_blocks else []
+    return ConversationInput(
+        messages=tuple(message(item) for item in [*prefix, *messages]),
+        tools=tuple(_tool(tool) for tool in tools),
+    )
+
+
+def _count(value: Any) -> int:
+    return value if isinstance(value, int) and value >= 0 else 0
+
+
+def _usage(message: AIMessage) -> Usage | None:
+    usage = message.usage_metadata
+    if not usage:
+        return None
+    details = usage.get("input_token_details") or {}
+    cache_read, cache_write = details.get("cache_read"), details.get("cache_creation")
+    raw = usage.get("input_tokens")
+    return Usage(
+        input_tokens=max(0, raw - _count(cache_read) - _count(cache_write))
+        if isinstance(raw, int)
+        else None,
+        output_tokens=usage.get("output_tokens"),
+        cache_read_tokens=cache_read,
+        cache_write_tokens=cache_write,
+    )
+
+
+def output(
+    response: AIMessage | None, generation_info: dict[str, Any] | None = None
+) -> ConversationOutput:
+    """Convert a model response; None becomes an empty assistant message.
+
+    Args:
+        response: The model's message.
+        generation_info: Metadata LangChain merges into the message only after the model
+            returns, such as the OpenAI finish reason.
+    """
+    if response is None:
+        return ConversationOutput(message=Message(role="assistant", content=()))
+    metadata = {**(generation_info or {}), **(response.response_metadata or {})}
+    stop = metadata.get("finish_reason") or metadata.get("stop_reason")
+    return ConversationOutput(
+        message=message(response),
+        usage=_usage(response),
+        stop_reason=stop if isinstance(stop, str) else None,
+    )
+
+
+def model_identity(model: Any) -> tuple[str | None, str | None]:
+    """Return the model's provider and name from its LangSmith parameters."""
+    try:
+        params = model._get_ls_params()
+    except Exception:
+        return None, None
+
+    def text(key: str) -> str | None:
+        value = params.get(key)
+        return value if isinstance(value, str) and value.strip() else None
+
+    return text("ls_provider"), text("ls_model_name")
+
+
+def with_lessons(messages: Sequence[Any], text: str) -> list[Any]:
+    """Return a copy with one user message holding lessons, before an assistant prefill."""
+    temporary = list(messages)
+    last = temporary[-1] if temporary else None
+    prefill = isinstance(last, AIMessage) and not last.tool_calls and bool(last.content)
+    temporary.insert(len(temporary) - 1 if prefill else len(temporary), HumanMessage(content=text))
+    return temporary
+
+
+def llm_call(
+    model: Any,
+    messages: Sequence[BaseMessage],
+    tools: Sequence[Any] = (),
+    system: BaseMessage | None = None,
+) -> LlmCall | None:
+    """Describe a model call, or return None to run it unrecorded.
+
+    Returns None outside a recording, while capture is suppressed (for example inside a
+    call the middleware owns) or when the request cannot be converted.
+    """
+    if not instrumentation.capture_active():
+        return None
+    try:
+        provider, name = model_identity(model)
+        return LlmCall(
+            input=conversation(messages, tools, system),
+            provider=provider,
+            model=name,
+            metadata=step_metadata(),
+        )
+    except Exception as exc:
+        warn_once(
+            "langchain-convert",
+            f"Sovara could not record a LangChain model call. error_type={type(exc).__name__}",
+        )
+        return None
+
+
+def safe_output(
+    response: AIMessage | None, generation_info: dict[str, Any] | None = None
+) -> ConversationOutput:
+    """Convert a model response, recording an empty one if conversion fails."""
+    try:
+        return output(response, generation_info)
+    except Exception as exc:
+        warn_once(
+            "langchain-output",
+            f"Sovara could not record a LangChain model response. error_type={type(exc).__name__}",
+        )
+        return output(None)
+
+
+def raised(exc: BaseException) -> tuple[Ending, tuple[Any, ...]]:
+    """Return the step method and arguments for an exception leaving a call."""
+    if _BUBBLE_UP is not None and isinstance(exc, _BUBBLE_UP):
+        return "cancel", ("Interrupted",)
+    return instrumentation.raised(exc)

sovara_langchain/_middleware.py

@@ -0,0 +1,143 @@
+"""Record LangChain ``create_agent`` model and tool calls, with lessons per model call.
+
+Requires ``langchain>=1.1`` (``pip install "sovara-langchain[agent]"``). Add the middleware
+last, so it records the request other middleware finalized (model, prompt, messages) and each
+attempt of a middleware retry as its own step::
+
+    agent = create_agent(model, tools, middleware=[*other_middleware, SovaraMiddleware()])
+    with client.trace("support"), client.turn(turn_input=question):
+        agent.invoke({"messages": [{"role": "user", "content": question}]})
+
+Outside a recording the middleware passes calls through. Lessons go into one temporary
+user message on the model request only; the agent's messages are never changed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from langchain.agents.middleware import AgentMiddleware, ModelRequest
+from langchain_core.messages import AIMessage, ToolMessage
+from langgraph.types import Command
+
+from sovara import Execution, LlmCall, Step, ToolCall
+from sovara import integration as instrumentation
+from sovara.integration import Ending, json_value
+from sovara_langchain import _messages as convert
+from sovara_langchain._tool_patch import own_tool_call, tool_outcome
+
+__all__ = ["SovaraMiddleware"]
+
+
+def _llm_call(request: ModelRequest) -> LlmCall | None:
+    return convert.llm_call(request.model, request.messages, request.tools, request.system_message)
+
+
+def _with_lessons(request: ModelRequest, step: Step) -> tuple[ModelRequest, Execution | None]:
+    context = step.lesson_context
+    if context is None:
+        return request, None
+    messages = convert.with_lessons(request.messages, context.text)
+    execution = Execution(
+        input=convert.conversation(messages, request.tools, request.system_message),
+        injected_retrieval_id=context.retrieval_id,
+    )
+    return request.override(messages=messages), execution
+
+
+def _model_output(response: Any) -> Any:
+    # Newer langchain versions may wrap it in an ExtendedModelResponse.
+    response = getattr(response, "model_response", response)
+    if not isinstance(response, AIMessage):
+        result = getattr(response, "result", ())
+        response = next((m for m in result if isinstance(m, AIMessage)), None)
+    return convert.safe_output(response)
+
+
+def _tool_call(request: Any) -> ToolCall:
+    call = request.tool_call
+    return ToolCall(
+        name=call["name"],
+        arguments=json_value(call.get("args")),
+        call_id=convert.call_id(call.get("id")),
+        metadata=convert.step_metadata(),
+    )
+
+
+def _tool_result(result: Any) -> tuple[Ending, tuple[Any, ...], dict[str, Any]]:
+    if not isinstance(result, Command):
+        return tool_outcome(result)
+    update = result.update if isinstance(result.update, dict) else {}
+    messages = [m.content for m in update.get("messages", ()) if isinstance(m, ToolMessage)]
+    return "finish", (json_value(messages) if messages else None,), {}
+
+
+class SovaraMiddleware(AgentMiddleware):
+    """Record each model and tool call of a LangChain agent as a Sovara step."""
+
+    def wrap_model_call(self, request: ModelRequest, handler: Callable[[ModelRequest], Any]) -> Any:
+        """Record the model call, adding retrieved lessons to this request only."""
+        call = _llm_call(request)
+        step = instrumentation.begin(call, lessons=True) if call is not None else None
+        if step is None:
+            return handler(request)
+        request, execution = _with_lessons(request, step)
+        try:
+            with step.activate():
+                response = handler(request)
+        except BaseException as exc:
+            instrumentation.report_raised(step, exc, classify=convert.raised, execution=execution)
+            raise
+        instrumentation.report(step, "finish", _model_output(response), execution=execution)
+        return response
+
+    async def awrap_model_call(
+        self, request: ModelRequest, handler: Callable[[ModelRequest], Awaitable[Any]]
+    ) -> Any:
+        """Asynchronous form of wrap_model_call()."""
+        call = _llm_call(request)
+        step = await instrumentation.abegin(call, lessons=True) if call is not None else None
+        if step is None:
+            return await handler(request)
+        request, execution = _with_lessons(request, step)
+        try:
+            with step.activate():
+                response = await handler(request)
+        except BaseException as exc:
+            await instrumentation.areport_raised(
+                step, exc, classify=convert.raised, execution=execution
+            )
+            raise
+        await instrumentation.areport(step, "finish", _model_output(response), execution=execution)
+        return response
+
+    def wrap_tool_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        """Record the tool call; the existing tool patch skips it."""
+        step = instrumentation.begin(_tool_call(request))
+        if step is None:
+            return handler(request)
+        try:
+            with own_tool_call(request.tool_call.get("id")):
+                result = handler(request)
+        except BaseException as exc:
+            instrumentation.report_raised(step, exc, classify=convert.raised)
+            raise
+        ending, args, kwargs = _tool_result(result)
+        instrumentation.report(step, ending, *args, **kwargs)
+        return result
+
+    async def awrap_tool_call(self, request: Any, handler: Callable[[Any], Awaitable[Any]]) -> Any:
+        """Asynchronous form of wrap_tool_call()."""
+        step = await instrumentation.abegin(_tool_call(request))
+        if step is None:
+            return await handler(request)
+        try:
+            with own_tool_call(request.tool_call.get("id")):
+                result = await handler(request)
+        except BaseException as exc:
+            await instrumentation.areport_raised(step, exc, classify=convert.raised)
+            raise
+        ending, args, kwargs = _tool_result(result)
+        await instrumentation.areport(step, ending, *args, **kwargs)
+        return result

sovara_langchain/_tool_patch.py

@@ -0,0 +1,150 @@
+"""Record synchronous and asynchronous LangChain tool execution."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from functools import wraps
+from typing import Any
+
+from sovara import ErrorInfo, ToolCall
+from sovara import integration as instrumentation
+from sovara.integration import Ending, json_value
+from sovara_langchain._log import logger
+from sovara_langchain._messages import graph_location
+
+# Tool call ID recorded by SovaraMiddleware. Only that tool is skipped here; model and
+# HTTP calls inside it are still recorded.
+_owned_tool_call_id: ContextVar[str | None] = ContextVar("owned_tool_call_id", default=None)
+_handled_errors: ContextVar[list[str] | None] = ContextVar("handled_tool_errors", default=None)
+
+
+@contextmanager
+def own_tool_call(tool_call_id: str | None):
+    """Mark a tool call as recorded by the caller, so this patch skips it."""
+    token = _owned_tool_call_id.set(tool_call_id)
+    try:
+        yield
+    finally:
+        _owned_tool_call_id.reset(token)
+
+
+@contextmanager
+def _capture_tool_errors():
+    """Keep handled errors local to this invocation, including across copied contexts."""
+    errors: list[str] = []
+    token = _handled_errors.set(errors)
+    try:
+        yield errors
+    finally:
+        _handled_errors.reset(token)
+
+
+def _skip(tool_call_id: Any) -> bool:
+    if not instrumentation.capture_active():
+        return True
+    return bool(tool_call_id) and str(tool_call_id) == _owned_tool_call_id.get()
+
+
+def _tool_call(tool: Any, tool_input: Any, tool_call_id: Any) -> ToolCall:
+    metadata = json_value(
+        {
+            "tool_class": tool.__class__.__name__,
+            "response_format": getattr(tool, "response_format", None),
+            **graph_location(),
+        }
+    )
+    return ToolCall(
+        name=tool.name,
+        arguments=json_value(tool_input),
+        call_id=(str(tool_call_id).strip() or None) if tool_call_id is not None else None,
+        metadata=metadata if isinstance(metadata, dict) else {},
+    )
+
+
+def tool_outcome(
+    result: Any, *, failed: bool = False
+) -> tuple[Ending, tuple[Any, ...], dict[str, Any]]:
+    """Return the step method and arguments for a tool result, unwrapping ToolMessage."""
+    is_message = getattr(result, "tool_call_id", None) is not None and hasattr(result, "content")
+    content = result.content if is_message else result
+    output = json_value(content)
+    if failed or (is_message and getattr(result, "status", None) == "error"):
+        message = content if isinstance(content, str) else None
+        return "fail", (ErrorInfo(type="ToolError", message=message),), {"output": output}
+    return "finish", (output,), {}
+
+
+def langchain_patch():
+    """Wrap LangChain tool run/arun methods once, if langchain_core is installed.
+
+    Capture requires a recording and enabled instrumentation. Tool
+    input and results pass through unchanged; exceptions are reported before being
+    re-raised. Methods are replaced globally on BaseTool.
+    """
+    try:
+        from langchain_core.tools import base
+        from langchain_core.tools.base import BaseTool
+    except ImportError:
+        logger.info("langchain_core not installed, skipping LangChain tool patches")
+        return
+
+    if getattr(BaseTool.run, "__sovara_langchain_patched__", False):
+        return
+
+    original_run = BaseTool.run
+    original_arun = BaseTool.arun
+    original_format_output = base._format_output
+
+    @wraps(original_format_output)
+    def format_output(content, artifact, tool_call_id, name, status):
+        # LangChain drops the status when an ID-less call returns plain content.
+        errors = _handled_errors.get()
+        if errors is not None and status == "error":
+            errors.append(status)
+        return original_format_output(content, artifact, tool_call_id, name, status)
+
+    @wraps(original_run)
+    def patched_run(self, tool_input, *args, tool_call_id=None, **kwargs):
+        def run():
+            return original_run(self, tool_input, *args, tool_call_id=tool_call_id, **kwargs)
+
+        with _capture_tool_errors() as errors:
+            if _skip(tool_call_id):
+                with own_tool_call(None):
+                    return run()
+            step = instrumentation.begin(_tool_call(self, tool_input, tool_call_id))
+            try:
+                result = run()
+            except BaseException as exc:
+                instrumentation.report_raised(step, exc)
+                raise
+            ending, report_args, report_kwargs = tool_outcome(result, failed=bool(errors))
+            instrumentation.report(step, ending, *report_args, **report_kwargs)
+            return result
+
+    @wraps(original_arun)
+    async def patched_arun(self, tool_input, *args, tool_call_id=None, **kwargs):
+        async def arun():
+            return await original_arun(self, tool_input, *args, tool_call_id=tool_call_id, **kwargs)
+
+        with _capture_tool_errors() as errors:
+            if _skip(tool_call_id):
+                with own_tool_call(None):
+                    return await arun()
+            step = await instrumentation.abegin(_tool_call(self, tool_input, tool_call_id))
+            try:
+                result = await arun()
+            except BaseException as exc:
+                await instrumentation.areport_raised(step, exc)
+                raise
+            ending, report_args, report_kwargs = tool_outcome(result, failed=bool(errors))
+            await instrumentation.areport(step, ending, *report_args, **report_kwargs)
+            return result
+
+    patched_run.__sovara_langchain_patched__ = True  # pyright: ignore[reportAttributeAccessIssue]
+    patched_arun.__sovara_langchain_patched__ = True  # pyright: ignore[reportAttributeAccessIssue]
+    base._format_output = format_output
+    BaseTool.run = patched_run
+    BaseTool.arun = patched_arun
+    logger.info("langchain_core tool patch applied")

sovara_langchain-0.1.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: sovara-langchain
+Version: 0.1.0
+Summary: Sovara recording and lessons for LangChain and LangGraph
+License-Expression: MIT
+Project-URL: Documentation, https://docs.sovara-labs.com/integrations/langchain
+Project-URL: Repository, https://github.com/SovaraLabs/sovara-langchain/tree/main/python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sovara<0.11,>=0.10
+Requires-Dist: langchain-core<2,>=1
+Provides-Extra: agent
+Requires-Dist: langchain<2,>=1.1; extra == "agent"
+Dynamic: license-file
+
+# Sovara for LangChain (Python)
+
+Record LangChain and LangGraph model and tool calls in Sovara, and add relevant lessons to each
+model request.
+
+```bash
+uv add "sovara-langchain[agent]"
+# or: pip install "sovara-langchain[agent]"
+```
+
+Omit `[agent]` if you only use `wrap_chat_model`.
+
+## Use
+
+Inside a Sovara trace, pick one per model:
+
+```python
+import sovara_langchain
+from sovara_langchain import SovaraMiddleware, wrap_chat_model
+
+# create_agent: add the middleware last. It records model and tool calls.
+agent = create_agent(model, tools, middleware=[*other_middleware, SovaraMiddleware()])
+
+# Anything else (LangGraph nodes, create_react_agent, with_structured_output): wrap the model,
+# and call instrument_tools() once at startup to record tool calls too.
+sovara_langchain.instrument_tools()
+model = wrap_chat_model(ChatOpenAI(model="gpt-5.4")).bind_tools(tools)
+```
+
+- `instrument_tools()` also records tools called directly, without a model-generated tool call.
+- Lessons are one temporary user message at the end of the request. The agent's messages and
+  graph state are never changed.
+- Outside a trace, calls pass through unrecorded. If Sovara is unavailable, calls still run.
+- Last in the list, the middleware records the model, prompt and messages that other middleware
+  settled on, and each retry by other middleware as its own step.
+- Don't use the middleware and the wrapper for the same model.
+- Model calls are recorded as conversations, so **Rerun** is not available for them.
+
+Requires `langchain-core` 1.x (`langchain` 1.1+ for the middleware).
+
+## License
+
+MIT.

sovara_langchain-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+sovara_langchain/__init__.py,sha256=RCdDxsjfea2DTjVp1FzYWLnHMV85ZTeLdTjj7EMFj6g,1764
+sovara_langchain/_chat_model.py,sha256=krg5ZLgQviFhFl9KEgtgPdZMagac_TB9x4gBPdW5gMo,14662
+sovara_langchain/_log.py,sha256=stsnhIRDcDbRHZ8Cvij4qsYTI10Nyy8wd-05GEvCuyY,505
+sovara_langchain/_messages.py,sha256=jYz9lUQA6tgisUTspK2qaHWVO9mCSB73BDAb8xdNmDA,10103
+sovara_langchain/_middleware.py,sha256=HsEVSCYTmEXC43izfdJkJ5xLXSzXTD3rrOOWESeMWoQ,6110
+sovara_langchain/_tool_patch.py,sha256=lAZn3XJucCS6BsYjY8Jenp-Oo1ro3iKwQJieCaZgplk,5929
+sovara_langchain-0.1.0.dist-info/licenses/LICENSE,sha256=pHqKd1w5Do29Q1QUMye-4Tz6olJxRgwzNYqcjjfN524,1068
+sovara_langchain-0.1.0.dist-info/METADATA,sha256=Lpb7p5MuLlF7zQoBX4KHqi4zcpZwxns8SGED3R0fJFk,2161
+sovara_langchain-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sovara_langchain-0.1.0.dist-info/top_level.txt,sha256=9lzuHbox-IktVl9Gay63na8AGHxGlDgNb0GgAXVmuVY,17
+sovara_langchain-0.1.0.dist-info/RECORD,,

sovara_langchain-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sovara_langchain-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sovara Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sovara_langchain-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sovara_langchain