langchain-failover 0.1.0__tar.gz

langchain_failover-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.env

langchain_failover-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Initial release.
+- `FailoverChatModel`: primary/secondary failover with stateful recovery.
+- Connection-aware failover that walks the exception cause/context chain.
+- `bind_tools` preserved across failover (binds both legs).
+- Mid-stream safety: only fails over before the first streamed token.
+- `create_failover_llm` convenience constructor with `/models` auto-discovery.
+- `extract_token_metrics` helper for OpenAI-compatible and Ollama metadata.

langchain_failover-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinay Vobbilichetty
+
+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.

langchain_failover-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: langchain-failover
+Version: 0.1.0
+Summary: Primary/secondary failover wrapper for LangChain chat models, with tool-calling preserved across failover.
+Project-URL: Homepage, https://github.com/vinayvobbili/langchain-failover
+Project-URL: Repository, https://github.com/vinayvobbili/langchain-failover
+Project-URL: Issues, https://github.com/vinayvobbili/langchain-failover/issues
+Author-email: Vinay Vobbilichetty <vinayvobbilichetty11@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Vinay Vobbilichetty
+        
+        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.
+License-File: LICENSE
+Keywords: chat-model,failover,fallback,high-availability,langchain,llm,resilience
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: langchain-core>=0.2
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: langchain-openai>=0.1; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: langchain-openai>=0.1; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# langchain-failover
+
+A tiny, dependency-light **primary/secondary failover wrapper** for LangChain chat
+models. Point it at two chat models; it serves from the primary, transparently
+falls back to the secondary on connection errors, and switches back the moment the
+primary recovers — **and tool-calling keeps working across the failover.**
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain_failover import FailoverChatModel
+
+primary = ChatOpenAI(base_url="http://gpu-box:8001/v1", api_key="x", model="local")
+backup  = ChatOpenAI(base_url="http://cpu-box:8002/v1", api_key="x", model="local")
+
+llm = FailoverChatModel(primary=primary, secondary=backup)
+
+llm.invoke("Summarise this incident…")   # served by primary
+# …primary host dies…
+llm.invoke("And the next one?")           # transparently served by backup
+# …primary comes back…
+llm.invoke("One more")                     # back on primary, logged as recovered
+```
+
+## Install
+
+```bash
+pip install langchain-failover            # core
+pip install "langchain-failover[openai]"  # + langchain-openai for create_failover_llm
+```
+
+## Why not `RunnableWithFallbacks` / `.with_fallbacks()`?
+
+LangChain ships per-invocation fallbacks, and they're great for what they do. This
+package exists for the cases they don't cover well:
+
+- **Stateful recovery.** `FailoverChatModel` remembers which leg it's on and logs
+  the transition both ways (`active` property tells you). `.with_fallbacks()` is
+  stateless — every call re-tries the (possibly still-dead) primary first.
+- **Tool-calling survives failover.** `bind_tools` is overridden to bind on *both*
+  legs and return another `FailoverChatModel`. With strict langchain-core
+  (`>=1.4`, where `BaseChatModel.bind_tools` raises by default) naïve wrappers
+  break at bind time; agents using this one keep working.
+- **Connection-aware, not blanket.** It only fails over on connection/network
+  errors (walking the exception's `__cause__`/`__context__` chain, so a socket
+  error wrapped three layers deep still counts). A `ValueError` from a bad prompt
+  propagates instead of being silently retried on a second endpoint.
+- **Mid-stream safety.** During `stream()`, it only fails over if the primary dies
+  *before* the first token — so you never get duplicated, half-streamed output.
+
+## Local-model convenience
+
+If you run local OpenAI-compatible servers (vLLM, mlx-lm, Ollama, LM Studio) and
+don't want to hardcode model names, `create_failover_llm` auto-discovers the served
+model id from each endpoint's `/models`:
+
+```python
+from langchain_failover import create_failover_llm
+
+llm = create_failover_llm(
+    primary_url="http://localhost:8001/v1",
+    secondary_url="http://localhost:8002/v1",
+)
+```
+
+## Bonus helper
+
+`extract_token_metrics(response.response_metadata)` normalises token counts and
+timings across OpenAI-compatible and Ollama metadata shapes into a single
+`{input_tokens, output_tokens, prompt_time, generation_time}` dict.
+
+## License
+
+MIT

langchain_failover-0.1.0/README.md

@@ -0,0 +1,73 @@
+# langchain-failover
+
+A tiny, dependency-light **primary/secondary failover wrapper** for LangChain chat
+models. Point it at two chat models; it serves from the primary, transparently
+falls back to the secondary on connection errors, and switches back the moment the
+primary recovers — **and tool-calling keeps working across the failover.**
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain_failover import FailoverChatModel
+
+primary = ChatOpenAI(base_url="http://gpu-box:8001/v1", api_key="x", model="local")
+backup  = ChatOpenAI(base_url="http://cpu-box:8002/v1", api_key="x", model="local")
+
+llm = FailoverChatModel(primary=primary, secondary=backup)
+
+llm.invoke("Summarise this incident…")   # served by primary
+# …primary host dies…
+llm.invoke("And the next one?")           # transparently served by backup
+# …primary comes back…
+llm.invoke("One more")                     # back on primary, logged as recovered
+```
+
+## Install
+
+```bash
+pip install langchain-failover            # core
+pip install "langchain-failover[openai]"  # + langchain-openai for create_failover_llm
+```
+
+## Why not `RunnableWithFallbacks` / `.with_fallbacks()`?
+
+LangChain ships per-invocation fallbacks, and they're great for what they do. This
+package exists for the cases they don't cover well:
+
+- **Stateful recovery.** `FailoverChatModel` remembers which leg it's on and logs
+  the transition both ways (`active` property tells you). `.with_fallbacks()` is
+  stateless — every call re-tries the (possibly still-dead) primary first.
+- **Tool-calling survives failover.** `bind_tools` is overridden to bind on *both*
+  legs and return another `FailoverChatModel`. With strict langchain-core
+  (`>=1.4`, where `BaseChatModel.bind_tools` raises by default) naïve wrappers
+  break at bind time; agents using this one keep working.
+- **Connection-aware, not blanket.** It only fails over on connection/network
+  errors (walking the exception's `__cause__`/`__context__` chain, so a socket
+  error wrapped three layers deep still counts). A `ValueError` from a bad prompt
+  propagates instead of being silently retried on a second endpoint.
+- **Mid-stream safety.** During `stream()`, it only fails over if the primary dies
+  *before* the first token — so you never get duplicated, half-streamed output.
+
+## Local-model convenience
+
+If you run local OpenAI-compatible servers (vLLM, mlx-lm, Ollama, LM Studio) and
+don't want to hardcode model names, `create_failover_llm` auto-discovers the served
+model id from each endpoint's `/models`:
+
+```python
+from langchain_failover import create_failover_llm
+
+llm = create_failover_llm(
+    primary_url="http://localhost:8001/v1",
+    secondary_url="http://localhost:8002/v1",
+)
+```
+
+## Bonus helper
+
+`extract_token_metrics(response.response_metadata)` normalises token counts and
+timings across OpenAI-compatible and Ollama metadata shapes into a single
+`{input_tokens, output_tokens, prompt_time, generation_time}` dict.
+
+## License
+
+MIT

langchain_failover-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-failover"
+version = "0.1.0"
+description = "Primary/secondary failover wrapper for LangChain chat models, with tool-calling preserved across failover."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "Vinay Vobbilichetty", email = "vinayvobbilichetty11@gmail.com" }]
+keywords = ["langchain", "llm", "failover", "fallback", "resilience", "high-availability", "chat-model"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "langchain-core>=0.2",
+]
+
+[project.optional-dependencies]
+openai = ["langchain-openai>=0.1"]
+dev = [
+    "langchain-openai>=0.1",
+    "pytest>=7",
+    "ruff>=0.4",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/vinayvobbili/langchain-failover"
+Repository = "https://github.com/vinayvobbili/langchain-failover"
+Issues = "https://github.com/vinayvobbili/langchain-failover/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_failover"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

langchain_failover-0.1.0/src/langchain_failover/__init__.py

@@ -0,0 +1,17 @@
+"""langchain-failover — a primary/secondary failover wrapper for LangChain chat models."""
+from langchain_failover.failover import (
+    FailoverChatModel,
+    create_failover_llm,
+    extract_token_metrics,
+    is_connection_error,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "FailoverChatModel",
+    "create_failover_llm",
+    "extract_token_metrics",
+    "is_connection_error",
+    "__version__",
+]

langchain_failover-0.1.0/src/langchain_failover/failover.py

@@ -0,0 +1,248 @@
+"""A LangChain chat model that fails over between a primary and a secondary model.
+
+The wrapper delegates every call to the primary chat model. If the primary raises
+a connection-related error it transparently retries on the secondary, and it
+switches back to the primary the moment the primary answers again. ``bind_tools``
+is preserved across the failover so tool-calling agents keep working when either
+leg is the one serving the request.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from langchain_core.language_models import BaseChatModel
+from pydantic import ConfigDict
+
+logger = logging.getLogger(__name__)
+
+# Exception *type names* (not classes) that we treat as "the endpoint is
+# unreachable, try the other one." Matching by name keeps us independent of
+# which HTTP/client library raised it (httpx, requests, urllib, openai, ...).
+_CONNECTION_ERROR_NAMES = (
+    "ConnectionError",
+    "ConnectError",
+    "RemoteProtocolError",
+    "ConnectionRefusedError",
+    "TimeoutError",
+    "ReadTimeout",
+    "APIConnectionError",
+)
+
+
+def is_connection_error(exc: BaseException) -> bool:
+    """Return True if ``exc`` (or anything in its cause/context chain) looks like
+    a connection/network failure worth failing over on.
+
+    We walk ``__cause__``/``__context__`` because client libraries routinely wrap
+    the original socket error inside a higher-level exception, so the interesting
+    type is often several links down the chain.
+    """
+    seen: set[int] = set()
+    current: Optional[BaseException] = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        name = type(current).__name__
+        if name in _CONNECTION_ERROR_NAMES:
+            return True
+        if "connection" in name.lower():
+            return True
+        if "connection" in str(current).lower()[:200]:
+            return True
+        current = current.__cause__ or current.__context__
+    return False
+
+
+class FailoverChatModel(BaseChatModel):
+    """Wraps two chat models — tries ``primary``, falls back to ``secondary``.
+
+    All calls (``invoke``, ``stream``, ``generate``, tool-bound variants) are
+    delegated to ``primary``. On a connection-related error the call is retried
+    on ``secondary`` and the model remembers it is running degraded; the next
+    successful ``primary`` call flips it back and logs the recovery.
+
+    Example
+    -------
+    >>> from langchain_openai import ChatOpenAI
+    >>> from langchain_failover import FailoverChatModel
+    >>> primary = ChatOpenAI(base_url="http://localhost:8001/v1", api_key="x", model="local")
+    >>> backup = ChatOpenAI(base_url="http://localhost:8002/v1", api_key="x", model="local")
+    >>> llm = FailoverChatModel(primary=primary, secondary=backup)
+    >>> llm.invoke("hello").content  # doctest: +SKIP
+    """
+
+    # ``Any`` rather than ``BaseChatModel`` on purpose: ``ChatModel.bind_tools``
+    # returns a ``Runnable`` binding (e.g. langchain's ``_ChatModelBinding``),
+    # not a ``BaseChatModel``. The binding still exposes ``_generate``/``_stream``,
+    # so wrapping it works — but a strict type would reject it.
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    primary: Any
+    secondary: Any
+    _active: str = "primary"
+
+    @property
+    def _llm_type(self) -> str:
+        return "failover"
+
+    def _mark_primary_recovered(self) -> None:
+        if self._active != "primary":
+            logger.info("Failover: primary recovered, switching back")
+            self._active = "primary"
+
+    def _switch_to_secondary(self, exc: BaseException) -> None:
+        logger.warning(
+            "Failover: primary down (%s), switching to secondary",
+            type(exc).__name__,
+        )
+        self._active = "secondary"
+
+    def _generate(self, messages, stop=None, run_manager=None, **kwargs):
+        try:
+            result = self.primary._generate(
+                messages, stop=stop, run_manager=run_manager, **kwargs
+            )
+            self._mark_primary_recovered()
+            return result
+        except Exception as exc:
+            if is_connection_error(exc):
+                self._switch_to_secondary(exc)
+                return self.secondary._generate(
+                    messages, stop=stop, run_manager=run_manager, **kwargs
+                )
+            raise
+
+    def _stream(self, messages, stop=None, run_manager=None, **kwargs):
+        # Only fail over if the primary dies *before* emitting its first chunk;
+        # once tokens are flowing a mid-stream error is a real error, not a
+        # connect failure, and retrying would duplicate already-yielded output.
+        try:
+            started = False
+            for chunk in self.primary._stream(
+                messages, stop=stop, run_manager=run_manager, **kwargs
+            ):
+                if not started:
+                    started = True
+                    self._mark_primary_recovered()
+                yield chunk
+        except Exception as exc:
+            if is_connection_error(exc) and not started:
+                self._switch_to_secondary(exc)
+                yield from self.secondary._stream(
+                    messages, stop=stop, run_manager=run_manager, **kwargs
+                )
+            else:
+                raise
+
+    def bind_tools(self, tools, **kwargs) -> "FailoverChatModel":
+        """Bind tools on both legs so failover preserves tool-calling.
+
+        langchain-core >=1.4 made ``BaseChatModel.bind_tools`` strict (it raises
+        ``NotImplementedError`` by default), so without this override any agent
+        that binds tools to a ``FailoverChatModel`` would fail at bind time. Each
+        bound leg is a ``Runnable`` that still exposes ``_generate``/``_stream``,
+        so the delegation above keeps working on the returned wrapper.
+        """
+        return FailoverChatModel(
+            primary=self.primary.bind_tools(tools, **kwargs),
+            secondary=self.secondary.bind_tools(tools, **kwargs),
+        )
+
+    @property
+    def active(self) -> str:
+        """Which leg served the most recent call: ``"primary"`` or ``"secondary"``."""
+        return self._active
+
+
+def create_failover_llm(
+    primary_url: str,
+    secondary_url: str,
+    temperature: float = 0.1,
+    api_key: str = "not-needed",
+    **kwargs: Any,
+) -> FailoverChatModel:
+    """Build a :class:`FailoverChatModel` from two OpenAI-compatible base URLs.
+
+    The served model id is auto-discovered from each endpoint's ``/models`` list
+    (handy for local servers like vLLM, mlx-lm, Ollama, or LM Studio, where you
+    often don't want to hardcode the model name). Extra ``kwargs`` are forwarded
+    to both underlying ``ChatOpenAI`` instances.
+
+    Args:
+        primary_url: Primary endpoint base URL, e.g. ``http://localhost:8001/v1``.
+        secondary_url: Fallback endpoint base URL.
+        temperature: Sampling temperature for both legs.
+        api_key: Bearer token sent to both endpoints (many local servers ignore it).
+    """
+    try:
+        from langchain_openai import ChatOpenAI
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "create_failover_llm requires langchain-openai. "
+            "Install it with `pip install langchain-failover[openai]`."
+        ) from exc
+
+    import urllib.request
+    import json
+
+    def _discover_model(base_url: str) -> str:
+        try:
+            req = urllib.request.Request(
+                f"{base_url.rstrip('/')}/models",
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
+            with urllib.request.urlopen(req, timeout=5) as resp:
+                data = json.loads(resp.read()).get("data", [])
+            if data:
+                return data[0]["id"]
+        except Exception:
+            pass
+        return "default"
+
+    def _make_client(base_url: str) -> Any:
+        return ChatOpenAI(
+            model=_discover_model(base_url),
+            temperature=temperature,
+            base_url=base_url,
+            api_key=api_key,
+            **kwargs,
+        )
+
+    logger.info("Failover LLM: primary=%s, secondary=%s", primary_url, secondary_url)
+    return FailoverChatModel(
+        primary=_make_client(primary_url),
+        secondary=_make_client(secondary_url),
+    )
+
+
+def extract_token_metrics(meta: Optional[dict]) -> dict:
+    """Pull token counts and timings out of a LangChain ``response_metadata`` dict.
+
+    Handles both OpenAI-compatible servers (``token_usage``/``usage``; no timing)
+    and Ollama (``prompt_eval_count``/``eval_count`` plus nanosecond durations).
+    Every field defaults to 0 when absent so callers never have to guard.
+
+    Returns:
+        ``{"input_tokens", "output_tokens", "prompt_time", "generation_time"}``.
+    """
+    if not meta:
+        return {
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "prompt_time": 0.0,
+            "generation_time": 0.0,
+        }
+
+    usage = meta.get("token_usage") or meta.get("usage") or {}
+    input_tokens = usage.get("prompt_tokens", 0) or meta.get("prompt_eval_count", 0)
+    output_tokens = usage.get("completion_tokens", 0) or meta.get("eval_count", 0)
+
+    prompt_time = meta.get("prompt_eval_duration", 0) / 1e9 if "prompt_eval_duration" in meta else 0.0
+    generation_time = meta.get("eval_duration", 0) / 1e9 if "eval_duration" in meta else 0.0
+
+    return {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "prompt_time": prompt_time,
+        "generation_time": generation_time,
+    }

langchain_failover-0.1.0/tests/test_failover.py

@@ -0,0 +1,107 @@
+"""Tests for FailoverChatModel — no network required.
+
+Uses tiny fake chat models that either answer or raise, so the failover,
+recovery, streaming, and bind_tools behaviour can be exercised deterministically.
+"""
+from typing import Any, List, Optional
+
+import pytest
+from langchain_core.callbacks import CallbackManagerForLLMRun
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage
+from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult
+from langchain_core.messages import AIMessageChunk
+
+from langchain_failover import FailoverChatModel, is_connection_error
+
+
+class _FakeChat(BaseChatModel):
+    """Answers with a fixed reply, or raises a chosen exception on every call."""
+
+    reply: str = "ok"
+    raises: Any = None
+    calls: int = 0
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    @property
+    def _llm_type(self) -> str:
+        return "fake"
+
+    def _generate(
+        self,
+        messages,
+        stop: Optional[List[str]] = None,
+        run_manager: Optional[CallbackManagerForLLMRun] = None,
+        **kwargs: Any,
+    ) -> ChatResult:
+        object.__setattr__(self, "calls", self.calls + 1)
+        if self.raises is not None:
+            raise self.raises
+        return ChatResult(generations=[ChatGeneration(message=AIMessage(content=self.reply))])
+
+    def _stream(self, messages, stop=None, run_manager=None, **kwargs):
+        object.__setattr__(self, "calls", self.calls + 1)
+        if self.raises is not None:
+            raise self.raises
+        yield ChatGenerationChunk(message=AIMessageChunk(content=self.reply))
+
+    def bind_tools(self, tools, **kwargs):
+        # Mirror the reply so a bound model is still identifiable in tests.
+        return _FakeChat(reply=f"bound:{self.reply}", raises=self.raises)
+
+
+def test_primary_serves_when_healthy():
+    llm = FailoverChatModel(primary=_FakeChat(reply="primary"), secondary=_FakeChat(reply="secondary"))
+    assert llm.invoke("hi").content == "primary"
+    assert llm.active == "primary"
+
+
+def test_fails_over_on_connection_error():
+    primary = _FakeChat(raises=ConnectionError("refused"))
+    llm = FailoverChatModel(primary=primary, secondary=_FakeChat(reply="secondary"))
+    assert llm.invoke("hi").content == "secondary"
+    assert llm.active == "secondary"
+
+
+def test_non_connection_error_propagates():
+    primary = _FakeChat(raises=ValueError("bad prompt"))
+    llm = FailoverChatModel(primary=primary, secondary=_FakeChat(reply="secondary"))
+    with pytest.raises(ValueError):
+        llm.invoke("hi")
+
+
+def test_recovers_back_to_primary():
+    primary = _FakeChat(raises=ConnectionError("down"))
+    secondary = _FakeChat(reply="secondary")
+    llm = FailoverChatModel(primary=primary, secondary=secondary)
+    assert llm.invoke("hi").content == "secondary"
+    assert llm.active == "secondary"
+    # Primary heals.
+    object.__setattr__(primary, "raises", None)
+    object.__setattr__(primary, "reply", "primary-back")
+    assert llm.invoke("hi").content == "primary-back"
+    assert llm.active == "primary"
+
+
+def test_streaming_fails_over():
+    primary = _FakeChat(raises=ConnectionError("refused"))
+    llm = FailoverChatModel(primary=primary, secondary=_FakeChat(reply="streamed"))
+    chunks = list(llm.stream("hi"))
+    assert "".join(c.content for c in chunks) == "streamed"
+
+
+def test_bind_tools_preserved_on_both_legs():
+    llm = FailoverChatModel(primary=_FakeChat(reply="p"), secondary=_FakeChat(reply="s"))
+    bound = llm.bind_tools([])
+    assert isinstance(bound, FailoverChatModel)
+    assert bound.invoke("hi").content == "bound:p"
+
+
+def test_is_connection_error_walks_cause_chain():
+    inner = ConnectionRefusedError("nope")
+    outer = RuntimeError("wrapper")
+    outer.__cause__ = inner
+    assert is_connection_error(outer)
+    assert not is_connection_error(ValueError("totally unrelated"))