handoffkit 0.6.0__tar.gz → 0.7.0__tar.gz

{handoffkit-0.6.0/handoffkit.egg-info → handoffkit-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoffkit
-Version: 0.6.0
+Version: 0.7.0
 Summary: A lightweight Python framework for building multi-agent workflows with structured state transfer protocols.
 Author: DaosPath
 License-Expression: MIT
@@ -80,6 +80,21 @@ Tester
 
 That makes agent workflows easier to inspect, test, replay, and improve.
 
+## What 0.7.0 Adds
+
+HandoffKit 0.7.0 adds reusable validation and quality layers for mature
+multi-agent workflows:
+
+- `ValidationIssue` and `ValidationReport` for reusable contract reports,
+- `HandoffStateValidator`, `StructuredOutputValidator`, and `ToolSchemaValidator`,
+- `validate_report(...)` helpers while keeping existing `validate()` behavior,
+- `HandoffQualityEvaluator` with deterministic handoff quality scoring,
+- quality metrics for completeness, clarity, actionability, traceability, and error awareness,
+- provider-native tool schemas for `handoffkit`, `openai`, and `anthropic`,
+- provider-style tool call parsing with call ID preservation,
+- `provider_adapter` support in `Agent.run_with_tools(...)`,
+- offline quality, validator, and provider-format demos with JSON/Markdown reports.
+
 ## What 0.6.0 Adds
 
 HandoffKit 0.6.0 adds structured outputs and provider-neutral tool adapters:
@@ -353,6 +368,105 @@ whether a provider returns HandoffKit JSON or function-style tool calls. This is
 provider-neutral by design; HandoffKit does not require any external SDK for
 normal tests.
 
+## Handoff Quality Metrics
+
+Quality checks are deterministic and offline. They help compare handoff states
+without calling a provider or judging prose with another model.
+
+```python
+from handoffkit import HandoffQualityEvaluator, HandoffState
+
+state = HandoffState(
+    task="Create a Python CLI calculator.",
+    from_agent="Architect",
+    to_agent="Coder",
+    summary="Build an argparse calculator with pure operations and tests.",
+    decisions=["Use argparse.", "Keep operations pure."],
+    important_files=["calculator.py", "test_calculator.py"],
+    next_steps=["Implement calculator.py", "Run pytest -q"],
+    context_refs=["README.md#real-task-demo"],
+    metadata={"errors_checked": True},
+)
+
+report = HandoffQualityEvaluator().evaluate(state)
+print(report.score, report.grade)
+print(report.to_markdown())
+```
+
+Metrics:
+
+| Metric | Checks |
+|---|---|
+| `completeness` | required fields, summary, decisions, files, context, next steps |
+| `clarity` | useful summary length and non-empty decisions |
+| `actionability` | next steps written as concrete actions |
+| `traceability` | important files and context references |
+| `error_awareness` | recorded errors or explicit error-check metadata |
+
+## Contract Validators
+
+Validators return `ValidationReport` objects that can be serialized, rendered as
+Markdown, or raised as exceptions. Existing APIs stay compatible:
+`HandoffState.validate()` still returns `self` or raises `HandoffValidationError`,
+and `StructuredOutputSchema.validate()` still returns the input dictionary or
+raises `OutputValidationError`.
+
+```python
+from handoffkit import (
+    HandoffStateValidator,
+    StructuredOutputSchema,
+    StructuredOutputValidator,
+    ToolSchemaValidator,
+    tool,
+)
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two integers."""
+    return a + b
+
+schema = StructuredOutputSchema(
+    name="Plan",
+    fields={"title": str, "ready": bool},
+    required=["title", "ready"],
+)
+
+print(StructuredOutputValidator().validate(schema, {"title": "Demo", "ready": True}).to_json())
+print(ToolSchemaValidator().validate(add).to_markdown())
+```
+
+## Provider Tool Formats
+
+`ProviderToolAdapter` can render tools as HandoffKit, OpenAI function-style, or
+Anthropic `tool_use` schemas. It also parses provider-native tool call payloads
+back into HandoffKit `ToolCall` objects.
+
+```python
+from handoffkit import ProviderToolAdapter, tool
+
+@tool
+def read_file(path: str) -> str:
+    """Read a file."""
+    return f"read:{path}"
+
+openai_adapter = ProviderToolAdapter(provider_format="openai")
+anthropic_adapter = ProviderToolAdapter(provider_format="anthropic")
+
+print(openai_adapter.tools_to_provider_format([read_file]))
+print(anthropic_adapter.tools_to_provider_format([read_file]))
+
+calls = openai_adapter.parse_tool_calls({
+    "tool_calls": [
+        {
+            "id": "call_123",
+            "type": "function",
+            "function": {"name": "read_file", "arguments": "{\"path\":\"README.md\"}"},
+        }
+    ]
+})
+print(calls[0].tool_name, calls[0].arguments, calls[0].call_id)
+```
+
 ## Memory + Project Context
 
 HandoffKit can store durable project decisions, index local files, retrieve
@@ -559,6 +673,9 @@ handoffkit demo-recipe
 handoffkit demo-extension
 handoffkit demo-structured
 handoffkit demo-provider-tools
+handoffkit demo-quality
+handoffkit demo-validators
+handoffkit demo-provider-formats
 ```
 
 ## Examples
@@ -572,6 +689,9 @@ python examples/tool_execution_demo.py
 python examples/fake_provider_tool_call_demo.py
 python examples/structured_output_demo.py
 python examples/provider_tool_adapter_demo.py
+python examples/handoff_quality_demo.py
+python examples/contract_validation_demo.py
+python examples/provider_tool_formats_demo.py
 python examples/structured_recipe_demo.py
 python examples/recipe_demo.py
 python examples/coding_review_recipe.py
@@ -631,11 +751,10 @@ HandoffKit is a developer library, not a copy of that repository.
 
 ## Roadmap
 
-- richer contract validators,
+- richer memory persistence adapters,
 - broader tool schema coverage,
-- provider adapters,
-- structured tool calling loops,
-- handoff quality metrics,
+- provider-specific integration examples,
+- benchmark-inspired quality comparisons,
 - memory integrations,
 - project context retrieval,
 - benchmark-inspired examples,

{handoffkit-0.6.0 → handoffkit-0.7.0}/README.md

@@ -51,6 +51,21 @@ Tester
 
 That makes agent workflows easier to inspect, test, replay, and improve.
 
+## What 0.7.0 Adds
+
+HandoffKit 0.7.0 adds reusable validation and quality layers for mature
+multi-agent workflows:
+
+- `ValidationIssue` and `ValidationReport` for reusable contract reports,
+- `HandoffStateValidator`, `StructuredOutputValidator`, and `ToolSchemaValidator`,
+- `validate_report(...)` helpers while keeping existing `validate()` behavior,
+- `HandoffQualityEvaluator` with deterministic handoff quality scoring,
+- quality metrics for completeness, clarity, actionability, traceability, and error awareness,
+- provider-native tool schemas for `handoffkit`, `openai`, and `anthropic`,
+- provider-style tool call parsing with call ID preservation,
+- `provider_adapter` support in `Agent.run_with_tools(...)`,
+- offline quality, validator, and provider-format demos with JSON/Markdown reports.
+
 ## What 0.6.0 Adds
 
 HandoffKit 0.6.0 adds structured outputs and provider-neutral tool adapters:
@@ -324,6 +339,105 @@ whether a provider returns HandoffKit JSON or function-style tool calls. This is
 provider-neutral by design; HandoffKit does not require any external SDK for
 normal tests.
 
+## Handoff Quality Metrics
+
+Quality checks are deterministic and offline. They help compare handoff states
+without calling a provider or judging prose with another model.
+
+```python
+from handoffkit import HandoffQualityEvaluator, HandoffState
+
+state = HandoffState(
+    task="Create a Python CLI calculator.",
+    from_agent="Architect",
+    to_agent="Coder",
+    summary="Build an argparse calculator with pure operations and tests.",
+    decisions=["Use argparse.", "Keep operations pure."],
+    important_files=["calculator.py", "test_calculator.py"],
+    next_steps=["Implement calculator.py", "Run pytest -q"],
+    context_refs=["README.md#real-task-demo"],
+    metadata={"errors_checked": True},
+)
+
+report = HandoffQualityEvaluator().evaluate(state)
+print(report.score, report.grade)
+print(report.to_markdown())
+```
+
+Metrics:
+
+| Metric | Checks |
+|---|---|
+| `completeness` | required fields, summary, decisions, files, context, next steps |
+| `clarity` | useful summary length and non-empty decisions |
+| `actionability` | next steps written as concrete actions |
+| `traceability` | important files and context references |
+| `error_awareness` | recorded errors or explicit error-check metadata |
+
+## Contract Validators
+
+Validators return `ValidationReport` objects that can be serialized, rendered as
+Markdown, or raised as exceptions. Existing APIs stay compatible:
+`HandoffState.validate()` still returns `self` or raises `HandoffValidationError`,
+and `StructuredOutputSchema.validate()` still returns the input dictionary or
+raises `OutputValidationError`.
+
+```python
+from handoffkit import (
+    HandoffStateValidator,
+    StructuredOutputSchema,
+    StructuredOutputValidator,
+    ToolSchemaValidator,
+    tool,
+)
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two integers."""
+    return a + b
+
+schema = StructuredOutputSchema(
+    name="Plan",
+    fields={"title": str, "ready": bool},
+    required=["title", "ready"],
+)
+
+print(StructuredOutputValidator().validate(schema, {"title": "Demo", "ready": True}).to_json())
+print(ToolSchemaValidator().validate(add).to_markdown())
+```
+
+## Provider Tool Formats
+
+`ProviderToolAdapter` can render tools as HandoffKit, OpenAI function-style, or
+Anthropic `tool_use` schemas. It also parses provider-native tool call payloads
+back into HandoffKit `ToolCall` objects.
+
+```python
+from handoffkit import ProviderToolAdapter, tool
+
+@tool
+def read_file(path: str) -> str:
+    """Read a file."""
+    return f"read:{path}"
+
+openai_adapter = ProviderToolAdapter(provider_format="openai")
+anthropic_adapter = ProviderToolAdapter(provider_format="anthropic")
+
+print(openai_adapter.tools_to_provider_format([read_file]))
+print(anthropic_adapter.tools_to_provider_format([read_file]))
+
+calls = openai_adapter.parse_tool_calls({
+    "tool_calls": [
+        {
+            "id": "call_123",
+            "type": "function",
+            "function": {"name": "read_file", "arguments": "{\"path\":\"README.md\"}"},
+        }
+    ]
+})
+print(calls[0].tool_name, calls[0].arguments, calls[0].call_id)
+```
+
 ## Memory + Project Context
 
 HandoffKit can store durable project decisions, index local files, retrieve
@@ -530,6 +644,9 @@ handoffkit demo-recipe
 handoffkit demo-extension
 handoffkit demo-structured
 handoffkit demo-provider-tools
+handoffkit demo-quality
+handoffkit demo-validators
+handoffkit demo-provider-formats
 ```
 
 ## Examples
@@ -543,6 +660,9 @@ python examples/tool_execution_demo.py
 python examples/fake_provider_tool_call_demo.py
 python examples/structured_output_demo.py
 python examples/provider_tool_adapter_demo.py
+python examples/handoff_quality_demo.py
+python examples/contract_validation_demo.py
+python examples/provider_tool_formats_demo.py
 python examples/structured_recipe_demo.py
 python examples/recipe_demo.py
 python examples/coding_review_recipe.py
@@ -602,11 +722,10 @@ HandoffKit is a developer library, not a copy of that repository.
 
 ## Roadmap
 
-- richer contract validators,
+- richer memory persistence adapters,
 - broader tool schema coverage,
-- provider adapters,
-- structured tool calling loops,
-- handoff quality metrics,
+- provider-specific integration examples,
+- benchmark-inspired quality comparisons,
 - memory integrations,
 - project context retrieval,
 - benchmark-inspired examples,

handoffkit-0.7.0/examples/contract_validation_demo.py

@@ -0,0 +1,85 @@
+"""Contract validation demo without external APIs."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from handoffkit import (
+    HandoffState,
+    HandoffStateValidator,
+    StructuredOutputSchema,
+    StructuredOutputValidator,
+    ToolSchemaValidator,
+    tool,
+)
+
+ROOT = Path(__file__).resolve().parents[1]
+REPORTS_DIR = ROOT / "reports"
+
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two integers."""
+    return a + b
+
+
+def build_state() -> HandoffState:
+    """Build a deterministic valid handoff state."""
+    return HandoffState(
+        task="Create a Python CLI calculator.",
+        from_agent="Architect",
+        to_agent="Coder",
+        summary="Architecture plan is ready for implementation.",
+        decisions=["Use argparse.", "Return non-zero on invalid input."],
+        important_files=["calculator.py"],
+        next_steps=["Implement calculator.py", "Run pytest -q"],
+        context_refs=["docs/calculator-contract.md"],
+        metadata={"errors_checked": True},
+    )
+
+
+def _json_default(value: Any) -> Any:
+    if hasattr(value, "to_dict"):
+        return value.to_dict()
+    return str(value)
+
+
+def main() -> None:
+    """Validate handoff, structured output, and tool contracts."""
+    REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+    schema = StructuredOutputSchema(
+        name="CalculatorPlan",
+        fields={"title": str, "steps": list, "ready": bool},
+        required=["title", "steps", "ready"],
+    )
+    reports = {
+        "handoff": HandoffStateValidator().validate(build_state()),
+        "structured_output": StructuredOutputValidator().validate(
+            schema,
+            {"title": "CLI calculator", "steps": ["implement", "test"], "ready": True},
+        ),
+        "tool_schema": ToolSchemaValidator().validate(add),
+    }
+
+    markdown = "# Contract Validation Demo\n\n" + "\n\n".join(
+        f"## {name}\n\n{report.to_markdown()}" for name, report in reports.items()
+    )
+    payload = {name: report.to_dict() for name, report in reports.items()}
+
+    markdown_path = REPORTS_DIR / "contract_validation_demo.md"
+    json_path = REPORTS_DIR / "contract_validation_demo.json"
+    markdown_path.write_text(markdown, encoding="utf-8")
+    json_text = json.dumps(payload, ensure_ascii=False, indent=2, default=_json_default)
+    json_path.write_text(json_text, encoding="utf-8")
+
+    print(f"Handoff validation: {reports['handoff'].success}")
+    print(f"Structured output validation: {reports['structured_output'].success}")
+    print(f"Tool schema validation: {reports['tool_schema'].success}")
+    print(f"Markdown report: {markdown_path}")
+    print(f"JSON report: {json_path}")
+
+
+if __name__ == "__main__":
+    main()

handoffkit-0.7.0/examples/handoff_quality_demo.py

@@ -0,0 +1,46 @@
+"""Handoff quality metrics demo without external APIs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from handoffkit import HandoffQualityEvaluator, HandoffState
+
+ROOT = Path(__file__).resolve().parents[1]
+REPORTS_DIR = ROOT / "reports"
+
+
+def build_state() -> HandoffState:
+    """Build a deterministic handoff state for quality scoring."""
+    return HandoffState(
+        task="Create a Python CLI calculator.",
+        from_agent="Architect",
+        to_agent="Coder",
+        summary="Build a dependency-free argparse calculator with pure operations and tests.",
+        decisions=["Use argparse for CLI parsing.", "Keep math operations in pure functions."],
+        important_files=["calculator.py", "test_calculator.py"],
+        next_steps=["Implement calculator.py", "Write pytest coverage", "Run pytest -q"],
+        context_refs=["README.md#real-task-demo"],
+        metadata={"errors_checked": True},
+    )
+
+
+def main() -> None:
+    """Evaluate one handoff state and write Markdown/JSON reports."""
+    REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+    report = HandoffQualityEvaluator().evaluate(build_state())
+
+    markdown_path = REPORTS_DIR / "handoff_quality_demo.md"
+    json_path = REPORTS_DIR / "handoff_quality_demo.json"
+    markdown_path.write_text(report.to_markdown(), encoding="utf-8")
+    json_path.write_text(report.to_json(), encoding="utf-8")
+
+    print(f"Handoff quality success: {report.success}")
+    print(f"Score: {report.score:.3f}")
+    print(f"Grade: {report.grade}")
+    print(f"Markdown report: {markdown_path}")
+    print(f"JSON report: {json_path}")
+
+
+if __name__ == "__main__":
+    main()

{handoffkit-0.6.0 → handoffkit-0.7.0}/examples/provider_tool_adapter_demo.py

@@ -25,6 +25,7 @@ def main() -> None:
     provider_response = {
         "tool_calls": [
             {
+                "id": "call_provider_adapter_demo",
                 "function": {
                     "name": "label",
                     "arguments": '{"value":"provider-adapter"}',

handoffkit-0.7.0/examples/provider_tool_formats_demo.py

@@ -0,0 +1,98 @@
+"""Provider tool format demo without external APIs."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from handoffkit import ProviderToolAdapter, tool
+
+ROOT = Path(__file__).resolve().parents[1]
+REPORTS_DIR = ROOT / "reports"
+
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two integers."""
+    return a + b
+
+
+def _json_default(value: Any) -> Any:
+    if hasattr(value, "to_dict"):
+        return value.to_dict()
+    return str(value)
+
+
+def main() -> None:
+    """Render provider-native tool schemas and parse provider tool calls."""
+    REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+    handoffkit_adapter = ProviderToolAdapter(provider_format="handoffkit")
+    openai_adapter = ProviderToolAdapter(provider_format="openai")
+    anthropic_adapter = ProviderToolAdapter(provider_format="anthropic")
+
+    schemas = {
+        "handoffkit": handoffkit_adapter.tools_to_provider_format([add]),
+        "openai": openai_adapter.tools_to_provider_format([add]),
+        "anthropic": anthropic_adapter.tools_to_provider_format([add]),
+    }
+    parsed_calls = {
+        "openai": [
+            call.to_dict()
+            for call in openai_adapter.parse_tool_calls(
+                {
+                    "tool_calls": [
+                        {
+                            "id": "call_openai_1",
+                            "type": "function",
+                            "function": {"name": "add", "arguments": '{"a":2,"b":3}'},
+                        }
+                    ]
+                }
+            )
+        ],
+        "anthropic": [
+            call.to_dict()
+            for call in anthropic_adapter.parse_tool_calls(
+                {
+                    "content": [
+                        {
+                            "type": "tool_use",
+                            "id": "toolu_1",
+                            "name": "add",
+                            "input": {"a": 5, "b": 8},
+                        }
+                    ]
+                }
+            )
+        ],
+    }
+    payload = {"schemas": schemas, "parsed_calls": parsed_calls}
+    parsed_json = json.dumps(parsed_calls, ensure_ascii=False, indent=2)
+    markdown = (
+        "# Provider Tool Formats Demo\n\n"
+        "## Formats\n\n"
+        f"- handoffkit tools: {len(schemas['handoffkit'])}\n"
+        f"- openai tools: {len(schemas['openai'])}\n"
+        f"- anthropic tools: {len(schemas['anthropic'])}\n\n"
+        "## Parsed Calls\n\n"
+        f"```json\n{parsed_json}\n```\n"
+    )
+
+    markdown_path = REPORTS_DIR / "provider_tool_formats_demo.md"
+    json_path = REPORTS_DIR / "provider_tool_formats_demo.json"
+    markdown_path.write_text(markdown, encoding="utf-8")
+    json_text = json.dumps(payload, ensure_ascii=False, indent=2, default=_json_default)
+    json_path.write_text(json_text, encoding="utf-8")
+
+    print(f"HandoffKit format tools: {len(schemas['handoffkit'])}")
+    print(f"OpenAI format tools: {len(schemas['openai'])}")
+    print(f"Anthropic format tools: {len(schemas['anthropic'])}")
+    print(f"OpenAI call id: {parsed_calls['openai'][0]['call_id']}")
+    print(f"Anthropic call id: {parsed_calls['anthropic'][0]['call_id']}")
+    print(f"Markdown report: {markdown_path}")
+    print(f"JSON report: {json_path}")
+
+
+if __name__ == "__main__":
+    main()

{handoffkit-0.6.0 → handoffkit-0.7.0}/handoffkit/__init__.py

@@ -16,8 +16,14 @@ from handoffkit.protocol import HandoffProtocol
 from handoffkit.provider_adapters import (
     ProviderCapabilities,
     ProviderToolAdapter,
+    ProviderToolFormat,
     ToolCallParser,
 )
+from handoffkit.quality import (
+    HandoffQualityEvaluator,
+    HandoffQualityMetric,
+    HandoffQualityReport,
+)
 from handoffkit.recipes import (
     Recipe,
     RecipeRunner,
@@ -40,8 +46,15 @@ from handoffkit.tool_execution import (
     ToolRegistry,
     ToolResult,
 )
+from handoffkit.validation import (
+    HandoffStateValidator,
+    StructuredOutputValidator,
+    ToolSchemaValidator,
+    ValidationIssue,
+    ValidationReport,
+)
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     "Agent",
@@ -53,7 +66,11 @@ __all__ = [
     "ExtensionRegistry",
     "HandoffValidationError",
     "HandoffProtocol",
+    "HandoffQualityEvaluator",
+    "HandoffQualityMetric",
+    "HandoffQualityReport",
     "HandoffState",
+    "HandoffStateValidator",
     "JsonMemoryStore",
     "JsonOutputParser",
     "MemoryItem",
@@ -64,12 +81,14 @@ __all__ = [
     "ProjectIndexer",
     "ProviderCapabilities",
     "ProviderToolAdapter",
+    "ProviderToolFormat",
     "Recipe",
     "RecipeRunResult",
     "RecipeRunner",
     "RecipeStep",
     "StructuredOutputResult",
     "StructuredOutputSchema",
+    "StructuredOutputValidator",
     "Team",
     "TeamRunResult",
     "Tool",
@@ -78,6 +97,9 @@ __all__ = [
     "ToolExecutionReport",
     "ToolRegistry",
     "ToolResult",
+    "ToolSchemaValidator",
+    "ValidationIssue",
+    "ValidationReport",
     "WorkflowTemplate",
     "__version__",
     "tool",