handoff-guard 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

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/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.dist-info → handoff_guard-0.2.1.dist-info}/METADATA

@@ -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.dist-info → handoff_guard-0.2.1.dist-info}/RECORD

@@ -1,11 +1,11 @@
-handoff/__init__.py,sha256=RDO2wqA1zROrtM2GE_B_1pLA4OOClCzzjMARaorB-Oo,449
+handoff/__init__.py,sha256=2dMVFewz6vrM0v6VYkdX0Vn0OOiSwbEu8AEI8wj4ExI,481
 handoff/core.py,sha256=zVGKyLO7TxwoJS_J5n-c47OdQGUmrQJjIvRW97tInBs,3173
 handoff/guard.py,sha256=gmrg9odUin8YSUUjtUSzIMTz7u9DPWyLXYjfvcJlA4g,18603
 handoff/langgraph.py,sha256=MLm4G2uZWiE30lFKU99DEA_LjlSHzTvb5Ci7urFlyF8,1931
 handoff/retry.py,sha256=QVuPAygS3hEEXKS9h073uW4N0erURXiyIYFllsaR1YY,3891
 handoff/testing.py,sha256=WlsEKyOX8_M8cfUc3xbcoMFU4Pyn-j1ffD8xPigAQ_Q,915
-handoff/utils.py,sha256=u3zsnvwf5vcmzVUCiy73iNaskaUNpRnlljle57tu3Ks,8281
-handoff_guard-0.2.0.dist-info/METADATA,sha256=PsauQeZ7e_ez0ilb4JIrL4O5-9qSQkz1pMD7qraApp0,7868
-handoff_guard-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-handoff_guard-0.2.0.dist-info/licenses/LICENSE,sha256=HroDuVS_iz3RlUAJhww1Ma4olb4onXHg1MXaIZCb06s,1063
-handoff_guard-0.2.0.dist-info/RECORD,,
+handoff/utils.py,sha256=hMsvdxgoFtF324iBMVrlniS-6mZKLsCVuDYD5mRRJts,10688
+handoff_guard-0.2.1.dist-info/METADATA,sha256=MwcPliqUxlc7XFd36rZfuZSc4SAeN9hz6K9oA2qMLLk,8554
+handoff_guard-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+handoff_guard-0.2.1.dist-info/licenses/LICENSE,sha256=HroDuVS_iz3RlUAJhww1Ma4olb4onXHg1MXaIZCb06s,1063
+handoff_guard-0.2.1.dist-info/RECORD,,