handoffkit 0.3.0__tar.gz → 0.4.0__tar.gz

{handoffkit-0.3.0 → handoffkit-0.4.0}/MANIFEST.in

@@ -4,6 +4,7 @@ graft examples
 graft tests
 prune examples/output
 prune tests/_tmp_tool_execution
+prune tests/_tmp_memory_context
 global-exclude __pycache__
 global-exclude __pycache__/*
 global-exclude *.py[cod]

{handoffkit-0.3.0/handoffkit.egg-info → handoffkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: handoffkit
-Version: 0.3.0
+Version: 0.4.0
 Summary: A lightweight Python framework for building multi-agent workflows with structured state transfer protocols.
 Author: DaosPath
 License-Expression: MIT
@@ -80,7 +80,21 @@ Tester
 
 That makes agent workflows easier to inspect, test, replay, and improve.
 
-## What 0.3.0 Adds
+## What 0.4.0 Adds
+
+HandoffKit 0.4.0 adds a lightweight memory and project context engine:
+
+- `MemoryItem`, `MemoryStore`, and `JsonMemoryStore` for structured memory,
+- `ProjectIndexer` for scanning local project files,
+- `ContextRetriever` for deterministic keyword retrieval,
+- `ContextPack` for bundling relevant files and memories,
+- `Agent.run_with_context()` for context-aware agent runs,
+- `HandoffState.context_refs` so agents can pass explicit context references.
+
+No vector database. No heavy dependency stack. Just transparent, inspectable
+context for agent workflows.
+
+## What 0.3.0 Added
 
 HandoffKit 0.3.0 adds a real tool execution loop:
 
@@ -243,6 +257,56 @@ Safety:
 - when `require_approval=True`, write and shell tools return
   `approval_required` instead of executing.
 
+## Memory + Project Context
+
+HandoffKit can store durable project decisions, index local files, retrieve
+relevant context, and hand explicit references from one agent to the next.
+
+```python
+from handoffkit import (
+    Agent,
+    ContextPack,
+    ContextRetriever,
+    JsonMemoryStore,
+    ProjectIndexer,
+)
+
+memory = JsonMemoryStore("examples/output/memory.json")
+memory.add(
+    "Calculator CLI should use argparse and pure functions.",
+    kind="decision",
+    tags=["calculator", "cli"],
+)
+
+documents = ProjectIndexer(".").index()
+retriever = ContextRetriever(documents)
+matches = retriever.search("calculator argparse tests", limit=3)
+
+context = ContextPack(
+    query="Create a calculator CLI implementation plan.",
+    documents=matches,
+    memories=memory.search("calculator cli", limit=3),
+)
+
+agent = Agent("Architect", "Create concise implementation plans.")
+result = agent.run_with_context(
+    "Create a concise architecture plan for a Python CLI calculator.",
+    context=context,
+    memory=memory,
+)
+
+print(result.final_output)
+print(context.to_markdown())
+```
+
+Run the included demos:
+
+```bash
+python examples/memory_demo.py
+python examples/project_context_demo.py
+python examples/context_handoff_demo.py
+```
+
 ## Real Task Demo
 
 HandoffKit includes a reproducible real task demo:
@@ -340,6 +404,9 @@ 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/memory_demo.py
+python examples/project_context_demo.py
+python examples/context_handoff_demo.py
 python examples/real_task_calculator.py
 ```
 
@@ -398,6 +465,7 @@ HandoffKit is a developer library, not a copy of that repository.
 - structured tool calling loops,
 - handoff quality metrics,
 - memory integrations,
+- project context retrieval,
 - benchmark-inspired examples,
 - multi-agent workflow templates.
 

{handoffkit-0.3.0 → handoffkit-0.4.0}/README.md

@@ -51,7 +51,21 @@ Tester
 
 That makes agent workflows easier to inspect, test, replay, and improve.
 
-## What 0.3.0 Adds
+## What 0.4.0 Adds
+
+HandoffKit 0.4.0 adds a lightweight memory and project context engine:
+
+- `MemoryItem`, `MemoryStore`, and `JsonMemoryStore` for structured memory,
+- `ProjectIndexer` for scanning local project files,
+- `ContextRetriever` for deterministic keyword retrieval,
+- `ContextPack` for bundling relevant files and memories,
+- `Agent.run_with_context()` for context-aware agent runs,
+- `HandoffState.context_refs` so agents can pass explicit context references.
+
+No vector database. No heavy dependency stack. Just transparent, inspectable
+context for agent workflows.
+
+## What 0.3.0 Added
 
 HandoffKit 0.3.0 adds a real tool execution loop:
 
@@ -214,6 +228,56 @@ Safety:
 - when `require_approval=True`, write and shell tools return
   `approval_required` instead of executing.
 
+## Memory + Project Context
+
+HandoffKit can store durable project decisions, index local files, retrieve
+relevant context, and hand explicit references from one agent to the next.
+
+```python
+from handoffkit import (
+    Agent,
+    ContextPack,
+    ContextRetriever,
+    JsonMemoryStore,
+    ProjectIndexer,
+)
+
+memory = JsonMemoryStore("examples/output/memory.json")
+memory.add(
+    "Calculator CLI should use argparse and pure functions.",
+    kind="decision",
+    tags=["calculator", "cli"],
+)
+
+documents = ProjectIndexer(".").index()
+retriever = ContextRetriever(documents)
+matches = retriever.search("calculator argparse tests", limit=3)
+
+context = ContextPack(
+    query="Create a calculator CLI implementation plan.",
+    documents=matches,
+    memories=memory.search("calculator cli", limit=3),
+)
+
+agent = Agent("Architect", "Create concise implementation plans.")
+result = agent.run_with_context(
+    "Create a concise architecture plan for a Python CLI calculator.",
+    context=context,
+    memory=memory,
+)
+
+print(result.final_output)
+print(context.to_markdown())
+```
+
+Run the included demos:
+
+```bash
+python examples/memory_demo.py
+python examples/project_context_demo.py
+python examples/context_handoff_demo.py
+```
+
 ## Real Task Demo
 
 HandoffKit includes a reproducible real task demo:
@@ -311,6 +375,9 @@ 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/memory_demo.py
+python examples/project_context_demo.py
+python examples/context_handoff_demo.py
 python examples/real_task_calculator.py
 ```
 
@@ -369,6 +436,7 @@ HandoffKit is a developer library, not a copy of that repository.
 - structured tool calling loops,
 - handoff quality metrics,
 - memory integrations,
+- project context retrieval,
 - benchmark-inspired examples,
 - multi-agent workflow templates.
 

handoffkit-0.4.0/examples/context_handoff_demo.py

@@ -0,0 +1,116 @@
+"""Context-aware Architect -> Coder -> Tester handoff demo."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from handoffkit import (
+    Agent,
+    ContextPack,
+    ContextRetriever,
+    HandoffProtocol,
+    JsonMemoryStore,
+    ProjectIndexer,
+)
+
+ROOT = Path(__file__).resolve().parents[1]
+OUTPUT_DIR = ROOT / "examples" / "output" / "context_handoff_demo"
+SAMPLE_PROJECT = OUTPUT_DIR / "sample_project"
+REPORTS_DIR = ROOT / "reports"
+
+
+def write_sample_project() -> None:
+    """Create deterministic files for the context demo."""
+    SAMPLE_PROJECT.mkdir(parents=True, exist_ok=True)
+    (SAMPLE_PROJECT / "README.md").write_text(
+        "Calculator CLI\n\nUse argparse and keep calculator operations pure.",
+        encoding="utf-8",
+    )
+    (SAMPLE_PROJECT / "test_plan.md").write_text(
+        "Test add, subtract, multiply, divide, and divide-by-zero behavior.",
+        encoding="utf-8",
+    )
+
+
+def main() -> None:
+    """Pass context references through a three-agent workflow."""
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+    write_sample_project()
+
+    memory = JsonMemoryStore(str(OUTPUT_DIR / "memory.json"))
+    memory.clear()
+    memory.add(
+        "Use argparse for the CLI and pure functions for arithmetic.",
+        kind="decision",
+        tags=["calculator", "architecture"],
+    )
+
+    documents = ProjectIndexer(str(SAMPLE_PROJECT)).index()
+    matches = ContextRetriever(documents).search("calculator argparse tests", limit=3)
+    context = ContextPack(
+        query="Create a Python CLI calculator plan.",
+        documents=matches,
+        memories=memory.search("calculator argparse", limit=3),
+    )
+
+    architect = Agent("Architect", "Create implementation plans.")
+    coder = Agent("Coder", "Implement from structured state.")
+    tester = Agent("Tester", "Validate behavior and report evidence.")
+    protocol = HandoffProtocol(mode="hybrid_state")
+
+    architect_result = architect.run_with_context(
+        "Create a concise architecture plan for a Python CLI calculator.",
+        context=context,
+        memory=memory,
+    )
+    coder_state = protocol.transfer(
+        from_agent=architect,
+        to_agent=coder,
+        task="Implement the calculator CLI from the architecture plan.",
+        summary=architect_result.final_output,
+        decisions=["Use argparse.", "Keep arithmetic functions pure."],
+        important_files=[doc.path for doc in matches],
+        next_steps=["Create calculator.py.", "Create pytest coverage."],
+        context_refs=[doc.path for doc in matches],
+    )
+    tester_state = protocol.transfer(
+        from_agent=coder,
+        to_agent=tester,
+        task="Validate the calculator CLI implementation.",
+        summary="Coder received context-aware handoff and implementation constraints.",
+        decisions=coder_state.decisions,
+        important_files=coder_state.important_files,
+        next_steps=["Run pytest.", "Report failures with context references."],
+        context_refs=coder_state.context_refs,
+    )
+
+    report = "\n".join(
+        [
+            "# Context Handoff Demo",
+            "",
+            "## Context Pack",
+            "",
+            context.to_markdown(),
+            "",
+            "## Coder Handoff",
+            "",
+            coder_state.to_json(),
+            "",
+            "## Tester Handoff",
+            "",
+            tester_state.to_json(),
+            "",
+        ]
+    )
+    report_path = REPORTS_DIR / "context_handoff_demo.md"
+    report_path.write_text(report, encoding="utf-8")
+
+    print(f"Context documents: {[doc.path for doc in matches]}")
+    print(f"Coder context_refs: {coder_state.context_refs}")
+    print(f"Tester context_refs: {tester_state.context_refs}")
+    print(f"Report: {report_path}")
+
+
+if __name__ == "__main__":
+    main()

handoffkit-0.4.0/examples/memory_demo.py

@@ -0,0 +1,55 @@
+"""Structured memory demo."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from handoffkit import JsonMemoryStore, MemoryReport
+
+ROOT = Path(__file__).resolve().parents[1]
+OUTPUT_DIR = ROOT / "examples" / "output" / "memory_demo"
+REPORTS_DIR = ROOT / "reports"
+
+
+def main() -> None:
+    """Create, search, and report structured memories."""
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+
+    store = JsonMemoryStore(str(OUTPUT_DIR / "memory.json"))
+    store.clear()
+    stored = [
+        store.add(
+            "Calculator CLI should use argparse and pure functions.",
+            kind="decision",
+            tags=["calculator", "cli"],
+        ),
+        store.add(
+            "Tester agent must verify divide-by-zero behavior.",
+            kind="test-note",
+            tags=["calculator", "tests"],
+        ),
+    ]
+
+    query = "calculator cli tests"
+    matches = store.search(query, limit=5)
+    report = MemoryReport(
+        memories_stored=stored,
+        searches_executed=[query],
+        final_result=f"Found {len(matches)} relevant memories.",
+    )
+
+    markdown_path = REPORTS_DIR / "memory_demo.md"
+    json_path = REPORTS_DIR / "memory_demo.json"
+    markdown_path.write_text(report.to_markdown(), encoding="utf-8")
+    json_path.write_text(report.to_json(), encoding="utf-8")
+
+    print(f"Memories stored: {len(stored)}")
+    print(f"Search query: {query}")
+    print(f"Matches: {[item.kind for item in matches]}")
+    print(f"Markdown report: {markdown_path}")
+    print(f"JSON report: {json_path}")
+
+
+if __name__ == "__main__":
+    main()

handoffkit-0.4.0/examples/project_context_demo.py

@@ -0,0 +1,66 @@
+"""Project context indexing and retrieval demo."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from handoffkit import ContextPack, ContextRetriever, ProjectIndexer
+
+ROOT = Path(__file__).resolve().parents[1]
+OUTPUT_DIR = ROOT / "examples" / "output" / "project_context_demo"
+SAMPLE_PROJECT = OUTPUT_DIR / "sample_project"
+REPORTS_DIR = ROOT / "reports"
+
+
+def write_sample_project() -> None:
+    """Create a tiny project for deterministic retrieval."""
+    SAMPLE_PROJECT.mkdir(parents=True, exist_ok=True)
+    (SAMPLE_PROJECT / "calculator.py").write_text(
+        "\n".join(
+            [
+                "def add(a: int, b: int) -> int:",
+                "    return a + b",
+                "",
+                "def divide(a: int, b: int) -> float:",
+                "    if b == 0:",
+                "        raise ValueError('division by zero')",
+                "    return a / b",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    (SAMPLE_PROJECT / "README.md").write_text(
+        "Calculator CLI\n\nUse argparse. Test add, subtract, multiply, and divide.",
+        encoding="utf-8",
+    )
+    ignored = SAMPLE_PROJECT / "dist"
+    ignored.mkdir(exist_ok=True)
+    (ignored / "generated.txt").write_text("This file should not be indexed.", encoding="utf-8")
+
+
+def main() -> None:
+    """Index a sample project and write a context report."""
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    REPORTS_DIR.mkdir(parents=True, exist_ok=True)
+    write_sample_project()
+
+    documents = ProjectIndexer(str(SAMPLE_PROJECT)).index()
+    retriever = ContextRetriever(documents)
+    query = "argparse divide tests"
+    matches = retriever.search(query, limit=3)
+    pack = ContextPack(query=query, documents=matches)
+
+    markdown_path = REPORTS_DIR / "project_context_demo.md"
+    json_path = REPORTS_DIR / "project_context_demo.json"
+    markdown_path.write_text(pack.to_markdown(), encoding="utf-8")
+    json_path.write_text(pack.to_json(), encoding="utf-8")
+
+    print(f"Documents indexed: {len(documents)}")
+    print(f"Query: {query}")
+    print(f"Matches: {[doc.path for doc in matches]}")
+    print(f"Markdown report: {markdown_path}")
+    print(f"JSON report: {json_path}")
+
+
+if __name__ == "__main__":
+    main()

{handoffkit-0.3.0 → handoffkit-0.4.0}/handoffkit/__init__.py

@@ -1,8 +1,16 @@
 """Public API for HandoffKit."""
 
 from handoffkit.agent import Agent
+from handoffkit.context import (
+    ContextDocument,
+    ContextPack,
+    ContextRetriever,
+    ContextRunResult,
+    ProjectIndexer,
+)
 from handoffkit.errors import HandoffValidationError
 from handoffkit.handoff import HandoffState
+from handoffkit.memory import JsonMemoryStore, MemoryItem, MemoryReport, MemoryStore
 from handoffkit.protocol import HandoffProtocol
 from handoffkit.runner import Team, TeamRunResult
 from handoffkit.tool import Tool, tool
@@ -13,13 +21,22 @@ from handoffkit.tool_execution import (
     ToolResult,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "Agent",
+    "ContextDocument",
+    "ContextPack",
+    "ContextRetriever",
+    "ContextRunResult",
     "HandoffValidationError",
     "HandoffProtocol",
     "HandoffState",
+    "JsonMemoryStore",
+    "MemoryItem",
+    "MemoryReport",
+    "MemoryStore",
+    "ProjectIndexer",
     "Team",
     "TeamRunResult",
     "Tool",

{handoffkit-0.3.0 → handoffkit-0.4.0}/handoffkit/agent.py

@@ -7,8 +7,9 @@ import shlex
 from collections.abc import Callable, Sequence
 from typing import Any
 
+from handoffkit.context import ContextPack, ContextRunResult
 from handoffkit.handoff import HandoffState
-from handoffkit.memory import AgentMemory
+from handoffkit.memory import AgentMemory, MemoryStore
 from handoffkit.providers import BaseProvider, EchoProvider
 from handoffkit.tool import Tool, ensure_tool
 from handoffkit.tool_execution import (
@@ -104,6 +105,29 @@ class Agent:
             require_approval=require_approval,
         )
 
+    def run_with_context(
+        self,
+        task: str,
+        context: ContextPack | None = None,
+        memory: MemoryStore | None = None,
+        tools: Sequence[Tool | Callable[..., Any]] | None = None,
+    ) -> ContextRunResult:
+        """Run the agent with retrieved project context and structured memory."""
+        memories = memory.search(task, limit=5) if memory else []
+        prompt = self._build_context_prompt(task, context=context, memories=memories)
+        self.memory.add("user", task, agent=self.name)
+        output = self.provider.generate(prompt)
+        self.memory.add("assistant", output, agent=self.name)
+        if tools:
+            tool_report = self.run_with_tools(task, tools=tools)
+            output = f"{output}\n\nTool execution: {tool_report.final_output}"
+        return ContextRunResult(
+            final_output=output,
+            context_used=context,
+            memories_used=memories,
+            success=True,
+        )
+
     def _run_local_tool_mode(
         self,
         task: str,
@@ -254,6 +278,28 @@ class Agent:
             'To finish, return {"final":"Done"}.'
         )
 
+    def _build_context_prompt(
+        self,
+        task: str,
+        *,
+        context: ContextPack | None,
+        memories: list[Any],
+    ) -> str:
+        """Build prompt with context and memory summaries."""
+        context_text = context.to_markdown() if context else "No context pack."
+        memory_text = "\n".join(f"- {item.kind}: {item.content}" for item in memories)
+        if not memory_text:
+            memory_text = "No relevant structured memories."
+        return (
+            f"Agent: {self.name}\n"
+            f"Role: {self.role}\n"
+            f"Task: {task}\n\n"
+            f"Project context:\n{context_text}\n\n"
+            f"Relevant memory:\n{memory_text}\n\n"
+            "Use the provided context and memories. "
+            "Report useful progress, decisions, errors if any, and next steps."
+        )
+
     def _build_prompt(self, task: str, *, handoff_state: HandoffState | None) -> str:
         tool_lines = "\n".join(
             f"- {tool.name}: {tool.description or 'No description'}"