taisce-langgraph 0.1.0__tar.gz

taisce_langgraph-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: taisce-langgraph
+Version: 0.1.0
+Summary: LangGraph adapter for Taisce: agent middleware that injects governed memory as one untrusted human message and records the turn afterwards.
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: taisce>=0.1.0
+Requires-Dist: langchain>=1.0
+Requires-Dist: langgraph>=1.0
+Requires-Dist: langchain-core>=1.0
+
+# taisce-langgraph
+
+LangGraph has no context-provider interface; its seam is agent middleware. `TaisceMemory` is an
+`AgentMiddleware` for `create_agent`: before each model call it injects memory as one human message
+marked untrusted, and after the agent run it records the person's message and the assistant's final
+reply. Tool calls, tool results and the injected message are never stored. Recall failure is not
+fatal; a failed store raises. Held to the conformance suite through
+`python -m taisce_langgraph.conformance`.

taisce_langgraph-0.1.0/README.md

@@ -0,0 +1,8 @@
+# taisce-langgraph
+
+LangGraph has no context-provider interface; its seam is agent middleware. `TaisceMemory` is an
+`AgentMiddleware` for `create_agent`: before each model call it injects memory as one human message
+marked untrusted, and after the agent run it records the person's message and the assistant's final
+reply. Tool calls, tool results and the injected message are never stored. Recall failure is not
+fatal; a failed store raises. Held to the conformance suite through
+`python -m taisce_langgraph.conformance`.

taisce_langgraph-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "taisce-langgraph"
+version = "0.1.0"
+description = "LangGraph adapter for Taisce: agent middleware that injects governed memory as one untrusted human message and records the turn afterwards."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = ["taisce>=0.1.0", "langchain>=1.0", "langgraph>=1.0", "langchain-core>=1.0"]
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["taisce_langgraph*"]

taisce_langgraph-0.1.0/setup.cfg

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

taisce_langgraph-0.1.0/taisce_langgraph/__init__.py

@@ -0,0 +1,6 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+"""LangGraph adapter for Taisce."""
+from .memory import UNTRUSTED_KEY, TaisceMemory, turn_messages
+
+__all__ = ["TaisceMemory", "UNTRUSTED_KEY", "turn_messages"]

taisce_langgraph-0.1.0/taisce_langgraph/conformance.py

@@ -0,0 +1,139 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+"""The conformance driver: the middleware wrapped in the subprocess protocol the suite speaks.
+
+The agent is LangGraph's own ``create_agent`` with the middleware attached and one tool; the model
+is a scripted chat model that records what it was handed and answers the turn's reply, calling the
+tool first when the turn has tool calls, or fails when the turn says so.
+
+    python -m taisce_langgraph.conformance
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from typing import Any, List, Optional
+
+import httpx
+from langchain.agents import create_agent
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
+from langchain_core.tools import tool
+from pydantic import PrivateAttr
+
+from taisce import Client
+from taisce_langgraph import UNTRUSTED_KEY, TaisceMemory
+
+
+@tool
+def act(call: str) -> str:
+    """Performs the call the turn scripted and answers its result."""
+    return _RESULTS.get(call, "")
+
+
+_RESULTS: dict = {}
+
+
+class ScriptedModel(BaseChatModel):
+    """Records what it was handed on the first call, then follows the turn's script.
+
+    The report is a private attribute rather than a field: a field holding a dict is validated
+    into a copy, and a copy is where the record of what the model saw would silently go."""
+
+    turn: dict
+    _report: dict = PrivateAttr(default_factory=dict)
+    _calls: int = PrivateAttr(default=0)
+
+    def attach(self, report: dict) -> "ScriptedModel":
+        self._report = report
+        return self
+
+    @property
+    def _llm_type(self) -> str:
+        return "scripted"
+
+    def _generate(self, messages: List[BaseMessage], stop: Optional[List[str]] = None, run_manager: Any = None, **kwargs: Any) -> ChatResult:
+        if self._calls == 0:
+            self._report["model_messages"] = [
+                {"role": _role(m), "content": _text(m), "untrusted": bool((m.additional_kwargs or {}).get(UNTRUSTED_KEY))}
+                for m in messages
+            ]
+        self._calls += 1
+        if self.turn.get("model_failure"):
+            raise RuntimeError("the model failed")
+        tool_calls = self.turn.get("tool_calls") or []
+        if self._calls <= len(tool_calls):
+            call = tool_calls[self._calls - 1]
+            message = AIMessage(content="", tool_calls=[{"name": "act", "args": {"call": call["call"]}, "id": f"call-{self._calls}"}])
+        else:
+            message = AIMessage(content=self.turn.get("assistant") or "")
+        return ChatResult(generations=[ChatGeneration(message=message)])
+
+    def bind_tools(self, tools: Any, **kwargs: Any) -> "ScriptedModel":
+        return self
+
+
+def _role(m: BaseMessage) -> str:
+    return {"human": "user", "ai": "assistant", "system": "system", "tool": "tool"}.get(m.type, m.type)
+
+
+def _text(m: BaseMessage) -> str:
+    return m.content if isinstance(m.content, str) else "".join(p.get("text", "") if isinstance(p, dict) else str(p) for p in m.content)
+
+
+async def run_turn(instruction: dict) -> dict:
+    report: dict = {"model_messages": [], "fatal": False, "observed": False}
+    turn = instruction["turn"]
+    _RESULTS.clear()
+    for call in turn.get("tool_calls") or []:
+        _RESULTS[call["call"]] = call["result"]
+
+    async def saw_request(request: httpx.Request) -> None:
+        if request.method == "POST" and request.url.path.endswith("/observations"):
+            report["observed"] = True
+
+    http = httpx.AsyncClient(timeout=10.0, event_hooks={"request": [saw_request]})
+    client = Client(instruction["api"], instruction["token"], http=http)
+
+    def on_error(stage: str, exc: Exception) -> None:
+        # Stderr is the driver's own: a swallowed recall failure is still worth a line for a person.
+        sys.stderr.write(f"{instruction['case']}: {stage} failed: {exc!r}\n")
+        if stage == "observe":
+            report["store_error"] = str(exc)
+
+    # When the turn arms compaction, any history at all trips it.
+    memory = TaisceMemory(client, data_subject_id=instruction.get("data_subject_id"), run_id=instruction["case"], on_error=on_error,
+                          compact_after_messages=1 if turn.get("compact") else None)
+    model = ScriptedModel(turn=turn).attach(report)
+    agent = create_agent(model, tools=[act], middleware=[memory])
+    # The history is the state the application's graph already holds; here it enters with the
+    # turn's input, which is where LangGraph puts an existing conversation.
+    messages: List[BaseMessage] = [AIMessage(content=m["content"]) if m["role"] == "assistant" else HumanMessage(content=m["content"])
+                                   for m in (turn.get("history") or []) + (turn.get("synthetic") or [])]
+    messages.append(HumanMessage(content=turn["user"]))
+    try:
+        await agent.ainvoke({"messages": messages})
+    except Exception:  # noqa: BLE001 - the run's error reaches the application; which it was is in the report
+        report["fatal"] = "store_error" not in report
+    finally:
+        await http.aclose()
+    return report
+
+
+async def main() -> int:
+    loop = asyncio.get_running_loop()
+    while True:
+        line = await loop.run_in_executor(None, sys.stdin.readline)
+        if not line:
+            return 0
+        if not line.strip():
+            continue
+        report = await run_turn(json.loads(line))
+        sys.stdout.write(json.dumps(report) + "\n")
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main()))

taisce_langgraph-0.1.0/taisce_langgraph/memory.py

@@ -0,0 +1,166 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+"""The memory middleware: recall before the model call, observe after the agent run.
+
+LangGraph's agent has no context-provider interface; what it has is middleware around the model
+call and around the agent run, and that is the seam this maps onto, with nothing of its own.
+
+**The role rule.** Memory is injected into the model request as one ``HumanMessage`` marked
+untrusted in its ``additional_kwargs``, never as a ``SystemMessage``: the same bytes as a system
+message are instructions the model obeys, and every memory is something somebody said once. It is
+injected into the request only, not into the graph's state, so it is never persisted as history
+and never stored as though a person said it.
+
+**Failure policy is asymmetric.** A recall that cannot reach the deployment injects nothing and
+raises nothing; the agent runs without memory. A failed store raises, because a lost turn is
+invisible until a subject access request asks for it.
+
+**Store only on success, and only what people said.** ``aafter_agent`` runs when the agent run
+completed; a model that raised never reaches it. What is stored is the last human message and the
+assistant messages after it that carry text and no tool calls; tool messages, tool-calling
+messages and anything before the human message, which the framework or an earlier turn wrote, are
+not this turn's memory.
+
+**Compaction is replacement, in the state, the way the framework's own summarisation middleware
+works.** When ``compact_after_messages`` is set and the state holds more non-system messages than
+that, ``abefore_model`` asks the deployment for the subject's context and rewrites the state with
+the framework's remove-all message: the system messages, one untrusted ``HumanMessage`` carrying
+the context unchanged, and the person's current message. Nothing is summarised here; a context
+that cannot be fetched leaves the state as it was and reports.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Callable, List, Optional, Sequence
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, RemoveMessage, SystemMessage
+from langgraph.graph.message import REMOVE_ALL_MESSAGES
+
+from taisce import Client, bundle_is_empty
+from taisce.memory import is_memory_text, render_context_message, render_memory_message, turn_key
+
+#: The key under which the injected message is marked untrusted in its additional kwargs.
+UNTRUSTED_KEY = "taisce.untrusted"
+
+
+class TaisceMemory(AgentMiddleware):
+    """Injects governed memory before each model call and records the turn after the run."""
+
+    def __init__(
+        self,
+        client: Client,
+        *,
+        data_subject_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        max_characters: Optional[int] = None,
+        source_roles: Optional[Sequence[str]] = None,
+        on_error: Optional[Callable[[str, Exception], None]] = None,
+        compact_after_messages: Optional[int] = None,
+    ) -> None:
+        super().__init__()
+        if compact_after_messages is not None:
+            if compact_after_messages <= 0:
+                raise ValueError("compact_after_messages must be positive: it is the history length that triggers compaction")
+            if not data_subject_id or not data_subject_id.strip():
+                raise ValueError("a data subject is required to compact: a context is one subject's history")
+        self._client = client
+        self._data_subject_id = data_subject_id
+        self._run_id = run_id
+        self._max_characters = max_characters
+        self._source_roles = list(source_roles) if source_roles else None
+        self._on_error = on_error
+        self._compact_after = compact_after_messages
+
+    async def abefore_model(self, state: Any, runtime: Any) -> Optional[dict]:
+        if self._compact_after is None:
+            return None
+        messages = list(state.get("messages") or [])
+        if sum(1 for m in messages if not isinstance(m, SystemMessage)) <= self._compact_after:
+            return None
+        at = _last_human_index(messages)
+        if at >= len(messages):
+            return None
+        try:
+            assembled = await self._client.context(data_subject_id=self._data_subject_id, max_characters=self._max_characters)
+        except Exception as exc:  # noqa: BLE001 - swallowed by design, see the module docstring
+            self._report("context", exc)
+            return None
+        memory = HumanMessage(content=render_context_message(assembled), name="taisce", additional_kwargs={UNTRUSTED_KEY: True})
+        kept = [m for m in messages[:at] if isinstance(m, SystemMessage)]
+        return {"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES), *kept, memory, *messages[at:]]}
+
+    async def awrap_model_call(self, request: Any, handler: Any) -> Any:
+        question = _last_human_text(request.messages)
+        if not question:
+            return await handler(request)
+        try:
+            watermark = await self._client.freshness()
+            bundle = await self._client.recall(
+                question=question, data_subject_id=self._data_subject_id,
+                max_characters=self._max_characters, source_roles=self._source_roles)
+        except Exception as exc:  # noqa: BLE001 - swallowed by design, see the module docstring
+            self._report("recall", exc)
+            return await handler(request)
+        if bundle_is_empty(bundle):
+            return await handler(request)
+        rendered = render_memory_message(
+            {"stored": watermark.stored, "formed": watermark.formed, "parked": watermark.parked}, bundle)
+        memory = HumanMessage(content=rendered, name="taisce", additional_kwargs={UNTRUSTED_KEY: True})
+        # Before the person's last message, so the model reads memory and then the question.
+        messages = list(request.messages)
+        at = _last_human_index(messages)
+        messages.insert(at, memory)
+        return await handler(request.override(messages=messages))
+
+    async def aafter_agent(self, state: Any, runtime: Any) -> Optional[dict]:
+        messages = turn_messages(state.get("messages") or [])
+        if not messages:
+            return None
+        try:
+            await self._client.observe(
+                idempotency_key=turn_key(self._data_subject_id, self._run_id, messages),
+                messages=messages, data_subject_id=self._data_subject_id,
+                occurred_at=datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"))
+        except Exception as exc:  # noqa: BLE001 - reported, then raised
+            self._report("observe", exc)
+            raise
+        return None
+
+    def _report(self, stage: str, exc: Exception) -> None:
+        if self._on_error is not None:
+            self._on_error(stage, exc)
+
+
+def turn_messages(messages: Sequence[BaseMessage]) -> List[dict]:
+    """The turn as the deployment stores it: the last human message and the assistant's own words
+    after it. A tool message is the tool talking; an assistant message with tool calls is the
+    model talking to a tool; neither is something a person said."""
+    at = _last_human_index(list(messages))
+    if at >= len(messages):
+        return []
+    out = [{"role": "user", "content": _text(messages[at])}]
+    for m in messages[at + 1:]:
+        if isinstance(m, AIMessage) and not m.tool_calls and _text(m).strip():
+            out.append({"role": "assistant", "content": _text(m)})
+    return out
+
+
+def _text(message: BaseMessage) -> str:
+    content = message.content
+    if isinstance(content, str):
+        return content
+    return "".join(part.get("text", "") if isinstance(part, dict) else str(part) for part in content)
+
+
+def _last_human_index(messages: List[BaseMessage]) -> int:
+    for i in range(len(messages) - 1, -1, -1):
+        m = messages[i]
+        if isinstance(m, HumanMessage) and not is_memory_text(_text(m)) and _text(m).strip():
+            return i
+    return len(messages)
+
+
+def _last_human_text(messages: Sequence[BaseMessage]) -> str:
+    at = _last_human_index(list(messages))
+    return _text(messages[at]).strip() if at < len(messages) else ""

taisce_langgraph-0.1.0/taisce_langgraph.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: taisce-langgraph
+Version: 0.1.0
+Summary: LangGraph adapter for Taisce: agent middleware that injects governed memory as one untrusted human message and records the turn afterwards.
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: taisce>=0.1.0
+Requires-Dist: langchain>=1.0
+Requires-Dist: langgraph>=1.0
+Requires-Dist: langchain-core>=1.0
+
+# taisce-langgraph
+
+LangGraph has no context-provider interface; its seam is agent middleware. `TaisceMemory` is an
+`AgentMiddleware` for `create_agent`: before each model call it injects memory as one human message
+marked untrusted, and after the agent run it records the person's message and the assistant's final
+reply. Tool calls, tool results and the injected message are never stored. Recall failure is not
+fatal; a failed store raises. Held to the conformance suite through
+`python -m taisce_langgraph.conformance`.

taisce_langgraph-0.1.0/taisce_langgraph.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+taisce_langgraph/__init__.py
+taisce_langgraph/conformance.py
+taisce_langgraph/memory.py
+taisce_langgraph.egg-info/PKG-INFO
+taisce_langgraph.egg-info/SOURCES.txt
+taisce_langgraph.egg-info/dependency_links.txt
+taisce_langgraph.egg-info/requires.txt
+taisce_langgraph.egg-info/top_level.txt
+tests/test_compaction_middleware.py
+tests/test_memory.py

taisce_langgraph-0.1.0/taisce_langgraph.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

taisce_langgraph-0.1.0/taisce_langgraph.egg-info/requires.txt

@@ -0,0 +1,4 @@
+taisce>=0.1.0
+langchain>=1.0
+langgraph>=1.0
+langchain-core>=1.0

taisce_langgraph-0.1.0/taisce_langgraph.egg-info/top_level.txt

@@ -0,0 +1 @@
+taisce_langgraph

taisce_langgraph-0.1.0/tests/test_compaction_middleware.py

@@ -0,0 +1,51 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+"""What holds without a deployment: the state rewrite a compaction returns. The rest is held by the
+conformance suite."""
+import pytest
+from langchain_core.messages import AIMessage, HumanMessage, RemoveMessage, SystemMessage
+from langgraph.graph.message import REMOVE_ALL_MESSAGES
+
+from taisce import Client, MEMORY_MESSAGE_PREFIX
+from taisce_langgraph import TaisceMemory, UNTRUSTED_KEY
+
+
+class _ContextClient:
+    def __init__(self, answer=None, error=None):
+        self.answer, self.error, self.calls = answer, error, 0
+
+    async def context(self, *, data_subject_id, max_characters=None):
+        self.calls += 1
+        if self.error:
+            raise self.error
+        return self.answer
+
+
+def test_compaction_needs_a_subject_and_a_positive_trigger():
+    client = Client("http://127.0.0.1:1", "tsk")
+    with pytest.raises(ValueError):
+        TaisceMemory(client, compact_after_messages=8)
+    with pytest.raises(ValueError):
+        TaisceMemory(client, data_subject_id="s", compact_after_messages=0)
+    assert TaisceMemory(client, data_subject_id="s", compact_after_messages=8) is not None
+
+
+@pytest.mark.asyncio
+async def test_the_state_is_rewritten_as_system_messages_the_context_and_the_persons_message():
+    history = [SystemMessage(content="Be brief."), HumanMessage(content="old one"), AIMessage(content="old reply"), HumanMessage(content="now?")]
+    client = _ContextClient(answer={"watermark": {"stored": 3}, "segments": [{"summary": "It began."}], "turns": [], "characters": 9, "truncated": False})
+    update = await TaisceMemory(client, data_subject_id="s", compact_after_messages=1).abefore_model({"messages": history}, None)
+    messages = update["messages"]
+    assert isinstance(messages[0], RemoveMessage) and messages[0].id == REMOVE_ALL_MESSAGES
+    assert messages[1].content == "Be brief."
+    assert isinstance(messages[2], HumanMessage) and messages[2].content.startswith(MEMORY_MESSAGE_PREFIX) and messages[2].additional_kwargs[UNTRUSTED_KEY] is True
+    assert messages[3].content == "now?" and len(messages) == 4
+    # Under the trigger, or with no person's message, nothing is rewritten; a failing deployment leaves the state as it was.
+    idle = _ContextClient()
+    assert await TaisceMemory(idle, data_subject_id="s", compact_after_messages=8).abefore_model({"messages": history}, None) is None
+    assert await TaisceMemory(idle, data_subject_id="s", compact_after_messages=1).abefore_model({"messages": [AIMessage(content="a"), AIMessage(content="b")]}, None) is None
+    assert idle.calls == 0
+    seen = []
+    broken = _ContextClient(error=RuntimeError("down"))
+    assert await TaisceMemory(broken, data_subject_id="s", compact_after_messages=1, on_error=lambda stage, exc: seen.append(stage)).abefore_model({"messages": history}, None) is None
+    assert seen == ["context"]

taisce_langgraph-0.1.0/tests/test_memory.py

@@ -0,0 +1,30 @@
+# Copyright 2026 The Taisce Authors
+# SPDX-License-Identifier: Apache-2.0
+"""What holds without a deployment: which messages of a run become the turn. Everything the
+middleware does against a deployment is held by the conformance suite through
+``python -m taisce_langgraph.conformance``."""
+from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+
+from taisce.memory import render_memory_message
+from taisce_langgraph import turn_messages
+
+
+def test_the_turn_is_the_last_human_message_and_the_assistants_own_words_after_it():
+    memory = render_memory_message({"stored": 1}, {"facts": [{"fact_id": "f1"}]})
+    messages = [
+        AIMessage(content="Summary of earlier conversation."),
+        HumanMessage(content="Book the room for Tuesday."),
+        HumanMessage(content=memory),
+        AIMessage(content="", tool_calls=[{"name": "act", "args": {"call": "book"}, "id": "c1"}]),
+        ToolMessage(content="booked", tool_call_id="c1"),
+        AIMessage(content="Room A is booked for Tuesday."),
+    ]
+    assert turn_messages(messages) == [
+        {"role": "user", "content": "Book the room for Tuesday."},
+        {"role": "assistant", "content": "Room A is booked for Tuesday."},
+    ]
+
+
+def test_a_run_with_no_human_message_is_no_turn():
+    assert turn_messages([AIMessage(content="hello")]) == []
+    assert turn_messages([]) == []