handoffkit 0.2.0__tar.gz

handoffkit-0.2.0/LICENSE

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

handoffkit-0.2.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+graft examples
+graft tests
+global-exclude __pycache__
+global-exclude __pycache__/*
+global-exclude *.py[cod]
+global-exclude *.pyc.*

handoffkit-0.2.0/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: handoffkit
+Version: 0.2.0
+Summary: A lightweight Python framework for building multi-agent workflows with structured state transfer protocols.
+Author: DaosPath
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/DaosPath/handoffkit
+Project-URL: Source, https://github.com/DaosPath/handoffkit
+Project-URL: Issues, https://github.com/DaosPath/handoffkit/issues
+Keywords: agents,handoff,multi-agent,state-transfer,protocols,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: twine>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# HandoffKit
+
+[![Tests](https://github.com/DaosPath/handoffkit/actions/workflows/ci.yml/badge.svg)](https://github.com/DaosPath/handoffkit/actions/workflows/ci.yml)
+![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
+![Package version](https://img.shields.io/badge/version-0.2.0-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+HandoffKit helps developers build reliable multi-agent AI workflows by letting agents transfer structured state instead of messy free-text context.
+
+## What Problem It Solves
+
+Multi-agent systems often lose useful context at the exact moment one agent hands work to another. A prose summary may omit files, decisions, constraints, errors, and next steps. That makes workflows hard to test, replay, inspect, and improve.
+
+HandoffKit gives you a small Python API for making those handoffs explicit:
+
+- agents run with pluggable providers,
+- tools expose metadata and JSON-schema-style parameter schemas,
+- handoffs move through `HandoffState`,
+- protocols choose how much state to preserve,
+- team workflows can be tested locally with no API key.
+
+## Why HandoffKit Exists
+
+Most agent demos pass free text between roles. Real workflows need a clearer contract. HandoffKit is intentionally lightweight: it does not try to be a full orchestration platform, but it gives developers reliable primitives for state transfer, tool description, and sequential agent collaboration.
+
+The default `EchoProvider` makes examples and tests deterministic. You can later swap in providers such as Ollama or OpenAI.
+
+## Installation
+
+From PyPI after publication:
+
+```bash
+pip install handoffkit
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from handoffkit import Agent
+
+agent = Agent(
+    name="Planner",
+    role="Create concise implementation plans."
+)
+
+print(agent.run("Create a plan for a Python CLI app with tests."))
+```
+
+No provider is required for local demos. If none is configured, HandoffKit uses `EchoProvider`.
+
+## Tool Schema Example
+
+```python
+from handoffkit import tool
+
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+
+print(add.to_schema())
+print(add.run(a=2, b=3))
+```
+
+Schema output:
+
+```python
+{
+    "name": "add",
+    "description": "Add two numbers.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "a": {"type": "integer"},
+            "b": {"type": "integer"},
+        },
+        "required": ["a", "b"],
+    },
+}
+```
+
+Supported schema types include `str`, `int`, `float`, `bool`, `list`, and `dict`.
+
+## HandoffState Example
+
+```python
+from handoffkit import HandoffState
+
+state = HandoffState(
+    task="Prepare a Python package for release.",
+    from_agent="Architect",
+    to_agent="Coder",
+    summary="Package needs tests, CI, and metadata validation.",
+    decisions=["Keep runtime dependencies empty."],
+    important_files=["pyproject.toml", "README.md"],
+    errors=[],
+    next_steps=["Run pytest.", "Build wheel.", "Run twine check."],
+    metadata={"mode": "hybrid_state"},
+)
+
+state.validate()
+print(state.to_json())
+```
+
+`validate()` raises `HandoffValidationError` when required fields are empty or state fields have the wrong shape.
+
+## Protocol Comparison
+
+HandoffKit ships four protocol modes:
+
+| Mode | Shape | Use case |
+|---|---|---|
+| `natural` | Human-readable handoff summary | Debugging and simple collaboration |
+| `compressed` | Short compact summary | Token-sensitive handoffs |
+| `hybrid_min` | Task, summary, next steps | Minimal structured transfer |
+| `hybrid_state` | Full state with decisions, files, errors, metadata | Workflows that need replayable state |
+
+```python
+from handoffkit import Agent, HandoffProtocol
+
+architect = Agent("Architect", "Create technical plans.")
+coder = Agent("Coder", "Implement from handoff state.")
+
+protocol = HandoffProtocol(mode="hybrid_state")
+state = protocol.transfer(
+    from_agent=architect,
+    to_agent=coder,
+    task="Prepare a package release.",
+    summary="Use typed package metadata, tests, CI, and twine validation.",
+    decisions=["Keep package runtime dependency-free."],
+    important_files=["pyproject.toml", "README.md"],
+    next_steps=["Implement changes.", "Run pytest and twine check."],
+)
+
+print(state.to_json())
+```
+
+## Architect -> Coder -> Tester Example
+
+Run the local example:
+
+```bash
+python examples/coding_team.py
+```
+
+The example shows:
+
+1. Architect receives a task.
+2. Architect produces decisions and next steps.
+3. Coder receives `HandoffState`.
+4. Coder produces simulated implementation output.
+5. Tester receives state from Coder.
+6. Tester produces a final result.
+
+It runs without an API key using `EchoProvider`.
+
+## Real Task Demo
+
+Run a reproducible multi-agent task that generates a tiny calculator CLI, tests it,
+and writes Markdown and JSON evidence:
+
+```bash
+python examples/real_task_calculator.py
+```
+
+The demo creates:
+
+- `examples/output/calculator_cli/calculator.py`
+- `examples/output/calculator_cli/test_calculator.py`
+- `examples/output/calculator_cli/README.md`
+- `reports/real_task_calculator.md`
+- `reports/real_task_calculator.json`
+
+It uses `EchoProvider` by default, so it works without network access. If
+`OPENAI_API_KEY` is configured, it tries an OpenAI-compatible provider through
+`OPENAI_BASE_URL` and prefers `gpt-5.4` before falling back to `gpt-4o-mini`.
+
+## Providers
+
+Built-in providers:
+
+- `EchoProvider`: deterministic local responses for tests and examples.
+- `OllamaProvider`: calls a local Ollama server.
+- `OpenAIProvider`: calls the OpenAI API when configured.
+
+Ollama example:
+
+```bash
+ollama pull llama3.1
+ollama serve
+python examples/ollama_agent.py --model llama3.1
+```
+
+OpenAI usage requires `OPENAI_API_KEY` in your environment.
+
+## OpenAI-compatible Providers
+
+`OpenAIProvider` can call OpenAI-compatible chat-completions APIs by setting a custom base URL and model.
+
+PowerShell example:
+
+```powershell
+$env:OPENAI_API_KEY="..."
+$env:OPENAI_BASE_URL="https://api.freemodel.dev/v1"
+$env:OPENAI_MODEL="gpt-4o-mini"
+python examples/freemodel_openai_compatible.py
+```
+
+Optional real API tests are skipped unless explicitly enabled:
+
+```powershell
+$env:HANDOFFKIT_RUN_API_TESTS="1"
+$env:OPENAI_API_KEY="..."
+$env:OPENAI_BASE_URL="https://api.freemodel.dev/v1"
+$env:OPENAI_MODEL="gpt-4o-mini"
+pytest tests_api -q
+```
+
+Use a temporary or scoped token for provider experiments. Do not commit API keys.
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run checks:
+
+```bash
+ruff check .
+pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+Useful CLI commands:
+
+```bash
+handoffkit --version
+handoffkit demo
+```
+
+## Publishing
+
+Validate before publishing:
+
+```bash
+pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+Publish only after validating the target repository and token:
+
+```bash
+python -m twine upload dist/*
+```
+
+## Inspiration
+
+This package is inspired by the research and reproducibility repository [`DaosPath/state-transfer-protocols`](https://github.com/DaosPath/state-transfer-protocols), especially its comparison of `natural`, `compressed`, `hybrid_min`, and `hybrid_state` handoff protocols for multilingual multi-agent workflows.
+
+HandoffKit is a developer library, not a copy of that repository.
+
+## Roadmap
+
+- richer contract validators,
+- better tool schema coverage,
+- provider adapters,
+- structured tool calling loops,
+- handoff quality metrics,
+- memory integrations,
+- benchmark-inspired examples,
+- multi-agent workflow templates.
+
+## License
+
+MIT.

handoffkit-0.2.0/README.md

@@ -0,0 +1,288 @@
+# HandoffKit
+
+[![Tests](https://github.com/DaosPath/handoffkit/actions/workflows/ci.yml/badge.svg)](https://github.com/DaosPath/handoffkit/actions/workflows/ci.yml)
+![Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
+![Package version](https://img.shields.io/badge/version-0.2.0-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+HandoffKit helps developers build reliable multi-agent AI workflows by letting agents transfer structured state instead of messy free-text context.
+
+## What Problem It Solves
+
+Multi-agent systems often lose useful context at the exact moment one agent hands work to another. A prose summary may omit files, decisions, constraints, errors, and next steps. That makes workflows hard to test, replay, inspect, and improve.
+
+HandoffKit gives you a small Python API for making those handoffs explicit:
+
+- agents run with pluggable providers,
+- tools expose metadata and JSON-schema-style parameter schemas,
+- handoffs move through `HandoffState`,
+- protocols choose how much state to preserve,
+- team workflows can be tested locally with no API key.
+
+## Why HandoffKit Exists
+
+Most agent demos pass free text between roles. Real workflows need a clearer contract. HandoffKit is intentionally lightweight: it does not try to be a full orchestration platform, but it gives developers reliable primitives for state transfer, tool description, and sequential agent collaboration.
+
+The default `EchoProvider` makes examples and tests deterministic. You can later swap in providers such as Ollama or OpenAI.
+
+## Installation
+
+From PyPI after publication:
+
+```bash
+pip install handoffkit
+```
+
+For local development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from handoffkit import Agent
+
+agent = Agent(
+    name="Planner",
+    role="Create concise implementation plans."
+)
+
+print(agent.run("Create a plan for a Python CLI app with tests."))
+```
+
+No provider is required for local demos. If none is configured, HandoffKit uses `EchoProvider`.
+
+## Tool Schema Example
+
+```python
+from handoffkit import tool
+
+
+@tool
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+
+print(add.to_schema())
+print(add.run(a=2, b=3))
+```
+
+Schema output:
+
+```python
+{
+    "name": "add",
+    "description": "Add two numbers.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "a": {"type": "integer"},
+            "b": {"type": "integer"},
+        },
+        "required": ["a", "b"],
+    },
+}
+```
+
+Supported schema types include `str`, `int`, `float`, `bool`, `list`, and `dict`.
+
+## HandoffState Example
+
+```python
+from handoffkit import HandoffState
+
+state = HandoffState(
+    task="Prepare a Python package for release.",
+    from_agent="Architect",
+    to_agent="Coder",
+    summary="Package needs tests, CI, and metadata validation.",
+    decisions=["Keep runtime dependencies empty."],
+    important_files=["pyproject.toml", "README.md"],
+    errors=[],
+    next_steps=["Run pytest.", "Build wheel.", "Run twine check."],
+    metadata={"mode": "hybrid_state"},
+)
+
+state.validate()
+print(state.to_json())
+```
+
+`validate()` raises `HandoffValidationError` when required fields are empty or state fields have the wrong shape.
+
+## Protocol Comparison
+
+HandoffKit ships four protocol modes:
+
+| Mode | Shape | Use case |
+|---|---|---|
+| `natural` | Human-readable handoff summary | Debugging and simple collaboration |
+| `compressed` | Short compact summary | Token-sensitive handoffs |
+| `hybrid_min` | Task, summary, next steps | Minimal structured transfer |
+| `hybrid_state` | Full state with decisions, files, errors, metadata | Workflows that need replayable state |
+
+```python
+from handoffkit import Agent, HandoffProtocol
+
+architect = Agent("Architect", "Create technical plans.")
+coder = Agent("Coder", "Implement from handoff state.")
+
+protocol = HandoffProtocol(mode="hybrid_state")
+state = protocol.transfer(
+    from_agent=architect,
+    to_agent=coder,
+    task="Prepare a package release.",
+    summary="Use typed package metadata, tests, CI, and twine validation.",
+    decisions=["Keep package runtime dependency-free."],
+    important_files=["pyproject.toml", "README.md"],
+    next_steps=["Implement changes.", "Run pytest and twine check."],
+)
+
+print(state.to_json())
+```
+
+## Architect -> Coder -> Tester Example
+
+Run the local example:
+
+```bash
+python examples/coding_team.py
+```
+
+The example shows:
+
+1. Architect receives a task.
+2. Architect produces decisions and next steps.
+3. Coder receives `HandoffState`.
+4. Coder produces simulated implementation output.
+5. Tester receives state from Coder.
+6. Tester produces a final result.
+
+It runs without an API key using `EchoProvider`.
+
+## Real Task Demo
+
+Run a reproducible multi-agent task that generates a tiny calculator CLI, tests it,
+and writes Markdown and JSON evidence:
+
+```bash
+python examples/real_task_calculator.py
+```
+
+The demo creates:
+
+- `examples/output/calculator_cli/calculator.py`
+- `examples/output/calculator_cli/test_calculator.py`
+- `examples/output/calculator_cli/README.md`
+- `reports/real_task_calculator.md`
+- `reports/real_task_calculator.json`
+
+It uses `EchoProvider` by default, so it works without network access. If
+`OPENAI_API_KEY` is configured, it tries an OpenAI-compatible provider through
+`OPENAI_BASE_URL` and prefers `gpt-5.4` before falling back to `gpt-4o-mini`.
+
+## Providers
+
+Built-in providers:
+
+- `EchoProvider`: deterministic local responses for tests and examples.
+- `OllamaProvider`: calls a local Ollama server.
+- `OpenAIProvider`: calls the OpenAI API when configured.
+
+Ollama example:
+
+```bash
+ollama pull llama3.1
+ollama serve
+python examples/ollama_agent.py --model llama3.1
+```
+
+OpenAI usage requires `OPENAI_API_KEY` in your environment.
+
+## OpenAI-compatible Providers
+
+`OpenAIProvider` can call OpenAI-compatible chat-completions APIs by setting a custom base URL and model.
+
+PowerShell example:
+
+```powershell
+$env:OPENAI_API_KEY="..."
+$env:OPENAI_BASE_URL="https://api.freemodel.dev/v1"
+$env:OPENAI_MODEL="gpt-4o-mini"
+python examples/freemodel_openai_compatible.py
+```
+
+Optional real API tests are skipped unless explicitly enabled:
+
+```powershell
+$env:HANDOFFKIT_RUN_API_TESTS="1"
+$env:OPENAI_API_KEY="..."
+$env:OPENAI_BASE_URL="https://api.freemodel.dev/v1"
+$env:OPENAI_MODEL="gpt-4o-mini"
+pytest tests_api -q
+```
+
+Use a temporary or scoped token for provider experiments. Do not commit API keys.
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run checks:
+
+```bash
+ruff check .
+pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+Useful CLI commands:
+
+```bash
+handoffkit --version
+handoffkit demo
+```
+
+## Publishing
+
+Validate before publishing:
+
+```bash
+pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+Publish only after validating the target repository and token:
+
+```bash
+python -m twine upload dist/*
+```
+
+## Inspiration
+
+This package is inspired by the research and reproducibility repository [`DaosPath/state-transfer-protocols`](https://github.com/DaosPath/state-transfer-protocols), especially its comparison of `natural`, `compressed`, `hybrid_min`, and `hybrid_state` handoff protocols for multilingual multi-agent workflows.
+
+HandoffKit is a developer library, not a copy of that repository.
+
+## Roadmap
+
+- richer contract validators,
+- better tool schema coverage,
+- provider adapters,
+- structured tool calling loops,
+- handoff quality metrics,
+- memory integrations,
+- benchmark-inspired examples,
+- multi-agent workflow templates.
+
+## License
+
+MIT.

handoffkit-0.2.0/examples/coding_team.py

@@ -0,0 +1,57 @@
+"""Architect -> Coder -> Tester structured handoff demo.
+
+This example runs fully locally with EchoProvider. It shows the state passed
+between agents instead of hiding the handoff behind a free-text prompt.
+"""
+
+from handoffkit import Agent, HandoffProtocol
+
+
+def main() -> None:
+    """Run a visible three-agent handoff chain."""
+    task = "Create a small Python CLI calculator with tests."
+    protocol = HandoffProtocol(mode="hybrid_state")
+
+    architect = Agent("Architect", "Create implementation plans.")
+    coder = Agent("Coder", "Implement code based on structured state.")
+    tester = Agent("Tester", "Review implementation and report test gaps.")
+
+    print("1. Architect receives task")
+    print(task)
+
+    print("\n2. Architect produces decisions and next steps")
+    architect_output = architect.run(task)
+    coder_state = protocol.transfer(
+        from_agent=architect,
+        to_agent=coder,
+        task=task,
+        summary=architect_output,
+        decisions=["Expose calculator operations through a small CLI."],
+        important_files=["pyproject.toml", "calculator.py", "tests/test_calculator.py"],
+        next_steps=["Implement CLI parser.", "Add pytest coverage for add/subtract."],
+    ).validate()
+    print(coder_state.to_json())
+
+    print("\n3. Coder receives HandoffState")
+    coder_output = coder.run(task, handoff_state=coder_state)
+    print(coder_output)
+
+    print("\n4. Coder produces simulated implementation state for Tester")
+    tester_state = protocol.transfer(
+        from_agent=coder,
+        to_agent=tester,
+        task=task,
+        summary=coder_output,
+        decisions=coder_state.decisions + ["Keep CLI behavior deterministic."],
+        important_files=coder_state.important_files,
+        next_steps=["Run pytest.", "Report missing edge cases."],
+    ).validate()
+    print(tester_state.to_json())
+
+    print("\n5. Tester receives Coder state and produces final result")
+    tester_output = tester.run(task, handoff_state=tester_state)
+    print(tester_output)
+
+
+if __name__ == "__main__":
+    main()