llmsessioncontract 0.1.0__py3-none-any.whl

llmcontract/__init__.py

@@ -0,0 +1,11 @@
+from llmcontract.monitor.monitor import Monitor, MonitorResult, Ok, Violation, Blocked
+from llmcontract.integration import (
+    MonitoredClient, ToolMiddleware, ToolResult,
+    LLMResponse, ToolCall, ProtocolViolationError,
+)
+
+__all__ = [
+    "Monitor", "MonitorResult", "Ok", "Violation", "Blocked",
+    "MonitoredClient", "ToolMiddleware", "ToolResult",
+    "LLMResponse", "ToolCall", "ProtocolViolationError",
+]

llmcontract/dsl/__init__.py

@@ -0,0 +1,11 @@
+from llmcontract.dsl.ast import (
+    Send, Receive, InternalChoice, ExternalChoice,
+    Sequence, Recursion, RecVar, End,
+)
+from llmcontract.dsl.parser import parse, ParseError
+
+__all__ = [
+    "Send", "Receive", "InternalChoice", "ExternalChoice",
+    "Sequence", "Recursion", "RecVar", "End",
+    "parse", "ParseError",
+]

llmcontract/dsl/ast.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Union
+
+
+@dataclass(frozen=True)
+class Send:
+    """!label — send action."""
+    label: str
+
+
+@dataclass(frozen=True)
+class Receive:
+    """?label — receive action."""
+    label: str
+
+
+@dataclass(frozen=True)
+class InternalChoice:
+    """!{a, b, ...} — sender chooses among branches."""
+    branches: dict[str, ProtocolNode]
+
+
+@dataclass(frozen=True)
+class ExternalChoice:
+    """?{a, b, ...} — receiver chooses among branches."""
+    branches: dict[str, ProtocolNode]
+
+
+@dataclass(frozen=True)
+class Sequence:
+    """left.right — sequential composition."""
+    left: ProtocolNode
+    right: ProtocolNode
+
+
+@dataclass(frozen=True)
+class Recursion:
+    """rec X. body — recursive protocol."""
+    var: str
+    body: ProtocolNode
+
+
+@dataclass(frozen=True)
+class RecVar:
+    """X — recursion variable reference."""
+    var: str
+
+
+@dataclass(frozen=True)
+class End:
+    """end — terminal state."""
+    pass
+
+
+ProtocolNode = Union[
+    Send, Receive, InternalChoice, ExternalChoice,
+    Sequence, Recursion, RecVar, End,
+]

llmcontract/dsl/parser.py

@@ -0,0 +1,175 @@
+"""Hand-written recursive descent parser for the session type DSL."""
+
+from __future__ import annotations
+
+from llmcontract.dsl.ast import (
+    End, ExternalChoice, InternalChoice, ProtocolNode,
+    Receive, Recursion, RecVar, Send, Sequence,
+)
+
+
+class ParseError(Exception):
+    """Raised on invalid input with position information."""
+
+    def __init__(self, message: str, pos: int) -> None:
+        self.pos = pos
+        super().__init__(f"Parse error at position {pos}: {message}")
+
+
+class _Parser:
+    def __init__(self, src: str) -> None:
+        self.src = src
+        self.pos = 0
+
+    # ── helpers ──────────────────────────────────────────────
+
+    def _skip_ws(self) -> None:
+        while self.pos < len(self.src) and self.src[self.pos] in " \t\n\r":
+            self.pos += 1
+
+    def _peek(self) -> str | None:
+        self._skip_ws()
+        if self.pos >= len(self.src):
+            return None
+        return self.src[self.pos]
+
+    def _expect(self, ch: str) -> None:
+        self._skip_ws()
+        if self.pos >= len(self.src) or self.src[self.pos] != ch:
+            found = self.src[self.pos] if self.pos < len(self.src) else "EOF"
+            raise ParseError(f"expected '{ch}', got '{found}'", self.pos)
+        self.pos += 1
+
+    def _read_ident(self) -> str:
+        self._skip_ws()
+        start = self.pos
+        while self.pos < len(self.src) and (self.src[self.pos].isalnum() or self.src[self.pos] == '_'):
+            self.pos += 1
+        if self.pos == start:
+            found = self.src[self.pos] if self.pos < len(self.src) else "EOF"
+            raise ParseError(f"expected identifier, got '{found}'", self.pos)
+        return self.src[start:self.pos]
+
+    def _at_keyword(self, kw: str) -> bool:
+        self._skip_ws()
+        end = self.pos + len(kw)
+        if self.src[self.pos:end] == kw:
+            # Make sure it's not a prefix of a longer identifier
+            if end >= len(self.src) or not (self.src[end].isalnum() or self.src[end] == '_'):
+                return True
+        return False
+
+    # ── grammar ──────────────────────────────────────────────
+    #
+    # protocol  ::= atom ('.' protocol)?
+    # atom      ::= '!' choice_or_label
+    #             | '?' choice_or_label
+    #             | 'rec' IDENT '.' protocol
+    #             | 'end'
+    #             | IDENT              (recursion variable)
+    #
+    # choice_or_label ::= '{' branch (',' branch)* '}'
+    #                   | IDENT
+    #
+    # branch ::= IDENT ('.' protocol)?
+
+    def parse(self) -> ProtocolNode:
+        node = self._parse_protocol()
+        self._skip_ws()
+        if self.pos < len(self.src):
+            raise ParseError(f"unexpected character '{self.src[self.pos]}'", self.pos)
+        return node
+
+    def _parse_protocol(self) -> ProtocolNode:
+        left = self._parse_atom()
+        self._skip_ws()
+        if self._peek() == '.':
+            # Could be sequence or end-of-input
+            # We need to check that what follows '.' is another atom, not EOF
+            save = self.pos
+            self.pos += 1  # consume '.'
+            self._skip_ws()
+            if self.pos >= len(self.src):
+                raise ParseError("unexpected EOF after '.'", self.pos)
+            right = self._parse_protocol()
+            left = Sequence(left, right)
+        return left
+
+    def _parse_atom(self) -> ProtocolNode:
+        ch = self._peek()
+        if ch is None:
+            raise ParseError("unexpected EOF", self.pos)
+
+        if ch == '!':
+            self.pos += 1
+            return self._parse_send()
+        if ch == '?':
+            self.pos += 1
+            return self._parse_receive()
+        if self._at_keyword('rec'):
+            return self._parse_rec()
+        if self._at_keyword('end'):
+            self.pos += 3
+            return End()
+
+        # Must be a recursion variable
+        ident = self._read_ident()
+        return RecVar(ident)
+
+    def _parse_send(self) -> ProtocolNode:
+        if self._peek() == '{':
+            return self._parse_internal_choice()
+        label = self._read_ident()
+        return Send(label)
+
+    def _parse_receive(self) -> ProtocolNode:
+        if self._peek() == '{':
+            return self._parse_external_choice()
+        label = self._read_ident()
+        return Receive(label)
+
+    def _parse_internal_choice(self) -> InternalChoice:
+        self._expect('{')
+        branches = self._parse_branches()
+        self._expect('}')
+        return InternalChoice(branches)
+
+    def _parse_external_choice(self) -> ExternalChoice:
+        self._expect('{')
+        branches = self._parse_branches()
+        self._expect('}')
+        return ExternalChoice(branches)
+
+    def _parse_branches(self) -> dict[str, ProtocolNode]:
+        branches: dict[str, ProtocolNode] = {}
+        label, body = self._parse_branch()
+        branches[label] = body
+        while self._peek() == ',':
+            self.pos += 1  # consume ','
+            label, body = self._parse_branch()
+            if label in branches:
+                raise ParseError(f"duplicate branch label '{label}'", self.pos)
+            branches[label] = body
+        return branches
+
+    def _parse_branch(self) -> tuple[str, ProtocolNode]:
+        label = self._read_ident()
+        self._skip_ws()
+        if self._peek() == '.':
+            self.pos += 1  # consume '.'
+            body = self._parse_protocol()
+        else:
+            body = End()
+        return label, body
+
+    def _parse_rec(self) -> Recursion:
+        self.pos += 3  # consume 'rec'
+        var = self._read_ident()
+        self._expect('.')
+        body = self._parse_protocol()
+        return Recursion(var, body)
+
+
+def parse(src: str) -> ProtocolNode:
+    """Parse a session type DSL string into an AST."""
+    return _Parser(src).parse()

llmcontract/integration/__init__.py

@@ -0,0 +1,13 @@
+from llmcontract.integration.client import MonitoredClient
+from llmcontract.integration.middleware import ToolMiddleware, ToolResult
+from llmcontract.integration.types import LLMResponse, ToolCall
+from llmcontract.integration.exceptions import ProtocolViolationError
+
+__all__ = [
+    "MonitoredClient",
+    "ToolMiddleware",
+    "ToolResult",
+    "LLMResponse",
+    "ToolCall",
+    "ProtocolViolationError",
+]

llmcontract/integration/client.py

@@ -0,0 +1,75 @@
+"""Client wrapper that enforces protocol compliance on LLM calls."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from llmcontract.monitor.monitor import Monitor, Ok
+from llmcontract.integration.types import LLMResponse
+from llmcontract.integration.exceptions import ProtocolViolationError
+
+
+class MonitoredClient:
+    """Wraps an LLM call function and checks protocol events automatically.
+
+    Parameters
+    ----------
+    llm_call:
+        A function that sends a request to the LLM and returns a raw response.
+        Signature is flexible — MonitoredClient passes through *args/**kwargs.
+    response_adapter:
+        Converts the vendor-specific response object into an LLMResponse.
+    monitor:
+        Shared monitor instance that tracks protocol state.
+    send_label:
+        Label (or label-producing function) for the !Send event.
+        If callable, receives the same (*args, **kwargs) as llm_call.
+    receive_label:
+        Label (or label-producing function) for the ?Receive event.
+        If callable, receives the LLMResponse.
+    """
+
+    def __init__(
+        self,
+        llm_call: Callable[..., Any],
+        response_adapter: Callable[[Any], LLMResponse],
+        monitor: Monitor,
+        send_label: str | Callable[..., str] = "Request",
+        receive_label: str | Callable[[LLMResponse], str] = "Response",
+    ) -> None:
+        self._llm_call = llm_call
+        self._response_adapter = response_adapter
+        self._monitor = monitor
+        self._send_label = send_label
+        self._receive_label = receive_label
+
+    @property
+    def monitor(self) -> Monitor:
+        return self._monitor
+
+    def call(self, *args: Any, **kwargs: Any) -> LLMResponse:
+        """Send a request to the LLM, checking protocol on both sides.
+
+        1. Resolve send_label → monitor.send(label) → raise on violation
+        2. Call llm_call(*args, **kwargs)
+        3. Adapt response via response_adapter
+        4. Resolve receive_label → monitor.receive(label) → raise on violation
+        5. Return LLMResponse
+        """
+        # Send check
+        label = self._send_label(*args, **kwargs) if callable(self._send_label) else self._send_label
+        result = self._monitor.send(label)
+        if not isinstance(result, Ok):
+            raise ProtocolViolationError(result, "send")
+
+        # LLM call
+        raw = self._llm_call(*args, **kwargs)
+        response = self._response_adapter(raw)
+
+        # Receive check
+        label = self._receive_label(response) if callable(self._receive_label) else self._receive_label
+        result = self._monitor.receive(label)
+        if not isinstance(result, Ok):
+            raise ProtocolViolationError(result, "receive")
+
+        return response

llmcontract/integration/exceptions.py

@@ -0,0 +1,25 @@
+"""Exceptions raised by the integration layer."""
+
+from __future__ import annotations
+
+from llmcontract.monitor.monitor import MonitorResult, Violation, Blocked
+
+
+class ProtocolViolationError(Exception):
+    """Raised when an LLM interaction violates the session protocol."""
+
+    def __init__(self, result: MonitorResult, phase: str) -> None:
+        self.result = result
+        self.phase = phase
+        if isinstance(result, Violation):
+            expected = ", ".join(result.expected)
+            super().__init__(
+                f"Protocol violation during {phase}: "
+                f"got {result.got}, expected one of [{expected}]"
+            )
+        elif isinstance(result, Blocked):
+            super().__init__(
+                f"Protocol blocked during {phase}: {result.reason}"
+            )
+        else:
+            super().__init__(f"Protocol error during {phase}")

llmcontract/integration/middleware.py

@@ -0,0 +1,112 @@
+"""Tool middleware that monitors tool execution against a protocol."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from llmcontract.monitor.monitor import Monitor, Ok
+from llmcontract.integration.types import ToolCall, LLMResponse
+from llmcontract.integration.exceptions import ProtocolViolationError
+
+ToolFunction = Callable[..., Any]
+
+
+@dataclass
+class ToolResult:
+    """Result of a monitored tool execution."""
+
+    tool_call_id: str
+    tool_name: str
+    result: Any
+
+
+class ToolMiddleware:
+    """Intercepts LLM tool calls and checks them against the protocol.
+
+    Parameters
+    ----------
+    monitor:
+        The same monitor instance used by MonitoredClient.
+    tools:
+        Registry mapping tool name → implementation function.
+    receive_label:
+        Label for ?Receive when the LLM requests a tool call.
+        If None, uses the tool name itself.
+        If a string, uses that string for all tools.
+        If callable, receives the ToolCall and returns a label.
+    send_label:
+        Label for !Send when returning tool results to the LLM.
+        If None, uses the tool name itself.
+        If a string, uses that string for all tools.
+        If callable, receives (tool_name, tool_result) and returns a label.
+    """
+
+    def __init__(
+        self,
+        monitor: Monitor,
+        tools: dict[str, ToolFunction] | None = None,
+        receive_label: str | Callable[[ToolCall], str] | None = None,
+        send_label: str | Callable[[str, Any], str] | None = None,
+    ) -> None:
+        self._monitor = monitor
+        self._tools: dict[str, ToolFunction] = dict(tools) if tools else {}
+        self._receive_label = receive_label
+        self._send_label = send_label
+
+    @property
+    def monitor(self) -> Monitor:
+        return self._monitor
+
+    def register(self, name: str, fn: ToolFunction) -> None:
+        """Register a tool function."""
+        self._tools[name] = fn
+
+    def execute(self, tool_call: ToolCall) -> ToolResult:
+        """Execute a single tool call with protocol checks.
+
+        1. monitor.receive(label) — the LLM chose this tool
+        2. Execute the tool function
+        3. monitor.send(label) — sending the result back
+        """
+        if tool_call.name not in self._tools:
+            raise ValueError(f"Unknown tool: {tool_call.name!r}")
+
+        # Receive check — LLM requested this tool
+        recv_label = self._resolve_receive_label(tool_call)
+        result = self._monitor.receive(recv_label)
+        if not isinstance(result, Ok):
+            raise ProtocolViolationError(result, "receive")
+
+        # Execute
+        output = self._tools[tool_call.name](**tool_call.arguments)
+
+        # Send check — returning result to LLM
+        send_label = self._resolve_send_label(tool_call.name, output)
+        result = self._monitor.send(send_label)
+        if not isinstance(result, Ok):
+            raise ProtocolViolationError(result, "send")
+
+        return ToolResult(
+            tool_call_id=tool_call.id,
+            tool_name=tool_call.name,
+            result=output,
+        )
+
+    def process(self, response: LLMResponse) -> list[ToolResult]:
+        """Process all tool calls in an LLM response."""
+        return [self.execute(tc) for tc in response.tool_calls]
+
+    def _resolve_receive_label(self, tool_call: ToolCall) -> str:
+        if self._receive_label is None:
+            return tool_call.name
+        if callable(self._receive_label):
+            return self._receive_label(tool_call)
+        return self._receive_label
+
+    def _resolve_send_label(self, tool_name: str, tool_result: Any) -> str:
+        if self._send_label is None:
+            return tool_name
+        if callable(self._send_label):
+            return self._send_label(tool_name, tool_result)
+        return self._send_label

llmcontract/integration/types.py

@@ -0,0 +1,27 @@
+"""SDK-agnostic types for normalized LLM responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    """A single tool call requested by the LLM."""
+
+    name: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+    id: str = ""
+
+
+@dataclass(frozen=True)
+class LLMResponse:
+    """Normalized LLM response."""
+
+    content: str | None = None
+    tool_calls: list[ToolCall] = field(default_factory=list)
+
+    @property
+    def has_tool_calls(self) -> bool:
+        return len(self.tool_calls) > 0

llmcontract/monitor/__init__.py

@@ -0,0 +1,4 @@
+from llmcontract.monitor.automaton import Automaton
+from llmcontract.monitor.monitor import Monitor, MonitorResult, Ok, Violation, Blocked
+
+__all__ = ["Automaton", "Monitor", "MonitorResult", "Ok", "Violation", "Blocked"]

llmcontract/monitor/automaton.py

@@ -0,0 +1,151 @@
+"""Compiles a session type AST into a finite state automaton."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from llmcontract.dsl.ast import (
+    End, ExternalChoice, InternalChoice, ProtocolNode,
+    Receive, Recursion, RecVar, Send, Sequence,
+)
+
+Direction = Literal["send", "receive"]
+TransitionKey = tuple[Direction, str]
+
+
+@dataclass
+class Automaton:
+    """Finite state automaton compiled from a session type AST."""
+
+    transitions: dict[int, dict[TransitionKey, int]] = field(default_factory=dict)
+    terminal_states: set[int] = field(default_factory=set)
+    initial_state: int = 0
+    _next_id: int = field(default=0, repr=False)
+
+    def _new_state(self) -> int:
+        sid = self._next_id
+        self._next_id += 1
+        if sid not in self.transitions:
+            self.transitions[sid] = {}
+        return sid
+
+    def is_terminal(self, state: int) -> bool:
+        return state in self.terminal_states
+
+
+def compile_ast(node: ProtocolNode) -> Automaton:
+    """Compile an AST into a finite state automaton."""
+    aut = Automaton()
+    start = aut._new_state()
+    aut.initial_state = start
+    rec_env: dict[str, int] = {}
+    _compile(node, start, aut, rec_env)
+    return aut
+
+
+def _compile(
+    node: ProtocolNode,
+    current: int,
+    aut: Automaton,
+    rec_env: dict[str, int],
+) -> None:
+    """Recursively compile *node* starting from *current* state."""
+
+    if isinstance(node, End):
+        aut.terminal_states.add(current)
+
+    elif isinstance(node, Send):
+        nxt = aut._new_state()
+        aut.transitions[current][("send", node.label)] = nxt
+        # The next state is terminal by default; a Sequence wrapper overrides this.
+        aut.terminal_states.add(nxt)
+
+    elif isinstance(node, Receive):
+        nxt = aut._new_state()
+        aut.transitions[current][("receive", node.label)] = nxt
+        aut.terminal_states.add(nxt)
+
+    elif isinstance(node, InternalChoice):
+        for label, branch in node.branches.items():
+            nxt = aut._new_state()
+            aut.transitions[current][("send", label)] = nxt
+            _compile(branch, nxt, aut, rec_env)
+
+    elif isinstance(node, ExternalChoice):
+        for label, branch in node.branches.items():
+            nxt = aut._new_state()
+            aut.transitions[current][("receive", label)] = nxt
+            _compile(branch, nxt, aut, rec_env)
+
+    elif isinstance(node, Sequence):
+        # Compile left, find its "leaf" states (non-choice terminal sinks),
+        # then wire those into right.
+        _compile(node.left, current, aut, rec_env)
+        # The leaf states produced by left are terminal states reachable from current
+        # that were just added. We need to find them and make them non-terminal,
+        # then compile right from each.
+        leaf_states = _collect_leaf_states(node.left, current, aut)
+        for s in leaf_states:
+            aut.terminal_states.discard(s)
+            _compile(node.right, s, aut, rec_env)
+
+    elif isinstance(node, Recursion):
+        rec_env_copy = dict(rec_env)
+        rec_env_copy[node.var] = current
+        _compile(node.body, current, aut, rec_env_copy)
+
+    elif isinstance(node, RecVar):
+        # Back-edge: wire current state to the recursion point.
+        # We mark current as an epsilon-transition target by copying transitions.
+        target = rec_env[node.var]
+        # Copy all transitions from the target to current state
+        for key, dest in aut.transitions.get(target, {}).items():
+            aut.transitions[current][key] = dest
+
+    else:
+        raise TypeError(f"Unknown AST node: {type(node)}")
+
+
+def _collect_leaf_states(
+    node: ProtocolNode,
+    current: int,
+    aut: Automaton,
+) -> list[int]:
+    """Return the states that a compiled node ends in (its continuation points)."""
+
+    if isinstance(node, End):
+        return [current]
+
+    elif isinstance(node, (Send, Receive)):
+        # The single transition target
+        direction = "send" if isinstance(node, Send) else "receive"
+        label = node.label
+        nxt = aut.transitions[current].get((direction, label))
+        if nxt is not None:
+            return [nxt]
+        return []
+
+    elif isinstance(node, (InternalChoice, ExternalChoice)):
+        direction = "send" if isinstance(node, InternalChoice) else "receive"
+        leaves: list[int] = []
+        for label, branch in node.branches.items():
+            nxt = aut.transitions[current].get((direction, label))
+            if nxt is not None:
+                leaves.extend(_collect_leaf_states(branch, nxt, aut))
+        return leaves
+
+    elif isinstance(node, Sequence):
+        left_leaves = _collect_leaf_states(node.left, current, aut)
+        all_leaves: list[int] = []
+        for s in left_leaves:
+            all_leaves.extend(_collect_leaf_states(node.right, s, aut))
+        return all_leaves
+
+    elif isinstance(node, Recursion):
+        return _collect_leaf_states(node.body, current, aut)
+
+    elif isinstance(node, RecVar):
+        return [current]
+
+    return [current]

llmcontract/monitor/monitor.py

@@ -0,0 +1,82 @@
+"""Runtime monitor for session type protocols."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Union
+
+from llmcontract.dsl.parser import parse
+from llmcontract.monitor.automaton import Automaton, compile_ast
+
+
+# ── Result types ─────────────────────────────────────────────
+
+@dataclass(frozen=True)
+class Ok:
+    """The event was accepted."""
+    pass
+
+
+@dataclass(frozen=True)
+class Violation:
+    """Protocol violation: expected one thing, got another."""
+    expected: list[str]
+    got: str
+
+
+@dataclass(frozen=True)
+class Blocked:
+    """The monitor is halted and no further events are accepted."""
+    reason: str
+
+
+MonitorResult = Union[Ok, Violation, Blocked]
+
+
+# ── Monitor ──────────────────────────────────────────────────
+
+class Monitor:
+    """Runtime monitor that checks a stream of send/receive events against a protocol."""
+
+    def __init__(self, protocol: str) -> None:
+        ast = parse(protocol)
+        self._automaton: Automaton = compile_ast(ast)
+        self._current_state: int = self._automaton.initial_state
+        self._halted: bool = False
+
+    @property
+    def current_state(self) -> int:
+        return self._current_state
+
+    @property
+    def is_terminal(self) -> bool:
+        return self._automaton.is_terminal(self._current_state)
+
+    @property
+    def is_halted(self) -> bool:
+        return self._halted
+
+    def send(self, label: str) -> MonitorResult:
+        """Record a send event."""
+        return self._step("send", label)
+
+    def receive(self, label: str) -> MonitorResult:
+        """Record a receive event."""
+        return self._step("receive", label)
+
+    def _step(self, direction: str, label: str) -> MonitorResult:
+        if self._halted:
+            return Blocked("monitor halted after a previous violation")
+
+        transitions = self._automaton.transitions.get(self._current_state, {})
+        key = (direction, label)
+
+        if key in transitions:
+            self._current_state = transitions[key]
+            return Ok()
+
+        # Build a useful violation message
+        expected = [f"{'!' if d == 'send' else '?'}{l}" for d, l in transitions]
+        got = f"{'!' if direction == 'send' else '?'}{label}"
+        self._halted = True
+        return Violation(expected=expected, got=got)

llmsessioncontract-0.1.0.dist-info/METADATA

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: llmsessioncontract
+Version: 0.1.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
+Project-URL: Homepage, https://llmcontract.dev
+Project-URL: Repository, https://github.com/chrisbartoloburlo/llmcontract
+Project-URL: Issues, https://github.com/chrisbartoloburlo/llmcontract/issues
+Keywords: llm,agents,session-types,runtime-monitoring,protocol,contracts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# llmcontract
+
+A runtime monitor for LLM agent interaction protocols based on session type theory.
+
+`llmcontract` lets you define communication protocols using a concise DSL inspired by session types, then monitor agent interactions at runtime to catch protocol violations the moment they happen.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Protocol DSL
+
+Protocols are written as strings using this syntax:
+
+| Syntax | Meaning |
+|--------|---------|
+| `!label` | Send action |
+| `?label` | Receive action |
+| `!{a, b}` | Internal choice (sender chooses) |
+| `?{a, b}` | External choice (receiver chooses) |
+| `.` | Sequence |
+| `rec X. ...X...` | Recursion |
+| `end` | Terminal state |
+
+### Examples
+
+A flight booking protocol — a strict linear sequence:
+
+```
+!SearchFlights.?FlightResults.!PresentOptions.?UserApproval.!BookFlight.?BookingConfirmation.end
+```
+
+A card payment protocol — with branching and recursion:
+
+```
+!CreateCard.?{CardCreated.rec X.!Transaction.?{TransactionOK.X, SessionEnd}, CardError}.end
+```
+
+## Usage
+
+```python
+from llmcontract import Monitor, Ok, Violation, Blocked
+
+protocol = "!SearchFlights.?FlightResults.!BookFlight.?BookingConfirmation.end"
+m = Monitor(protocol)
+
+m.send("SearchFlights")    # Ok()
+m.receive("FlightResults") # Ok()
+m.send("BookFlight")       # Ok()
+m.receive("BookingConfirmation") # Ok()
+assert m.is_terminal
+```
+
+### Catching violations
+
+```python
+m = Monitor("!Ping.?Pong.end")
+m.send("Ping")       # Ok()
+m.send("Pong")       # Violation(expected=['?Pong'], got='!Pong')
+m.send("Anything")   # Blocked('monitor halted after a previous violation')
+```
+
+### Working with choices
+
+```python
+protocol = "!CreateCard.?{CardCreated.!Done.end, CardError.end}"
+m = Monitor(protocol)
+m.send("CreateCard")       # Ok()
+m.receive("CardError")     # Ok() — the receiver chose this branch
+assert m.is_terminal
+```
+
+### Recursion
+
+```python
+protocol = "rec X.!Ping.?Pong.X"
+m = Monitor(protocol)
+for _ in range(100):
+    m.send("Ping")     # Ok()
+    m.receive("Pong")  # Ok()
+```
+
+## Integration Layer
+
+For real agent loops, `llmcontract` provides a client wrapper and tool middleware that share a single monitor — so the full interaction is tracked automatically.
+
+### Client Wrapper
+
+Wraps any LLM client call. Checks `!Send` before calling the LLM and `?Receive` after getting the response. SDK-agnostic — you provide a small adapter function.
+
+```python
+from llmcontract import Monitor, MonitoredClient, LLMResponse, ToolCall
+
+monitor = Monitor(
+    "rec Loop.!Request.?{ToolCall.!ToolResult.Loop, FinalAnswer.end}"
+)
+
+# Adapt your SDK's response to LLMResponse
+def adapt(raw):
+    if raw.tool_calls:
+        return LLMResponse(tool_calls=[
+            ToolCall(name=tc.function.name, arguments=tc.arguments, id=tc.id)
+            for tc in raw.tool_calls
+        ])
+    return LLMResponse(content=raw.content)
+
+client = MonitoredClient(
+    llm_call=openai.chat.completions.create,
+    response_adapter=adapt,
+    monitor=monitor,
+    send_label="Request",
+    receive_label=lambda r: "ToolCall" if r.has_tool_calls else "FinalAnswer",
+)
+
+response = client.call(model="gpt-4", messages=[...])
+# Automatically fires !Request then ?ToolCall or ?FinalAnswer
+```
+
+### Tool Middleware
+
+Wraps tool execution. When the LLM requests a tool, the middleware checks `?Receive` (tool requested) and `!Send` (result returned) against the protocol.
+
+```python
+from llmcontract import ToolMiddleware
+
+middleware = ToolMiddleware(
+    monitor=monitor,  # same monitor as the client
+    tools={
+        "search": search_fn,
+        "book": book_fn,
+    },
+)
+
+# Process all tool calls from a response
+results = middleware.process(response)
+# Each tool call checks ?receive and !send against the protocol
+```
+
+### Combined Agent Loop
+
+```python
+from llmcontract import (
+    Monitor, MonitoredClient, ToolMiddleware,
+    LLMResponse, ToolCall, ProtocolViolationError,
+)
+
+protocol = "rec Loop.!Request.?{ToolCall.!ToolResult.Loop, FinalAnswer.end}"
+monitor = Monitor(protocol)
+
+client = MonitoredClient(
+    llm_call=my_llm_fn,
+    response_adapter=my_adapter,
+    monitor=monitor,
+    send_label="Request",
+    receive_label=lambda r: "ToolCall" if r.has_tool_calls else "FinalAnswer",
+)
+
+while True:
+    try:
+        response = client.call(messages=messages)
+    except ProtocolViolationError as e:
+        print(f"Protocol violated: {e}")
+        break
+
+    if not response.has_tool_calls:
+        break  # FinalAnswer — protocol complete
+
+    # Execute tools, send results back
+    for tc in response.tool_calls:
+        result = tools[tc.name](**tc.arguments)
+        monitor.send("ToolResult")  # record the send
+        messages.append(tool_result_msg(tc.id, result))
+```
+
+## Architecture
+
+```
+DSL string ──▶ Parser ──▶ AST ──▶ FSM Compiler ──▶ Automaton ──▶ Monitor
+```
+
+- **Parser** (`llmcontract.dsl.parser`) — hand-written recursive descent parser that produces an AST
+- **AST** (`llmcontract.dsl.ast`) — frozen dataclasses: `Send`, `Receive`, `InternalChoice`, `ExternalChoice`, `Sequence`, `Recursion`, `RecVar`, `End`
+- **FSM Compiler** (`llmcontract.monitor.automaton`) — compiles the AST into a finite state automaton with transitions keyed by `(direction, label)`
+- **Monitor** (`llmcontract.monitor.monitor`) — steps through the automaton on each `send`/`receive` call, returning `Ok`, `Violation`, or `Blocked`
+- **MonitoredClient** (`llmcontract.integration.client`) — wraps any LLM client call with automatic protocol checks
+- **ToolMiddleware** (`llmcontract.integration.middleware`) — intercepts tool execution with protocol checks
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest llmcontract/tests/ -v
+```
+
+## License
+
+MIT

llmsessioncontract-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+llmcontract/__init__.py,sha256=SYWSqt9MWsaL9lwDaMS58demzejxCvxiDurglysZZG8,416
+llmcontract/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+llmcontract/dsl/__init__.py,sha256=pB671a6dRxQ95GPLam8UDJphxtrtmswofFK7lshoAdo,325
+llmcontract/dsl/ast.py,sha256=7OFNH4QbA87m1Rlz5p-tv3sXkJN-lt3KJJiISswoYOw,1121
+llmcontract/dsl/parser.py,sha256=9qQoaklOwMfDPKAMg_LLAmyJz3uUKKcu5f-IQlPMquA,5982
+llmcontract/integration/__init__.py,sha256=MAA1z7g8bciigCVwMa4xhaKARa91y97ECj_z_PqvgbE,410
+llmcontract/integration/client.py,sha256=kh68oEcqz-DhMCUXEx5dAfBZLruGruoO_-dqmm9qYIA,2758
+llmcontract/integration/exceptions.py,sha256=ptCUOzMoxjexSGEOEs_5v_fVQmhPkIn5J-IJ1dhcZgI,888
+llmcontract/integration/middleware.py,sha256=Apiv7Jh2RbgLNwwl9l1lv_yWMB5NfvMYQ5wU2NW6hkE,3864
+llmcontract/integration/types.py,sha256=ASzM75v07LdkjmrHQ3D9Mr-GJUdyIyq60zRXB2qQ2Jw,607
+llmcontract/monitor/__init__.py,sha256=NrX9iz18CfzKIAidQys1MLaJn-_6Sf1uM5P8oqoT7es,222
+llmcontract/monitor/automaton.py,sha256=f0e6OgGuGW-Eve4NQWrfobIxtu8oMa7jBFjMQfse6uk,5081
+llmcontract/monitor/monitor.py,sha256=_qy3N_r95Ym7tPif1Cp1WVuRe8mSAtBQNlQmcAXMzrk,2504
+llmsessioncontract-0.1.0.dist-info/licenses/LICENSE,sha256=mcR8lKquleZezlTcyz-3b7n_TdmfmYDCv-c6d5kwXJw,1076
+llmsessioncontract-0.1.0.dist-info/METADATA,sha256=5oyONlzF4FFRriZIlOnfNEDKWunlIUQY-icJY29W4gM,6903
+llmsessioncontract-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+llmsessioncontract-0.1.0.dist-info/top_level.txt,sha256=Nu0YFezqebcB29ZwR2ynLIKIMSKxphVE02oIsVMB3Ro,12
+llmsessioncontract-0.1.0.dist-info/RECORD,,

llmsessioncontract-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

llmsessioncontract-0.1.0.dist-info/licenses/LICENSE

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

llmsessioncontract-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+llmcontract