llmsessioncontract 0.2.2__tar.gz → 0.3.0__tar.gz

{llmsessioncontract-0.2.2/llmsessioncontract.egg-info → llmsessioncontract-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llmsessioncontract
-Version: 0.2.2
+Version: 0.3.0
 Summary: Runtime monitor for LLM agent interaction protocols based on session type theory
 Author-email: Chris Bartolo Burlo <chris@mizziburlo.com>
 License-Expression: MIT
@@ -23,8 +23,12 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: langfuse
 Requires-Dist: langfuse>=3.0.0; extra == "langfuse"
+Provides-Extra: langchain
+Requires-Dist: langchain>=1.0.0; extra == "langchain"
+Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
 Dynamic: license-file
 
 # llmcontract
@@ -230,6 +234,80 @@ while True:
         messages.append(tool_result_msg(tc.id, result))
 ```
 
+## LangChain Integration (`llmcontract.langchain`, 0.3.0+)
+
+A focused FSM-as-data API for users who want to wire protocol monitoring
+into LangChain agents without touching the DSL parser. Tool references
+are real Python callables, transitions are explicit objects with
+optional guards and actions, and violation handling is fully
+user-controlled.
+
+```bash
+pip install llmsessioncontract[langchain]
+```
+
+```python
+from langchain_core.tools import tool
+from langchain.agents import create_agent
+from llmcontract.langchain import (
+    ProtocolFSM, Transition, ProtocolMonitor,
+    ProtocolEnforcerMiddleware, ViolationEvent,
+    ProtocolViolationError, ref,
+)
+
+@tool
+def search(query: str) -> str:
+    """Search for available flights."""
+    return f"Results for: {query}"
+
+@tool
+def book(result: str) -> str:
+    """Book a selected flight."""
+    return f"Booked: {result}"
+
+search_ref = ref(search)
+book_ref = ref(book)
+
+fsm = (
+    ProtocolFSM(initial="idle")
+    .add_transition(Transition(source="idle", tool=search_ref, phase="send", target="searching"))
+    .add_transition(Transition(source="searching", tool=search_ref, phase="recv", target="results"))
+    .add_transition(Transition(source="results", tool=book_ref, phase="send", target="booking",
+                               guard=lambda ctx: bool(ctx.metadata.get("args", {}))))
+    .add_transition(Transition(source="booking", tool=book_ref, phase="recv", target="done"))
+    .mark_terminal("done")
+)
+
+def on_violation(v: ViolationEvent) -> None:
+    raise ProtocolViolationError(f"Illegal {v.phase}:{v.tool_ref.label} from {v.current_state!r}", violation=v)
+
+monitor = ProtocolMonitor(fsm=fsm, on_violation=on_violation)
+middleware = ProtocolEnforcerMiddleware(monitor=monitor, tool_refs=[search_ref, book_ref]).middleware
+
+agent = create_agent(model=..., tools=[search, book], middleware=[middleware])
+agent.invoke({"messages": [("user", "Book me a flight to Rome.")]})
+
+print(monitor.state)        # → "done"
+print(monitor.is_complete()) # → True
+print(monitor.trace)        # → ["send:search", "recv:search", "send:book", "recv:book"]
+```
+
+When to pick this over the DSL `Monitor`:
+
+- You're already in a LangChain stack and want a drop-in `AgentMiddleware`
+- You need per-transition guards and actions (e.g., audit logs, business rules)
+- You want enforcement (block tool calls), not just observation
+- You don't need recursion / choice / `Unrecognized` from the DSL
+
+When to stick with the DSL `Monitor`:
+
+- You want to write protocols as concise strings (`!Search.?Result.end`)
+- You need recursion or compositional choice
+- You're outside LangChain (Anthropic SDK, OpenAI SDK, custom loop)
+- You want first-class natural-language ambiguity via `Unrecognized`
+
+Worked example: [`examples/langchain_booking/booking_agent_submodule.py`](examples/langchain_booking/booking_agent_submodule.py).
+
 ## Langfuse Integration
 
 Track protocol compliance in [Langfuse](https://langfuse.com) — every send/receive is recorded as a guardrail observation with a pass/fail score.
@@ -280,7 +358,8 @@ The skill validates each draft DSL against `llmcontract`'s parser, so anything i
 
 ## Case Studies
 
-- **[`llmcontract-tau2`](https://github.com/chrisbartoloburlo/llmcontract-tau2)** — Standalone replay of [tau2-bench](https://github.com/sierra-research/tau2-bench)'s shipped trajectories through `Monitor`. Headline: 11/1755 (0.6%) of trajectories that tau2 scored as passing violate the documented "obtain user confirmation before mutating the database" policy. Discussion upstream: [tau2-bench#298](https://github.com/sierra-research/tau2-bench/issues/298).
+- **[`llmcontract-tau2`](https://github.com/chrisbartoloburlo/llmcontract-tau2)** — *user ↔ agent layer.* Standalone replay of [tau2-bench](https://github.com/sierra-research/tau2-bench)'s shipped trajectories through `Monitor`. Headline: 11/1755 (0.6%) of trajectories that tau2 scored as passing violate the documented "obtain user confirmation before mutating the database" policy. Discussion upstream: [tau2-bench#298](https://github.com/sierra-research/tau2-bench/issues/298).
+- **[`llmcontract-playwright-mcp`](https://github.com/chrisbartoloburlo/llmcontract-playwright-mcp)** — *agent ↔ tool layer.* 90-trajectory sweep across Claude Haiku 4.5 / Sonnet 4.6 / Opus 4.7 driving [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp), checked against two invariants from the server's documented usage. Headline: 9% violate `snap-before-interact`, 29% violate `stay-on-snapshot-refs` — and the failure modes scale opposite directions with model capability (Haiku snapshots religiously but ignores the snapshot 57% of the time; Opus skips the snapshot 13% of the time but follows through cleanly when it commits).
 
 ## Research
 

{llmsessioncontract-0.2.2 → llmsessioncontract-0.3.0}/README.md

@@ -201,6 +201,80 @@ while True:
         messages.append(tool_result_msg(tc.id, result))
 ```
 
+## LangChain Integration (`llmcontract.langchain`, 0.3.0+)
+
+A focused FSM-as-data API for users who want to wire protocol monitoring
+into LangChain agents without touching the DSL parser. Tool references
+are real Python callables, transitions are explicit objects with
+optional guards and actions, and violation handling is fully
+user-controlled.
+
+```bash
+pip install llmsessioncontract[langchain]
+```
+
+```python
+from langchain_core.tools import tool
+from langchain.agents import create_agent
+from llmcontract.langchain import (
+    ProtocolFSM, Transition, ProtocolMonitor,
+    ProtocolEnforcerMiddleware, ViolationEvent,
+    ProtocolViolationError, ref,
+)
+
+@tool
+def search(query: str) -> str:
+    """Search for available flights."""
+    return f"Results for: {query}"
+
+@tool
+def book(result: str) -> str:
+    """Book a selected flight."""
+    return f"Booked: {result}"
+
+search_ref = ref(search)
+book_ref = ref(book)
+
+fsm = (
+    ProtocolFSM(initial="idle")
+    .add_transition(Transition(source="idle", tool=search_ref, phase="send", target="searching"))
+    .add_transition(Transition(source="searching", tool=search_ref, phase="recv", target="results"))
+    .add_transition(Transition(source="results", tool=book_ref, phase="send", target="booking",
+                               guard=lambda ctx: bool(ctx.metadata.get("args", {}))))
+    .add_transition(Transition(source="booking", tool=book_ref, phase="recv", target="done"))
+    .mark_terminal("done")
+)
+
+def on_violation(v: ViolationEvent) -> None:
+    raise ProtocolViolationError(f"Illegal {v.phase}:{v.tool_ref.label} from {v.current_state!r}", violation=v)
+
+monitor = ProtocolMonitor(fsm=fsm, on_violation=on_violation)
+middleware = ProtocolEnforcerMiddleware(monitor=monitor, tool_refs=[search_ref, book_ref]).middleware
+
+agent = create_agent(model=..., tools=[search, book], middleware=[middleware])
+agent.invoke({"messages": [("user", "Book me a flight to Rome.")]})
+
+print(monitor.state)        # → "done"
+print(monitor.is_complete()) # → True
+print(monitor.trace)        # → ["send:search", "recv:search", "send:book", "recv:book"]
+```
+
+When to pick this over the DSL `Monitor`:
+
+- You're already in a LangChain stack and want a drop-in `AgentMiddleware`
+- You need per-transition guards and actions (e.g., audit logs, business rules)
+- You want enforcement (block tool calls), not just observation
+- You don't need recursion / choice / `Unrecognized` from the DSL
+
+When to stick with the DSL `Monitor`:
+
+- You want to write protocols as concise strings (`!Search.?Result.end`)
+- You need recursion or compositional choice
+- You're outside LangChain (Anthropic SDK, OpenAI SDK, custom loop)
+- You want first-class natural-language ambiguity via `Unrecognized`
+
+Worked example: [`examples/langchain_booking/booking_agent_submodule.py`](examples/langchain_booking/booking_agent_submodule.py).
+
 ## Langfuse Integration
 
 Track protocol compliance in [Langfuse](https://langfuse.com) — every send/receive is recorded as a guardrail observation with a pass/fail score.
@@ -251,7 +325,8 @@ The skill validates each draft DSL against `llmcontract`'s parser, so anything i
 
 ## Case Studies
 
-- **[`llmcontract-tau2`](https://github.com/chrisbartoloburlo/llmcontract-tau2)** — Standalone replay of [tau2-bench](https://github.com/sierra-research/tau2-bench)'s shipped trajectories through `Monitor`. Headline: 11/1755 (0.6%) of trajectories that tau2 scored as passing violate the documented "obtain user confirmation before mutating the database" policy. Discussion upstream: [tau2-bench#298](https://github.com/sierra-research/tau2-bench/issues/298).
+- **[`llmcontract-tau2`](https://github.com/chrisbartoloburlo/llmcontract-tau2)** — *user ↔ agent layer.* Standalone replay of [tau2-bench](https://github.com/sierra-research/tau2-bench)'s shipped trajectories through `Monitor`. Headline: 11/1755 (0.6%) of trajectories that tau2 scored as passing violate the documented "obtain user confirmation before mutating the database" policy. Discussion upstream: [tau2-bench#298](https://github.com/sierra-research/tau2-bench/issues/298).
+- **[`llmcontract-playwright-mcp`](https://github.com/chrisbartoloburlo/llmcontract-playwright-mcp)** — *agent ↔ tool layer.* 90-trajectory sweep across Claude Haiku 4.5 / Sonnet 4.6 / Opus 4.7 driving [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp), checked against two invariants from the server's documented usage. Headline: 9% violate `snap-before-interact`, 29% violate `stay-on-snapshot-refs` — and the failure modes scale opposite directions with model capability (Haiku snapshots religiously but ignores the snapshot 57% of the time; Opus skips the snapshot 13% of the time but follows through cleanly when it commits).
 
 ## Research
 

llmsessioncontract-0.3.0/llmcontract/langchain/__init__.py

@@ -0,0 +1,43 @@
+"""LangChain-native protocol enforcement for ``llmcontract``.
+
+A focused, FSM-as-data API for users who want to wire protocol monitoring
+into LangChain agents with no DSL parsing and no magic strings. Tool
+references are real Python callables; transitions are explicit objects
+with optional guards and actions; violation handling is fully
+user-controlled.
+
+The full design and rationale live at
+https://llmcontract.dev/findings/ and in the project README.
+
+Submodules:
+    tool_ref     ToolRef, ref()
+    fsm          ProtocolFSM, Transition, MonitorContext, ViolationEvent
+    monitor      ProtocolMonitor
+    middleware   ProtocolEnforcerMiddleware
+    exceptions   ProtocolViolationError
+"""
+
+from llmcontract.langchain.exceptions import ProtocolViolationError
+from llmcontract.langchain.fsm import (
+    MonitorContext,
+    ProtocolFSM,
+    Transition,
+    ViolationEvent,
+    ViolationHandler,
+)
+from llmcontract.langchain.middleware import ProtocolEnforcerMiddleware
+from llmcontract.langchain.monitor import ProtocolMonitor
+from llmcontract.langchain.tool_ref import ToolRef, ref
+
+__all__ = [
+    "ToolRef",
+    "ref",
+    "ProtocolFSM",
+    "Transition",
+    "MonitorContext",
+    "ViolationEvent",
+    "ViolationHandler",
+    "ProtocolMonitor",
+    "ProtocolEnforcerMiddleware",
+    "ProtocolViolationError",
+]

llmsessioncontract-0.3.0/llmcontract/langchain/exceptions.py

@@ -0,0 +1,26 @@
+"""Exception type for protocol violations.
+
+The library never raises this itself — it is provided as a convenience for
+``on_violation`` callbacks that want to halt execution by raising. The
+runtime decision of *what* to do on a violation belongs to the user, not
+to the library.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from llmcontract.langchain.fsm import ViolationEvent
+
+
+class ProtocolViolationError(RuntimeError):
+    """Convenience exception for use in ``on_violation`` callbacks.
+
+    The library never raises this itself. Construct and raise it inside
+    your handler if you want a violation to abort the agent invocation.
+    """
+
+    def __init__(self, message: str, violation: "ViolationEvent") -> None:
+        super().__init__(message)
+        self.violation = violation

llmsessioncontract-0.3.0/llmcontract/langchain/fsm.py

@@ -0,0 +1,184 @@
+"""Pure finite-state-machine protocol definition.
+
+This module has zero LangChain imports. ``ProtocolFSM`` is an explicit
+transition table you build via ``add_transition`` calls; it has no notion
+of recursion, choice, or any other DSL primitive — those compose by
+hand from individual ``Transition`` edges.
+
+State is held entirely in ``ProtocolMonitor`` (a sibling module). The FSM
+itself is immutable after the developer finishes adding transitions and
+marking terminal states.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from llmcontract.langchain.tool_ref import ToolRef
+
+
+# ── Per-step contextual data ────────────────────────────────
+
+
+@dataclass
+class MonitorContext:
+    """Transient data passed to ``guard``/``action`` callables and embedded
+    in ``ViolationEvent``. Built fresh by the monitor for each transition
+    attempt; do not retain references."""
+
+    current_state: str
+    """FSM state *before* the transition attempt."""
+
+    event: str
+    """Full event string, e.g. ``"send:search"``."""
+
+    tool_ref: ToolRef
+    """The ``ToolRef`` whose call triggered this event."""
+
+    phase: str
+    """Either ``"send"`` (tool call about to run) or ``"recv"`` (result returned)."""
+
+    trace: list[str]
+    """Snapshot copy of all events fired so far. Mutating this list does
+    not affect the monitor's internal trace."""
+
+    metadata: dict[str, Any] = field(default_factory=dict)
+    """Per-phase context — tool ``args`` on ``send`` events, tool
+    ``result`` on ``recv`` events. The library does not interpret it;
+    it's threaded through to user-supplied guards and actions."""
+
+
+@dataclass
+class ViolationEvent:
+    """Argument passed to the user's ``on_violation`` callback when a
+    transition cannot fire (no rule matches, or a guard returned
+    ``False``)."""
+
+    current_state: str
+    event: str
+    expected: list[str]
+    """Event strings that *would* have been valid from ``current_state``.
+    May be empty if no transitions are defined from this state."""
+    trace: list[str]
+    """All events fired so far, *including* the violating one."""
+    tool_ref: ToolRef
+    phase: str
+
+
+ViolationHandler = Callable[[ViolationEvent], None]
+
+
+# ── Transitions ─────────────────────────────────────────────
+
+
+_VALID_PHASES = ("send", "recv")
+
+
+@dataclass
+class Transition:
+    """One edge in the FSM graph.
+
+    ``event`` is computed from ``phase`` and ``tool.label``; it must not
+    be assigned by the developer. ``guard`` (if set) decides whether the
+    edge fires; ``action`` (if set) runs as a side effect when the edge
+    commits.
+    """
+
+    source: str
+    tool: ToolRef
+    phase: str
+    target: str
+    guard: Callable[[MonitorContext], bool] | None = None
+    action: Callable[[MonitorContext], None] | None = None
+
+    def __post_init__(self) -> None:
+        if self.phase not in _VALID_PHASES:
+            raise ValueError(
+                f"Transition.phase must be one of {_VALID_PHASES!r}; "
+                f"got {self.phase!r}"
+            )
+
+    @property
+    def event(self) -> str:
+        """The lookup key for this transition: ``"<phase>:<tool.label>"``.
+        Always recomputed; never stored — keeps correctness if internals
+        of ``ToolRef`` ever shift.
+        """
+        return f"{self.phase}:{self.tool.label}"
+
+
+# ── The FSM ─────────────────────────────────────────────────
+
+
+class ProtocolFSM:
+    """Pure FSM definition — initial state, transition table, terminal
+    set. No reference to LangChain or to monitor state.
+
+    ``step()`` is the workhorse: given a current state and an incoming
+    event, it consults the table, runs any guard, fires any action, and
+    returns ``(next_state, ok)``. Failures (no rule, or guard rejected)
+    return ``(state, False)`` — the monitor decides what to do with that.
+    """
+
+    def __init__(self, initial: str) -> None:
+        self.initial: str = initial
+        # Indexed by (source_state, event_string) for O(1) lookup.
+        self._transitions: dict[tuple[str, str], Transition] = {}
+        self._terminal: set[str] = set()
+
+    # ── Building the FSM (fluent) ────────────────────────────
+
+    def add_transition(self, t: Transition) -> "ProtocolFSM":
+        """Register a transition. Returns ``self`` so calls chain.
+
+        Raises ``ValueError`` if a transition with the same
+        ``(source, event)`` already exists — duplicates would make the
+        FSM non-deterministic, which we forbid by construction.
+        """
+        key = (t.source, t.event)
+        if key in self._transitions:
+            raise ValueError(
+                f"duplicate transition for state={t.source!r}, "
+                f"event={t.event!r}"
+            )
+        self._transitions[key] = t
+        return self
+
+    def mark_terminal(self, *states: str) -> "ProtocolFSM":
+        """Flag one or more states as protocol-complete. Returns ``self``."""
+        self._terminal.update(states)
+        return self
+
+    # ── Querying the FSM ─────────────────────────────────────
+
+    def valid_events(self, state: str) -> list[str]:
+        """All event strings with a registered transition out of ``state``.
+        Returns ``[]`` when ``state`` is unknown or has no outgoing edges.
+        """
+        return [event for (src, event) in self._transitions if src == state]
+
+    def step(
+        self,
+        state: str,
+        event: str,
+        ctx: MonitorContext,
+    ) -> tuple[str, bool]:
+        """Try to fire transition ``(state, event)``.
+
+        On success: run the action (if any), return ``(target, True)``.
+        On failure: return ``(state, False)`` *without* mutating anything.
+        Calling ``on_violation`` is the monitor's responsibility, not the
+        FSM's — keeping the FSM pure makes it trivially unit-testable.
+        """
+        transition = self._transitions.get((state, event))
+        if transition is None:
+            return state, False
+        if transition.guard is not None and not transition.guard(ctx):
+            return state, False
+        if transition.action is not None:
+            transition.action(ctx)
+        return transition.target, True
+
+    def is_terminal(self, state: str) -> bool:
+        return state in self._terminal

llmsessioncontract-0.3.0/llmcontract/langchain/middleware.py

@@ -0,0 +1,111 @@
+"""LangChain integration: a thin ``AgentMiddleware`` that drives a
+``ProtocolMonitor`` from ``wrap_tool_call`` / ``awrap_tool_call``.
+
+This is the only module in the submodule that imports LangChain. The
+FSM, the monitor, and ``ToolRef`` are all framework-agnostic; they can
+be unit-tested in isolation without LangChain installed.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable
+
+from llmcontract.langchain.monitor import ProtocolMonitor
+from llmcontract.langchain.tool_ref import ToolRef
+
+
+class ProtocolEnforcerMiddleware:
+    """LangChain ``AgentMiddleware`` that fires ``send`` and ``recv``
+    transitions on the wrapped monitor for every registered tool call.
+
+    Construction does the import-and-subclass dance against LangChain's
+    ``AgentMiddleware`` lazily so the rest of the package stays
+    importable without LangChain. The actual middleware object exposed
+    via ``.middleware`` is a real ``AgentMiddleware`` subclass instance
+    that you pass to ``create_agent(middleware=[...])``.
+    """
+
+    def __init__(
+        self,
+        monitor: ProtocolMonitor,
+        tool_refs: list[ToolRef],
+    ) -> None:
+        self._monitor = monitor
+        # The only place tool *name strings* surface inside the library —
+        # we look up by the name LangChain hands us in the request, so
+        # the developer never has to write or see a string.
+        self._ref_by_label: dict[str, ToolRef] = {t.label: t for t in tool_refs}
+        self._impl = self._build_impl()
+
+    @property
+    def middleware(self) -> Any:
+        """The ``AgentMiddleware`` subclass instance to pass to
+        ``create_agent(middleware=[...])``."""
+        return self._impl
+
+    # ── Build the real AgentMiddleware subclass instance ────
+
+    def _build_impl(self) -> Any:
+        # Imports happen here, not at module load — keeps the rest of
+        # the langchain submodule usable in environments without
+        # langchain installed.
+        from langchain.agents.middleware import AgentMiddleware
+
+        outer = self  # captured by closure into the methods below
+
+        class _Impl(AgentMiddleware):
+            def wrap_tool_call(self, request, handler):  # type: ignore[override]
+                return outer._dispatch_sync(request, handler)
+
+            async def awrap_tool_call(self, request, handler):  # type: ignore[override]
+                return await outer._dispatch_async(request, handler)
+
+        return _Impl()
+
+    # ── Sync and async dispatch share one logical body ──────
+
+    def _dispatch_sync(
+        self,
+        request: Any,
+        handler: Callable[[Any], Any],
+    ) -> Any:
+        name = request.tool_call["name"]
+        tool_ref = self._ref_by_label.get(name)
+        if tool_ref is None:
+            # Tool isn't registered in this protocol — pass through
+            # unmonitored. Partial protocol coverage is a valid use case
+            # (e.g., monitoring only the booking subset of a larger tool
+            # surface).
+            return handler(request)
+
+        args = request.tool_call.get("args", {}) or {}
+        self._monitor.transition(tool_ref, phase="send", metadata={"args": args})
+
+        # Tool exception path: let it propagate. We deliberately do NOT
+        # fire the recv transition — the protocol stays in the
+        # post-send state, mirroring reality (the tool didn't actually
+        # produce a result). A tool exception is *not* a protocol
+        # violation; it's an orthogonal failure mode and the user's
+        # outer error handling owns it.
+        result = handler(request)
+
+        self._monitor.transition(tool_ref, phase="recv", metadata={"result": result})
+        return result
+
+    async def _dispatch_async(
+        self,
+        request: Any,
+        handler: Callable[[Any], Awaitable[Any]],
+    ) -> Any:
+        name = request.tool_call["name"]
+        tool_ref = self._ref_by_label.get(name)
+        if tool_ref is None:
+            return await handler(request)
+
+        args = request.tool_call.get("args", {}) or {}
+        self._monitor.transition(tool_ref, phase="send", metadata={"args": args})
+
+        result = await handler(request)
+
+        self._monitor.transition(tool_ref, phase="recv", metadata={"result": result})
+        return result

llmsessioncontract-0.3.0/llmcontract/langchain/monitor.py

@@ -0,0 +1,117 @@
+"""Stateful runner that drives a ``ProtocolFSM`` through one chain
+execution.
+
+One ``ProtocolMonitor`` instance per agent invocation. Holds the current
+state and the trace of every event that has fired so far. Calls the
+user-supplied ``on_violation`` handler whenever the FSM rejects a
+transition.
+
+This module does not import LangChain.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from llmcontract.langchain.fsm import (
+    MonitorContext,
+    ProtocolFSM,
+    ViolationEvent,
+    ViolationHandler,
+)
+from llmcontract.langchain.tool_ref import ToolRef
+
+
+class ProtocolMonitor:
+    """Owns the mutable state for one chain execution.
+
+    Construct once per ``agent.invoke`` (or call ``reset()`` between
+    invocations). The middleware calls ``transition()`` on every tool
+    call — once with ``phase="send"`` before the tool runs, once with
+    ``phase="recv"`` after it returns successfully.
+    """
+
+    def __init__(
+        self,
+        fsm: ProtocolFSM,
+        on_violation: ViolationHandler,
+        initial_state: str | None = None,
+    ) -> None:
+        self._fsm = fsm
+        self._on_violation = on_violation
+        self._initial = initial_state if initial_state is not None else fsm.initial
+        self._state: str = self._initial
+        self._trace: list[str] = []
+
+    # ── Read-only views ─────────────────────────────────────
+
+    @property
+    def state(self) -> str:
+        return self._state
+
+    @property
+    def trace(self) -> list[str]:
+        # Snapshot copy — callers must not mutate the monitor's history.
+        return list(self._trace)
+
+    # ── Driving the FSM ─────────────────────────────────────
+
+    def transition(
+        self,
+        tool_ref: ToolRef,
+        phase: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> bool:
+        """Attempt one FSM step.
+
+        Returns ``True`` on success (state advanced), ``False`` on
+        violation (state unchanged, ``on_violation`` invoked).
+        """
+        event = f"{phase}:{tool_ref.label}"
+        # The trace records the *attempted* event regardless of outcome,
+        # so violation handlers see the full history including the
+        # violating step. ``ViolationEvent.trace`` and
+        # ``MonitorContext.trace`` are both snapshot copies, never
+        # references to this list.
+        self._trace.append(event)
+
+        ctx = MonitorContext(
+            current_state=self._state,
+            event=event,
+            tool_ref=tool_ref,
+            phase=phase,
+            trace=list(self._trace),
+            metadata=dict(metadata) if metadata else {},
+        )
+
+        next_state, ok = self._fsm.step(self._state, event, ctx)
+        if ok:
+            self._state = next_state
+            return True
+
+        self._on_violation(
+            ViolationEvent(
+                current_state=self._state,
+                event=event,
+                expected=self._fsm.valid_events(self._state),
+                trace=list(self._trace),
+                tool_ref=tool_ref,
+                phase=phase,
+            )
+        )
+        return False
+
+    def reset(self) -> None:
+        """Restore the monitor to its initial state and clear the trace.
+
+        Use this if you want to reuse one ``ProtocolMonitor`` instance
+        across multiple ``agent.invoke`` calls. The cleaner pattern is
+        to construct a fresh monitor per invocation, but reset is
+        provided for callers who pool resources.
+        """
+        self._state = self._initial
+        self._trace.clear()
+
+    def is_complete(self) -> bool:
+        """Whether the monitor's current state is terminal."""
+        return self._fsm.is_terminal(self._state)

llmsessioncontract-0.3.0/llmcontract/langchain/tool_ref.py

@@ -0,0 +1,87 @@
+"""Stable, hashable references to LangChain tools.
+
+A ``ToolRef`` wraps a ``BaseTool`` instance, a ``@tool``-decorated callable,
+or any plain callable, and exposes a single read-only string label derived
+once at construction. Two ``ToolRef`` objects are equal (and share a hash)
+iff their labels match — which lets developers refer to the same tool from
+multiple FSM transitions without juggling identity.
+
+Crucially, this module does **not** import LangChain. The label resolution
+walks duck-typed attributes (``.name`` first, ``.__name__`` second) so the
+core FSM/monitor stays importable in environments without LangChain
+installed. The actual ``BaseTool`` import only happens inside the
+middleware module.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class ToolRef:
+    """Stable label-bearing reference to a LangChain tool or callable.
+
+    Label resolution order, applied once at construction:
+
+    1. If ``tool`` has a ``.name`` attribute that is a non-empty string,
+       use it. (Covers ``BaseTool`` instances and ``@tool``-decorated
+       callables, which expose ``.name`` on the resulting
+       ``StructuredTool``.)
+    2. Otherwise, if ``tool`` is callable and has ``__name__``, use that.
+    3. Otherwise, raise ``TypeError``.
+
+    The label is read-only. Comparing or hashing two ``ToolRef`` objects
+    uses the label only — wrapping different callables that happen to
+    share a name yields equal refs.
+    """
+
+    __slots__ = ("_label", "_tool")
+
+    def __init__(self, tool: Any) -> None:
+        # `.name` first — covers BaseTool subclasses and @tool wrappers
+        # (StructuredTool exposes .name) without importing langchain.
+        name = getattr(tool, "name", None)
+        if isinstance(name, str) and name:
+            label = name
+        elif callable(tool) and getattr(tool, "__name__", None):
+            label = tool.__name__
+        else:
+            raise TypeError(
+                f"ToolRef expects a BaseTool, @tool callable, or named "
+                f"callable; got {type(tool).__name__}"
+            )
+        # __slots__ disables __dict__; assign through object.__setattr__
+        # so future attempts to overwrite (label/tool are read-only) fail.
+        object.__setattr__(self, "_label", label)
+        object.__setattr__(self, "_tool", tool)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        raise AttributeError(f"ToolRef is immutable; cannot set {name!r}")
+
+    @property
+    def label(self) -> str:
+        return self._label
+
+    @property
+    def tool(self) -> Any:
+        return self._tool
+
+    def __repr__(self) -> str:
+        return f"ToolRef({self._label!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ToolRef):
+            return NotImplemented
+        return self._label == other._label
+
+    def __hash__(self) -> int:
+        return hash(("ToolRef", self._label))
+
+
+def ref(tool: Any) -> ToolRef:
+    """Convenience shorthand for ``ToolRef(tool)``.
+
+    This is the primary API developers reach for — they always pass the
+    tool function, never a name string.
+    """
+    return ToolRef(tool)

{llmsessioncontract-0.2.2 → llmsessioncontract-0.3.0/llmsessioncontract.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llmsessioncontract
-Version: 0.2.2
+Version: 0.3.0
 Summary: Runtime monitor for LLM agent interaction protocols based on session type theory
 Author-email: Chris Bartolo Burlo <chris@mizziburlo.com>
 License-Expression: MIT
@@ -23,8 +23,12 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: langfuse
 Requires-Dist: langfuse>=3.0.0; extra == "langfuse"
+Provides-Extra: langchain
+Requires-Dist: langchain>=1.0.0; extra == "langchain"
+Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
 Dynamic: license-file
 
 # llmcontract
@@ -230,6 +234,80 @@ while True:
         messages.append(tool_result_msg(tc.id, result))
 ```
 
+## LangChain Integration (`llmcontract.langchain`, 0.3.0+)
+
+A focused FSM-as-data API for users who want to wire protocol monitoring
+into LangChain agents without touching the DSL parser. Tool references
+are real Python callables, transitions are explicit objects with
+optional guards and actions, and violation handling is fully
+user-controlled.
+
+```bash
+pip install llmsessioncontract[langchain]
+```
+
+```python
+from langchain_core.tools import tool
+from langchain.agents import create_agent
+from llmcontract.langchain import (
+    ProtocolFSM, Transition, ProtocolMonitor,
+    ProtocolEnforcerMiddleware, ViolationEvent,
+    ProtocolViolationError, ref,
+)
+
+@tool
+def search(query: str) -> str:
+    """Search for available flights."""
+    return f"Results for: {query}"
+
+@tool
+def book(result: str) -> str:
+    """Book a selected flight."""
+    return f"Booked: {result}"
+
+search_ref = ref(search)
+book_ref = ref(book)
+
+fsm = (
+    ProtocolFSM(initial="idle")
+    .add_transition(Transition(source="idle", tool=search_ref, phase="send", target="searching"))
+    .add_transition(Transition(source="searching", tool=search_ref, phase="recv", target="results"))
+    .add_transition(Transition(source="results", tool=book_ref, phase="send", target="booking",
+                               guard=lambda ctx: bool(ctx.metadata.get("args", {}))))
+    .add_transition(Transition(source="booking", tool=book_ref, phase="recv", target="done"))
+    .mark_terminal("done")
+)
+
+def on_violation(v: ViolationEvent) -> None:
+    raise ProtocolViolationError(f"Illegal {v.phase}:{v.tool_ref.label} from {v.current_state!r}", violation=v)
+
+monitor = ProtocolMonitor(fsm=fsm, on_violation=on_violation)
+middleware = ProtocolEnforcerMiddleware(monitor=monitor, tool_refs=[search_ref, book_ref]).middleware
+
+agent = create_agent(model=..., tools=[search, book], middleware=[middleware])
+agent.invoke({"messages": [("user", "Book me a flight to Rome.")]})
+
+print(monitor.state)        # → "done"
+print(monitor.is_complete()) # → True
+print(monitor.trace)        # → ["send:search", "recv:search", "send:book", "recv:book"]
+```
+
+When to pick this over the DSL `Monitor`:
+
+- You're already in a LangChain stack and want a drop-in `AgentMiddleware`
+- You need per-transition guards and actions (e.g., audit logs, business rules)
+- You want enforcement (block tool calls), not just observation
+- You don't need recursion / choice / `Unrecognized` from the DSL
+
+When to stick with the DSL `Monitor`:
+
+- You want to write protocols as concise strings (`!Search.?Result.end`)
+- You need recursion or compositional choice
+- You're outside LangChain (Anthropic SDK, OpenAI SDK, custom loop)
+- You want first-class natural-language ambiguity via `Unrecognized`
+
+Worked example: [`examples/langchain_booking/booking_agent_submodule.py`](examples/langchain_booking/booking_agent_submodule.py).
+
 ## Langfuse Integration
 
 Track protocol compliance in [Langfuse](https://langfuse.com) — every send/receive is recorded as a guardrail observation with a pass/fail score.
@@ -280,7 +358,8 @@ The skill validates each draft DSL against `llmcontract`'s parser, so anything i
 
 ## Case Studies
 
-- **[`llmcontract-tau2`](https://github.com/chrisbartoloburlo/llmcontract-tau2)** — Standalone replay of [tau2-bench](https://github.com/sierra-research/tau2-bench)'s shipped trajectories through `Monitor`. Headline: 11/1755 (0.6%) of trajectories that tau2 scored as passing violate the documented "obtain user confirmation before mutating the database" policy. Discussion upstream: [tau2-bench#298](https://github.com/sierra-research/tau2-bench/issues/298).
+- **[`llmcontract-tau2`](https://github.com/chrisbartoloburlo/llmcontract-tau2)** — *user ↔ agent layer.* Standalone replay of [tau2-bench](https://github.com/sierra-research/tau2-bench)'s shipped trajectories through `Monitor`. Headline: 11/1755 (0.6%) of trajectories that tau2 scored as passing violate the documented "obtain user confirmation before mutating the database" policy. Discussion upstream: [tau2-bench#298](https://github.com/sierra-research/tau2-bench/issues/298).
+- **[`llmcontract-playwright-mcp`](https://github.com/chrisbartoloburlo/llmcontract-playwright-mcp)** — *agent ↔ tool layer.* 90-trajectory sweep across Claude Haiku 4.5 / Sonnet 4.6 / Opus 4.7 driving [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp), checked against two invariants from the server's documented usage. Headline: 9% violate `snap-before-interact`, 29% violate `stay-on-snapshot-refs` — and the failure modes scale opposite directions with model capability (Haiku snapshots religiously but ignores the snapshot 57% of the time; Opus skips the snapshot 13% of the time but follows through cleanly when it commits).
 
 ## Research
 

{llmsessioncontract-0.2.2 → llmsessioncontract-0.3.0}/llmsessioncontract.egg-info/SOURCES.txt

@@ -12,6 +12,12 @@ llmcontract/integration/exceptions.py
 llmcontract/integration/langfuse.py
 llmcontract/integration/middleware.py
 llmcontract/integration/types.py
+llmcontract/langchain/__init__.py
+llmcontract/langchain/exceptions.py
+llmcontract/langchain/fsm.py
+llmcontract/langchain/middleware.py
+llmcontract/langchain/monitor.py
+llmcontract/langchain/tool_ref.py
 llmcontract/monitor/__init__.py
 llmcontract/monitor/automaton.py
 llmcontract/monitor/monitor.py

llmsessioncontract-0.3.0/llmsessioncontract.egg-info/requires.txt

@@ -0,0 +1,11 @@
+
+[dev]
+pytest
+pytest-asyncio
+
+[langchain]
+langchain>=1.0.0
+langchain-core>=0.3.0
+
+[langfuse]
+langfuse>=3.0.0

{llmsessioncontract-0.2.2 → llmsessioncontract-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "llmsessioncontract"
-version = "0.2.2"
+version = "0.3.0"
 description = "Runtime monitor for LLM agent interaction protocols based on session type theory"
 requires-python = ">=3.10"
 license = "MIT"
@@ -33,7 +33,8 @@ Issues = "https://github.com/chrisbartoloburlo/llmcontract/issues"
 
 [project.optional-dependencies]
 langfuse = ["langfuse>=3.0.0"]
-dev = ["pytest"]
+langchain = ["langchain>=1.0.0", "langchain-core>=0.3.0"]
+dev = ["pytest", "pytest-asyncio"]
 
 [tool.setuptools.packages.find]
 include = ["llmcontract*"]

llmsessioncontract-0.2.2/llmsessioncontract.egg-info/requires.txt

@@ -1,6 +0,0 @@
-
-[dev]
-pytest
-
-[langfuse]
-langfuse>=3.0.0