llmsessioncontract 0.2.0__tar.gz → 0.2.2__tar.gz

{llmsessioncontract-0.2.0 → llmsessioncontract-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llmsessioncontract
-Version: 0.2.0
+Version: 0.2.2
 Summary: Runtime monitor for LLM agent interaction protocols based on session type theory
 Author-email: Chris Bartolo Burlo <chris@mizziburlo.com>
 License-Expression: MIT
@@ -111,6 +111,33 @@ for _ in range(100):
     m.receive("Pong")  # Ok()
 ```
 
+### Handling natural-language input: `Unrecognized`
+
+When the projection layer (typically over user chat) can't classify an event into a known label, it can emit the sentinel `UNRECOGNIZED` instead. The monitor treats this as a soft signal — distinct from `Violation` — without halting or advancing state, so the outer loop can drive a clarification turn:
+
+```python
+from llmcontract import Monitor, Ok, Unrecognized, UNRECOGNIZED
+
+m = Monitor("?{Yes.end, No.end}")
+result = m.receive(UNRECOGNIZED)         # projection couldn't decide
+assert isinstance(result, Unrecognized)  # not a Violation
+# state preserved; ask the agent to ask the user to clarify, then:
+m.receive("Yes")                         # Ok()
+```
+
+A protocol can also handle `Unrecognized` *explicitly* as a first-class branch — useful for "ask again" loops:
+
+```python
+protocol = "rec Loop.!Ask.?{Yes.end, No.end, Unrecognized.Loop}"
+m = Monitor(protocol)
+m.send("Ask")
+m.receive(UNRECOGNIZED)  # Ok — protocol routes back to Loop
+m.send("Ask")
+m.receive("Yes")         # Ok — terminal
+```
+
+The distinction matters at the system boundary: `Violation` means the agent broke the rules; `Unrecognized` means we don't have enough information to decide yet. Different responses (halt vs. clarify) come naturally from the typed result.
+
 ## 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.
@@ -236,6 +263,25 @@ Each step appears as a guardrail observation in your Langfuse trace with:
 - **Output**: `passed: true/false`, violation details if applicable
 - **Score**: `protocol_compliance` (boolean) for filtering and analytics
 
+## Claude Code Plugin
+
+A Claude Code plugin ships with this repo: **protocol-builder** walks you through designing a session-type protocol conversationally, validates it as you go, and emits a ready-to-paste Python integration snippet.
+
+```bash
+# Install in Claude Code
+/plugin marketplace add chrisbartoloburlo/llmcontract
+/plugin install protocol-builder@llmcontract
+
+# Then in any conversation
+/protocol-builder
+```
+
+The skill validates each draft DSL against `llmcontract`'s parser, so anything it produces is guaranteed to load with `Monitor(...)`. Source lives under `skills/protocol-builder/`.
+
+## 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).
+
 ## Research
 
 This work is based on the theory developed in:

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

@@ -82,6 +82,33 @@ for _ in range(100):
     m.receive("Pong")  # Ok()
 ```
 
+### Handling natural-language input: `Unrecognized`
+
+When the projection layer (typically over user chat) can't classify an event into a known label, it can emit the sentinel `UNRECOGNIZED` instead. The monitor treats this as a soft signal — distinct from `Violation` — without halting or advancing state, so the outer loop can drive a clarification turn:
+
+```python
+from llmcontract import Monitor, Ok, Unrecognized, UNRECOGNIZED
+
+m = Monitor("?{Yes.end, No.end}")
+result = m.receive(UNRECOGNIZED)         # projection couldn't decide
+assert isinstance(result, Unrecognized)  # not a Violation
+# state preserved; ask the agent to ask the user to clarify, then:
+m.receive("Yes")                         # Ok()
+```
+
+A protocol can also handle `Unrecognized` *explicitly* as a first-class branch — useful for "ask again" loops:
+
+```python
+protocol = "rec Loop.!Ask.?{Yes.end, No.end, Unrecognized.Loop}"
+m = Monitor(protocol)
+m.send("Ask")
+m.receive(UNRECOGNIZED)  # Ok — protocol routes back to Loop
+m.send("Ask")
+m.receive("Yes")         # Ok — terminal
+```
+
+The distinction matters at the system boundary: `Violation` means the agent broke the rules; `Unrecognized` means we don't have enough information to decide yet. Different responses (halt vs. clarify) come naturally from the typed result.
+
 ## 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.
@@ -207,6 +234,25 @@ Each step appears as a guardrail observation in your Langfuse trace with:
 - **Output**: `passed: true/false`, violation details if applicable
 - **Score**: `protocol_compliance` (boolean) for filtering and analytics
 
+## Claude Code Plugin
+
+A Claude Code plugin ships with this repo: **protocol-builder** walks you through designing a session-type protocol conversationally, validates it as you go, and emits a ready-to-paste Python integration snippet.
+
+```bash
+# Install in Claude Code
+/plugin marketplace add chrisbartoloburlo/llmcontract
+/plugin install protocol-builder@llmcontract
+
+# Then in any conversation
+/protocol-builder
+```
+
+The skill validates each draft DSL against `llmcontract`'s parser, so anything it produces is guaranteed to load with `Monitor(...)`. Source lives under `skills/protocol-builder/`.
+
+## 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).
+
 ## Research
 
 This work is based on the theory developed in:

{llmsessioncontract-0.2.0 → llmsessioncontract-0.2.2}/llmcontract/__init__.py

@@ -1,4 +1,6 @@
-from llmcontract.monitor.monitor import Monitor, MonitorResult, Ok, Violation, Blocked
+from llmcontract.monitor.monitor import (
+    Monitor, MonitorResult, Ok, Violation, Blocked, Unrecognized, UNRECOGNIZED,
+)
 from llmcontract.integration import (
     MonitoredClient, ToolMiddleware, ToolResult,
     LLMResponse, ToolCall, ProtocolViolationError,
@@ -6,6 +8,7 @@ from llmcontract.integration import (
 
 __all__ = [
     "Monitor", "MonitorResult", "Ok", "Violation", "Blocked",
+    "Unrecognized", "UNRECOGNIZED",
     "MonitoredClient", "ToolMiddleware", "ToolResult",
     "LLMResponse", "ToolCall", "ProtocolViolationError",
 ]

{llmsessioncontract-0.2.0 → llmsessioncontract-0.2.2}/llmcontract/monitor/automaton.py

@@ -22,6 +22,11 @@ class Automaton:
     terminal_states: set[int] = field(default_factory=set)
     initial_state: int = 0
     _next_id: int = field(default=0, repr=False)
+    # State aliases produced by recursion back-edges. `aliases[child] = target`
+    # means the child state behaves identically to target. Resolved after
+    # compilation finishes so back-edges see the *final* set of target
+    # transitions, not just the ones that existed when the back-edge was hit.
+    _aliases: dict[int, int] = field(default_factory=dict, repr=False)
 
     def _new_state(self) -> int:
         sid = self._next_id
@@ -41,9 +46,47 @@ def compile_ast(node: ProtocolNode) -> Automaton:
     aut.initial_state = start
     rec_env: dict[str, int] = {}
     _compile(node, start, aut, rec_env)
+    _resolve_aliases(aut)
     return aut
 
 
+def _resolve_aliases(aut: Automaton) -> None:
+    """Collapse alias states by redirecting every reference to its canonical id.
+
+    A state X marked as an alias of T behaves like T for all observers. We
+    redirect every outgoing transition that points at X to point at T instead
+    (chasing alias chains), then drop X from the state set entirely. This must
+    happen after `_compile` finishes so the snapshot of T's transitions is
+    final — fixing the bug where a recursion back-edge inside a choice only
+    saw the branches that were compiled before it.
+    """
+
+    def canonical(state: int) -> int:
+        seen: set[int] = set()
+        cur = state
+        while cur in aut._aliases and cur not in seen:
+            seen.add(cur)
+            cur = aut._aliases[cur]
+        return cur
+
+    aliased = set(aut._aliases.keys())
+    if not aliased:
+        return
+
+    for src in list(aut.transitions.keys()):
+        if src in aliased:
+            continue
+        for key, dest in list(aut.transitions[src].items()):
+            aut.transitions[src][key] = canonical(dest)
+
+    for s in aliased:
+        aut.transitions.pop(s, None)
+        aut.terminal_states.discard(s)
+
+    if aut.initial_state in aliased:
+        aut.initial_state = canonical(aut.initial_state)
+
+
 def _compile(
     node: ProtocolNode,
     current: int,
@@ -96,12 +139,12 @@ def _compile(
         _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.
+        # Back-edge: alias current to the recursion target. We can't copy the
+        # target's transitions now because more branches of the surrounding
+        # choice may still be compiled; resolution happens once compilation
+        # finishes (see `_resolve_aliases`).
         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
+        aut._aliases[current] = target
 
     else:
         raise TypeError(f"Unknown AST node: {type(node)}")

{llmsessioncontract-0.2.0 → llmsessioncontract-0.2.2}/llmcontract/monitor/monitor.py

@@ -30,7 +30,36 @@ class Blocked:
     reason: str
 
 
-MonitorResult = Union[Ok, Violation, Blocked]
+@dataclass(frozen=True)
+class Unrecognized:
+    """The projection couldn't classify the event into a known label.
+
+    Distinct from `Violation`: a violation means the agent did the wrong
+    thing, an `Unrecognized` means the projection layer (typically over
+    natural language) couldn't decide which label to emit. Outer-loop code
+    is expected to react by asking the underlying agent to clarify with the
+    user — not by halting as if the protocol had been broken.
+
+    The monitor's state is NOT advanced when it returns `Unrecognized` and
+    the monitor is NOT halted, so a follow-up event after clarification
+    can be fed normally.
+
+    A protocol can opt out of this behavior by including a literal
+    `Unrecognized` transition at any state — in that case the monitor
+    follows the transition and returns `Ok`, treating clarification as a
+    first-class branch of the protocol.
+    """
+    expected: list[str]
+    direction: str
+
+
+MonitorResult = Union[Ok, Violation, Blocked, Unrecognized]
+
+
+# Sentinel label that triggers Unrecognized handling. Use this constant
+# rather than a bare string so callers don't typo their way around the
+# special case.
+UNRECOGNIZED = "Unrecognized"
 
 
 # ── Monitor ──────────────────────────────────────────────────
@@ -75,8 +104,16 @@ class Monitor:
             self._current_state = transitions[key]
             return Ok()
 
-        # Build a useful violation message
         expected = [f"{'!' if d == 'send' else '?'}{l}" for d, l in transitions]
+
+        # Soft fail-open path for projection-induced uncertainty: if the
+        # event's label is the UNRECOGNIZED sentinel and the protocol does
+        # not declare a transition for it at this state, return Unrecognized
+        # without halting and without advancing state — the outer loop is
+        # expected to drive a clarification turn and re-feed the result.
+        if label == UNRECOGNIZED:
+            return Unrecognized(expected=expected, direction=direction)
+
         got = f"{'!' if direction == 'send' else '?'}{label}"
         self._halted = True
         return Violation(expected=expected, got=got)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llmsessioncontract
-Version: 0.2.0
+Version: 0.2.2
 Summary: Runtime monitor for LLM agent interaction protocols based on session type theory
 Author-email: Chris Bartolo Burlo <chris@mizziburlo.com>
 License-Expression: MIT
@@ -111,6 +111,33 @@ for _ in range(100):
     m.receive("Pong")  # Ok()
 ```
 
+### Handling natural-language input: `Unrecognized`
+
+When the projection layer (typically over user chat) can't classify an event into a known label, it can emit the sentinel `UNRECOGNIZED` instead. The monitor treats this as a soft signal — distinct from `Violation` — without halting or advancing state, so the outer loop can drive a clarification turn:
+
+```python
+from llmcontract import Monitor, Ok, Unrecognized, UNRECOGNIZED
+
+m = Monitor("?{Yes.end, No.end}")
+result = m.receive(UNRECOGNIZED)         # projection couldn't decide
+assert isinstance(result, Unrecognized)  # not a Violation
+# state preserved; ask the agent to ask the user to clarify, then:
+m.receive("Yes")                         # Ok()
+```
+
+A protocol can also handle `Unrecognized` *explicitly* as a first-class branch — useful for "ask again" loops:
+
+```python
+protocol = "rec Loop.!Ask.?{Yes.end, No.end, Unrecognized.Loop}"
+m = Monitor(protocol)
+m.send("Ask")
+m.receive(UNRECOGNIZED)  # Ok — protocol routes back to Loop
+m.send("Ask")
+m.receive("Yes")         # Ok — terminal
+```
+
+The distinction matters at the system boundary: `Violation` means the agent broke the rules; `Unrecognized` means we don't have enough information to decide yet. Different responses (halt vs. clarify) come naturally from the typed result.
+
 ## 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.
@@ -236,6 +263,25 @@ Each step appears as a guardrail observation in your Langfuse trace with:
 - **Output**: `passed: true/false`, violation details if applicable
 - **Score**: `protocol_compliance` (boolean) for filtering and analytics
 
+## Claude Code Plugin
+
+A Claude Code plugin ships with this repo: **protocol-builder** walks you through designing a session-type protocol conversationally, validates it as you go, and emits a ready-to-paste Python integration snippet.
+
+```bash
+# Install in Claude Code
+/plugin marketplace add chrisbartoloburlo/llmcontract
+/plugin install protocol-builder@llmcontract
+
+# Then in any conversation
+/protocol-builder
+```
+
+The skill validates each draft DSL against `llmcontract`'s parser, so anything it produces is guaranteed to load with `Monitor(...)`. Source lives under `skills/protocol-builder/`.
+
+## 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).
+
 ## Research
 
 This work is based on the theory developed in:

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "llmsessioncontract"
-version = "0.2.0"
+version = "0.2.2"
 description = "Runtime monitor for LLM agent interaction protocols based on session type theory"
 requires-python = ">=3.10"
 license = "MIT"