sovara-langchain 0.1.0__tar.gz

sovara_langchain-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,43 @@
+# 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/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sovara-langchain"
+version = "0.1.0"
+description = "Sovara recording and lessons for LangChain and LangGraph"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "sovara>=0.10,<0.11",
+    "langchain-core>=1,<2",
+]
+
+[project.optional-dependencies]
+# SovaraMiddleware for create_agent.
+agent = ["langchain>=1.1,<2"]
+
+[project.urls]
+Documentation = "https://docs.sovara-labs.com/integrations/langchain"
+Repository = "https://github.com/SovaraLabs/sovara-langchain/tree/main/python"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sovara_langchain*"]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff==0.17.2",
+    "httpx",
+    "langchain>=1.1,<2",
+    "langchain-anthropic",
+    "langchain-openai",
+    "langgraph",
+    # Newer releases reject the httpx client the provider tests inject.
+    "anthropic==0.88.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E4", "E7", "E9", "F", "I", "UP", "B",
+    "D100", "D101", "D102", "D103", "D104", "D106", "D107",
+    "D200", "D205", "D400", "D401", "D419",
+    "ERA001", "PGH004", "RUF100",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D1"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# End-to-end tests need a running Sovara test server; run them with `-m e2e`.
+addopts = "-m 'not e2e'"
+markers = ["e2e: runs against a real Sovara exec server (see tests/e2e/support.py)"]
+
+[tool.ruff.lint.isort]
+# Sovara's own packages sort together, as in the sovara repository.
+known-first-party = ["sovara", "sovara_common", "sovara_langchain", "tests"]

sovara_langchain-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sovara_langchain-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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)