llmsessioncontract 0.1.0__tar.gz

llmsessioncontract-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,199 @@
+# 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/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",
+]

llmsessioncontract-0.1.0/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",
+]

llmsessioncontract-0.1.0/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,
+]

llmsessioncontract-0.1.0/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()