handoffkit 0.2.0__py3-none-any.whl

handoffkit/__init__.py

@@ -0,0 +1,22 @@
+"""Public API for HandoffKit."""
+
+from handoffkit.agent import Agent
+from handoffkit.errors import HandoffValidationError
+from handoffkit.handoff import HandoffState
+from handoffkit.protocol import HandoffProtocol
+from handoffkit.runner import Team, TeamRunResult
+from handoffkit.tool import Tool, tool
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Agent",
+    "HandoffValidationError",
+    "HandoffProtocol",
+    "HandoffState",
+    "Team",
+    "TeamRunResult",
+    "Tool",
+    "__version__",
+    "tool",
+]

handoffkit/agent.py

@@ -0,0 +1,91 @@
+"""Agent abstraction."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from handoffkit.handoff import HandoffState
+from handoffkit.memory import AgentMemory
+from handoffkit.providers import BaseProvider, EchoProvider
+from handoffkit.tool import Tool, ensure_tool
+
+
+class Agent:
+    """AI agent with a role, provider, memory, and executable tools."""
+
+    def __init__(
+        self,
+        name: str,
+        role: str,
+        *,
+        model: str = "echo",
+        tools: Sequence[Tool | Callable[..., Any]] | None = None,
+        provider: BaseProvider | None = None,
+        memory: AgentMemory | None = None,
+    ) -> None:
+        if not name.strip():
+            raise ValueError("Agent name cannot be empty.")
+        if not role.strip():
+            raise ValueError("Agent role cannot be empty.")
+        self.name = name
+        self.role = role
+        self.model = model
+        self.provider = provider or EchoProvider(model=model)
+        self.memory = memory or AgentMemory()
+        self.tools: list[Tool] = []
+        for item in tools or []:
+            self.add_tool(item)
+
+    def add_tool(self, item: Tool | Callable[..., Any]) -> Tool:
+        """Add a tool or callable to this agent."""
+        wrapped = ensure_tool(item)
+        self.tools.append(wrapped)
+        return wrapped
+
+    def describe(self) -> dict[str, Any]:
+        """Return a structured description of the agent."""
+        return {
+            "name": self.name,
+            "role": self.role,
+            "model": self.model,
+            "provider": self.provider.__class__.__name__,
+            "tools": [tool.to_dict() for tool in self.tools],
+        }
+
+    def run_tool(self, name: str, **kwargs: Any) -> Any:
+        """Run one registered tool by name."""
+        for item in self.tools:
+            if item.name == name:
+                return item.run(**kwargs)
+        raise ValueError(f"Tool not found for agent {self.name!r}: {name}")
+
+    def run(self, task: str, *, handoff_state: HandoffState | None = None, **kwargs: Any) -> str:
+        """Run the agent on a task and return provider output."""
+        prompt = self._build_prompt(task, handoff_state=handoff_state)
+        self.memory.add("user", task, agent=self.name)
+        output = self.provider.generate(prompt, **kwargs)
+        self.memory.add("assistant", output, agent=self.name)
+        return output
+
+    def _build_prompt(self, task: str, *, handoff_state: HandoffState | None) -> str:
+        tool_lines = "\n".join(
+            f"- {tool.name}: {tool.description or 'No description'}"
+            for tool in self.tools
+        )
+        if not tool_lines:
+            tool_lines = "- No tools registered"
+        memory_text = self.memory.to_text(count=4) or "No prior memory."
+        handoff_text = handoff_state.to_json(indent=None) if handoff_state else "No handoff state."
+        return (
+            f"Agent: {self.name}\n"
+            f"Role: {self.role}\n"
+            f"Task: {task}\n\n"
+            f"Tools:\n{tool_lines}\n\n"
+            f"Recent memory:\n{memory_text}\n\n"
+            f"Handoff state:\n{handoff_text}\n\n"
+            "Respond with useful progress, decisions, errors if any, and next steps."
+        )
+
+    def __repr__(self) -> str:
+        return f"Agent(name={self.name!r}, role={self.role!r})"

handoffkit/cli.py

@@ -0,0 +1,49 @@
+"""Command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+
+from handoffkit import __version__
+from handoffkit.agent import Agent
+from handoffkit.protocol import HandoffProtocol
+from handoffkit.runner import Team
+
+
+def run_demo() -> str:
+    """Run a local demo using EchoProvider."""
+    architect = Agent("Architect", "Analyze projects and create technical plans")
+    coder = Agent("Coder", "Write code based on received handoff state")
+    tester = Agent("Tester", "Test implementation and report errors")
+    team = Team(
+        agents=[architect, coder, tester],
+        protocol=HandoffProtocol(mode="hybrid_state"),
+    )
+    result = team.run("Create a small Python CLI calculator with tests")
+    return (
+        "HandoffKit demo\n"
+        "Protocol: hybrid_state\n"
+        f"Agents: {', '.join(agent.name for agent in team.agents)}\n"
+        f"Handoffs: {len(result.handoffs)}\n"
+        f"Final output:\n{result.final_output}"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command-line interface."""
+    parser = argparse.ArgumentParser(prog="handoffkit")
+    parser.add_argument("--version", action="version", version=f"handoffkit {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+    subparsers.add_parser("demo", help="Run a local EchoProvider demo.")
+    args = parser.parse_args(argv)
+
+    if args.command == "demo":
+        print(run_demo())
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

handoffkit/errors.py

@@ -0,0 +1,33 @@
+"""Package-specific exceptions."""
+
+
+class StateTransferError(Exception):
+    """Base exception for handoffkit."""
+
+
+class AgentError(StateTransferError):
+    """Raised when an agent cannot complete an operation."""
+
+
+class ProtocolError(StateTransferError):
+    """Raised when a handoff protocol is invalid or cannot run."""
+
+
+class HandoffValidationError(StateTransferError):
+    """Raised when a handoff state violates the expected contract."""
+
+
+class ToolExecutionError(StateTransferError):
+    """Raised when a tool fails during execution."""
+
+
+class DangerousCommandError(StateTransferError):
+    """Raised when a shell command is blocked by the safety policy."""
+
+
+class ProviderConfigurationError(StateTransferError):
+    """Raised when a provider is missing required configuration."""
+
+
+class ProviderExecutionError(StateTransferError):
+    """Raised when a provider request fails."""

handoffkit/handoff.py

@@ -0,0 +1,86 @@
+"""Structured handoff state between agents."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from handoffkit.errors import HandoffValidationError
+
+REQUIRED_TEXT_FIELDS = ("task", "from_agent", "to_agent")
+LIST_FIELDS = ("decisions", "important_files", "errors", "next_steps")
+
+
+def _value_or_default(data: dict[str, Any], key: str, default: Any) -> Any:
+    """Read a key without coercing invalid caller data into a valid shape."""
+    value = data.get(key, default)
+    return default if value is None else value
+
+
+@dataclass
+class HandoffState:
+    """State transferred from one agent to another."""
+
+    task: str
+    from_agent: str
+    to_agent: str
+    summary: str = ""
+    decisions: list[str] = field(default_factory=list)
+    important_files: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    next_steps: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable dictionary."""
+        return asdict(self)
+
+    def to_json(self, *, indent: int | None = 2) -> str:
+        """Return a JSON string."""
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)
+
+    def validate(self) -> HandoffState:
+        """Validate the handoff state contract and return self."""
+        problems: list[str] = []
+        for field_name in REQUIRED_TEXT_FIELDS:
+            value = getattr(self, field_name)
+            if not isinstance(value, str) or not value.strip():
+                problems.append(f"{field_name} must be a non-empty string")
+        if not isinstance(self.summary, str):
+            problems.append("summary must be a string")
+        for field_name in LIST_FIELDS:
+            value = getattr(self, field_name)
+            if not isinstance(value, list):
+                problems.append(f"{field_name} must be a list")
+                continue
+            if not all(isinstance(item, str) for item in value):
+                problems.append(f"{field_name} must contain only strings")
+        if not isinstance(self.metadata, dict):
+            problems.append("metadata must be a dictionary")
+        if problems:
+            raise HandoffValidationError("; ".join(problems))
+        return self
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> HandoffState:
+        """Create a handoff state from a dictionary."""
+        return cls(
+            task=_value_or_default(data, "task", ""),
+            from_agent=_value_or_default(data, "from_agent", ""),
+            to_agent=_value_or_default(data, "to_agent", ""),
+            summary=_value_or_default(data, "summary", ""),
+            decisions=_value_or_default(data, "decisions", []),
+            important_files=_value_or_default(data, "important_files", []),
+            errors=_value_or_default(data, "errors", []),
+            next_steps=_value_or_default(data, "next_steps", []),
+            metadata=_value_or_default(data, "metadata", {}),
+        )
+
+    @classmethod
+    def from_json(cls, value: str) -> HandoffState:
+        """Create a handoff state from JSON."""
+        data = json.loads(value)
+        if not isinstance(data, dict):
+            raise ValueError("HandoffState JSON must decode to an object.")
+        return cls.from_dict(data)

handoffkit/memory.py

@@ -0,0 +1,44 @@
+"""Simple in-memory agent memory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class MemoryEntry:
+    """One memory entry created by an agent run."""
+
+    role: str
+    content: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+
+@dataclass
+class AgentMemory:
+    """Small append-only memory used by agents."""
+
+    entries: list[MemoryEntry] = field(default_factory=list)
+
+    def add(self, role: str, content: str, **metadata: Any) -> MemoryEntry:
+        """Add an entry and return it."""
+        entry = MemoryEntry(role=role, content=content, metadata=metadata)
+        self.entries.append(entry)
+        return entry
+
+    def last(self, count: int = 5) -> list[MemoryEntry]:
+        """Return the most recent entries."""
+        if count <= 0:
+            return []
+        return self.entries[-count:]
+
+    def to_text(self, count: int = 5) -> str:
+        """Render recent memory entries as compact text."""
+        return "\n".join(f"{entry.role}: {entry.content}" for entry in self.last(count))
+
+    def clear(self) -> None:
+        """Remove all entries."""
+        self.entries.clear()

handoffkit/protocol.py

@@ -0,0 +1,60 @@
+"""Handoff protocol facade."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from handoffkit.agent import Agent
+from handoffkit.errors import ProtocolError
+from handoffkit.handoff import HandoffState
+from handoffkit.protocols import compressed, hybrid_min, hybrid_state, natural
+from handoffkit.schemas import ProtocolMode
+
+SUPPORTED_MODES: set[str] = {"natural", "compressed", "hybrid_min", "hybrid_state"}
+
+
+class HandoffProtocol:
+    """Transfer state between agents using a named protocol mode."""
+
+    def __init__(self, mode: ProtocolMode = "hybrid_state") -> None:
+        if mode not in SUPPORTED_MODES:
+            raise ProtocolError(f"Unsupported handoff protocol mode: {mode}")
+        self.mode = mode
+
+    def transfer(
+        self,
+        *,
+        from_agent: Agent,
+        to_agent: Agent,
+        task: str,
+        summary: str | None = None,
+        decisions: list[str] | None = None,
+        important_files: list[str] | None = None,
+        errors: list[str] | None = None,
+        next_steps: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> HandoffState:
+        """Create handoff state from one agent to another."""
+        source_summary = summary if summary is not None else from_agent.run(task)
+        if self.mode == "natural":
+            return natural.build_state(task, from_agent.name, to_agent.name, source_summary)
+        if self.mode == "compressed":
+            return compressed.build_state(task, from_agent.name, to_agent.name, source_summary)
+        if self.mode == "hybrid_min":
+            return hybrid_min.build_state(task, from_agent.name, to_agent.name, source_summary)
+        if self.mode == "hybrid_state":
+            return hybrid_state.build_state(
+                task,
+                from_agent.name,
+                to_agent.name,
+                source_summary,
+                decisions=decisions,
+                important_files=important_files,
+                errors=errors,
+                next_steps=next_steps,
+                metadata=metadata,
+            )
+        raise ProtocolError(f"Unsupported handoff protocol mode: {self.mode}")
+
+    def __repr__(self) -> str:
+        return f"HandoffProtocol(mode={self.mode!r})"

handoffkit/protocols/__init__.py

@@ -0,0 +1,5 @@
+"""Protocol module exports."""
+
+from handoffkit.protocols import compressed, hybrid_min, hybrid_state, natural
+
+__all__ = ["compressed", "hybrid_min", "hybrid_state", "natural"]

handoffkit/protocols/compressed.py

@@ -0,0 +1,31 @@
+"""Compressed handoff protocol."""
+
+from __future__ import annotations
+
+from handoffkit.handoff import HandoffState
+
+
+def compact(text: str, max_chars: int = 360) -> str:
+    """Compact whitespace and cap text length."""
+    clean = " ".join(text.strip().split())
+    if len(clean) <= max_chars:
+        return clean
+    return clean[: max_chars - 3].rstrip() + "..."
+
+
+def build_state(task: str, from_agent: str, to_agent: str, summary: str) -> HandoffState:
+    """Build a compact handoff state."""
+    return HandoffState(
+        task=compact(task, 220),
+        from_agent=from_agent,
+        to_agent=to_agent,
+        summary=compact(summary, 360),
+        next_steps=[
+            compact(f"{to_agent}: continue task; preserve constraints; report blockers.", 180)
+        ],
+        metadata={
+            "mode": "compressed",
+            "format": "compact",
+            "compression": "whitespace-normalized-char-cap",
+        },
+    )

handoffkit/protocols/hybrid_min.py

@@ -0,0 +1,17 @@
+"""Minimal hybrid handoff protocol."""
+
+from __future__ import annotations
+
+from handoffkit.handoff import HandoffState
+
+
+def build_state(task: str, from_agent: str, to_agent: str, summary: str) -> HandoffState:
+    """Build a minimal structured handoff state."""
+    return HandoffState(
+        task=task,
+        from_agent=from_agent,
+        to_agent=to_agent,
+        summary=summary,
+        next_steps=[f"{to_agent} should use task and summary as the minimal state contract."],
+        metadata={"mode": "hybrid_min", "fields": ["task", "summary", "next_steps"]},
+    )

handoffkit/protocols/hybrid_state.py

@@ -0,0 +1,52 @@
+"""Full structured state handoff protocol."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from handoffkit.handoff import HandoffState
+
+
+def build_state(
+    task: str,
+    from_agent: str,
+    to_agent: str,
+    summary: str,
+    *,
+    decisions: list[str] | None = None,
+    important_files: list[str] | None = None,
+    errors: list[str] | None = None,
+    next_steps: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> HandoffState:
+    """Build a full structured handoff state."""
+    merged_metadata = {
+        "mode": "hybrid_state",
+        "handoff_version": "1.0",
+        "state_contract": [
+            "task",
+            "from_agent",
+            "to_agent",
+            "summary",
+            "decisions",
+            "important_files",
+            "errors",
+            "next_steps",
+            "metadata",
+        ],
+    }
+    merged_metadata.update(metadata or {})
+    return HandoffState(
+        task=task,
+        from_agent=from_agent,
+        to_agent=to_agent,
+        summary=summary,
+        decisions=decisions or [f"{from_agent} completed its current role output."],
+        important_files=important_files or [],
+        errors=errors or [],
+        next_steps=next_steps or [
+            f"{to_agent} should inspect the structured handoff.",
+            "Continue the task while preserving decisions and constraints.",
+        ],
+        metadata=merged_metadata,
+    )

handoffkit/protocols/natural.py

@@ -0,0 +1,22 @@
+"""Natural-language handoff protocol."""
+
+from __future__ import annotations
+
+from handoffkit.handoff import HandoffState
+
+
+def build_state(task: str, from_agent: str, to_agent: str, summary: str) -> HandoffState:
+    """Build a natural-language handoff state."""
+    natural_summary = (
+        f"{from_agent} is handing off to {to_agent}. "
+        f"The original task is: {task}. "
+        f"Progress summary: {summary}"
+    )
+    return HandoffState(
+        task=task,
+        from_agent=from_agent,
+        to_agent=to_agent,
+        summary=natural_summary,
+        next_steps=[f"{to_agent} should continue from the summary and preserve task intent."],
+        metadata={"mode": "natural", "format": "human_readable"},
+    )

handoffkit/providers/__init__.py

@@ -0,0 +1,21 @@
+"""Provider exports."""
+
+from handoffkit.providers.base import BaseProvider
+from handoffkit.providers.echo_provider import EchoProvider
+from handoffkit.providers.ollama_provider import OllamaProvider
+from handoffkit.providers.openai_compatible import (
+    ModelSelectionResult,
+    choose_openai_compatible_model,
+    list_openai_compatible_models,
+)
+from handoffkit.providers.openai_provider import OpenAIProvider
+
+__all__ = [
+    "BaseProvider",
+    "EchoProvider",
+    "ModelSelectionResult",
+    "OllamaProvider",
+    "OpenAIProvider",
+    "choose_openai_compatible_model",
+    "list_openai_compatible_models",
+]

handoffkit/providers/base.py

@@ -0,0 +1,16 @@
+"""Provider interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseProvider(ABC):
+    """Base class for text generation providers."""
+
+    model: str
+
+    @abstractmethod
+    def generate(self, prompt: str, **kwargs: Any) -> str:
+        """Generate a response for a prompt."""

handoffkit/providers/echo_provider.py

@@ -0,0 +1,26 @@
+"""Local provider that returns deterministic useful text."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from handoffkit.providers.base import BaseProvider
+
+
+class EchoProvider(BaseProvider):
+    """Provider for local tests and demos without external APIs."""
+
+    def __init__(self, model: str = "echo") -> None:
+        self.model = model
+
+    def generate(self, prompt: str, **kwargs: Any) -> str:
+        """Return a deterministic response summarizing the prompt."""
+        preview = " ".join(prompt.strip().split())
+        if len(preview) > 420:
+            preview = preview[:417].rstrip() + "..."
+        return (
+            f"EchoProvider[{self.model}] response\n"
+            f"Summary: {preview}\n"
+            "Decisions: keep state explicit, preserve constraints, continue with next step.\n"
+            "Next steps: inspect the handoff state, act on the task, report errors."
+        )

handoffkit/providers/ollama_provider.py

@@ -0,0 +1,48 @@
+"""Ollama local HTTP provider."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from handoffkit.errors import ProviderExecutionError
+from handoffkit.providers.base import BaseProvider
+
+
+class OllamaProvider(BaseProvider):
+    """Provider for a local Ollama server."""
+
+    def __init__(
+        self,
+        model: str = "llama3.1",
+        *,
+        base_url: str = "http://localhost:11434",
+        timeout: float = 60.0,
+    ) -> None:
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def generate(self, prompt: str, **kwargs: Any) -> str:
+        """Generate text using Ollama's `/api/generate` endpoint."""
+        payload = {
+            "model": kwargs.pop("model", self.model),
+            "prompt": prompt,
+            "stream": False,
+            **kwargs,
+        }
+        data = json.dumps(payload).encode("utf-8")
+        request = urllib.request.Request(
+            f"{self.base_url}/api/generate",
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                body = json.loads(response.read().decode("utf-8"))
+        except urllib.error.URLError as exc:
+            raise ProviderExecutionError(f"Ollama request failed: {exc}") from exc
+        return str(body.get("response", ""))