handoff-guard 0.1.0__py3-none-any.whl

handoff/__init__.py

@@ -0,0 +1,19 @@
+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
+
+__all__ = [
+    "guard",
+    "GuardConfig",
+    "HandoffViolation",
+    "ViolationContext",
+    "retry",
+    "RetryState",
+    "Diagnostic",
+    "AttemptRecord",
+    "ParseError",
+    "parse_json",
+]
+
+__version__ = "0.2.0"

handoff/core.py

@@ -0,0 +1,95 @@
+"""Core types for handoff validation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, TYPE_CHECKING
+from datetime import datetime, timezone
+
+if TYPE_CHECKING:
+    from handoff.retry import AttemptRecord
+
+
+@dataclass
+class ViolationContext:
+    """Rich context about where and why validation failed."""
+
+    node_name: str
+    contract_type: str  # "input" | "output" | "invariant"
+    field_path: str     # e.g., "response.refund_id"
+    expected: str       # Human-readable expectation
+    received: Any       # What we actually got
+    received_type: str  # Type of what we got
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    upstream_node: str | None = None
+    suggestion: str | None = None
+
+    def __str__(self) -> str:
+        lines = [
+            f"HandoffViolation in '{self.node_name}':",
+            f"  Contract: {self.contract_type}",
+            f"  Field: {self.field_path}",
+            f"  Expected: {self.expected}",
+            f"  Received: {repr(self.received)[:100]} ({self.received_type})",
+        ]
+        if self.upstream_node:
+            lines.append(f"  Upstream: {self.upstream_node}")
+        if self.suggestion:
+            lines.append(f"  Suggestion: {self.suggestion}")
+        return "\n".join(lines)
+
+
+class HandoffViolation(Exception):
+    """Raised when validation fails at an agent boundary."""
+
+    def __init__(
+        self,
+        context: ViolationContext,
+        history: list[AttemptRecord] | None = None,
+    ):
+        self.context = context
+        self.history: list[AttemptRecord] = history or []
+        super().__init__(str(context))
+
+    @property
+    def node_name(self) -> str:
+        return self.context.node_name
+
+    @property
+    def field_path(self) -> str:
+        return self.context.field_path
+
+    @property
+    def total_attempts(self) -> int:
+        return len(self.history) if self.history else 1
+
+    def to_dict(self) -> dict:
+        """Serialize for logging/telemetry."""
+        d = {
+            "node_name": self.context.node_name,
+            "contract_type": self.context.contract_type,
+            "field_path": self.context.field_path,
+            "expected": self.context.expected,
+            "received": repr(self.context.received)[:200],
+            "received_type": self.context.received_type,
+            "timestamp": self.context.timestamp.isoformat(),
+            "upstream_node": self.context.upstream_node,
+            "suggestion": self.context.suggestion,
+        }
+        if self.history:
+            d["total_attempts"] = self.total_attempts
+            d["history"] = [
+                {
+                    "attempt": rec.attempt,
+                    "timestamp": rec.timestamp.isoformat(),
+                    "duration_ms": rec.duration_ms,
+                    "diagnostic": {
+                        "cause": rec.diagnostic.cause,
+                        "message": rec.diagnostic.message,
+                    }
+                    if rec.diagnostic
+                    else None,
+                }
+                for rec in self.history
+            ]
+        return d

handoff/guard.py

@@ -0,0 +1,469 @@
+"""The @guard decorator for validating agent boundaries."""
+
+import json
+import time
+from dataclasses import dataclass
+from functools import wraps
+from typing import Any, Callable, TypeVar, Type, Literal
+import inspect
+
+from pydantic import BaseModel, ValidationError
+
+from handoff.core import HandoffViolation, ViolationContext
+from handoff.retry import (
+    _retry_context,
+    RetryState,
+    Diagnostic,
+    AttemptRecord,
+)
+from handoff.utils import ParseError
+
+
+T = TypeVar("T")
+OnFailAction = Literal["raise", "return_none", "return_input"]
+
+
+@dataclass
+class GuardConfig:
+    """Configuration for guard behavior."""
+
+    input_schema: Type[BaseModel] | None = None
+    output_schema: Type[BaseModel] | None = None
+    node_name: str | None = None  # Auto-detected from function name if not provided
+    on_fail: OnFailAction | Callable[[HandoffViolation], Any] = "raise"
+    validate_input: bool = True
+    validate_output: bool = True
+
+
+def _generate_suggestion(
+    err_type: str, field_path: str, contract_type: str
+) -> str | None:
+    """Generate a helpful suggestion based on Pydantic error type."""
+    if err_type == "missing":
+        return f"Add '{field_path}' to the {contract_type} data"
+    elif err_type == "string_type":
+        return f"Convert '{field_path}' to string"
+    elif err_type == "int_type":
+        return f"Convert '{field_path}' to integer"
+    elif err_type == "string_too_short":
+        return f"Increase the length of '{field_path}'"
+    elif err_type == "string_too_long":
+        return f"Reduce the length of '{field_path}'"
+    elif err_type == "too_short":
+        return f"Add more items to '{field_path}'"
+    elif err_type == "too_long":
+        return f"Reduce the number of items in '{field_path}'"
+    elif err_type == "greater_than_equal":
+        return f"Increase the value of '{field_path}'"
+    elif err_type == "less_than_equal":
+        return f"Decrease the value of '{field_path}'"
+    elif err_type == "string_pattern_mismatch":
+        return f"'{field_path}' does not match the required pattern"
+    return None
+
+
+def _extract_violations(
+    error: ValidationError,
+    node_name: str,
+    contract_type: str,
+    raw_data: Any,
+) -> list[ViolationContext]:
+    """Convert Pydantic ValidationError to rich ViolationContext objects."""
+
+    violations = []
+    for err in error.errors():
+        field_path = ".".join(str(loc) for loc in err["loc"])
+
+        # Try to get the actual value at the path
+        received = raw_data
+        for loc in err["loc"]:
+            if isinstance(received, dict):
+                received = received.get(loc, "<missing>")
+            elif hasattr(received, str(loc)):
+                received = getattr(received, str(loc), "<missing>")
+            else:
+                received = "<missing>"
+                break
+
+        suggestion = _generate_suggestion(err["type"], field_path, contract_type)
+
+        violations.append(
+            ViolationContext(
+                node_name=node_name,
+                contract_type=contract_type,
+                field_path=field_path or "<root>",
+                expected=err["msg"],
+                received=received,
+                received_type=type(received).__name__,
+                suggestion=suggestion,
+            )
+        )
+
+    return violations
+
+
+def _validate_data(
+    data: Any,
+    schema: Type[BaseModel],
+    node_name: str,
+    contract_type: str,
+) -> tuple[bool, BaseModel | None, list[ViolationContext]]:
+    """Validate data against schema, return (success, validated_model, violations)."""
+
+    try:
+        # Handle both dict and BaseModel inputs
+        if isinstance(data, BaseModel):
+            validated = schema.model_validate(data.model_dump())
+        elif isinstance(data, dict):
+            validated = schema.model_validate(data)
+        else:
+            # Try to convert to dict
+            validated = schema.model_validate(
+                data.__dict__ if hasattr(data, "__dict__") else {"value": data}
+            )
+        return True, validated, []
+
+    except ValidationError as e:
+        violations = _extract_violations(e, node_name, contract_type, data)
+        return False, None, violations
+
+
+def _build_validation_diagnostic(
+    violations: list[ViolationContext],
+    result: Any,
+) -> Diagnostic:
+    """Build a Diagnostic from output validation violations."""
+    errors = [
+        f"{v.field_path}: expected {v.expected}, got {repr(v.received)[:100]}"
+        for v in violations
+    ]
+    return Diagnostic(
+        cause="validation",
+        message="Output validation failed",
+        errors=errors,
+        raw_output=repr(result)[:500] if result is not None else None,
+        field_path=violations[0].field_path if violations else None,
+        suggestion=violations[0].suggestion if violations else None,
+    )
+
+
+def _build_parse_diagnostic(exc: Exception, raw: Any = None) -> Diagnostic:
+    """Build a Diagnostic from a parse error."""
+    raw_output = None
+    if isinstance(exc, ParseError):
+        raw_output = exc.raw_output
+    elif raw is not None:
+        raw_output = repr(raw)[:500]
+    return Diagnostic(
+        cause="parse",
+        message=str(exc),
+        raw_output=raw_output,
+    )
+
+
+def guard(
+    input: Type[BaseModel] | None = None,
+    output: Type[BaseModel] | None = None,
+    *,
+    node_name: str | None = None,
+    max_attempts: int = 1,
+    retry_on: tuple[str, ...] = ("validation", "parse"),
+    on_fail: OnFailAction | Callable[[HandoffViolation], Any] = "raise",
+    input_param: str | None = "state",
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    Decorator to validate input/output at agent boundaries.
+
+    Args:
+        input: Pydantic model to validate input against
+        output: Pydantic model to validate output against
+        node_name: Override the node name (defaults to function name)
+        max_attempts: Maximum number of attempts (1 = no retry, default)
+        retry_on: Tuple of error types to retry on ("validation", "parse")
+        on_fail: What to do on validation failure:
+            - "raise": Raise HandoffViolation (default)
+            - "return_none": Return None
+            - "return_input": Return input unchanged
+            - callable: Call with HandoffViolation, return its result
+        input_param: Name of the input argument to validate (default: "state")
+
+    Example:
+        @guard(input=RequestSchema, output=ResponseSchema)
+        def my_agent_node(state: dict) -> dict:
+            ...
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        _node_name = node_name or func.__name__
+        is_async = inspect.iscoroutinefunction(func)
+
+        # Check if function accepts a 'retry' parameter
+        sig = inspect.signature(func)
+        _accepts_retry = "retry" in sig.parameters
+
+        def _bind_input(args: tuple, kwargs: dict) -> Any:
+            """Extract the input argument using signature binding."""
+            if input_param is None:
+                if args:
+                    return args[0]
+                return kwargs.get("state")
+            try:
+                bound = sig.bind_partial(*args, **kwargs)
+            except TypeError:
+                return kwargs.get(input_param)
+            if input_param in bound.arguments:
+                return bound.arguments[input_param]
+            return kwargs.get(input_param)
+
+        def _handle_violation(violation: HandoffViolation, input_data: Any) -> Any:
+            if on_fail == "raise":
+                raise violation
+            elif on_fail == "return_none":
+                return None
+            elif on_fail == "return_input":
+                return input_data
+            elif callable(on_fail):
+                return on_fail(violation)
+            else:
+                raise violation
+
+        def _validate_input(
+            args: tuple, kwargs: dict
+        ) -> tuple[Any, list[ViolationContext]]:
+            if not input:
+                return _bind_input(args, kwargs), []
+
+            input_data = _bind_input(args, kwargs)
+
+            success, validated, violations = _validate_data(
+                input_data, input, _node_name, "input"
+            )
+
+            if not success:
+                return input_data, violations
+
+            return input_data, []
+
+        def _validate_output_data(result: Any) -> list[ViolationContext]:
+            if not output:
+                return []
+
+            success, validated, violations = _validate_data(
+                result, output, _node_name, "output"
+            )
+
+            return violations
+
+        def _is_retryable_parse_error(exc: Exception) -> bool:
+            """Check if exception is a parse-related error eligible for retry."""
+            return isinstance(exc, (ParseError, json.JSONDecodeError))
+
+        if is_async:
+
+            @wraps(func)
+            async def async_wrapper(*args, **kwargs) -> T:
+                # Validate input (outside retry loop — input doesn't change)
+                input_data, input_violations = _validate_input(args, kwargs)
+                if input_violations:
+                    violation = HandoffViolation(input_violations[0])
+                    return _handle_violation(violation, input_data)
+
+                history: list[AttemptRecord] = []
+                last_diagnostic: Diagnostic | None = None
+
+                for attempt_num in range(1, max_attempts + 1):
+                    state = RetryState(
+                        attempt=attempt_num,
+                        max_attempts=max_attempts,
+                        last_error=last_diagnostic,
+                        history=list(history),
+                    )
+                    token = _retry_context.set(state)
+                    start_time = time.monotonic()
+                    try:
+                        # Inject retry kwarg if function accepts it
+                        call_kwargs = dict(kwargs)
+                        if _accepts_retry and "retry" not in call_kwargs:
+                            call_kwargs["retry"] = state
+
+                        try:
+                            result = await func(*args, **call_kwargs)
+                        except Exception as exc:
+                            if (
+                                _is_retryable_parse_error(exc)
+                                and "parse" in retry_on
+                                and max_attempts > 1
+                            ):
+                                elapsed = (time.monotonic() - start_time) * 1000
+                                diag = _build_parse_diagnostic(
+                                    exc, getattr(exc, "raw_output", None)
+                                )
+                                last_diagnostic = diag
+                                history.append(
+                                    AttemptRecord(
+                                        attempt=attempt_num,
+                                        diagnostic=diag,
+                                        duration_ms=elapsed,
+                                    )
+                                )
+                                if attempt_num < max_attempts:
+                                    continue
+                                # Final attempt — build violation
+                                violation_ctx = ViolationContext(
+                                    node_name=_node_name,
+                                    contract_type="output",
+                                    field_path="<parse>",
+                                    expected="Valid parseable output",
+                                    received=str(exc),
+                                    received_type=type(exc).__name__,
+                                    suggestion="Return valid JSON or structured data",
+                                )
+                                violation = HandoffViolation(
+                                    violation_ctx, history=history
+                                )
+                                return _handle_violation(violation, input_data)
+                            else:
+                                raise
+
+                        # Validate output
+                        output_violations = _validate_output_data(result)
+                        elapsed = (time.monotonic() - start_time) * 1000
+                        if output_violations:
+                            diag = _build_validation_diagnostic(
+                                output_violations, result
+                            )
+                            last_diagnostic = diag
+                            history.append(
+                                AttemptRecord(
+                                    attempt=attempt_num,
+                                    diagnostic=diag,
+                                    duration_ms=elapsed,
+                                )
+                            )
+                            if "validation" in retry_on and attempt_num < max_attempts:
+                                continue
+                            # Final attempt or validation not retried
+                            violation = HandoffViolation(
+                                output_violations[0], history=history
+                            )
+                            return _handle_violation(violation, input_data)
+
+                        # Success
+                        history.append(
+                            AttemptRecord(
+                                attempt=attempt_num,
+                                duration_ms=elapsed,
+                            )
+                        )
+                        return result
+
+                    finally:
+                        _retry_context.reset(token)
+
+            return async_wrapper
+
+        else:
+
+            @wraps(func)
+            def sync_wrapper(*args, **kwargs) -> T:
+                # Validate input (outside retry loop — input doesn't change)
+                input_data, input_violations = _validate_input(args, kwargs)
+                if input_violations:
+                    violation = HandoffViolation(input_violations[0])
+                    return _handle_violation(violation, input_data)
+
+                history: list[AttemptRecord] = []
+                last_diagnostic: Diagnostic | None = None
+
+                for attempt_num in range(1, max_attempts + 1):
+                    state = RetryState(
+                        attempt=attempt_num,
+                        max_attempts=max_attempts,
+                        last_error=last_diagnostic,
+                        history=list(history),
+                    )
+                    token = _retry_context.set(state)
+                    start_time = time.monotonic()
+                    try:
+                        # Inject retry kwarg if function accepts it
+                        call_kwargs = dict(kwargs)
+                        if _accepts_retry and "retry" not in call_kwargs:
+                            call_kwargs["retry"] = state
+
+                        try:
+                            result = func(*args, **call_kwargs)
+                        except Exception as exc:
+                            if (
+                                _is_retryable_parse_error(exc)
+                                and "parse" in retry_on
+                                and max_attempts > 1
+                            ):
+                                elapsed = (time.monotonic() - start_time) * 1000
+                                diag = _build_parse_diagnostic(
+                                    exc, getattr(exc, "raw_output", None)
+                                )
+                                last_diagnostic = diag
+                                history.append(
+                                    AttemptRecord(
+                                        attempt=attempt_num,
+                                        diagnostic=diag,
+                                        duration_ms=elapsed,
+                                    )
+                                )
+                                if attempt_num < max_attempts:
+                                    continue
+                                # Final attempt — build violation
+                                violation_ctx = ViolationContext(
+                                    node_name=_node_name,
+                                    contract_type="output",
+                                    field_path="<parse>",
+                                    expected="Valid parseable output",
+                                    received=str(exc),
+                                    received_type=type(exc).__name__,
+                                    suggestion="Return valid JSON or structured data",
+                                )
+                                violation = HandoffViolation(
+                                    violation_ctx, history=history
+                                )
+                                return _handle_violation(violation, input_data)
+                            else:
+                                raise
+
+                        # Validate output
+                        output_violations = _validate_output_data(result)
+                        elapsed = (time.monotonic() - start_time) * 1000
+                        if output_violations:
+                            diag = _build_validation_diagnostic(
+                                output_violations, result
+                            )
+                            last_diagnostic = diag
+                            history.append(
+                                AttemptRecord(
+                                    attempt=attempt_num,
+                                    diagnostic=diag,
+                                    duration_ms=elapsed,
+                                )
+                            )
+                            if "validation" in retry_on and attempt_num < max_attempts:
+                                continue
+                            # Final attempt or validation not retried
+                            violation = HandoffViolation(
+                                output_violations[0], history=history
+                            )
+                            return _handle_violation(violation, input_data)
+
+                        # Success
+                        history.append(
+                            AttemptRecord(
+                                attempt=attempt_num,
+                                duration_ms=elapsed,
+                            )
+                        )
+                        return result
+
+                    finally:
+                        _retry_context.reset(token)
+
+            return sync_wrapper
+
+    return decorator

handoff/langgraph.py

@@ -0,0 +1,76 @@
+"""LangGraph-specific utilities for handoff validation."""
+
+from typing import Any, Type, Callable, TypeVar
+from pydantic import BaseModel
+
+from handoff.guard import guard
+from handoff.core import HandoffViolation
+
+
+T = TypeVar("T")
+
+
+def guarded_node(
+    input: Type[BaseModel] | None = None,
+    output: Type[BaseModel] | None = None,
+    *,
+    max_attempts: int = 1,
+    retry_on: tuple[str, ...] = ("validation", "parse"),
+    on_fail: str | Callable[[HandoffViolation], Any] = "raise",
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """
+    LangGraph-specific decorator for node validation.
+
+    Wraps @guard with LangGraph-friendly defaults.
+
+    Example:
+        from handoff.langgraph import guarded_node
+
+        class AgentInput(BaseModel):
+            messages: list
+            context: dict
+
+        class AgentOutput(BaseModel):
+            messages: list
+            next_agent: str
+
+        @guarded_node(input=AgentInput, output=AgentOutput)
+        def my_agent(state: dict) -> dict:
+            # Your agent logic
+            return {"messages": [...], "next_agent": "reviewer"}
+    """
+    return guard(
+        input=input,
+        output=output,
+        max_attempts=max_attempts,
+        retry_on=retry_on,
+        on_fail=on_fail,
+    )
+
+
+def validate_state(
+    state: dict | BaseModel,
+    schema: Type[BaseModel],
+    node_name: str = "unknown",
+) -> BaseModel:
+    """
+    Explicitly validate state against a schema.
+
+    Use this for manual validation points, e.g., before checkpointing.
+
+    Raises:
+        HandoffViolation: If validation fails
+
+    Example:
+        validated = validate_state(state, MyStateSchema, node_name="pre_checkpoint")
+    """
+    from handoff.guard import _validate_data
+
+    success, validated, violations = _validate_data(
+        state, schema, node_name, "state"
+    )
+
+    if not success:
+        raise HandoffViolation(violations[0])
+
+    return validated

handoff/retry.py

@@ -0,0 +1,145 @@
+"""Retry-with-feedback data structures and async-safe proxy."""
+
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Literal
+
+RetryCause = Literal["validation", "parse"]
+
+_RAW_OUTPUT_MAX = 500
+_FEEDBACK_MAX_DEFAULT = 2000
+
+
+@dataclass
+class Diagnostic:
+    """Describes why an attempt failed."""
+
+    cause: RetryCause
+    message: str
+    errors: list[str] = field(default_factory=list)
+    raw_output: str | None = None
+    field_path: str | None = None
+    suggestion: str | None = None
+
+    def __post_init__(self):
+        if self.raw_output and len(self.raw_output) > _RAW_OUTPUT_MAX:
+            self.raw_output = self.raw_output[:_RAW_OUTPUT_MAX]
+
+
+@dataclass
+class AttemptRecord:
+    """Record of a single attempt."""
+
+    attempt: int
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    diagnostic: Diagnostic | None = None
+    duration_ms: float | None = None
+
+
+@dataclass
+class RetryState:
+    """Current retry state passed to functions."""
+
+    attempt: int = 1
+    max_attempts: int = 1
+    last_error: Diagnostic | None = None
+    history: list[AttemptRecord] = field(default_factory=list)
+
+    @property
+    def remaining(self) -> int:
+        return max(0, self.max_attempts - self.attempt)
+
+    @property
+    def is_retry(self) -> bool:
+        return self.attempt > 1
+
+    @property
+    def is_final_attempt(self) -> bool:
+        return self.attempt >= self.max_attempts
+
+    def feedback(self, max_chars: int = _FEEDBACK_MAX_DEFAULT) -> str | None:
+        if self.last_error is None:
+            return None
+        text = _format_diagnostic(self.last_error)
+        if len(text) > max_chars:
+            text = text[:max_chars]
+        return text
+
+
+def _format_diagnostic(diag: Diagnostic) -> str:
+    """Render a Diagnostic as LLM-friendly text."""
+    lines = [
+        f"[Retry] Previous attempt failed ({diag.cause}):",
+        f"  Message: {diag.message}",
+    ]
+    if diag.errors:
+        lines.append("  Errors:")
+        for err in diag.errors:
+            lines.append(f"    - {err}")
+    if diag.field_path:
+        lines.append(f"  Field: {diag.field_path}")
+    if diag.suggestion:
+        lines.append(f"  Suggestion: {diag.suggestion}")
+    if diag.raw_output:
+        lines.append(f"  Raw output: {diag.raw_output}")
+    return "\n".join(lines)
+
+
+_retry_context: ContextVar[RetryState | None] = ContextVar(
+    "_retry_context", default=None
+)
+
+
+class _RetryProxy:
+    """Reads from _retry_context, exposes RetryState interface with safe defaults."""
+
+    def _get(self) -> RetryState | None:
+        return _retry_context.get(None)
+
+    def get(self) -> RetryState | None:
+        return self._get()
+
+    @property
+    def attempt(self) -> int:
+        state = self._get()
+        return state.attempt if state else 1
+
+    @property
+    def max_attempts(self) -> int:
+        state = self._get()
+        return state.max_attempts if state else 1
+
+    @property
+    def remaining(self) -> int:
+        state = self._get()
+        return state.remaining if state else 0
+
+    @property
+    def is_retry(self) -> bool:
+        state = self._get()
+        return state.is_retry if state else False
+
+    @property
+    def is_final_attempt(self) -> bool:
+        state = self._get()
+        return state.is_final_attempt if state else True
+
+    @property
+    def last_error(self) -> Diagnostic | None:
+        state = self._get()
+        return state.last_error if state else None
+
+    @property
+    def history(self) -> list[AttemptRecord]:
+        state = self._get()
+        return state.history if state else []
+
+    def feedback(self, max_chars: int = _FEEDBACK_MAX_DEFAULT) -> str | None:
+        state = self._get()
+        if state is None:
+            return None
+        return state.feedback(max_chars)
+
+
+retry = _RetryProxy()

handoff/testing.py

@@ -0,0 +1,39 @@
+"""Test utilities for handoff retry."""
+
+from contextlib import contextmanager
+
+from handoff.retry import (
+    _retry_context,
+    RetryState,
+    Diagnostic,
+)
+
+
+@contextmanager
+def mock_retry(
+    attempt: int = 2,
+    max_attempts: int = 3,
+    last_error: Diagnostic | None = None,
+    feedback_text: str | None = None,
+):
+    """Context manager that sets retry state for testing.
+
+    If feedback_text is provided without last_error, creates a simple
+    validation Diagnostic with that text as the message.
+    """
+    if feedback_text and last_error is None:
+        last_error = Diagnostic(
+            cause="validation",
+            message=feedback_text,
+        )
+
+    state = RetryState(
+        attempt=attempt,
+        max_attempts=max_attempts,
+        last_error=last_error,
+    )
+    token = _retry_context.set(state)
+    try:
+        yield state
+    finally:
+        _retry_context.reset(token)

handoff/utils.py

@@ -0,0 +1,49 @@
+"""Utility functions for handoff."""
+
+import json
+
+
+class ParseError(Exception):
+    """Raised when output cannot be parsed as JSON."""
+
+    def __init__(self, message: str, raw_output: str | None = None):
+        self.raw_output = raw_output
+        super().__init__(message)
+
+
+def parse_json(text: str) -> dict:
+    """Parse JSON from text, handling common LLM output quirks.
+
+    Strips UTF-8 BOM and markdown code fences before parsing.
+
+    Raises:
+        ParseError: If text cannot be parsed as JSON.
+    """
+    if not isinstance(text, str):
+        raise ParseError(
+            f"Expected string, got {type(text).__name__}",
+            raw_output=repr(text)[:500],
+        )
+
+    # Strip UTF-8 BOM
+    cleaned = text.lstrip("\ufeff")
+
+    # Strip markdown code fences
+    stripped = cleaned.strip()
+    if stripped.startswith("```"):
+        lines = stripped.split("\n", 1)
+        if len(lines) > 1:
+            body = lines[1]
+        else:
+            body = ""
+        if body.rstrip().endswith("```"):
+            body = body.rstrip()[: -len("```")]
+        stripped = body.strip()
+
+    try:
+        return json.loads(stripped)
+    except json.JSONDecodeError as e:
+        raise ParseError(
+            f"Failed to parse JSON: {e}",
+            raw_output=text[:500],
+        ) from e

handoff_guard-0.1.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: handoff-guard
+Version: 0.1.0
+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
+Author-email: Arnold <cartagena.arnold@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,handoff,langgraph,multi-agent,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
+Provides-Extra: llm
+Requires-Dist: httpx>=0.25.0; extra == 'llm'
+Requires-Dist: langgraph>=0.2.0; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# handoff-guard
+
+> Validation for LLM agents that retries with feedback.
+
+[![PyPI version](https://badge.fury.io/py/handoff-guard.svg)](https://badge.fury.io/py/handoff-guard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## The Problem
+
+When an LLM agent returns bad output, you get a generic error and no recovery path:
+
+```
+ValidationError: 1 validation error for State
+   field required (type=value_error.missing)
+```
+
+Which node? Which field? What was passed? Can the agent fix it?
+
+## The Solution
+
+```python
+from handoff import guard, retry, parse_json
+from pydantic import BaseModel, Field
+
+class WriterOutput(BaseModel):
+    draft: str = Field(min_length=100)
+    word_count: int = Field(ge=50)
+    tone: str
+    title: str
+
+@guard(output=WriterOutput, node_name="writer", max_attempts=3)
+def writer_agent(state: dict) -> dict:
+    prompt = "Write a JSON response with: draft, word_count, tone, title."
+
+    if retry.is_retry:
+        prompt += f"\n\nYour previous attempt failed:\n{retry.feedback()}"
+
+    response = call_llm(prompt)
+    return parse_json(response)
+```
+
+When validation fails, the agent retries with feedback about what went wrong. After all attempts are exhausted:
+
+```
+HandoffViolation in 'writer' (attempt 3/3):
+  Contract: output
+  Field: draft
+  Expected: String should have at least 100 characters
+  Suggestion: Increase the length of 'draft'
+  History: 3 failed attempts
+```
+
+## Quick Start
+
+```bash
+pip install handoff-guard
+```
+
+```bash
+# See retry-with-feedback in action (no API key needed)
+python -m examples.llm_demo.run_demo
+
+# Run with real LLM calls
+export OPENROUTER_API_KEY=your_key
+python -m examples.llm_demo.run_demo --pipeline --api
+```
+
+## Features
+
+- **Retry with feedback** — Failed outputs are fed back to the agent as context
+- **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, handles BOM, raises `ParseError` on failure
+- **Framework agnostic** — Works with LangGraph, CrewAI, or plain Python
+- **Lightweight** — Just Pydantic, no Docker, no telemetry servers
+
+## API
+
+### `@guard` decorator
+
+```python
+@guard(
+    input=InputSchema,          # Pydantic model for input validation
+    output=OutputSchema,        # Pydantic model for output validation
+    node_name="my_node",        # Identifies the node in errors (default: function name)
+    max_attempts=3,             # Retry up to 3 times (default: 1, no retry)
+    retry_on=("validation", "parse"),  # What errors trigger retry (default)
+    on_fail="raise",            # "raise" | "return_none" | "return_input" | callable
+)
+```
+
+### `retry` proxy
+
+Access retry state inside any guarded function:
+
+```python
+from handoff import retry
+
+retry.is_retry        # True if attempt > 1
+retry.attempt         # Current attempt number
+retry.max_attempts    # Total allowed attempts
+retry.remaining       # Attempts left
+retry.is_final_attempt
+retry.feedback()      # Formatted string describing last error, or None
+retry.last_error      # Diagnostic object, or None
+retry.history         # List of AttemptRecord objects
+```
+
+### `parse_json`
+
+```python
+from handoff import parse_json
+
+data = parse_json('```json\n{"key": "value"}\n```')
+# Returns: {"key": "value"}
+# Raises ParseError on failure (retryable by @guard)
+```
+
+### `HandoffViolation`
+
+Raised when all retry attempts are exhausted:
+
+```python
+from handoff import HandoffViolation
+
+try:
+    result = my_agent(state)
+except HandoffViolation as e:
+    print(e.node_name)       # "writer"
+    print(e.total_attempts)  # 3
+    print(e.history)         # List of AttemptRecord with diagnostics
+    print(e.to_dict())       # Serializable for logging
+```
+
+### Handle Failures
+
+```python
+@guard(output=Schema, on_fail="raise")        # Raise exception (default)
+@guard(output=Schema, on_fail="return_none")   # Return None on failure
+@guard(output=Schema, on_fail="return_input")  # Return input unchanged
+@guard(output=Schema, on_fail=my_handler)      # Custom handler
+```
+
+## Examples
+
+| Demo | What it shows |
+|------|---------------|
+| [`examples/llm_demo`](examples/llm_demo/) | Retry-with-feedback: writer fails, gets feedback, self-corrects |
+| [`examples/rag_demo`](examples/rag_demo/) | Multi-stage pipeline validation + hallucinated citation detection |
+
+Both demos support `--api` for real LLM calls and run with mock data by default.
+
+## With LangGraph
+
+```python
+from handoff.langgraph import guarded_node
+from pydantic import BaseModel, Field
+
+class RouterOutput(BaseModel):
+    next_agent: str = Field(pattern="^(writer|reviewer|done)$")
+    messages: list
+
+@guarded_node(output=RouterOutput)
+def router(state: dict) -> dict:
+    return {
+        "next_agent": "writer",
+        "messages": state["messages"]
+    }
+```
+
+## Why not just use Pydantic directly?
+
+You should! Handoff uses Pydantic under the hood.
+
+The difference:
+
+| Pydantic alone | Handoff |
+|----------------|---------|
+| `ValidationError: 1 validation error` | `HandoffViolation in 'router_node'` |
+| Generic stack trace | Exact node + field + suggestion |
+| You wire up validation manually | One decorator |
+| 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.
+
+## License
+
+MIT
+
+---
+
+Built for developers who are tired of debugging agent handoffs.

handoff_guard-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+handoff/__init__.py,sha256=RDO2wqA1zROrtM2GE_B_1pLA4OOClCzzjMARaorB-Oo,449
+handoff/core.py,sha256=zVGKyLO7TxwoJS_J5n-c47OdQGUmrQJjIvRW97tInBs,3173
+handoff/guard.py,sha256=Mf3Nj7b8MC_WHcvMhzaVWFTSTGjTPHu64Jz2AeTnAvI,18752
+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=c0nN5AAXgx3mbVKa8jHFMqkor0qtchpC0Jc_e_yjzTE,1302
+handoff_guard-0.1.0.dist-info/METADATA,sha256=g8B526tyQGMVMRcA3isJGJwTu2PkSw9PKMFjdmF45xo,6969
+handoff_guard-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+handoff_guard-0.1.0.dist-info/licenses/LICENSE,sha256=HroDuVS_iz3RlUAJhww1Ma4olb4onXHg1MXaIZCb06s,1063
+handoff_guard-0.1.0.dist-info/RECORD,,

handoff_guard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

handoff_guard-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arnold
+
+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.