langchain-signafaide 0.1.0__tar.gz

langchain_signafaide-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+target/
+node_modules/
+.venv/
+dist/
+__pycache__/
+*.pyc
+.signafaide/
+.env
+data/
+*.key
+*.tgz

langchain_signafaide-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: langchain-signafaide
+Version: 0.1.0
+Summary: signafAIde for LangChain: signed, tamper-evident records of every tool call an agent makes.
+Project-URL: Homepage, https://signafaide.co.uk
+Project-URL: Documentation, https://signafaide.co.uk/docs/frameworks/langchain
+Project-URL: Repository, https://github.com/AIME-TECH-UK-LIMITED/signafaide-sdk
+Project-URL: Issues, https://github.com/AIME-TECH-UK-LIMITED/signafaide-sdk/issues
+Author: AIME TECH UK LIMITED
+License: Apache-2.0
+Keywords: ai-agents,audit-trail,eu-ai-act,langchain,middleware,tamper-evident
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: langchain<2,>=1.0
+Requires-Dist: signafaide<0.4,>=0.3.1
+Description-Content-Type: text/markdown
+
+# langchain-signafaide
+
+signafAIde for LangChain: a signed, tamper-evident record of every tool call an agent makes.
+
+Each tool call writes a `decision` record before the tool runs and an `outcome` record after it. Records are signed with the agent's own key and chained on the machine that wrote them, in `.signafaide/`. Once a person opts in, a witness (the signafAIde service, or one you host) co-signs them and timestamps them publicly, so neither side can forge or edit a record alone. An auditor can verify the records without trusting either side. Records attest integrity and timing, never whether a decision was right.
+
+## Install
+
+```bash
+pip install langchain-signafaide
+```
+
+Needs Python 3.10 or later and LangChain 1.x.
+
+## Middleware
+
+```python
+from langchain.agents import create_agent
+from langchain_signafaide import SignafaideMiddleware
+
+agent = create_agent(
+    model="openai:gpt-5",
+    tools=[get_weather, refund],
+    middleware=[SignafaideMiddleware(agent="support-bot", tools=[get_weather, refund])],
+)
+agent.invoke({"messages": [("user", "Refund order A1")]})
+```
+
+Then check the records:
+
+```bash
+signafaide verify
+```
+
+| Argument | What it does |
+|---|---|
+| `agent` | The name of the record chain. Use one name per running agent instance in production. Default: the project folder's name. |
+| `tools` | Every tool the agent can call (tools or names). They are declared in the chain as recorded, so a verifier can report that all of the agent's tools are covered. Without it, a tool is declared when it is first called. |
+| `strict` | A tool runs only once its decision has a receipt from the witness. If the witness cannot be reached, the call raises `NotRecorded` and the tool does not run. |
+| `store_content` | Also send inputs and outputs to the witness, encrypted. Default: hashes only. |
+
+The middleware works with `invoke` and `ainvoke`. A tool that raises is recorded with its error and the exception is raised unchanged.
+
+## Tools outside an agent
+
+For tools you call yourself, or pass to something other than `create_agent`:
+
+```python
+from langchain_signafaide import wrap_tools
+
+tools = wrap_tools([get_weather, refund], agent="support-bot")
+```
+
+Use the middleware or `wrap_tools` for an agent's tools, not both, or each call is recorded twice.
+
+## What is sent, and where
+
+- Before a person opts in: nothing. Records are signed, chained and verified locally.
+- After `signafaide init` (a free sandbox: no account, email or card) or with `SIGNAFAIDE_API_KEY` set: each record sends its content hash with its tool name, agent name and time to `https://api.signafaide.co.uk` (hosted in London), or to the address in `SIGNAFAIDE_URL`. Inputs and outputs are not sent unless stored content is turned on. Do not put personal data in tool or agent names.
+- The middleware records the tool calls that go through the agent it is attached to. A call your application makes around the agent is not recorded.
+
+## Links
+
+- Documentation: https://signafaide.co.uk/docs/frameworks/langchain
+- Privacy notice: https://signafaide.co.uk/legal/privacy
+- Support: https://github.com/AIME-TECH-UK-LIMITED/signafaide-sdk/issues or sales@signafaide.co.uk
+- Source: the `python-langchain/` folder of the signafAIde SDK repository. Apache-2.0.

langchain_signafaide-0.1.0/README.md

@@ -0,0 +1,67 @@
+# langchain-signafaide
+
+signafAIde for LangChain: a signed, tamper-evident record of every tool call an agent makes.
+
+Each tool call writes a `decision` record before the tool runs and an `outcome` record after it. Records are signed with the agent's own key and chained on the machine that wrote them, in `.signafaide/`. Once a person opts in, a witness (the signafAIde service, or one you host) co-signs them and timestamps them publicly, so neither side can forge or edit a record alone. An auditor can verify the records without trusting either side. Records attest integrity and timing, never whether a decision was right.
+
+## Install
+
+```bash
+pip install langchain-signafaide
+```
+
+Needs Python 3.10 or later and LangChain 1.x.
+
+## Middleware
+
+```python
+from langchain.agents import create_agent
+from langchain_signafaide import SignafaideMiddleware
+
+agent = create_agent(
+    model="openai:gpt-5",
+    tools=[get_weather, refund],
+    middleware=[SignafaideMiddleware(agent="support-bot", tools=[get_weather, refund])],
+)
+agent.invoke({"messages": [("user", "Refund order A1")]})
+```
+
+Then check the records:
+
+```bash
+signafaide verify
+```
+
+| Argument | What it does |
+|---|---|
+| `agent` | The name of the record chain. Use one name per running agent instance in production. Default: the project folder's name. |
+| `tools` | Every tool the agent can call (tools or names). They are declared in the chain as recorded, so a verifier can report that all of the agent's tools are covered. Without it, a tool is declared when it is first called. |
+| `strict` | A tool runs only once its decision has a receipt from the witness. If the witness cannot be reached, the call raises `NotRecorded` and the tool does not run. |
+| `store_content` | Also send inputs and outputs to the witness, encrypted. Default: hashes only. |
+
+The middleware works with `invoke` and `ainvoke`. A tool that raises is recorded with its error and the exception is raised unchanged.
+
+## Tools outside an agent
+
+For tools you call yourself, or pass to something other than `create_agent`:
+
+```python
+from langchain_signafaide import wrap_tools
+
+tools = wrap_tools([get_weather, refund], agent="support-bot")
+```
+
+Use the middleware or `wrap_tools` for an agent's tools, not both, or each call is recorded twice.
+
+## What is sent, and where
+
+- Before a person opts in: nothing. Records are signed, chained and verified locally.
+- After `signafaide init` (a free sandbox: no account, email or card) or with `SIGNAFAIDE_API_KEY` set: each record sends its content hash with its tool name, agent name and time to `https://api.signafaide.co.uk` (hosted in London), or to the address in `SIGNAFAIDE_URL`. Inputs and outputs are not sent unless stored content is turned on. Do not put personal data in tool or agent names.
+- The middleware records the tool calls that go through the agent it is attached to. A call your application makes around the agent is not recorded.
+
+## Links
+
+- Documentation: https://signafaide.co.uk/docs/frameworks/langchain
+- Privacy notice: https://signafaide.co.uk/legal/privacy
+- Support: https://github.com/AIME-TECH-UK-LIMITED/signafaide-sdk/issues or sales@signafaide.co.uk
+- Source: the `python-langchain/` folder of the signafAIde SDK repository. Apache-2.0.

langchain_signafaide-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-signafaide"
+version = "0.1.0"
+description = "signafAIde for LangChain: signed, tamper-evident records of every tool call an agent makes."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "AIME TECH UK LIMITED" }]
+dependencies = ["signafaide>=0.3.1,<0.4", "langchain>=1.0,<2"]
+keywords = ["langchain", "middleware", "ai-agents", "audit-trail", "tamper-evident", "eu-ai-act"]
+classifiers = [
+  "License :: OSI Approved :: Apache Software License",
+  "Topic :: Security :: Cryptography",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://signafaide.co.uk"
+Documentation = "https://signafaide.co.uk/docs/frameworks/langchain"
+Repository = "https://github.com/AIME-TECH-UK-LIMITED/signafaide-sdk"
+Issues = "https://github.com/AIME-TECH-UK-LIMITED/signafaide-sdk/issues"
+
+[dependency-groups]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_signafaide"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

langchain_signafaide-0.1.0/src/langchain_signafaide/__init__.py

@@ -0,0 +1,20 @@
+"""signafAIde for LangChain.
+
+    from langchain.agents import create_agent
+    from langchain_signafaide import SignafaideMiddleware
+
+    agent = create_agent(model, tools=tools, middleware=[SignafaideMiddleware(agent="support-bot")])
+
+Every tool call the agent makes writes a signed ``decision`` record before the tool runs and an
+``outcome`` record after it. Records are chained on the machine that wrote them, in
+``.signafaide/``; nothing is sent until a person opts in (``signafaide init``, or
+``SIGNAFAIDE_API_KEY``).
+"""
+
+from signafaide import NotRecorded, wrap_tool, wrap_tools
+
+from .middleware import SignafaideMiddleware
+
+__version__ = "0.1.0"
+
+__all__ = ["SignafaideMiddleware", "wrap_tools", "wrap_tool", "NotRecorded", "__version__"]

langchain_signafaide-0.1.0/src/langchain_signafaide/middleware.py

@@ -0,0 +1,79 @@
+"""``SignafaideMiddleware``: record every tool call a LangChain agent makes."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Iterable, Optional
+
+import signafaide
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import ToolMessage
+from signafaide import telemetry
+
+# The recording step itself (decision, run, outcome) lives in the signafaide package. It has
+# no public entry point for "record this call, which I run myself" yet, so this is the one
+# place that reaches into it; tests/test_middleware.py fails if it changes shape.
+from signafaide.decorator import _Spec
+
+
+def _tool_output(result: Any) -> Any:
+    """What the outcome records for the value a tool call produced."""
+    if isinstance(result, ToolMessage):
+        # A tool that failed where the agent handles tool errors comes back as an error
+        # message, not an exception: keep that visible in the record.
+        if getattr(result, "status", None) == "error":
+            return {"tool_error": result.content}
+        return result.content
+    update = getattr(result, "update", None)  # a langgraph Command
+    return {"command": signafaide.to_jsonable(update)} if update is not None else signafaide.to_jsonable(result)
+
+
+class SignafaideMiddleware(AgentMiddleware):
+    """Record every tool call of the agent as signed, chained signafAIde records.
+
+    Args:
+        agent: The name of the record chain. Give one name per running agent instance in
+            production. Default: the project folder's name.
+        strict: A tool runs only once its decision has a receipt from the witness. When the
+            witness cannot be reached the call raises ``NotRecorded`` and the tool does not run.
+        store_content: Send inputs and outputs to the witness, encrypted, as well as their
+            hashes. Default: the project's setting (hashes only).
+        tools: The names of every tool the agent can call. They are declared in the chain as
+            recorded, so a verifier can say that all of the agent's tools are covered. Without
+            it, each tool is declared when it is first called.
+    """
+
+    def __init__(
+        self,
+        *,
+        agent: Optional[str] = None,
+        strict: bool = False,
+        store_content: Optional[bool] = None,
+        tools: Optional[Iterable[Any]] = None,
+    ) -> None:
+        super().__init__()
+        self._agent = agent
+        self._strict = strict
+        self._store_content = store_content
+        self._specs: dict[str, _Spec] = {}
+        telemetry.ADAPTERS.add("langchain")
+        for t in tools or ():
+            self._spec(t if isinstance(t, str) else t.name)
+
+    def _spec(self, name: str) -> _Spec:
+        spec = self._specs.get(name)
+        if spec is None:
+            spec = self._specs[name] = _Spec(name, self._agent, self._strict, self._store_content, listed=True)
+        return spec
+
+    @staticmethod
+    def _call(request: Any) -> tuple[str, Any]:
+        call = request.tool_call
+        return call["name"], call.get("args", {})
+
+    def wrap_tool_call(self, request: Any, handler: Callable[[Any], Any]) -> Any:
+        name, args = self._call(request)
+        return self._spec(name).call(args, lambda: handler(request), _tool_output)
+
+    async def awrap_tool_call(self, request: Any, handler: Callable[[Any], Awaitable[Any]]) -> Any:
+        name, args = self._call(request)
+        return await self._spec(name).acall(args, lambda: handler(request), _tool_output)

langchain_signafaide-0.1.0/tests/test_middleware.py

@@ -0,0 +1,123 @@
+import asyncio
+import atexit
+import inspect
+import os
+
+import pytest
+from langchain.agents import create_agent
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage
+from langchain_core.tools import tool
+
+import signafaide
+from langchain_signafaide import SignafaideMiddleware
+from signafaide import decorator, runtime, telemetry
+
+
+class FakeModel(GenericFakeChatModel):
+    def bind_tools(self, tools, **kwargs):
+        return self
+
+
+def model_calling(*calls):
+    """A model that asks for *calls* (name, args), one per turn, then answers."""
+    msgs = [AIMessage(content="", tool_calls=[{"name": n, "args": a, "id": f"call_{i}", "type": "tool_call"}]) for i, (n, a) in enumerate(calls)]
+    return FakeModel(messages=iter(msgs + [AIMessage(content="done")]))
+
+
+@tool
+def get_weather(city: str) -> str:
+    """Weather for a city."""
+    if city == "Atlantis":
+        raise RuntimeError("no such city")
+    return f"sunny in {city}"
+
+
+@tool
+def refund(order: str, amount: float) -> str:
+    """Refund an order."""
+    return f"refunded {amount} on {order}"
+
+
+@pytest.fixture
+def recorder(tmp_path, monkeypatch):
+    root = tmp_path / "Claims Project"
+    root.mkdir()
+    (root / ".git").mkdir()
+    monkeypatch.chdir(root)
+    for k in list(os.environ):
+        if k.startswith("SIGNAFAIDE_"):
+            monkeypatch.delenv(k)
+    monkeypatch.setenv("SIGNAFAIDE_TEST", "0")  # exercise the real recorder, local only
+    monkeypatch.setattr(telemetry, "ADAPTERS", set())
+    decorator._reset_tool_registry()
+    r = runtime.configure(quiet=True, flush_interval=3600)
+    yield r
+    r._stopped = True
+    r._wake.set()
+    r._tool_stop.set()
+    atexit.unregister(r.close)
+    runtime._default = None
+
+
+def records(rec, agent):
+    (chain,) = [c for c in rec.state.chains() if c.rsplit("/", 1)[1] == agent]
+    return list(rec.state.read_all(chain))
+
+
+def calls(recs):
+    return [(r["envelope"]["kind"], r["envelope"]["name"]) for r in recs if r["envelope"]["kind"] != "note"]
+
+
+def test_agent_tool_calls_are_recorded(recorder):
+    agent = create_agent(model_calling(("get_weather", {"city": "Paris"}), ("refund", {"order": "A1", "amount": 12.5})), tools=[get_weather, refund], middleware=[SignafaideMiddleware(agent="support-bot")])
+    out = agent.invoke({"messages": [("user", "weather, then refund")]})
+    assert out["messages"][-1].content == "done"
+    recs = records(recorder, "support-bot")
+    assert calls(recs) == [("decision", "get_weather"), ("outcome", "get_weather"), ("decision", "refund"), ("outcome", "refund")]
+    body = [r for r in recs if r["envelope"]["kind"] != "note"]
+    assert body[0]["content"]["input"] == {"city": "Paris"} and body[1]["content"]["output"] == "sunny in Paris"
+    assert body[2]["content"]["input"] == {"order": "A1", "amount": 12.5} and body[3]["content"]["output"] == "refunded 12.5 on A1"
+    assert signafaide.verify().ok
+
+
+def test_async_agent(recorder):
+    agent = create_agent(model_calling(("get_weather", {"city": "Oslo"})), tools=[get_weather], middleware=[SignafaideMiddleware(agent="support-bot")])
+    asyncio.run(agent.ainvoke({"messages": [("user", "weather")]}))
+    body = [r for r in records(recorder, "support-bot") if r["envelope"]["kind"] != "note"]
+    assert calls(body) == [("decision", "get_weather"), ("outcome", "get_weather")]
+    assert body[1]["content"]["output"] == "sunny in Oslo"
+
+
+def test_tool_error_is_recorded_and_raised(recorder):
+    agent = create_agent(model_calling(("get_weather", {"city": "Atlantis"})), tools=[get_weather], middleware=[SignafaideMiddleware(agent="support-bot")])
+    with pytest.raises(RuntimeError, match="no such city"):
+        agent.invoke({"messages": [("user", "weather")]})
+    body = [r for r in records(recorder, "support-bot") if r["envelope"]["kind"] != "note"]
+    assert body[1]["content"]["error"] == {"type": "RuntimeError", "message": "no such city"}
+
+
+def test_declared_tools_cover_the_agent(recorder):
+    mw = SignafaideMiddleware(agent="support-bot", tools=[get_weather, refund])
+    agent = create_agent(model_calling(("get_weather", {"city": "Rome"})), tools=[get_weather, refund], middleware=[mw])
+    agent.invoke({"messages": [("user", "weather")]})
+    notes = [r["envelope"]["name"] for r in records(recorder, "support-bot") if r["envelope"]["kind"] == "note"]
+    # refund was never called, and is still declared as one of the agent's recorded tools.
+    assert "signafaide.tool/refund" in notes and "signafaide.tool/get_weather" in notes
+    assert not [n for n in notes if n.startswith("signafaide.tool_unrecorded/")]
+
+
+def test_recording_seam_has_the_shape_this_package_uses():
+    spec = inspect.signature(decorator._Spec)
+    assert list(spec.parameters)[:4] == ["name", "agent", "strict", "store_content"] and "listed" in spec.parameters
+    for fn in (decorator._Spec.call, decorator._Spec.acall):
+        assert list(inspect.signature(fn).parameters) == ["self", "args", "fn", "output"]
+
+
+def test_handled_tool_error_stays_visible_in_the_record():
+    from langchain_core.messages import ToolMessage
+
+    from langchain_signafaide.middleware import _tool_output
+
+    assert _tool_output(ToolMessage(content="ok", tool_call_id="c1")) == "ok"
+    assert _tool_output(ToolMessage(content="boom", tool_call_id="c1", status="error")) == {"tool_error": "boom"}