handoffkit 1.2.0__tar.gz → 1.3.0__tar.gz

{handoffkit-1.2.0/handoffkit.egg-info → handoffkit-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoffkit
-Version: 1.2.0
+Version: 1.3.0
 Summary: A lightweight Python framework for building multi-agent workflows with structured state transfer protocols.
 Author: DaosPath
 License-Expression: MIT
@@ -30,7 +30,7 @@ Requires-Dist: twine>=6.0.0; extra == "dev"
 Requires-Dist: wheel; extra == "dev"
 Dynamic: license-file
 
-<div align="center">
+<div align="center">
 
 <img src="https://raw.githubusercontent.com/DaosPath/handoffkit/main/docs/assets/handoffkit-hero.svg" alt="HandoffKit: structured state transfer for multi-agent Python workflows" width="100%">
 
@@ -125,6 +125,44 @@ replay evidence stay attached to the work.
 
 <img src="https://raw.githubusercontent.com/DaosPath/handoffkit/main/docs/assets/handoffkit-report-gallery.svg" alt="HandoffKit report gallery for coding agents, support escalation, and research workflow" width="100%">
 
+Bonus educational healthcare workflow:
+
+```bash
+handoffkit showcase doctor-orchestrator
+handoffkit report runs/latest
+```
+
+`doctor-orchestrator` is a synthetic demo inspired by virtual physician-panel
+orchestration patterns: Intake -> Hypothesis -> Challenger -> Test Steward ->
+Checklist -> Final Reviewer. It demonstrates structured uncertainty, missing
+questions, red-flag tracking, cost-aware test reasoning, and replayable review
+evidence. It is not medical advice.
+
+Real open-access case benchmark preview:
+
+```bash
+handoffkit benchmark-doctor --cases 30
+handoffkit report runs/latest
+```
+
+`benchmark-doctor` uses 30 real cases from the public MedCaseReasoning test
+split, derived from PMC Open Access case reports. It runs in `gold_replay` mode:
+it replays clinician-authored diagnoses and reasoning to test HandoffKit
+contracts, reports, quality scoring, and traceability. It does not claim model
+diagnostic accuracy and is not medical advice.
+
+MAI/SDBench-style public benchmark preview:
+
+```bash
+handoffkit benchmark-doctor-mai --cases 30
+handoffkit report runs/latest
+```
+
+`benchmark-doctor-mai` mirrors the public mechanics described for SDBench:
+opening note, gatekeeper, targeted questions, tests, simulated costs, final
+diagnosis, trace, and replay. It uses public MedCaseReasoning / PMC Open Access
+cases, not private NEJM SDBench data.
+
 ## Report Gallery
 
 Reports generated by the 1.2.0 demos:
@@ -134,6 +172,9 @@ Reports generated by the 1.2.0 demos:
 | Coding agents | [`reports/coding_review.md`](reports/coding_review.md) | `handoffkit showcase coding-review` |
 | Support escalation | [`reports/support_escalation.md`](reports/support_escalation.md) | `handoffkit showcase support-escalation` |
 | Research workflow | [`reports/research_workflow.md`](reports/research_workflow.md) | `handoffkit showcase research-workflow` |
+| Doctor orchestrator | [`reports/doctor_orchestrator.md`](reports/doctor_orchestrator.md) | `handoffkit showcase doctor-orchestrator` |
+| Doctor benchmark 30 | [`reports/doctor_benchmark_30.md`](reports/doctor_benchmark_30.md) | `handoffkit benchmark-doctor --cases 30` |
+| MAI-style doctor benchmark 30 | [`reports/mai_style_doctor_benchmark_30.md`](reports/mai_style_doctor_benchmark_30.md) | `handoffkit benchmark-doctor-mai --cases 30` |
 
 Technical post: [`Context Soup vs Contract Handoffs`](docs/CONTEXT_SOUP_VS_CONTRACT_HANDOFFS.md).
 Launch copy for Hacker News, Reddit, X/LinkedIn, and LangGraph communities:
@@ -160,10 +201,36 @@ HandoffKit 1.2.0 improves the public demo experience:
 - `handoffkit showcase <slug>` runs a showcase and writes `runs/latest`,
 - `handoffkit init coding-review` now prints the next commands to run,
 - report gallery docs and SVG assets make README/PyPI easier to inspect,
+- real-case doctor benchmark harness with 30 MedCaseReasoning / PMC Open Access cases,
+- MAI/SDBench-style public sequential doctor benchmark with gatekeeper, costs,
+  trace, and replay,
 - Pydantic AI now has a runnable offline integration example,
 - integration docs include copy/paste adapter blocks for LangGraph, OpenAI
   Agents SDK, and Pydantic AI.
 
+## What 1.3.0 Adds
+
+HandoffKit 1.3.0 is focused on stronger tool creation and
+evidence-aware agent workflows:
+
+- `ToolSpec`, `ToolFactory`, `DeclarativeTool`, and `HttpJsonTool` for building
+  provider-ready tools without hand-writing wrappers,
+- public medical evidence lookup tools for PubMed, ClinicalTrials.gov, and
+  DailyMed,
+- clinical MAI-style MiMo benchmark runner with multi-stage handoffs,
+  adversarial challenge, label normalization, and replayable reports.
+
+Medical tools are for research and benchmark workflows only. They do not
+diagnose, treat, or replace clinical judgment.
+
+```python
+from handoffkit.tools import pubmed_search, clinical_trials_search, dailymed_drug_search
+
+pubmed_search.run(query="scleroderma renal crisis case report", max_results=3)
+clinical_trials_search.run(condition="systemic sclerosis", max_results=3)
+dailymed_drug_search.run(drug_name="ibuprofen", max_results=3)
+```
+
 ## What 1.1.0 Adds
 
 HandoffKit 1.1.0 focuses on adoption:
@@ -171,8 +238,11 @@ HandoffKit 1.1.0 focuses on adoption:
 - coding agents demo: `Architect -> Coder -> Reviewer -> Tester`,
 - customer support demo: `Triage -> Billing -> Refund -> Supervisor`,
 - research demo: `Researcher -> Extractor -> Fact-checker -> Writer`,
+- educational doctor-orchestrator demo: `Intake -> Hypothesis -> Challenger ->
+  Test Steward -> Checklist -> Final Reviewer`,
 - direct templates through `handoffkit init coding-review`,
-  `handoffkit init support-escalation`, and `handoffkit init research-workflow`,
+  `handoffkit init support-escalation`, `handoffkit init research-workflow`,
+  and `handoffkit init doctor-orchestrator`,
 - `handoffkit report runs/latest` for rendering generated run reports,
 - deterministic showcase reports that work offline and require no API key.
 
@@ -183,7 +253,9 @@ Use it as the contract and reporting layer beside orchestration frameworks:
 
 - [`LangGraph`](docs/integrations/LANGGRAPH.md): graph nodes pass `HandoffState`,
 - [`OpenAI Agents SDK`](docs/integrations/OPENAI_AGENTS.md): agent handoffs become auditable contracts,
-- [`Pydantic AI`](docs/integrations/PYDANTIC_AI.md): typed outputs become workflow handoff state.
+- [`Pydantic AI`](docs/integrations/PYDANTIC_AI.md): typed outputs become workflow handoff state,
+- [`OpenCode Go / Zen`](docs/integrations/OPENCODE.md): provider adapters route
+  OpenCode model families to their matching API endpoint styles.
 
 Runnable offline examples:
 [`examples/langgraph_integration.py`](examples/langgraph_integration.py),
@@ -328,6 +400,9 @@ HandoffKit gives you:
 - `EchoProvider`: deterministic local provider for tests and demos.
 - `OllamaProvider`: local Ollama integration.
 - `OpenAIProvider`: OpenAI and OpenAI-compatible APIs.
+- `OpenCodeZenProvider`: OpenCode Zen with GPT, Claude, Qwen, DeepSeek,
+  MiniMax, GLM, Kimi, MiMo, Grok, and free model routing.
+- `OpenCodeGoProvider`: OpenCode Go with curated open coding models.
 
 ## Core Concept
 
@@ -727,6 +802,7 @@ handoffkit demo-replay
 handoffkit demo-coding-review
 handoffkit demo-support
 handoffkit demo-research
+handoffkit demo-doctor
 handoffkit report runs/latest
 handoffkit validate-report reports/trace_demo.json
 handoffkit evaluate reports/trace_demo.json
@@ -954,6 +1030,42 @@ pytest tests_api -q
 
 Use temporary or scoped provider tokens. Do not commit API keys.
 
+### OpenCode Go and OpenCode Zen
+
+HandoffKit can call OpenCode Go and OpenCode Zen without adding provider SDK
+dependencies. Use one `OPENCODE_API_KEY`; choose the catalog-specific model with
+`OPENCODE_GO_MODEL` or `OPENCODE_ZEN_MODEL`.
+
+```powershell
+$env:OPENCODE_API_KEY="..."
+$env:OPENCODE_GO_MODEL="deepseek-v4-flash"
+python examples/opencode_go_agent.py
+```
+
+```powershell
+$env:OPENCODE_API_KEY="..."
+$env:OPENCODE_ZEN_MODEL="gpt-5.4"
+python examples/opencode_zen_agent.py
+```
+
+Supported routing:
+
+| Provider | Model family | Endpoint style |
+|---|---|---|
+| OpenCode Go | GLM, Kimi, MiMo, DeepSeek | `/chat/completions` |
+| OpenCode Go | MiniMax, Qwen | `/messages` |
+| OpenCode Zen | GPT | `/responses` |
+| OpenCode Zen | Claude, Qwen | `/messages` |
+| OpenCode Zen | DeepSeek, MiniMax, GLM, Kimi, Grok, free models | `/chat/completions` |
+
+Model ids may use OpenCode config prefixes such as `opencode-go/kimi-k2.7-code`
+or `opencode/gpt-5.4`; HandoffKit strips those prefixes before sending requests.
+Gemini models use OpenCode's Google-style endpoint and currently fail with a
+clear configuration error.
+
+Docs:
+[`docs/integrations/OPENCODE.md`](docs/integrations/OPENCODE.md).
+
 ## CLI
 
 ```bash
@@ -983,11 +1095,14 @@ python examples/simple_agent.py
 python examples/coding_review.py
 python examples/support_escalation.py
 python examples/research_workflow.py
+python examples/doctor_orchestrator.py
 python examples/handoff_demo.py
 python examples/coding_team.py
 python examples/tool_schema_demo.py
 python examples/tool_execution_demo.py
 python examples/fake_provider_tool_call_demo.py
+python examples/opencode_go_agent.py
+python examples/opencode_zen_agent.py
 python examples/structured_output_demo.py
 python examples/provider_tool_adapter_demo.py
 python examples/handoff_quality_demo.py
@@ -1074,3 +1189,4 @@ HandoffKit is a developer library, not a copy of that repository.
 ## License
 
 MIT.
+

{handoffkit-1.2.0 → handoffkit-1.3.0}/README.md

@@ -1,4 +1,4 @@
-<div align="center">
+<div align="center">
 
 <img src="https://raw.githubusercontent.com/DaosPath/handoffkit/main/docs/assets/handoffkit-hero.svg" alt="HandoffKit: structured state transfer for multi-agent Python workflows" width="100%">
 
@@ -93,6 +93,44 @@ replay evidence stay attached to the work.
 
 <img src="https://raw.githubusercontent.com/DaosPath/handoffkit/main/docs/assets/handoffkit-report-gallery.svg" alt="HandoffKit report gallery for coding agents, support escalation, and research workflow" width="100%">
 
+Bonus educational healthcare workflow:
+
+```bash
+handoffkit showcase doctor-orchestrator
+handoffkit report runs/latest
+```
+
+`doctor-orchestrator` is a synthetic demo inspired by virtual physician-panel
+orchestration patterns: Intake -> Hypothesis -> Challenger -> Test Steward ->
+Checklist -> Final Reviewer. It demonstrates structured uncertainty, missing
+questions, red-flag tracking, cost-aware test reasoning, and replayable review
+evidence. It is not medical advice.
+
+Real open-access case benchmark preview:
+
+```bash
+handoffkit benchmark-doctor --cases 30
+handoffkit report runs/latest
+```
+
+`benchmark-doctor` uses 30 real cases from the public MedCaseReasoning test
+split, derived from PMC Open Access case reports. It runs in `gold_replay` mode:
+it replays clinician-authored diagnoses and reasoning to test HandoffKit
+contracts, reports, quality scoring, and traceability. It does not claim model
+diagnostic accuracy and is not medical advice.
+
+MAI/SDBench-style public benchmark preview:
+
+```bash
+handoffkit benchmark-doctor-mai --cases 30
+handoffkit report runs/latest
+```
+
+`benchmark-doctor-mai` mirrors the public mechanics described for SDBench:
+opening note, gatekeeper, targeted questions, tests, simulated costs, final
+diagnosis, trace, and replay. It uses public MedCaseReasoning / PMC Open Access
+cases, not private NEJM SDBench data.
+
 ## Report Gallery
 
 Reports generated by the 1.2.0 demos:
@@ -102,6 +140,9 @@ Reports generated by the 1.2.0 demos:
 | Coding agents | [`reports/coding_review.md`](reports/coding_review.md) | `handoffkit showcase coding-review` |
 | Support escalation | [`reports/support_escalation.md`](reports/support_escalation.md) | `handoffkit showcase support-escalation` |
 | Research workflow | [`reports/research_workflow.md`](reports/research_workflow.md) | `handoffkit showcase research-workflow` |
+| Doctor orchestrator | [`reports/doctor_orchestrator.md`](reports/doctor_orchestrator.md) | `handoffkit showcase doctor-orchestrator` |
+| Doctor benchmark 30 | [`reports/doctor_benchmark_30.md`](reports/doctor_benchmark_30.md) | `handoffkit benchmark-doctor --cases 30` |
+| MAI-style doctor benchmark 30 | [`reports/mai_style_doctor_benchmark_30.md`](reports/mai_style_doctor_benchmark_30.md) | `handoffkit benchmark-doctor-mai --cases 30` |
 
 Technical post: [`Context Soup vs Contract Handoffs`](docs/CONTEXT_SOUP_VS_CONTRACT_HANDOFFS.md).
 Launch copy for Hacker News, Reddit, X/LinkedIn, and LangGraph communities:
@@ -128,10 +169,36 @@ HandoffKit 1.2.0 improves the public demo experience:
 - `handoffkit showcase <slug>` runs a showcase and writes `runs/latest`,
 - `handoffkit init coding-review` now prints the next commands to run,
 - report gallery docs and SVG assets make README/PyPI easier to inspect,
+- real-case doctor benchmark harness with 30 MedCaseReasoning / PMC Open Access cases,
+- MAI/SDBench-style public sequential doctor benchmark with gatekeeper, costs,
+  trace, and replay,
 - Pydantic AI now has a runnable offline integration example,
 - integration docs include copy/paste adapter blocks for LangGraph, OpenAI
   Agents SDK, and Pydantic AI.
 
+## What 1.3.0 Adds
+
+HandoffKit 1.3.0 is focused on stronger tool creation and
+evidence-aware agent workflows:
+
+- `ToolSpec`, `ToolFactory`, `DeclarativeTool`, and `HttpJsonTool` for building
+  provider-ready tools without hand-writing wrappers,
+- public medical evidence lookup tools for PubMed, ClinicalTrials.gov, and
+  DailyMed,
+- clinical MAI-style MiMo benchmark runner with multi-stage handoffs,
+  adversarial challenge, label normalization, and replayable reports.
+
+Medical tools are for research and benchmark workflows only. They do not
+diagnose, treat, or replace clinical judgment.
+
+```python
+from handoffkit.tools import pubmed_search, clinical_trials_search, dailymed_drug_search
+
+pubmed_search.run(query="scleroderma renal crisis case report", max_results=3)
+clinical_trials_search.run(condition="systemic sclerosis", max_results=3)
+dailymed_drug_search.run(drug_name="ibuprofen", max_results=3)
+```
+
 ## What 1.1.0 Adds
 
 HandoffKit 1.1.0 focuses on adoption:
@@ -139,8 +206,11 @@ HandoffKit 1.1.0 focuses on adoption:
 - coding agents demo: `Architect -> Coder -> Reviewer -> Tester`,
 - customer support demo: `Triage -> Billing -> Refund -> Supervisor`,
 - research demo: `Researcher -> Extractor -> Fact-checker -> Writer`,
+- educational doctor-orchestrator demo: `Intake -> Hypothesis -> Challenger ->
+  Test Steward -> Checklist -> Final Reviewer`,
 - direct templates through `handoffkit init coding-review`,
-  `handoffkit init support-escalation`, and `handoffkit init research-workflow`,
+  `handoffkit init support-escalation`, `handoffkit init research-workflow`,
+  and `handoffkit init doctor-orchestrator`,
 - `handoffkit report runs/latest` for rendering generated run reports,
 - deterministic showcase reports that work offline and require no API key.
 
@@ -151,7 +221,9 @@ Use it as the contract and reporting layer beside orchestration frameworks:
 
 - [`LangGraph`](docs/integrations/LANGGRAPH.md): graph nodes pass `HandoffState`,
 - [`OpenAI Agents SDK`](docs/integrations/OPENAI_AGENTS.md): agent handoffs become auditable contracts,
-- [`Pydantic AI`](docs/integrations/PYDANTIC_AI.md): typed outputs become workflow handoff state.
+- [`Pydantic AI`](docs/integrations/PYDANTIC_AI.md): typed outputs become workflow handoff state,
+- [`OpenCode Go / Zen`](docs/integrations/OPENCODE.md): provider adapters route
+  OpenCode model families to their matching API endpoint styles.
 
 Runnable offline examples:
 [`examples/langgraph_integration.py`](examples/langgraph_integration.py),
@@ -296,6 +368,9 @@ HandoffKit gives you:
 - `EchoProvider`: deterministic local provider for tests and demos.
 - `OllamaProvider`: local Ollama integration.
 - `OpenAIProvider`: OpenAI and OpenAI-compatible APIs.
+- `OpenCodeZenProvider`: OpenCode Zen with GPT, Claude, Qwen, DeepSeek,
+  MiniMax, GLM, Kimi, MiMo, Grok, and free model routing.
+- `OpenCodeGoProvider`: OpenCode Go with curated open coding models.
 
 ## Core Concept
 
@@ -695,6 +770,7 @@ handoffkit demo-replay
 handoffkit demo-coding-review
 handoffkit demo-support
 handoffkit demo-research
+handoffkit demo-doctor
 handoffkit report runs/latest
 handoffkit validate-report reports/trace_demo.json
 handoffkit evaluate reports/trace_demo.json
@@ -922,6 +998,42 @@ pytest tests_api -q
 
 Use temporary or scoped provider tokens. Do not commit API keys.
 
+### OpenCode Go and OpenCode Zen
+
+HandoffKit can call OpenCode Go and OpenCode Zen without adding provider SDK
+dependencies. Use one `OPENCODE_API_KEY`; choose the catalog-specific model with
+`OPENCODE_GO_MODEL` or `OPENCODE_ZEN_MODEL`.
+
+```powershell
+$env:OPENCODE_API_KEY="..."
+$env:OPENCODE_GO_MODEL="deepseek-v4-flash"
+python examples/opencode_go_agent.py
+```
+
+```powershell
+$env:OPENCODE_API_KEY="..."
+$env:OPENCODE_ZEN_MODEL="gpt-5.4"
+python examples/opencode_zen_agent.py
+```
+
+Supported routing:
+
+| Provider | Model family | Endpoint style |
+|---|---|---|
+| OpenCode Go | GLM, Kimi, MiMo, DeepSeek | `/chat/completions` |
+| OpenCode Go | MiniMax, Qwen | `/messages` |
+| OpenCode Zen | GPT | `/responses` |
+| OpenCode Zen | Claude, Qwen | `/messages` |
+| OpenCode Zen | DeepSeek, MiniMax, GLM, Kimi, Grok, free models | `/chat/completions` |
+
+Model ids may use OpenCode config prefixes such as `opencode-go/kimi-k2.7-code`
+or `opencode/gpt-5.4`; HandoffKit strips those prefixes before sending requests.
+Gemini models use OpenCode's Google-style endpoint and currently fail with a
+clear configuration error.
+
+Docs:
+[`docs/integrations/OPENCODE.md`](docs/integrations/OPENCODE.md).
+
 ## CLI
 
 ```bash
@@ -951,11 +1063,14 @@ python examples/simple_agent.py
 python examples/coding_review.py
 python examples/support_escalation.py
 python examples/research_workflow.py
+python examples/doctor_orchestrator.py
 python examples/handoff_demo.py
 python examples/coding_team.py
 python examples/tool_schema_demo.py
 python examples/tool_execution_demo.py
 python examples/fake_provider_tool_call_demo.py
+python examples/opencode_go_agent.py
+python examples/opencode_zen_agent.py
 python examples/structured_output_demo.py
 python examples/provider_tool_adapter_demo.py
 python examples/handoff_quality_demo.py
@@ -1042,3 +1157,4 @@ HandoffKit is a developer library, not a copy of that repository.
 ## License
 
 MIT.
+

handoffkit-1.3.0/examples/doctor_benchmark.py

@@ -0,0 +1,7 @@
+"""Run the real-case offline doctor benchmark harness."""
+
+from handoffkit.doctor_benchmark import run_doctor_benchmark
+
+if __name__ == "__main__":
+    result = run_doctor_benchmark(30)
+    print(result.to_markdown())

handoffkit-1.3.0/examples/doctor_orchestrator.py

@@ -0,0 +1,13 @@
+"""Educational diagnostic-orchestrator showcase.
+
+This is a synthetic workflow demo. It is not medical advice and does not produce
+patient-specific diagnosis or treatment.
+"""
+
+from __future__ import annotations
+
+from handoffkit import run_showcase
+
+if __name__ == "__main__":
+    result = run_showcase("doctor-orchestrator")
+    print(result.to_markdown())