langchain-breakwire 0.1.0__tar.gz

langchain_breakwire-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ethan Hawkes
+
+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_breakwire-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: langchain-breakwire
+Version: 0.1.0
+Summary: LangChain tools and callback handler for Breakwire: look up API/SDK errors and get the source-linked change that explains them, with the fix.
+Author: Breakwire
+License-Expression: MIT
+Project-URL: Homepage, https://breakwire.org
+Project-URL: Source, https://github.com/breakwire-org/breakwire/tree/main/packages/langchain-breakwire
+Project-URL: Issues, https://github.com/breakwire-org/breakwire/issues
+Keywords: langchain,breakwire,errors,breaking-changes,deprecations,ai-agents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: breakwire>=0.1.0
+Requires-Dist: langchain-core>=0.3
+Dynamic: license-file
+
+# langchain-breakwire
+
+LangChain integration for [Breakwire](https://breakwire.org): tools an agent can call to look up an API/SDK error or
+check upcoming deadlines, and a callback handler that looks up errors raised in your chains, LLM calls and tools.
+
+```bash
+pip install langchain-breakwire
+```
+
+```python
+from langchain_breakwire import BreakwireLookupTool, BreakwireDeadlinesTool, BreakwireCallbackHandler
+
+tools = [BreakwireLookupTool(), BreakwireDeadlinesTool()]      # give them to your agent
+
+handler = BreakwireCallbackHandler(service="openai-api")
+try:
+    chain.invoke(inputs, config={"callbacks": [handler]})
+except Exception as e:
+    print(e.breakwire.id, e.breakwire.fix)    # same exception, explanation attached
+    raise
+```
+
+- `BreakwireLookupTool` (`breakwire_lookup_error`): error text (+ optional service, sdk, sdk_version, model) → compact
+  matches with id, confidence, fix, source URL. Unmatched errors are not logged unless `log_miss=True`.
+- `BreakwireDeadlinesTool` (`breakwire_deadlines`): upcoming act-by dates for a service.
+- `BreakwireCallbackHandler`: `on_llm_error` / `on_tool_error` / `on_chain_error`; each exception is looked up once even
+  though LangChain reports it at every nesting level. Never raises, never changes the error. `on_match(info, error)` hook.
+
+Built on the stdlib-only [`breakwire`](https://pypi.org/project/breakwire/) client, which strips secrets before sending.
+Breakwire's community verification has just started; claims link primary sources, prefer those.
+
+MIT.

langchain_breakwire-0.1.0/README.md

@@ -0,0 +1,32 @@
+# langchain-breakwire
+
+LangChain integration for [Breakwire](https://breakwire.org): tools an agent can call to look up an API/SDK error or
+check upcoming deadlines, and a callback handler that looks up errors raised in your chains, LLM calls and tools.
+
+```bash
+pip install langchain-breakwire
+```
+
+```python
+from langchain_breakwire import BreakwireLookupTool, BreakwireDeadlinesTool, BreakwireCallbackHandler
+
+tools = [BreakwireLookupTool(), BreakwireDeadlinesTool()]      # give them to your agent
+
+handler = BreakwireCallbackHandler(service="openai-api")
+try:
+    chain.invoke(inputs, config={"callbacks": [handler]})
+except Exception as e:
+    print(e.breakwire.id, e.breakwire.fix)    # same exception, explanation attached
+    raise
+```
+
+- `BreakwireLookupTool` (`breakwire_lookup_error`): error text (+ optional service, sdk, sdk_version, model) → compact
+  matches with id, confidence, fix, source URL. Unmatched errors are not logged unless `log_miss=True`.
+- `BreakwireDeadlinesTool` (`breakwire_deadlines`): upcoming act-by dates for a service.
+- `BreakwireCallbackHandler`: `on_llm_error` / `on_tool_error` / `on_chain_error`; each exception is looked up once even
+  though LangChain reports it at every nesting level. Never raises, never changes the error. `on_match(info, error)` hook.
+
+Built on the stdlib-only [`breakwire`](https://pypi.org/project/breakwire/) client, which strips secrets before sending.
+Breakwire's community verification has just started; claims link primary sources, prefer those.
+
+MIT.

langchain_breakwire-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langchain-breakwire"
+version = "0.1.0"
+description = "LangChain tools and callback handler for Breakwire: look up API/SDK errors and get the source-linked change that explains them, with the fix."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Breakwire" }]
+keywords = ["langchain", "breakwire", "errors", "breaking-changes", "deprecations", "ai-agents"]
+dependencies = ["breakwire>=0.1.0", "langchain-core>=0.3"]
+
+[project.urls]
+Homepage = "https://breakwire.org"
+Source = "https://github.com/breakwire-org/breakwire/tree/main/packages/langchain-breakwire"
+Issues = "https://github.com/breakwire-org/breakwire/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

langchain_breakwire-0.1.0/setup.cfg

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

langchain_breakwire-0.1.0/src/langchain_breakwire/__init__.py

@@ -0,0 +1,126 @@
+"""LangChain integration for Breakwire: tools the agent can call, and a callback handler that looks up
+errors raised inside chains, LLM calls and tools.
+
+    from langchain_breakwire import BreakwireLookupTool, BreakwireDeadlinesTool, BreakwireCallbackHandler
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Type
+from uuid import UUID
+
+from breakwire import Breakwire, explain
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field
+
+__version__ = "0.1.0"
+__all__ = ["BreakwireLookupTool", "BreakwireDeadlinesTool", "BreakwireCallbackHandler", "__version__"]
+
+
+def _compact(r: Dict[str, Any], max_matches: int = 3) -> Dict[str, Any]:
+    cov = r.get("coverage") or {}
+    return {
+        "lookup_id": r.get("lookup_id"),
+        "explained": r.get("explained"),
+        "coverage_note": cov.get("note") if cov and not cov.get("covered", True) else None,
+        "matches": [
+            {"id": m.get("cid"), "title": m.get("title"), "confidence": m.get("confidence"), "fix": m.get("fix"),
+             "deadline": m.get("deadline"), "url": m.get("url"), "source_url": m.get("source_url")}
+            for m in (r.get("matches") or [])[:max_matches]
+        ],
+        "note": 'Community data: "signature" = vendor-documented error text matched; "related" = a lead only. Prefer source_url.',
+    }
+
+
+class _LookupInput(BaseModel):
+    error: str = Field(description="The error message text. Secrets are stripped before sending.")
+    service: Optional[str] = Field(default=None, description="Service slug, e.g. anthropic-api, openai-api, stripe, github-api, mcp")
+    sdk: Optional[str] = Field(default=None)
+    sdk_version: Optional[str] = Field(default=None)
+    model: Optional[str] = Field(default=None)
+
+
+class BreakwireLookupTool(BaseTool):
+    """Look up an API/SDK/platform error in Breakwire and get the claim that explains it, with the fix."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    name: str = "breakwire_lookup_error"
+    description: str = (
+        "Look up an API/SDK/platform error message in Breakwire, a source-linked registry of breaking changes, "
+        "deprecations and advisories. Returns the matching claim and its fix. Use when a call fails with an error you do not recognise."
+    )
+    args_schema: Type[BaseModel] = _LookupInput
+    client: Breakwire = Field(default_factory=Breakwire)
+    log_miss: bool = False
+    max_matches: int = 3
+
+    def _run(self, error: str, service: Optional[str] = None, sdk: Optional[str] = None,
+             sdk_version: Optional[str] = None, model: Optional[str] = None, run_manager: Any = None) -> Dict[str, Any]:
+        try:
+            r = self.client.lookup(error, service=service, sdk=sdk, version=sdk_version, model=model, log_miss=self.log_miss)
+            return _compact(r, self.max_matches)
+        except Exception as e:  # noqa: BLE001
+            return {"error": f"Breakwire unavailable: {e}"}
+
+
+class _DeadlinesInput(BaseModel):
+    service: Optional[str] = Field(default=None, description="Service slug; omit for all services")
+
+
+class BreakwireDeadlinesTool(BaseTool):
+    """Upcoming act-by dates (model retirements, API shutdowns, required migrations), soonest first."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    name: str = "breakwire_deadlines"
+    description: str = "Upcoming act-by dates (model retirements, API shutdowns, required migrations) for a service, soonest first."
+    args_schema: Type[BaseModel] = _DeadlinesInput
+    client: Breakwire = Field(default_factory=Breakwire)
+
+    def _run(self, service: Optional[str] = None, run_manager: Any = None) -> Any:
+        try:
+            return [{"id": c.get("cid"), "title": c.get("title"), "deadline": c.get("deadline"), "fix": c.get("fix"), "url": c.get("url")}
+                    for c in self.client.deadlines(service, limit=10)]
+        except Exception as e:  # noqa: BLE001
+            return {"error": f"Breakwire unavailable: {e}"}
+
+
+class BreakwireCallbackHandler(BaseCallbackHandler):
+    """Looks up errors raised in LLM calls, tools and chains; sets ``error.breakwire`` and calls ``on_match``.
+
+    Each exception is looked up once even though LangChain reports it at every level of nesting.
+    Never raises (``raise_error`` is False), never changes the error.
+    """
+
+    raise_error: bool = False
+
+    def __init__(self, service: Optional[str] = None, client: Optional[Breakwire] = None, timeout: float = 2.5,
+                 log_miss: bool = True, on_match: Optional[Any] = None, **lookup: Any):
+        self.client = client or Breakwire(timeout=timeout)
+        self.timeout = timeout
+        self.lookup = {"service": service, "log_miss": log_miss, **lookup}
+        self.on_match = on_match
+        self.results: List[Any] = []
+
+    def _handle(self, error: BaseException) -> None:
+        if not isinstance(error, Exception) or getattr(error, "breakwire", None) is not None:
+            return
+        info = explain(error, client=self.client, timeout=self.timeout, **{k: v for k, v in self.lookup.items() if v is not None})
+        try:
+            error.breakwire = info  # type: ignore[attr-defined]
+        except Exception:
+            pass
+        self.results.append(info)
+        if self.on_match:
+            try:
+                self.on_match(info, error)
+            except Exception:
+                pass
+
+    def on_llm_error(self, error: BaseException, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any) -> None:
+        self._handle(error)
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any) -> None:
+        self._handle(error)
+
+    def on_chain_error(self, error: BaseException, *, run_id: UUID, parent_run_id: Optional[UUID] = None, **kwargs: Any) -> None:
+        self._handle(error)

langchain_breakwire-0.1.0/src/langchain_breakwire.egg-info/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: langchain-breakwire
+Version: 0.1.0
+Summary: LangChain tools and callback handler for Breakwire: look up API/SDK errors and get the source-linked change that explains them, with the fix.
+Author: Breakwire
+License-Expression: MIT
+Project-URL: Homepage, https://breakwire.org
+Project-URL: Source, https://github.com/breakwire-org/breakwire/tree/main/packages/langchain-breakwire
+Project-URL: Issues, https://github.com/breakwire-org/breakwire/issues
+Keywords: langchain,breakwire,errors,breaking-changes,deprecations,ai-agents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: breakwire>=0.1.0
+Requires-Dist: langchain-core>=0.3
+Dynamic: license-file
+
+# langchain-breakwire
+
+LangChain integration for [Breakwire](https://breakwire.org): tools an agent can call to look up an API/SDK error or
+check upcoming deadlines, and a callback handler that looks up errors raised in your chains, LLM calls and tools.
+
+```bash
+pip install langchain-breakwire
+```
+
+```python
+from langchain_breakwire import BreakwireLookupTool, BreakwireDeadlinesTool, BreakwireCallbackHandler
+
+tools = [BreakwireLookupTool(), BreakwireDeadlinesTool()]      # give them to your agent
+
+handler = BreakwireCallbackHandler(service="openai-api")
+try:
+    chain.invoke(inputs, config={"callbacks": [handler]})
+except Exception as e:
+    print(e.breakwire.id, e.breakwire.fix)    # same exception, explanation attached
+    raise
+```
+
+- `BreakwireLookupTool` (`breakwire_lookup_error`): error text (+ optional service, sdk, sdk_version, model) → compact
+  matches with id, confidence, fix, source URL. Unmatched errors are not logged unless `log_miss=True`.
+- `BreakwireDeadlinesTool` (`breakwire_deadlines`): upcoming act-by dates for a service.
+- `BreakwireCallbackHandler`: `on_llm_error` / `on_tool_error` / `on_chain_error`; each exception is looked up once even
+  though LangChain reports it at every nesting level. Never raises, never changes the error. `on_match(info, error)` hook.
+
+Built on the stdlib-only [`breakwire`](https://pypi.org/project/breakwire/) client, which strips secrets before sending.
+Breakwire's community verification has just started; claims link primary sources, prefer those.
+
+MIT.

langchain_breakwire-0.1.0/src/langchain_breakwire.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/langchain_breakwire/__init__.py
+src/langchain_breakwire.egg-info/PKG-INFO
+src/langchain_breakwire.egg-info/SOURCES.txt
+src/langchain_breakwire.egg-info/dependency_links.txt
+src/langchain_breakwire.egg-info/requires.txt
+src/langchain_breakwire.egg-info/top_level.txt
+tests/test_unit.py

langchain_breakwire-0.1.0/src/langchain_breakwire.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

langchain_breakwire-0.1.0/src/langchain_breakwire.egg-info/requires.txt

@@ -0,0 +1,2 @@
+breakwire>=0.1.0
+langchain-core>=0.3

langchain_breakwire-0.1.0/src/langchain_breakwire.egg-info/top_level.txt

@@ -0,0 +1 @@
+langchain_breakwire

langchain_breakwire-0.1.0/tests/test_unit.py

@@ -0,0 +1,72 @@
+"""Offline tests with a fake Breakwire client. Run: python -m unittest discover -s tests"""
+import pathlib
+import sys
+import unittest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+sys.path.insert(0, str(ROOT.parent / "python" / "src"))
+
+from langchain_core.runnables import RunnableLambda  # noqa: E402
+from breakwire import Breakwire  # noqa: E402
+from langchain_breakwire import BreakwireCallbackHandler, BreakwireDeadlinesTool, BreakwireLookupTool  # noqa: E402
+
+LOOKUP = {"lookup_id": "lk_x", "explained": True, "coverage": None,
+          "matches": [{"cid": "AN-2026-0025", "title": "T", "confidence": "signature", "fix": "F", "url": "U", "source_url": "S", "deadline": None}]}
+
+
+class Fake(Breakwire):
+    def __init__(self, fail=False):
+        super().__init__(base_url="http://fake.invalid")
+        self.calls, self.fail = [], fail
+
+    def lookup(self, error, **kw):
+        self.calls.append(("lookup", str(error), kw))
+        if self.fail:
+            raise RuntimeError("down")
+        return LOOKUP
+
+    def deadlines(self, service=None, **kw):
+        self.calls.append(("deadlines", service, kw))
+        return [{"cid": "AN-2026-0004", "title": "D", "deadline": "2026-11-30", "fix": "F", "url": "U"}]
+
+
+class T(unittest.TestCase):
+    def test_lookup_tool(self):
+        f = Fake()
+        t = BreakwireLookupTool(client=f)
+        out = t.invoke({"error": "boom", "service": "anthropic-api"})
+        self.assertEqual(out["matches"][0]["id"], "AN-2026-0025")
+        self.assertEqual(f.calls[0][2]["service"], "anthropic-api")
+        self.assertFalse(f.calls[0][2]["log_miss"])
+        self.assertIn("error", t.args)
+
+    def test_lookup_tool_never_raises(self):
+        out = BreakwireLookupTool(client=Fake(fail=True)).invoke({"error": "boom"})
+        self.assertIn("unavailable", out["error"])
+
+    def test_deadlines_tool(self):
+        out = BreakwireDeadlinesTool(client=Fake()).invoke({"service": "anthropic-api"})
+        self.assertEqual(out[0]["deadline"], "2026-11-30")
+
+    def test_callback_handler_once_per_exception(self):
+        f = Fake()
+        h = BreakwireCallbackHandler(service="openai-api", client=f)
+        inner = RunnableLambda(lambda x: (_ for _ in ()).throw(ValueError("Error code: 429 organization_spend_limit_exceeded")))
+        chain = RunnableLambda(lambda x: x) | inner
+        with self.assertRaises(ValueError) as cm:
+            chain.invoke("hi", config={"callbacks": [h]})
+        self.assertEqual(cm.exception.breakwire.id, "AN-2026-0025")
+        self.assertEqual(len([c for c in f.calls if c[0] == "lookup"]), 1)
+
+    def test_callback_handler_never_masks(self):
+        h = BreakwireCallbackHandler(client=Fake(fail=True))
+        err = KeyError("x")
+        with self.assertRaises(KeyError) as cm:
+            RunnableLambda(lambda x: (_ for _ in ()).throw(err)).invoke(1, config={"callbacks": [h]})
+        self.assertIs(cm.exception, err)
+        self.assertIsNone(err.breakwire.id)
+
+
+if __name__ == "__main__":
+    unittest.main()