handoff-guard 0.2.0__tar.gz → 0.2.1__tar.gz

{handoff_guard-0.2.0 → handoff_guard-0.2.1}/.github/workflows/publish.yml

@@ -16,6 +16,8 @@ jobs:
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: false
 
       - name: Build package
         run: uv build

{handoff_guard-0.2.0 → handoff_guard-0.2.1}/AGENTS.md

@@ -55,7 +55,7 @@ examples/
 ```python
 from handoff import guard, GuardConfig, HandoffViolation, ViolationContext
 from handoff import retry, RetryState, Diagnostic, AttemptRecord
-from handoff import parse_json, ParseError
+from handoff import parse_json, ParseResult, ParseError
 from handoff.langgraph import guarded_node, validate_state
 ```
 
@@ -105,6 +105,17 @@ Parses JSON from LLM text output. Processing chain:
 5. Repair malformed JSON via `json-repair` (trailing commas, single quotes, unquoted keys, missing braces, JS comments)
 6. Raise `ParseError` with detailed error message
 
+```python
+# Default mode: returns data directly
+data = parse_json(text)
+
+# Detailed mode: returns ParseResult with truncation/repair info
+result = parse_json(text, detailed=True)
+result.data        # dict or list
+result.truncated   # True if unmatched braces (likely max_tokens hit)
+result.repaired    # True if JSON had syntax errors that were auto-fixed
+```
+
 `ParseError` includes:
 - `.raw_output` — truncated input for debugging
 - `.original` — the underlying `JSONDecodeError` with line/column info
@@ -184,6 +195,6 @@ Tests are split across four files:
 - `test_guard.py` — Guard decorator: valid passthrough, invalid input/output raises, on_fail modes, custom node_name, input/output-only, async support, violation context and serialization
 - `test_retry.py` — Retry loop: succeeds on later attempt, exhausts max_attempts, RetryState injection, proxy behavior, feedback text, violation history, parse error retry, retry_on filtering, on_fail after retry, input validation skips retry, async retry
 - `test_testing.py` — `mock_retry()` context manager sets context and proxy works
-- `test_utils.py` — `parse_json`: valid JSON, code fence stripping, conversational wrapper stripping (preamble, postamble, combined, multiline, nested, arrays, escaped strings), JSON repair (trailing commas, single quotes, unquoted keys, missing braces, comments), invalid raises ParseError with original exception, non-string raises, BOM stripping, error location and suggestions (context snippet, pointer, preview)
+- `test_utils.py` — `parse_json`: valid JSON, code fence stripping, conversational wrapper stripping (preamble, postamble, combined, multiline, nested, arrays, escaped strings), JSON repair (trailing commas, single quotes, unquoted keys, missing braces, comments), invalid raises ParseError with original exception, non-string raises, BOM stripping, error location and suggestions (context snippet, pointer, preview), detailed mode with truncation/repair detection
 
 Run with: `pytest tests/ -v`

{handoff_guard-0.2.0 → handoff_guard-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoff-guard
-Version: 0.2.0
+Version: 0.2.1
 Summary: Lightweight validation at agent boundaries. Know what broke and where.
 Project-URL: Homepage, https://github.com/acartag7/handoff-guard
 Project-URL: Repository, https://github.com/acartag7/handoff-guard
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Requires-Dist: json-repair>=0.55.0
-Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic<3,>=2.0.0
 Provides-Extra: dev
 Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
@@ -31,10 +31,11 @@ Description-Content-Type: text/markdown
 
 # handoff-guard
 
-> Validation for LLM agents that retries with feedback.
+> Pydantic contracts for LLM agents: validate, retry with feedback, get actionable errors.
 
 [![PyPI version](https://img.shields.io/pypi/v/handoff-guard)](https://pypi.org/project/handoff-guard/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 
 ## The Problem
 
@@ -50,7 +51,7 @@ Which node? Which field? What was passed? Can the agent fix it?
 ## The Solution
 
 ```python
-from handoff import guard, retry, parse_json
+from handoff import guard, retry, parse_json  # PyPI: handoff-guard
 from pydantic import BaseModel, Field
 
 class WriterOutput(BaseModel):
@@ -66,11 +67,11 @@ def writer_agent(state: dict) -> dict:
     if retry.is_retry:
         prompt += f"\n\nYour previous attempt failed:\n{retry.feedback()}"
 
-    response = call_llm(prompt)
-    return parse_json(response)
+    response = call_llm(prompt)  # your LLM call here
+    return parse_json(response)  # @guard validates dict against WriterOutput, returns dict as-is
 ```
 
-When validation fails, the agent retries with feedback about what went wrong. After all attempts are exhausted:
+If valid, the function returns normally. If invalid, it retries with feedback. After all attempts exhausted:
 
 ```
 HandoffViolation in 'writer' (attempt 3/3):
@@ -87,13 +88,18 @@ HandoffViolation in 'writer' (attempt 3/3):
 pip install handoff-guard
 ```
 
-```bash
-# See retry-with-feedback in action (no API key needed)
-python -m examples.llm_demo.run_demo
+Requires Python 3.10+ and Pydantic v2.
 
-# Run with real LLM calls
-export OPENROUTER_API_KEY=your_key
-python -m examples.llm_demo.run_demo --pipeline --api
+```python
+from handoff import guard, retry, parse_json  # PyPI: handoff-guard
+```
+
+To run demos, clone the repo:
+
+```bash
+git clone https://github.com/acartag7/handoff-guard && cd handoff-guard
+pip install -e ".[dev]"
+python -m examples.llm_demo.run_demo  # no API key needed
 ```
 
 ## Features
@@ -102,9 +108,10 @@ python -m examples.llm_demo.run_demo --pipeline --api
 - **Know which node failed** — No more guessing from stack traces
 - **Know which field failed** — Exact path to the problem
 - **Get fix suggestions** — Actionable error messages
-- **`parse_json`** — Strips code fences, conversational wrappers, handles BOM, repairs malformed JSON (trailing commas, single quotes, unquoted keys, missing braces, comments), raises `ParseError` with actionable line/column info
-- **Framework agnostic** — Works with LangGraph, CrewAI, or plain Python
-- **Lightweight** — Just Pydantic, no Docker, no telemetry servers
+- **`parse_json`** — Strips code fences, conversational wrappers, handles BOM, repairs malformed JSON (trailing commas, single quotes, unquoted keys, missing braces, comments), raises `ParseError` with actionable line/column info. Use `detailed=True` to detect truncation and repair status
+- **Framework agnostic** — Works with LangGraph or plain Python
+- **Async supported** — Works with `async def` functions (context-local retry state)
+- **Lightweight** — Pydantic + json-repair, no Docker, no telemetry
 
 ## API
 
@@ -142,7 +149,7 @@ retry.history         # List of AttemptRecord objects
 ### `parse_json`
 
 ```python
-from handoff import parse_json
+from handoff import parse_json  # ParseResult is the return type when detailed=True
 
 # Handles code fences
 data = parse_json('```json\n{"key": "value"}\n```')
@@ -159,6 +166,12 @@ data = parse_json('{a: 1}')           # unquoted keys
 data = parse_json('{"a": 1')          # missing brace
 data = parse_json('{"a": 1 // comment}')  # JS comments
 
+# Detailed mode: detect truncation and repair
+result = parse_json('{"draft": "long text...', detailed=True)
+result.data        # the parsed dict/list
+result.truncated   # True if unmatched braces (e.g., token limit or stream cutoff)
+result.repaired    # True if JSON had syntax errors that were auto-fixed
+
 # Raises ParseError on failure (retryable by @guard)
 # ParseError includes detailed context:
 #   - Line/column location
@@ -221,7 +234,7 @@ def router(state: dict) -> dict:
 
 ## Why not just use Pydantic directly?
 
-You should! Handoff uses Pydantic under the hood.
+You should! handoff-guard uses Pydantic under the hood.
 
 The difference:
 
@@ -233,13 +246,6 @@ The difference:
 | No retry | Automatic retry with feedback |
 | Errors are for developers | Errors are actionable for agents |
 
-## Roadmap
-
-- [ ] Invariant contracts (input/output relationships)
-- [ ] CrewAI adapter
-- [x] Retry with feedback loop
-- [ ] VS Code extension for violation inspection
-
 ## Contributing
 
 Contributions welcome! Please open an issue first to discuss what you'd like to change.

{handoff_guard-0.2.0 → handoff_guard-0.2.1}/README.md

@@ -1,9 +1,10 @@
 # handoff-guard
 
-> Validation for LLM agents that retries with feedback.
+> Pydantic contracts for LLM agents: validate, retry with feedback, get actionable errors.
 
 [![PyPI version](https://img.shields.io/pypi/v/handoff-guard)](https://pypi.org/project/handoff-guard/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 
 ## The Problem
 
@@ -19,7 +20,7 @@ Which node? Which field? What was passed? Can the agent fix it?
 ## The Solution
 
 ```python
-from handoff import guard, retry, parse_json
+from handoff import guard, retry, parse_json  # PyPI: handoff-guard
 from pydantic import BaseModel, Field
 
 class WriterOutput(BaseModel):
@@ -35,11 +36,11 @@ def writer_agent(state: dict) -> dict:
     if retry.is_retry:
         prompt += f"\n\nYour previous attempt failed:\n{retry.feedback()}"
 
-    response = call_llm(prompt)
-    return parse_json(response)
+    response = call_llm(prompt)  # your LLM call here
+    return parse_json(response)  # @guard validates dict against WriterOutput, returns dict as-is
 ```
 
-When validation fails, the agent retries with feedback about what went wrong. After all attempts are exhausted:
+If valid, the function returns normally. If invalid, it retries with feedback. After all attempts exhausted:
 
 ```
 HandoffViolation in 'writer' (attempt 3/3):
@@ -56,13 +57,18 @@ HandoffViolation in 'writer' (attempt 3/3):
 pip install handoff-guard
 ```
 
-```bash
-# See retry-with-feedback in action (no API key needed)
-python -m examples.llm_demo.run_demo
+Requires Python 3.10+ and Pydantic v2.
 
-# Run with real LLM calls
-export OPENROUTER_API_KEY=your_key
-python -m examples.llm_demo.run_demo --pipeline --api
+```python
+from handoff import guard, retry, parse_json  # PyPI: handoff-guard
+```
+
+To run demos, clone the repo:
+
+```bash
+git clone https://github.com/acartag7/handoff-guard && cd handoff-guard
+pip install -e ".[dev]"
+python -m examples.llm_demo.run_demo  # no API key needed
 ```
 
 ## Features
@@ -71,9 +77,10 @@ python -m examples.llm_demo.run_demo --pipeline --api
 - **Know which node failed** — No more guessing from stack traces
 - **Know which field failed** — Exact path to the problem
 - **Get fix suggestions** — Actionable error messages
-- **`parse_json`** — Strips code fences, conversational wrappers, handles BOM, repairs malformed JSON (trailing commas, single quotes, unquoted keys, missing braces, comments), raises `ParseError` with actionable line/column info
-- **Framework agnostic** — Works with LangGraph, CrewAI, or plain Python
-- **Lightweight** — Just Pydantic, no Docker, no telemetry servers
+- **`parse_json`** — Strips code fences, conversational wrappers, handles BOM, repairs malformed JSON (trailing commas, single quotes, unquoted keys, missing braces, comments), raises `ParseError` with actionable line/column info. Use `detailed=True` to detect truncation and repair status
+- **Framework agnostic** — Works with LangGraph or plain Python
+- **Async supported** — Works with `async def` functions (context-local retry state)
+- **Lightweight** — Pydantic + json-repair, no Docker, no telemetry
 
 ## API
 
@@ -111,7 +118,7 @@ retry.history         # List of AttemptRecord objects
 ### `parse_json`
 
 ```python
-from handoff import parse_json
+from handoff import parse_json  # ParseResult is the return type when detailed=True
 
 # Handles code fences
 data = parse_json('```json\n{"key": "value"}\n```')
@@ -128,6 +135,12 @@ data = parse_json('{a: 1}')           # unquoted keys
 data = parse_json('{"a": 1')          # missing brace
 data = parse_json('{"a": 1 // comment}')  # JS comments
 
+# Detailed mode: detect truncation and repair
+result = parse_json('{"draft": "long text...', detailed=True)
+result.data        # the parsed dict/list
+result.truncated   # True if unmatched braces (e.g., token limit or stream cutoff)
+result.repaired    # True if JSON had syntax errors that were auto-fixed
+
 # Raises ParseError on failure (retryable by @guard)
 # ParseError includes detailed context:
 #   - Line/column location
@@ -190,7 +203,7 @@ def router(state: dict) -> dict:
 
 ## Why not just use Pydantic directly?
 
-You should! Handoff uses Pydantic under the hood.
+You should! handoff-guard uses Pydantic under the hood.
 
 The difference:
 
@@ -202,13 +215,6 @@ The difference:
 | No retry | Automatic retry with feedback |
 | Errors are for developers | Errors are actionable for agents |
 
-## Roadmap
-
-- [ ] Invariant contracts (input/output relationships)
-- [ ] CrewAI adapter
-- [x] Retry with feedback loop
-- [ ] VS Code extension for violation inspection
-
 ## Contributing
 
 Contributions welcome! Please open an issue first to discuss what you'd like to change.

{handoff_guard-0.2.0 → handoff_guard-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "handoff-guard"
-version = "0.2.0"
+version = "0.2.1"
 description = "Lightweight validation at agent boundaries. Know what broke and where."
 readme = "README.md"
 license = {text = "MIT"}
@@ -18,7 +18,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-    "pydantic>=2.0.0",
+    "pydantic>=2.0.0,<3",
     "json-repair>=0.55.0",
 ]
 

{handoff_guard-0.2.0 → handoff_guard-0.2.1}/src/handoff/__init__.py

@@ -1,7 +1,7 @@
 from handoff.core import HandoffViolation, ViolationContext
 from handoff.guard import guard, GuardConfig
 from handoff.retry import retry, RetryState, Diagnostic, AttemptRecord
-from handoff.utils import ParseError, parse_json
+from handoff.utils import ParseError, ParseResult, parse_json
 
 __all__ = [
     "guard",
@@ -13,7 +13,8 @@ __all__ = [
     "Diagnostic",
     "AttemptRecord",
     "ParseError",
+    "ParseResult",
     "parse_json",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{handoff_guard-0.2.0 → handoff_guard-0.2.1}/src/handoff/utils.py

@@ -1,11 +1,28 @@
 """Utility functions for handoff."""
 
+from dataclasses import dataclass
 import json
 import re
+from typing import overload, Literal
 
 from json_repair import loads as repair_json
 
 
+@dataclass
+class ParseResult:
+    """Result of parse_json with detailed=True.
+
+    Attributes:
+        data: The parsed JSON data (dict or list).
+        truncated: True if the input appeared to be truncated (e.g., hit max_tokens).
+        repaired: True if the JSON had syntax errors that were auto-fixed.
+    """
+
+    data: dict | list
+    truncated: bool = False
+    repaired: bool = False
+
+
 def _format_context_snippet(text: str, lineno: int, colno: int) -> str:
     """Format a snippet of text around the error location.
 
@@ -205,7 +222,59 @@ def _extract_json_substring(text: str) -> str | None:
     return None
 
 
-def parse_json(text: str) -> dict:
+def _is_likely_truncated(text: str) -> bool:
+    """Detect if JSON appears to be truncated (e.g., hit max_tokens).
+
+    Returns True if there are unmatched opening braces/brackets,
+    indicating the JSON was cut off before completion.
+    """
+    if not text:
+        return False
+
+    # Count unmatched braces/brackets, respecting JSON string boundaries
+    depth_brace = 0
+    depth_bracket = 0
+    in_string = False
+    escape = False
+
+    for ch in text:
+        if escape:
+            escape = False
+            continue
+
+        if ch == "\\":
+            if in_string:
+                escape = True
+            continue
+
+        if ch == '"':
+            in_string = not in_string
+            continue
+
+        if in_string:
+            continue
+
+        if ch == "{":
+            depth_brace += 1
+        elif ch == "}":
+            depth_brace -= 1
+        elif ch == "[":
+            depth_bracket += 1
+        elif ch == "]":
+            depth_bracket -= 1
+
+    return depth_brace > 0 or depth_bracket > 0
+
+
+@overload
+def parse_json(text: str, *, detailed: Literal[False] = False) -> dict | list: ...
+
+
+@overload
+def parse_json(text: str, *, detailed: Literal[True]) -> ParseResult: ...
+
+
+def parse_json(text: str, *, detailed: bool = False) -> dict | list | ParseResult:
     """Parse JSON from text, handling common LLM output quirks.
 
     Strips UTF-8 BOM, markdown code fences, and conversational
@@ -213,6 +282,13 @@ def parse_json(text: str) -> dict:
     common JSON malformations (trailing commas, single quotes,
     unquoted keys, missing braces, comments).
 
+    Args:
+        text: The text to parse as JSON.
+        detailed: If True, return a ParseResult with truncation/repair info.
+
+    Returns:
+        The parsed JSON data (dict or list), or ParseResult if detailed=True.
+
     Raises:
         ParseError: If text cannot be parsed as JSON.
     """
@@ -228,16 +304,29 @@ def parse_json(text: str) -> dict:
     # Track first decode error for actionable feedback
     first_error: json.JSONDecodeError | None = None
 
+    # Track status for detailed mode
+    was_repaired = False
+    was_truncated = False
+
+    # Check for truncation before any processing
+    if _is_likely_truncated(cleaned):
+        was_truncated = True
+
+    def _return(data: dict | list) -> dict | list | ParseResult:
+        if detailed:
+            return ParseResult(data=data, truncated=was_truncated, repaired=was_repaired)
+        return data
+
     # Fast path: try parsing directly
     try:
-        return json.loads(cleaned)
+        return _return(json.loads(cleaned))
     except json.JSONDecodeError as e:
         first_error = e
 
     # Strip code fences and retry
     stripped = _strip_code_fences(cleaned)
     try:
-        return json.loads(stripped)
+        return _return(json.loads(stripped))
     except json.JSONDecodeError:
         pass
 
@@ -245,7 +334,7 @@ def parse_json(text: str) -> dict:
     extracted = _extract_json_substring(cleaned)
     if extracted is not None:
         try:
-            return json.loads(extracted)
+            return _return(json.loads(extracted))
         except json.JSONDecodeError:
             pass
 
@@ -255,7 +344,8 @@ def parse_json(text: str) -> dict:
         repaired = repair_json(repair_target)
         # Only accept dict/list results (json_repair returns "" for invalid input)
         if isinstance(repaired, (dict, list)):
-            return repaired
+            was_repaired = True
+            return _return(repaired)
     except Exception:
         pass
 

{handoff_guard-0.2.0 → handoff_guard-0.2.1}/tests/test_utils.py

@@ -1,7 +1,7 @@
 """Tests for handoff.utils."""
 
 import pytest
-from handoff.utils import parse_json, ParseError
+from handoff.utils import parse_json, ParseError, ParseResult
 
 
 class TestParseJson:
@@ -195,3 +195,78 @@ class TestParseJson:
         # Should have location info
         assert "line" in msg
         assert "column" in msg or "col" in msg
+
+    # --- Detailed mode with truncation/repair detection (HG-13) ---
+
+    def test_detailed_returns_parse_result(self):
+        result = parse_json('{"a": 1}', detailed=True)
+        assert isinstance(result, ParseResult)
+        assert result.data == {"a": 1}
+        assert result.truncated is False
+        assert result.repaired is False
+
+    def test_detailed_false_returns_data_directly(self):
+        result = parse_json('{"a": 1}', detailed=False)
+        assert result == {"a": 1}
+        assert not isinstance(result, ParseResult)
+
+    def test_detailed_detects_truncation_missing_brace(self):
+        # Simulates max_tokens cutoff mid-object
+        text = '{"draft": "This is a long article about technology'
+        result = parse_json(text, detailed=True)
+        assert result.truncated is True
+        assert result.repaired is True  # json_repair fixes it
+        assert result.data == {"draft": "This is a long article about technology"}
+
+    def test_detailed_detects_truncation_missing_bracket(self):
+        # Simulates max_tokens cutoff mid-array
+        text = '{"items": [1, 2, 3, 4, 5'
+        result = parse_json(text, detailed=True)
+        assert result.truncated is True
+        assert result.repaired is True
+        assert result.data == {"items": [1, 2, 3, 4, 5]}
+
+    def test_detailed_detects_truncation_nested(self):
+        # Deeply nested structure cut off
+        text = '{"a": {"b": {"c": "value'
+        result = parse_json(text, detailed=True)
+        assert result.truncated is True
+        assert result.repaired is True
+
+    def test_detailed_detects_repair_trailing_comma(self):
+        # Trailing comma needs repair but is not truncation
+        text = '{"a": 1, "b": 2,}'
+        result = parse_json(text, detailed=True)
+        assert result.truncated is False  # Balanced braces
+        assert result.repaired is True
+        assert result.data == {"a": 1, "b": 2}
+
+    def test_detailed_detects_repair_single_quotes(self):
+        text = "{'a': 'hello'}"
+        result = parse_json(text, detailed=True)
+        assert result.truncated is False
+        assert result.repaired is True
+        assert result.data == {"a": "hello"}
+
+    def test_detailed_valid_json_no_flags(self):
+        # Valid JSON should have both flags as False
+        text = '{"valid": true, "count": 42}'
+        result = parse_json(text, detailed=True)
+        assert result.truncated is False
+        assert result.repaired is False
+        assert result.data == {"valid": True, "count": 42}
+
+    def test_detailed_with_wrappers_no_repair(self):
+        # Conversational wrappers don't count as repair
+        text = 'Sure! Here is the JSON:\n{"a": 1}'
+        result = parse_json(text, detailed=True)
+        assert result.truncated is False
+        assert result.repaired is False  # Extraction != repair
+        assert result.data == {"a": 1}
+
+    def test_detailed_truncated_with_wrappers(self):
+        # Truncated JSON inside wrappers
+        text = 'Here you go:\n{"items": [1, 2, 3'
+        result = parse_json(text, detailed=True)
+        assert result.truncated is True
+        assert result.repaired is True