handoff-guard 0.1.0__tar.gz

handoff_guard-0.1.0/.claude/skills/update-docs/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: update-docs
+description: Update project documentation (README.md, AGENTS.md, example READMEs) to reflect current codebase state.
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Edit, Bash
+---
+
+# Update Documentation
+
+This skill updates the project's documentation files to reflect the current state of the codebase.
+
+## Files Updated
+
+1. **`README.md`** (project root) — Public-facing README with API docs and examples
+2. **`AGENTS.md`** (project root) — Guide for AI coding agents
+3. **`examples/llm_demo/README.md`** — LLM demo documentation
+4. **`examples/rag_demo/README.md`** — RAG demo documentation
+
+## Process
+
+### Step 1: Scan for Changes
+
+1. **Library source:**
+   ```
+   Glob: src/handoff/**/*.py
+   ```
+   Check for new/removed files, public API changes, new exports in `__init__.py`.
+
+2. **Public API:**
+   ```
+   Read: src/handoff/__init__.py
+   ```
+   Verify `__all__` matches what's documented in README and AGENTS.md.
+
+3. **Guard decorator:**
+   ```
+   Read: src/handoff/guard.py
+   ```
+   Check for new parameters, changed defaults, new on_fail modes.
+
+4. **Retry system:**
+   ```
+   Read: src/handoff/retry.py
+   ```
+   Check for new RetryState properties, new Diagnostic fields, proxy changes.
+
+5. **Utilities:**
+   ```
+   Read: src/handoff/utils.py
+   ```
+   Check for new utility functions or changed behavior.
+
+6. **Examples:**
+   ```
+   Glob: examples/**/*.py
+   ```
+   Check for new demos, changed CLI flags, new agent patterns.
+
+7. **Tests:**
+   ```
+   Glob: tests/test_*.py
+   ```
+   Check for new test files or significantly expanded coverage areas.
+
+8. **Package config:**
+   ```
+   Read: pyproject.toml
+   ```
+   Check version, dependencies, optional extras.
+
+### Step 2: Update README.md
+
+- **Hero example**: Verify it uses current API correctly (`guard`, `retry`, `parse_json`)
+- **Quick Start**: Verify install command and demo commands work
+- **Features list**: Add any new features, remove deprecated ones
+- **API section**: Sync `@guard` params, `retry` proxy properties, `parse_json` behavior, `HandoffViolation` attributes with actual source
+- **Handle Failures**: Verify on_fail modes match implementation
+- **Examples table**: Verify both demo links and descriptions are accurate
+- **LangGraph section**: Verify `guarded_node` API is current
+- **Comparison table**: Update if positioning has changed
+- **Roadmap**: Check off completed items, add new planned items
+
+### Step 3: Update AGENTS.md
+
+- **Repository Structure**: Match current file tree exactly — no deleted files, no missing new files
+- **Public API**: Sync imports with `__init__.py` `__all__`
+- **@guard decorator**: Sync all parameters and their defaults with `guard.py`
+- **retry proxy**: Sync all properties with `_RetryProxy` class in `retry.py`
+- **HandoffViolation**: Sync attributes with `core.py`
+- **Architecture Decisions**: Add any new decisions, remove outdated ones
+- **Development Commands**: Verify all commands work, especially demo commands with current CLI flags
+- **Testing section**: List all test files with accurate descriptions of what they cover
+
+### Step 4: Update Example READMEs
+
+For each example README (`examples/llm_demo/README.md`, `examples/rag_demo/README.md`):
+
+- **Quick Start commands**: Verify all CLI flags match `argparse` in `run_demo.py`
+- **Pipeline diagram**: Verify stages match actual agent/function names
+- **Key Patterns code**: Verify code snippet matches actual implementation
+- **Schemas table**: Verify schema names and validation rules match `schemas.py`
+- **Requirements**: Verify install commands and dependencies
+
+### Step 5: Report Summary
+
+Output a summary of changes:
+```
+## Documentation Update Summary
+
+### README.md
+- Updated: API section (new guard parameter X)
+- Updated: Features list (added Y)
+
+### AGENTS.md
+- Updated: Repository Structure (new file Z)
+- Updated: Testing section (new test file)
+
+### examples/llm_demo/README.md
+- No changes needed
+
+### examples/rag_demo/README.md
+- Updated: Schemas table (new field in RAGOutput)
+```
+
+## Important Notes
+
+- Keep README.md concise and user-facing — it's for people evaluating the library
+- Keep AGENTS.md comprehensive — it's for AI agents working on the code
+- Don't remove documentation for features that still exist
+- Verify code examples in README actually work (correct imports, correct API)
+- Keep the roadmap in README.md up to date — check off shipped features
+- Example READMEs should match the actual CLI interface exactly
+
+## When to Run
+
+- After adding new public API (new exports, new guard parameters, new retry properties)
+- After adding or removing source files
+- After changing CLI flags in demo runners
+- After adding new test files
+- After changing package version or dependencies
+- Before releasing a new version

handoff_guard-0.1.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

handoff_guard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+      - name: Run demo (no LLM)
+        run: python -m examples.rag_demo.run_demo
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+
+      - name: Lint with ruff
+        run: ruff check src/ tests/ examples/

handoff_guard-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # For trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

handoff_guard-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.env
+.venv/

handoff_guard-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

handoff_guard-0.1.0/AGENTS.md

@@ -0,0 +1,177 @@
+# AGENTS.md
+
+Guide for AI coding agents working on this codebase.
+
+## Project Overview
+
+**handoff-guard** is a lightweight Python library that validates data at agent/pipeline boundaries using Pydantic schemas. It wraps functions with a `@guard` decorator that validates output, retries with feedback on failure, and raises rich `HandoffViolation` exceptions identifying the exact node, field, and suggested fix.
+
+- **Package name (PyPI):** `handoff-guard`
+- **Import name:** `handoff`
+- **Python:** >= 3.10
+- **Core dependency:** Pydantic >= 2.0
+
+## Repository Structure
+
+```
+src/handoff/           # Library source code
+  __init__.py          # Public API exports
+  core.py              # ViolationContext dataclass, HandoffViolation exception
+  guard.py             # @guard decorator, retry loop, validation logic
+  retry.py             # RetryState, Diagnostic, AttemptRecord, _RetryProxy (retry singleton)
+  utils.py             # parse_json(), ParseError
+  testing.py           # mock_retry() context manager for tests
+  langgraph.py         # LangGraph adapter: guarded_node, validate_state
+
+tests/
+  test_guard.py        # Guard decorator tests (sync, async, on_fail modes)
+  test_retry.py        # Retry loop, proxy, history, parse error retry tests
+  test_testing.py      # mock_retry tests
+  test_utils.py        # parse_json tests
+
+examples/
+  llm_demo/            # Multi-agent pipeline (Planner -> Researcher -> Writer)
+    __init__.py
+    schemas.py         # PlannerOutput, ResearcherOutput, WriterOutput
+    agents.py          # Guarded agents with retry, module-level _mock_responses
+    run_demo.py        # Entry point: python -m examples.llm_demo.run_demo
+    README.md
+  rag_demo/            # RAG pipeline (Parser -> Retriever -> Reranker -> Generator)
+    __init__.py
+    schemas.py         # ParsedQuery, RetrievedDocs, RankedDocs, RAGOutput, etc.
+    pipeline.py        # Guarded pipeline stages with retry on generator
+    run_demo.py        # Entry point: python -m examples.rag_demo.run_demo
+    README.md
+
+.github/workflows/
+  ci.yml               # Tests on Python 3.10/3.11/3.12 + ruff lint
+  publish.yml          # Auto-publish to PyPI on GitHub release
+```
+
+## Key Concepts
+
+### Public API
+
+```python
+from handoff import guard, GuardConfig, HandoffViolation, ViolationContext
+from handoff import retry, RetryState, Diagnostic, AttemptRecord
+from handoff import parse_json, ParseError
+from handoff.langgraph import guarded_node, validate_state
+```
+
+### `@guard` decorator
+
+```python
+@guard(
+    input=Schema,              # Pydantic model for input validation
+    output=Schema,             # Pydantic model for output validation
+    node_name="...",           # Identifies the node in errors (default: function name)
+    max_attempts=3,            # Retry up to N times (default: 1, no retry)
+    retry_on=("validation", "parse"),  # Error types that trigger retry
+    on_fail="raise",           # "raise" | "return_none" | "return_input" | callable
+)
+```
+
+- Input validation happens once, outside the retry loop
+- Output validation happens inside the retry loop
+- Parse errors (`ParseError`, `json.JSONDecodeError`, `KeyError`, `TypeError`) are retried when `"parse"` is in `retry_on`
+- If the function has a `retry` parameter, `RetryState` is auto-injected
+
+### `retry` proxy
+
+Module-level singleton that reads from a ContextVar, safe to use anywhere:
+
+```python
+from handoff import retry
+
+retry.is_retry          # True if attempt > 1
+retry.attempt           # Current attempt number (1-based)
+retry.max_attempts      # Total allowed attempts
+retry.remaining         # Attempts left
+retry.is_final_attempt  # True if no more retries
+retry.feedback()        # Formatted error string from last attempt, or None
+retry.last_error        # Diagnostic object, or None
+retry.history           # List of AttemptRecord
+```
+
+### `parse_json`
+
+Parses JSON from LLM text output, stripping markdown code fences and BOM. Raises `ParseError` (retryable by `@guard`) on failure.
+
+### `HandoffViolation`
+
+Exception with:
+- `.context` — `ViolationContext` (node_name, contract_type, field_path, expected, received, suggestion)
+- `.history` — `list[AttemptRecord]` (empty if no retries)
+- `.node_name`, `.field_path` — shortcuts
+- `.total_attempts` — `len(history)` or 1
+- `.to_dict()` — serializable for logging
+
+### on_fail modes
+
+- `"raise"` — Raise HandoffViolation (default)
+- `"return_none"` — Return None
+- `"return_input"` — Return the original input unchanged
+- `callable` — Call with the HandoffViolation, return its result
+
+### Suggestion generation
+
+Auto-generated in `guard.py:_generate_suggestion` based on Pydantic error types: `missing`, `string_type`, `int_type`, `string_too_short`, `string_too_long`, `too_short`, `too_long`, `greater_than_equal`, `less_than_equal`, `string_pattern_mismatch`. Add new error types there.
+
+## Development Commands
+
+```bash
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run LLM demo (no API key needed)
+python -m examples.llm_demo.run_demo                # retry demo (default)
+python -m examples.llm_demo.run_demo --failure-demo  # exhausted retries
+python -m examples.llm_demo.run_demo --pipeline      # mock pipeline
+
+# Run RAG demo (no API key needed)
+python -m examples.rag_demo.run_demo                 # pipeline + hallucination check
+
+# Run with real LLM calls (needs OPENROUTER_API_KEY)
+python -m examples.llm_demo.run_demo --pipeline --api
+python -m examples.rag_demo.run_demo --api
+
+# Lint
+ruff check src/ tests/ examples/
+
+# Build package
+python -m build
+```
+
+## Architecture Decisions
+
+- **Pydantic v2 only** — Uses `model_validate`, `model_dump`, not v1 API
+- **No runtime deps beyond Pydantic** — LangGraph/httpx are optional
+- **Sync and async** — `@guard` detects `async def` and wraps accordingly
+- **First violation wins** — Only the first validation error is raised (not all)
+- **Dict-oriented** — Agents typically pass dicts; the decorator validates dicts against Pydantic models without requiring the function to use models directly
+- **ContextVar for retry state** — The `retry` proxy uses a ContextVar so it's async-safe and doesn't require passing state through function signatures
+- **Input validation outside retry loop** — Input doesn't change between retries, so it's validated once upfront
+- **Parse errors retryable** — `ParseError`, `json.JSONDecodeError`, `KeyError`, `TypeError` are caught and retried when `max_attempts > 1`
+
+## Adding New Features
+
+When adding a new error type suggestion, edit `_generate_suggestion` in `src/handoff/guard.py`.
+
+When adding a new framework adapter (e.g., CrewAI), create `src/handoff/crewai.py` following the pattern in `langgraph.py` and export from `__init__.py`.
+
+When adding a new demo, create `examples/<name>_demo/` with `__init__.py`, `schemas.py`, `run_demo.py` and a `README.md`. Run it with `python -m examples.<name>_demo.run_demo`.
+
+## Testing
+
+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, invalid raises ParseError, non-string raises, BOM stripping
+
+Run with: `pytest tests/ -v`

handoff_guard-0.1.0/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.

handoff_guard-0.1.0/PKG-INFO

@@ -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.