handoffkit 0.2.0__py3-none-any.whl

handoffkit-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,32 @@
+handoffkit/__init__.py,sha256=RDQ46rCRs_KPA1cQN_X19RENyXFNx9jdnAzT6hMxDfU,525
+handoffkit/agent.py,sha256=7YVGjsxtpgATXHMfL4XHEZq9M9DQB1Q55Mp6uI0262Q,3369
+handoffkit/cli.py,sha256=EsNg8AuhG2I6aWn2LTM8exLMJPWZ8ZOvn9PIz8ju9zk,1548
+handoffkit/errors.py,sha256=wy87Ib-mE_CWeE25MYINlmb8NNh19kDyFRGzfqaJcAE,928
+handoffkit/handoff.py,sha256=EOABD5YcM0LtgSdFnaO5O8IZxvGa_3rgEqVeVz8VyrM,3498
+handoffkit/memory.py,sha256=Mz7r_26CGVNawg6ZBCSGHQJrwnDBX5eI-z8MOOz1i9c,1315
+handoffkit/protocol.py,sha256=3ZnkiOnnACD92ccquAzgorIUaO6S6N9wKRLEthm7d9k,2245
+handoffkit/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+handoffkit/runner.py,sha256=LfahWmNBTc-_wHqk82Rxi-1paB_nqbzEWfeVjctwr0w,1645
+handoffkit/schemas.py,sha256=X1mQsOO7p6Z0A3cmJ66ZgUeOZmuAYZQoY0dRi6BZ_eY,1144
+handoffkit/tool.py,sha256=VeBatxpt2tcarkAHXbdyw-CmRu4lq9G8S1hLeGCGX9c,6537
+handoffkit/protocols/__init__.py,sha256=srXbb0Ubk88OLO_gUWvxRVj0hBGfJf58OuZk-VnTwTQ,178
+handoffkit/protocols/compressed.py,sha256=cmTqjEtV4wOYQpgO6tkDNCruZCmUiZOP2pVhNbHxeBk,978
+handoffkit/protocols/hybrid_min.py,sha256=AAPLHrwCy8YwwFqlr4yAGIFyWCpi6BGAzweBb3nB_i4,578
+handoffkit/protocols/hybrid_state.py,sha256=CTxwQ2X_19qkJdrzftqbdSIYKAkNNO5SzxU99q-mMzk,1442
+handoffkit/protocols/natural.py,sha256=ngr3re2-XhpJFev8LeLXPX0q93gOkvqOIenSGBhmlx4,732
+handoffkit/providers/__init__.py,sha256=cgUgj5lBDh41A2_fNmLppPkw5OQQCwQ3bpV5DWnnWqM,639
+handoffkit/providers/base.py,sha256=7nwjtx1NmpJHbCQ_MYGEkgV7B3MqkbOzRKCR0pmUgB8,345
+handoffkit/providers/echo_provider.py,sha256=gOtD5iwSWCIm7ru94kM7CjpzvioGEKyyQG6ye2wfmB0,919
+handoffkit/providers/ollama_provider.py,sha256=tFMiI6B8G7IUftElC81cAuN_uYnZeIDLGE9wDbSM5uY,1500
+handoffkit/providers/openai_compatible.py,sha256=2Z1t7aGpTAE-YIjcTe_I2B6CjE771G2g6UxaN0v1sDE,5111
+handoffkit/providers/openai_provider.py,sha256=VM8Y66tb3NsgbXmS4sz4abRNanPwJkc0ryG_Ofnzy_0,3089
+handoffkit/tools/__init__.py,sha256=dsCfBwEdKUnR03S12v3Q_xn8UdGUCm_xx4mQ-5TVxB0,376
+handoffkit/tools/filesystem.py,sha256=JP_NkKIznaUTfkRWpAJ71N8YFaTf-_BVC3NwZG3Z5nk,774
+handoffkit/tools/shell.py,sha256=yAh35_atKBvaDFQnbLYeqgwrySWCy619RREQ1gLi61E,1689
+handoffkit/tools/text.py,sha256=9I5Ld_lpDs_wlvRZN8bLob08g9wM-F_kuo0WMDEC1Mg,1027
+handoffkit-0.2.0.dist-info/licenses/LICENSE,sha256=031GM9k6mO_YqtDVNdA0Qx3x8KPDjdXFOCXOaN-LASQ,1065
+handoffkit-0.2.0.dist-info/METADATA,sha256=1jusdY6dlZSRdNWYBUWDjfe8kgVuoJrmKOSWlgwDubE,9118
+handoffkit-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+handoffkit-0.2.0.dist-info/entry_points.txt,sha256=YOy2qo6DAGg9sQ0I4hVbb9FNNUiRZH0HwV8SxQYt6gQ,51
+handoffkit-0.2.0.dist-info/top_level.txt,sha256=qYCNy1WtNJ3e1_XChaE3aCU6p3AlVO19-JWKVDUBnYk,11
+handoffkit-0.2.0.dist-info/RECORD,,

handoffkit-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

handoffkit-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+handoffkit = handoffkit.cli:main

handoffkit-0.2.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+handoffkit