llmsessioncontract 0.2.1__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llmsessioncontract
-Version: 0.2.1
+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.
@@ -251,6 +278,10 @@ A Claude Code plugin ships with this repo: **protocol-builder** walks you throug
 
 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.1 → 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.
@@ -222,6 +249,10 @@ A Claude Code plugin ships with this repo: **protocol-builder** walks you throug
 
 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.1 → 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.1 → 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.1 → llmsessioncontract-0.2.2/llmsessioncontract.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: llmsessioncontract
-Version: 0.2.1
+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.
@@ -251,6 +278,10 @@ A Claude Code plugin ships with this repo: **protocol-builder** walks you throug
 
 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.1 → llmsessioncontract-0.2.2}/pyproject.toml

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