somm-langchain 0.6.1__tar.gz

somm_langchain-0.6.1/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+
+# Environments
+.venv/
+.env
+.env.*
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local Claude session id log (per-machine, not source of truth)
+sessions.txt
+
+# Local data (never commit telemetry)
+.somm/
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# Author-local notes not for open source
+notes/
+.claude/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+
+# Archived internal design/process docs (see docs/BLUEPRINT.md for the public design doc)

somm_langchain-0.6.1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: somm-langchain
+Version: 0.6.1
+Summary: LangChain BaseChatModel adapter for somm — lets LangChain/LangGraph/deepagents apps use somm as their LLM substrate
+Project-URL: Homepage, https://github.com/lavallee/somm
+Project-URL: Repository, https://github.com/lavallee/somm
+Project-URL: Issues, https://github.com/lavallee/somm/issues
+Project-URL: Changelog, https://github.com/lavallee/somm/blob/main/CHANGELOG.md
+Author: Marc Lavallee
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: somm-core==0.6.1
+Requires-Dist: somm==0.6.1
+Description-Content-Type: text/markdown
+
+# somm-langchain
+
+LangChain `BaseChatModel` adapter for [`somm`](https://github.com/lavallee/somm).
+
+Lets LangChain / LangGraph / `deepagents` apps use somm as their LLM substrate — telemetry, routing, cost tracking, provider fallback, sommelier model memory — all without changing the agent-framework call sites.
+
+```python
+import somm
+from somm_langchain import SommChatModel
+
+llm = somm.llm(project="my_agent")
+chat = SommChatModel(somm_llm=llm, workload="agent_thinking")
+
+from deepagents import create_deep_agent
+agent = create_deep_agent(model=chat, tools=[...])
+```
+
+`SommChatModel` supports `bind_tools()` and routes tool-using calls through somm's neutral tool-calling shape (see [docs/tool-calling.md](https://github.com/lavallee/somm/blob/main/docs/tool-calling.md)). The adapter is thin: message translation in, somm.llm().generate() through, ChatGeneration out.
+
+Built for agent orchestrators that run on `deepagents` and similar LangChain-based stacks, which mandate a tool-calling `BaseChatModel`.

somm_langchain-0.6.1/README.md

@@ -0,0 +1,20 @@
+# somm-langchain
+
+LangChain `BaseChatModel` adapter for [`somm`](https://github.com/lavallee/somm).
+
+Lets LangChain / LangGraph / `deepagents` apps use somm as their LLM substrate — telemetry, routing, cost tracking, provider fallback, sommelier model memory — all without changing the agent-framework call sites.
+
+```python
+import somm
+from somm_langchain import SommChatModel
+
+llm = somm.llm(project="my_agent")
+chat = SommChatModel(somm_llm=llm, workload="agent_thinking")
+
+from deepagents import create_deep_agent
+agent = create_deep_agent(model=chat, tools=[...])
+```
+
+`SommChatModel` supports `bind_tools()` and routes tool-using calls through somm's neutral tool-calling shape (see [docs/tool-calling.md](https://github.com/lavallee/somm/blob/main/docs/tool-calling.md)). The adapter is thin: message translation in, somm.llm().generate() through, ChatGeneration out.
+
+Built for agent orchestrators that run on `deepagents` and similar LangChain-based stacks, which mandate a tool-calling `BaseChatModel`.

somm_langchain-0.6.1/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "somm-langchain"
+version = "0.6.1"
+description = "LangChain BaseChatModel adapter for somm — lets LangChain/LangGraph/deepagents apps use somm as their LLM substrate"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+readme = "README.md"
+authors = [{ name = "Marc Lavallee" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "somm-core==0.6.1",
+    "somm==0.6.1",
+    "langchain-core>=0.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/lavallee/somm"
+Repository = "https://github.com/lavallee/somm"
+Issues = "https://github.com/lavallee/somm/issues"
+Changelog = "https://github.com/lavallee/somm/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/somm_langchain"]

somm_langchain-0.6.1/src/somm_langchain/__init__.py

@@ -0,0 +1,5 @@
+"""somm-langchain — LangChain BaseChatModel adapter for somm."""
+
+from somm_langchain.chat_model import SommChatModel
+
+__all__ = ["SommChatModel"]

somm_langchain-0.6.1/src/somm_langchain/chat_model.py

@@ -0,0 +1,295 @@
+"""SommChatModel — LangChain BaseChatModel implementation that routes through somm.
+
+Lets LangChain / LangGraph / deepagents apps treat somm as their LLM substrate.
+Thin adapter: message translation in, somm.llm().generate() through, ChatGeneration out.
+
+Tool-calling routes through somm's neutral tool shape (see docs/tool-calling.md),
+which currently lands on Anthropic + OpenAI-compat providers. Gemini/Ollama follow.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, cast
+
+from langchain_core.callbacks.manager import CallbackManagerForLLMRun
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import (
+    AIMessage,
+    BaseMessage,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+)
+from langchain_core.outputs import ChatGeneration, ChatResult
+from langchain_core.runnables import Runnable
+from langchain_core.tools import BaseTool
+from langchain_core.utils.function_calling import convert_to_openai_tool
+from pydantic import ConfigDict
+from somm.client import SommLLM
+from somm_core import Outcome
+
+
+class SommChatModel(BaseChatModel):
+    """LangChain chat model that delegates to a `SommLLM`.
+
+    Usage:
+        ```python
+        import somm
+        from somm_langchain import SommChatModel
+
+        llm = somm.llm(project="my_agent")
+        chat = SommChatModel(somm_llm=llm, workload="agent_thinking")
+        ```
+
+    Pass to `deepagents.create_deep_agent(model=chat, ...)` or any LangChain
+    runnable expecting a chat model. `bind_tools()` works — tool schemas are
+    converted to somm-neutral form and routed via `SommLLM.generate(tools=...)`.
+
+    All telemetry, provider routing, cost tracking, and fallback semantics are
+    somm's — this adapter adds no behavior of its own.
+    """
+
+    # Allow non-pydantic types (SommLLM) as fields.
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    somm_llm: SommLLM
+    workload: str = "agent"
+    # Pin a specific (model, provider) when set; otherwise somm's router picks.
+    somm_model: str | None = None
+    somm_provider: str | None = None
+    temperature: float = 0.2
+    max_tokens: int = 4096
+
+    # Whether SommLLM.generate() failures (outcome != OK) should raise a
+    # RuntimeError or return as an AIMessage with the error in
+    # response_metadata. Default: raise — matches LangChain convention so
+    # retry / circuit-breaker middleware in the agent stack engages.
+    raise_on_failure: bool = True
+
+    # ClassVar so pydantic doesn't treat it as a field
+    LC_ROLE_BLOCK_KEYS: ClassVar[set[str]] = {"text", "tool_use", "tool_result", "image"}
+
+    # ------------------------------------------------------------------
+    # LangChain BaseChatModel interface
+
+    @property
+    def _llm_type(self) -> str:
+        return "somm"
+
+    def _generate(
+        self,
+        messages: list[BaseMessage],
+        stop: list[str] | None = None,
+        run_manager: CallbackManagerForLLMRun | None = None,
+        **kwargs: Any,
+    ) -> ChatResult:
+        system, somm_messages = self._translate_messages(messages)
+
+        # Tools come from bind_tools() via Runnable.bind kwargs. They were
+        # converted to OpenAI shape there; unwrap to somm-neutral here.
+        raw_tools = kwargs.get("tools") or []
+        somm_tools = [self._unwrap_oai_tool(t) for t in raw_tools]
+
+        tool_choice = kwargs.get("tool_choice")
+        somm_tool_choice = self._translate_tool_choice_lc_to_somm(tool_choice)
+
+        result = self.somm_llm.generate(
+            # `prompt` is required by somm's signature but ignored when
+            # `messages` is set — we pass an empty string as a marker.
+            prompt="",
+            messages=somm_messages or None,
+            system=system,
+            workload=self.workload,
+            model=kwargs.get("model") or self.somm_model,
+            provider=self.somm_provider,
+            temperature=kwargs.get("temperature", self.temperature),
+            max_tokens=kwargs.get("max_tokens", self.max_tokens),
+            tools=somm_tools if somm_tools else None,
+            tool_choice=somm_tool_choice,
+        )
+
+        if result.outcome != Outcome.OK and self.raise_on_failure:
+            raise RuntimeError(
+                f"somm call failed: workload={self.workload} "
+                f"outcome={result.outcome.value} kind={result.error_kind} — "
+                f"{result.error_detail}"
+            )
+
+        lc_tool_calls = [
+            {"name": tc.name, "args": tc.arguments, "id": tc.id}
+            for tc in result.tool_calls
+        ]
+        # Preserve reasoning_content (DeepSeek v4 thinking models) in
+        # additional_kwargs so it survives in LangGraph's message history and
+        # can be echoed back on the next turn (_translate_ai_message). DeepSeek
+        # 400s on the 2nd turn of a tool-calling loop without it.
+        additional_kwargs: dict[str, Any] = {}
+        if result.reasoning_content:
+            additional_kwargs["reasoning_content"] = result.reasoning_content
+        ai_message = AIMessage(
+            content=result.text,
+            tool_calls=lc_tool_calls,
+            additional_kwargs=additional_kwargs,
+            response_metadata={
+                "provider": result.provider,
+                "model": result.model,
+                "tokens_in": result.tokens_in,
+                "tokens_out": result.tokens_out,
+                "latency_ms": result.latency_ms,
+                "cost_usd": result.cost_usd,
+                "stop_reason": result.stop_reason,
+                "outcome": result.outcome.value,
+                "call_id": result.call_id,
+            },
+            usage_metadata={
+                "input_tokens": result.tokens_in,
+                "output_tokens": result.tokens_out,
+                "total_tokens": result.tokens_in + result.tokens_out,
+            },
+        )
+        return ChatResult(generations=[ChatGeneration(message=ai_message)])
+
+    def bind_tools(
+        self,
+        tools: list[dict[str, Any] | type | BaseTool],
+        *,
+        tool_choice: str | dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Runnable:
+        """Bind tools to this model. Returns a Runnable that injects them on call.
+
+        Tools are converted to OpenAI shape (the most common cross-LangChain
+        format) here; `_generate` unwraps them to somm-neutral before calling
+        SommLLM. This keeps interop wide: any LangChain-shaped tool spec works.
+        """
+        formatted_tools = [convert_to_openai_tool(t) for t in tools]
+        if tool_choice is not None:
+            kwargs["tool_choice"] = tool_choice
+        return self.bind(tools=formatted_tools, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Translation helpers — LangChain ⇄ somm-neutral
+
+    def _translate_messages(
+        self, messages: list[BaseMessage]
+    ) -> tuple[str, list[dict[str, Any]]]:
+        """LangChain messages → (system, somm-neutral messages).
+
+        somm takes system separately, so SystemMessage(s) are extracted and
+        joined into the `system` field. Remaining messages go into the
+        Anthropic-shaped neutral format. The OpenAI-compat provider adapter
+        translates the neutral shape back into OpenAI's tool_calls + role:tool
+        message form at the provider layer.
+        """
+        system_parts: list[str] = []
+        out: list[dict[str, Any]] = []
+        for m in messages:
+            if isinstance(m, SystemMessage):
+                system_parts.append(self._stringify_content(m.content))
+                continue
+            if isinstance(m, HumanMessage):
+                out.append({"role": "user", "content": m.content})
+                continue
+            if isinstance(m, AIMessage):
+                out.append(self._translate_ai_message(m))
+                continue
+            if isinstance(m, ToolMessage):
+                out.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "tool_result",
+                                "tool_use_id": m.tool_call_id,
+                                "content": self._stringify_content(m.content),
+                            }
+                        ],
+                    }
+                )
+                continue
+            # Unknown message subclass — best-effort string forward
+            out.append({"role": "user", "content": self._stringify_content(m.content)})
+        return "\n\n".join(p for p in system_parts if p), out
+
+    def _translate_ai_message(self, m: AIMessage) -> dict[str, Any]:
+        """AIMessage → somm-neutral assistant message with optional tool_use blocks."""
+        blocks: list[dict[str, Any]] = []
+        text = self._stringify_content(m.content)
+        if text:
+            blocks.append({"type": "text", "text": text})
+        for tc in m.tool_calls or []:
+            blocks.append(
+                {
+                    "type": "tool_use",
+                    "id": tc.get("id") or "",
+                    "name": tc.get("name") or "",
+                    "input": tc.get("args") or {},
+                }
+            )
+        # Echo reasoning_content (DeepSeek v4 thinking models) back on the
+        # assistant turn — required or DeepSeek 400s on the next turn. Carried
+        # as a top-level key the OpenAI-compat provider emits and the Anthropic
+        # provider strips. Only matters on tool-calling turns (which have
+        # tool_use blocks → list content, so collapse-to-string never drops it).
+        reasoning = (m.additional_kwargs or {}).get("reasoning_content")
+
+        # Collapse to plain-string content when the only block is text.
+        if len(blocks) == 1 and blocks[0].get("type") == "text" and not reasoning:
+            return {"role": "assistant", "content": cast(str, blocks[0]["text"])}
+        msg: dict[str, Any] = {"role": "assistant", "content": blocks}
+        if reasoning:
+            msg["reasoning_content"] = reasoning
+        return msg
+
+    @staticmethod
+    def _stringify_content(content: Any) -> str:
+        if isinstance(content, str):
+            return content
+        if isinstance(content, list):
+            parts: list[str] = []
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    parts.append(block.get("text", ""))
+                elif isinstance(block, str):
+                    parts.append(block)
+            return "".join(parts)
+        return str(content) if content is not None else ""
+
+    @staticmethod
+    def _unwrap_oai_tool(t: dict[str, Any]) -> dict[str, Any]:
+        """OpenAI `{type:function, function:{...}}` → somm-neutral
+        `{name, description, parameters}`. Pass through if already neutral."""
+        if t.get("type") == "function" and isinstance(t.get("function"), dict):
+            return dict(t["function"])
+        return t
+
+    @staticmethod
+    def _translate_tool_choice_lc_to_somm(
+        choice: str | dict[str, Any] | None,
+    ) -> str | dict[str, Any] | None:
+        """LangChain tool_choice (per bind_tools convention) → somm-neutral.
+
+        LangChain accepts: None, "auto", "any", "none", "required" (OpenAI
+        alias for any), a tool name string, or a dict like
+        `{"type":"function","function":{"name":"X"}}` / `{"type":"tool","name":"X"}`.
+        """
+        if choice is None:
+            return None
+        if isinstance(choice, str):
+            if choice in ("auto", "any", "none"):
+                return choice
+            if choice == "required":
+                return "any"  # somm uses "any" for "must call SOME tool"
+            # Anything else: assume it's a specific tool name
+            return {"type": "tool", "name": choice}
+        if isinstance(choice, dict):
+            # Already somm-neutral?
+            if choice.get("type") == "tool" and "name" in choice:
+                return choice
+            # OpenAI-shaped — extract the function name
+            if choice.get("type") == "function":
+                fn = choice.get("function") or {}
+                name = fn.get("name")
+                if name:
+                    return {"type": "tool", "name": name}
+        return choice

somm_langchain-0.6.1/tests/test_chat_model.py

@@ -0,0 +1,367 @@
+"""Tests for SommChatModel — LangChain ⇄ somm translation, bind_tools, error path."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+from langchain_core.tools import tool
+from somm.client import SommLLM
+from somm.providers.base import ProviderHealth, SommResponse
+from somm.providers.base import ToolCall as ProviderToolCall
+from somm_core.config import Config
+from somm_langchain import SommChatModel
+
+# ---------------------------------------------------------------------------
+# Recording fake provider — captures every SommRequest it sees
+
+
+class _RecordingProvider:
+    name = "recorder"
+
+    def __init__(
+        self,
+        text: str = "",
+        tool_calls: list[ProviderToolCall] | None = None,
+        stop_reason: str = "end_turn",
+    ):
+        self._text = text
+        self._tool_calls = tool_calls or []
+        self._stop_reason = stop_reason
+        self.received: list = []
+
+    def generate(self, request):
+        self.received.append(request)
+        return SommResponse(
+            text=self._text,
+            model=request.model or "fake-model",
+            tokens_in=3,
+            tokens_out=2,
+            latency_ms=5,
+            tool_calls=self._tool_calls,
+            stop_reason=self._stop_reason,
+        )
+
+    def stream(self, request):  # pragma: no cover
+        yield
+
+    def health(self):
+        return ProviderHealth(available=True)
+
+    def models(self):
+        return []
+
+    def estimate_tokens(self, text, model):
+        return 1
+
+
+def _tmp_llm(tmp_path: Path, provider: _RecordingProvider) -> SommLLM:
+    cfg = Config()
+    cfg.project = "somm-lc-test"
+    cfg.db_dir = tmp_path / ".somm"
+    cfg.spool_dir = cfg.db_dir / "spool"
+    return SommLLM(config=cfg, providers=[provider], on_error=lambda _e: None)
+
+
+# ---------------------------------------------------------------------------
+# Message translation
+
+
+def test_system_message_extracted_to_system_field(tmp_path):
+    p = _RecordingProvider(text="ok")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        chat.invoke([SystemMessage("be brief"), HumanMessage("hi")])
+        req = p.received[0]
+        assert req.system == "be brief"
+        assert req.messages == [{"role": "user", "content": "hi"}]
+    finally:
+        llm.close()
+
+
+def test_multiple_system_messages_concatenate(tmp_path):
+    p = _RecordingProvider(text="ok")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        chat.invoke([SystemMessage("rule one"), SystemMessage("rule two"), HumanMessage("hi")])
+        assert p.received[0].system == "rule one\n\nrule two"
+    finally:
+        llm.close()
+
+
+def test_ai_message_with_tool_calls_becomes_tool_use_blocks(tmp_path):
+    p = _RecordingProvider(text="next")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        chat.invoke(
+            [
+                HumanMessage("weather?"),
+                AIMessage(
+                    content="checking",
+                    tool_calls=[{"name": "get_weather", "args": {"location": "SF"}, "id": "tu_01"}],
+                ),
+                ToolMessage(content="62F sunny", tool_call_id="tu_01"),
+            ]
+        )
+        msgs = p.received[0].messages
+        # User text
+        assert msgs[0] == {"role": "user", "content": "weather?"}
+        # Assistant with text + tool_use blocks (mixed → list form)
+        assistant_blocks = msgs[1]["content"]
+        assert msgs[1]["role"] == "assistant"
+        assert {"type": "text", "text": "checking"} in assistant_blocks
+        tool_use_block = next(b for b in assistant_blocks if b.get("type") == "tool_use")
+        assert tool_use_block == {
+            "type": "tool_use",
+            "id": "tu_01",
+            "name": "get_weather",
+            "input": {"location": "SF"},
+        }
+        # Tool result becomes user message with tool_result block
+        assert msgs[2] == {
+            "role": "user",
+            "content": [
+                {"type": "tool_result", "tool_use_id": "tu_01", "content": "62F sunny"}
+            ],
+        }
+    finally:
+        llm.close()
+
+
+def test_ai_message_text_only_collapses_to_string(tmp_path):
+    """Text-only assistant turns use plain-string content (interoperable shape)."""
+    p = _RecordingProvider(text="ok")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        chat.invoke([HumanMessage("hi"), AIMessage(content="hello there")])
+        msgs = p.received[0].messages
+        assert msgs[1] == {"role": "assistant", "content": "hello there"}
+    finally:
+        llm.close()
+
+
+def test_ai_message_tool_calls_only_no_content(tmp_path):
+    """Assistant with only tool_calls (no text) — blocks list contains only tool_use."""
+    p = _RecordingProvider(text="ok")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        chat.invoke(
+            [
+                HumanMessage("x"),
+                AIMessage(
+                    content="",
+                    tool_calls=[{"name": "f", "args": {"a": 1}, "id": "tu_2"}],
+                ),
+                ToolMessage(content="r", tool_call_id="tu_2"),
+            ]
+        )
+        msgs = p.received[0].messages
+        assert msgs[1]["role"] == "assistant"
+        assert msgs[1]["content"] == [
+            {"type": "tool_use", "id": "tu_2", "name": "f", "input": {"a": 1}}
+        ]
+    finally:
+        llm.close()
+
+
+# ---------------------------------------------------------------------------
+# bind_tools — LangChain tools → somm-neutral; tool_choice routes correctly
+
+
+@tool
+def get_weather(location: str) -> str:
+    """Get the current weather for a location."""
+    return f"Sunny in {location}"
+
+
+def test_bind_tools_routes_through_to_somm_neutral_shape(tmp_path):
+    p = _RecordingProvider(text="ok")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        bound = chat.bind_tools([get_weather])
+        bound.invoke([HumanMessage("weather?")])
+
+        sent_tools = p.received[0].tools
+        assert len(sent_tools) == 1
+        # Neutral shape (post-unwrap), NOT OpenAI's {type:function,...}
+        sent = sent_tools[0]
+        assert sent["name"] == "get_weather"
+        assert "parameters" in sent
+        assert "type" not in sent  # would be present if OpenAI wrapping leaked
+    finally:
+        llm.close()
+
+
+def test_bind_tools_with_specific_tool_choice(tmp_path):
+    p = _RecordingProvider(text="ok")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        bound = chat.bind_tools([get_weather], tool_choice="get_weather")
+        bound.invoke([HumanMessage("weather?")])
+        assert p.received[0].tool_choice == {"type": "tool", "name": "get_weather"}
+    finally:
+        llm.close()
+
+
+def test_bind_tools_with_required(tmp_path):
+    """OpenAI alias 'required' maps to somm 'any'."""
+    p = _RecordingProvider(text="ok")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        bound = chat.bind_tools([get_weather], tool_choice="required")
+        bound.invoke([HumanMessage("weather?")])
+        assert p.received[0].tool_choice == "any"
+    finally:
+        llm.close()
+
+
+# ---------------------------------------------------------------------------
+# Response translation — SommResult → AIMessage
+
+
+def test_response_with_tool_calls_returns_aimessage_with_tool_calls(tmp_path):
+    tool_calls = [ProviderToolCall(id="tu_5", name="get_weather", arguments={"location": "NYC"})]
+    p = _RecordingProvider(text="checking", tool_calls=tool_calls, stop_reason="tool_use")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        result = chat.invoke([HumanMessage("weather?")])
+        assert isinstance(result, AIMessage)
+        assert result.content == "checking"
+        assert len(result.tool_calls) == 1
+        call = result.tool_calls[0]
+        assert call["id"] == "tu_5"
+        assert call["name"] == "get_weather"
+        assert call["args"] == {"location": "NYC"}
+        # Metadata exposes somm provenance
+        assert result.response_metadata["provider"] == "recorder"
+        assert result.response_metadata["stop_reason"] == "tool_use"
+        assert result.usage_metadata["input_tokens"] == 3
+        assert result.usage_metadata["output_tokens"] == 2
+    finally:
+        llm.close()
+
+
+def test_text_only_response_returns_aimessage_with_text(tmp_path):
+    p = _RecordingProvider(text="hello there")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        result = chat.invoke([HumanMessage("hi")])
+        assert result.content == "hello there"
+        assert result.tool_calls == []
+    finally:
+        llm.close()
+
+
+# ---------------------------------------------------------------------------
+# Error semantics
+
+
+class _FailingProvider(_RecordingProvider):
+    name = "broken"
+
+    def generate(self, request):
+        self.received.append(request)
+        from somm.errors import SommTransientError
+
+        raise SommTransientError("upstream down", cooldown_s=3600)
+
+
+def test_raise_on_failure_true_raises(tmp_path):
+    p = _FailingProvider()
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        with pytest.raises(RuntimeError, match="somm call failed"):
+            chat.invoke([HumanMessage("hi")])
+    finally:
+        llm.close()
+
+
+def test_raise_on_failure_false_returns_error_in_metadata(tmp_path):
+    p = _FailingProvider()
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t", raise_on_failure=False)
+        result = chat.invoke([HumanMessage("hi")])
+        # outcome is not OK; we still return a message rather than raising
+        assert result.response_metadata["outcome"] != "ok"
+        assert result.content == ""
+    finally:
+        llm.close()
+
+
+def test_model_and_provider_pinning(tmp_path):
+    """somm_model + somm_provider on the adapter pin the underlying SommLLM call."""
+    p = _RecordingProvider(text="ok")
+    p.name = "pinprovider"
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(
+            somm_llm=llm, workload="t",
+            somm_model="my-model-id", somm_provider="pinprovider",
+        )
+        chat.invoke([HumanMessage("hi")])
+        req = p.received[0]
+        assert req.model == "my-model-id"
+    finally:
+        llm.close()
+
+
+# ---------------------------------------------------------------------------
+# reasoning_content round-trip (DeepSeek v4 thinking models)
+
+
+def test_reasoning_content_surfaced_to_aimessage(tmp_path):
+    """A provider response with reasoning_content lands in AIMessage.additional_kwargs."""
+    p = _RecordingProvider(text="answer")
+    # SommResponse carries reasoning_content; RecordingProvider builds it,
+    # so set it via a subclass-free monkey: wrap generate.
+    orig = p.generate
+    def gen(req):
+        r = orig(req)
+        r.reasoning_content = "let me think... 2+2=4"
+        return r
+    p.generate = gen
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        result = chat.invoke([HumanMessage("2+2?")])
+        assert result.additional_kwargs.get("reasoning_content") == "let me think... 2+2=4"
+    finally:
+        llm.close()
+
+
+def test_reasoning_content_echoed_on_assistant_turn(tmp_path):
+    """An AIMessage carrying reasoning_content (with tool_calls) re-serializes it
+    onto the somm-neutral assistant message so the provider can echo it."""
+    p = _RecordingProvider(text="ok")
+    llm = _tmp_llm(tmp_path, p)
+    try:
+        chat = SommChatModel(somm_llm=llm, workload="t")
+        prior = AIMessage(
+            content="checking",
+            tool_calls=[{"name": "get_weather", "args": {"location": "SF"}, "id": "tu_1"}],
+            additional_kwargs={"reasoning_content": "I should call get_weather"},
+        )
+        chat.invoke([
+            HumanMessage("weather?"),
+            prior,
+            ToolMessage(content="62F", tool_call_id="tu_1"),
+        ])
+        msgs = p.received[0].messages
+        assistant = msgs[1]
+        assert assistant["role"] == "assistant"
+        assert assistant.get("reasoning_content") == "I should call get_weather"
+    finally:
+        llm.close()