handoffkit 0.2.0__py3-none-any.whl

handoffkit/providers/openai_compatible.py

@@ -0,0 +1,140 @@
+"""Helpers for OpenAI-compatible providers."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any
+
+from handoffkit.errors import ProviderConfigurationError, ProviderExecutionError
+from handoffkit.providers.openai_provider import (
+    DEFAULT_OPENAI_BASE_URL,
+    DEFAULT_OPENAI_MODEL,
+    OpenAIProvider,
+)
+
+DEFAULT_MODEL_CANDIDATES = ("gpt-5.4", DEFAULT_OPENAI_MODEL)
+
+
+@dataclass
+class ModelSelectionResult:
+    """Result returned by OpenAI-compatible model selection."""
+
+    model: str
+    base_url: str
+    models_endpoint_ok: bool
+    available_models: list[str] = field(default_factory=list)
+    attempted_models: list[str] = field(default_factory=list)
+    errors: dict[str, str] = field(default_factory=dict)
+
+
+def list_openai_compatible_models(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    timeout: float = 20.0,
+) -> list[str]:
+    """Return model ids from an OpenAI-compatible `/models` endpoint."""
+    resolved_api_key = api_key or os.getenv("OPENAI_API_KEY")
+    if not resolved_api_key:
+        raise ProviderConfigurationError("OPENAI_API_KEY is required to list models.")
+    configured_base_url = base_url or os.getenv("OPENAI_BASE_URL") or DEFAULT_OPENAI_BASE_URL
+    resolved_base_url = configured_base_url.rstrip("/")
+    request = urllib.request.Request(
+        f"{resolved_base_url}/models",
+        headers={"Authorization": f"Bearer {resolved_api_key}"},
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace").replace(
+            resolved_api_key, "[redacted-api-key]"
+        )
+        raise ProviderExecutionError(
+            f"OpenAI-compatible models request failed with HTTP {exc.code}: {detail}"
+        ) from exc
+    except urllib.error.URLError as exc:
+        raise ProviderExecutionError(
+            f"OpenAI-compatible models request failed for {resolved_base_url}: {exc.reason}"
+        ) from exc
+
+    raw_items: Any = body.get("data", body if isinstance(body, list) else [])
+    models: list[str] = []
+    for item in raw_items:
+        if isinstance(item, dict) and isinstance(item.get("id"), str):
+            models.append(item["id"])
+        elif isinstance(item, str):
+            models.append(item)
+    return sorted(set(models))
+
+
+def choose_openai_compatible_model(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    model: str | None = None,
+    fallback_models: tuple[str, ...] = DEFAULT_MODEL_CANDIDATES,
+    timeout: float = 30.0,
+) -> ModelSelectionResult:
+    """Choose the first working model for an OpenAI-compatible endpoint."""
+    resolved_api_key = api_key or os.getenv("OPENAI_API_KEY")
+    if not resolved_api_key:
+        raise ProviderConfigurationError("OPENAI_API_KEY is required to choose a model.")
+    configured_base_url = base_url or os.getenv("OPENAI_BASE_URL") or DEFAULT_OPENAI_BASE_URL
+    resolved_base_url = configured_base_url.rstrip("/")
+    env_model = model or os.getenv("OPENAI_MODEL")
+    candidates = [env_model] if env_model else list(fallback_models)
+    result = ModelSelectionResult(
+        model="",
+        base_url=resolved_base_url,
+        models_endpoint_ok=False,
+        attempted_models=[],
+    )
+
+    try:
+        result.available_models = list_openai_compatible_models(
+            api_key=resolved_api_key,
+            base_url=resolved_base_url,
+            timeout=timeout,
+        )
+        result.models_endpoint_ok = True
+    except ProviderExecutionError as exc:
+        result.errors["/models"] = str(exc)
+
+    for candidate in candidates:
+        if not candidate:
+            continue
+        if result.available_models and candidate not in result.available_models:
+            result.errors[candidate] = "Model not listed by /models endpoint."
+            continue
+        result.attempted_models.append(candidate)
+        provider = OpenAIProvider(
+            api_key=resolved_api_key,
+            base_url=resolved_base_url,
+            model=candidate,
+            timeout=timeout,
+        )
+        try:
+            response = provider.generate(
+                "Reply with exactly: OK",
+                max_tokens=8,
+                temperature=0,
+            )
+        except ProviderExecutionError as exc:
+            result.errors[candidate] = str(exc)
+            continue
+        if response.strip():
+            result.model = candidate
+            return result
+        result.errors[candidate] = "Model returned an empty response."
+
+    attempted = ", ".join(candidates)
+    raise ProviderExecutionError(
+        f"No OpenAI-compatible model succeeded for {resolved_base_url}. "
+        f"Candidates: {attempted}. Errors: {result.errors}"
+    )

handoffkit/providers/openai_provider.py

@@ -0,0 +1,80 @@
+"""Minimal OpenAI-compatible HTTP provider."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any
+
+from handoffkit.errors import ProviderConfigurationError, ProviderExecutionError
+from handoffkit.providers.base import BaseProvider
+
+DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1"
+DEFAULT_OPENAI_MODEL = "gpt-4o-mini"
+
+
+class OpenAIProvider(BaseProvider):
+    """Provider that calls OpenAI or an OpenAI-compatible API."""
+
+    def __init__(
+        self,
+        model: str | None = None,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self.model = model or os.getenv("OPENAI_MODEL") or DEFAULT_OPENAI_MODEL
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
+        configured_base_url = base_url or os.getenv("OPENAI_BASE_URL") or DEFAULT_OPENAI_BASE_URL
+        self.base_url = configured_base_url.rstrip("/")
+        self.timeout = timeout
+        if not self.api_key:
+            raise ProviderConfigurationError(
+                "OPENAI_API_KEY is required for OpenAIProvider. "
+                "Set the environment variable or pass api_key explicitly."
+            )
+
+    def generate(self, prompt: str, **kwargs: Any) -> str:
+        """Generate text using OpenAI chat completions."""
+        payload = {
+            "model": kwargs.pop("model", self.model),
+            "messages": [{"role": "user", "content": prompt}],
+            **kwargs,
+        }
+        data = json.dumps(payload).encode("utf-8")
+        request = urllib.request.Request(
+            f"{self.base_url}/chat/completions",
+            data=data,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "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.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")
+            raise ProviderExecutionError(
+                f"OpenAI-compatible request failed with HTTP {exc.code}: "
+                f"{self._sanitize_error_detail(detail)}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise ProviderExecutionError(
+                f"OpenAI-compatible request failed for {self.base_url}: {exc.reason}"
+            ) from exc
+        choices = body.get("choices") or []
+        if not choices:
+            return ""
+        message = choices[0].get("message") or {}
+        return str(message.get("content", ""))
+
+    def _sanitize_error_detail(self, detail: str) -> str:
+        """Return provider error text without leaking the configured API key."""
+        if not self.api_key:
+            return detail
+        return detail.replace(self.api_key, "[redacted-api-key]")

handoffkit/py.typed

@@ -0,0 +1 @@
+

handoffkit/runner.py

@@ -0,0 +1,51 @@
+"""Team runner."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from handoffkit.agent import Agent
+from handoffkit.protocol import HandoffProtocol
+from handoffkit.schemas import AgentOutput, TeamRunResult
+
+
+class Team:
+    """Sequential multi-agent team runner."""
+
+    def __init__(
+        self,
+        agents: Sequence[Agent],
+        *,
+        protocol: HandoffProtocol | None = None,
+    ) -> None:
+        if not agents:
+            raise ValueError("Team requires at least one agent.")
+        self.agents = list(agents)
+        self.protocol = protocol or HandoffProtocol(mode="hybrid_state")
+
+    def run(self, task: str) -> TeamRunResult:
+        """Run the task through all agents in sequence."""
+        outputs: list[AgentOutput] = []
+        handoffs = []
+
+        first = self.agents[0]
+        current_output = first.run(task)
+        outputs.append(AgentOutput(agent=first.name, output=current_output))
+
+        for previous, current in zip(self.agents, self.agents[1:], strict=False):
+            handoff = self.protocol.transfer(
+                from_agent=previous,
+                to_agent=current,
+                task=task,
+                summary=current_output,
+            )
+            handoffs.append(handoff)
+            current_output = current.run(task, handoff_state=handoff)
+            outputs.append(AgentOutput(agent=current.name, output=current_output))
+
+        return TeamRunResult(
+            task=task,
+            final_output=current_output,
+            agent_outputs=outputs,
+            handoffs=handoffs,
+        )

handoffkit/schemas.py

@@ -0,0 +1,45 @@
+"""Shared schema helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+ProtocolMode = Literal["natural", "compressed", "hybrid_min", "hybrid_state"]
+
+
+@dataclass
+class AgentOutput:
+    """Output produced by a named agent."""
+
+    agent: str
+    output: str
+
+    def to_dict(self) -> dict[str, str]:
+        """Return a dictionary representation."""
+        return {"agent": self.agent, "output": self.output}
+
+
+@dataclass
+class TeamRunResult:
+    """Result returned by Team.run."""
+
+    task: str
+    final_output: str
+    agent_outputs: list[AgentOutput]
+    handoffs: list[Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-friendly result."""
+        return {
+            "task": self.task,
+            "final_output": self.final_output,
+            "agent_outputs": [output.to_dict() for output in self.agent_outputs],
+            "handoffs": [
+                handoff.to_dict() if hasattr(handoff, "to_dict") else handoff
+                for handoff in self.handoffs
+            ],
+        }
+
+    def __str__(self) -> str:
+        return self.final_output

handoffkit/tool.py

@@ -0,0 +1,196 @@
+"""Tool decorator and metadata model."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar, get_args, get_origin, get_type_hints
+
+from handoffkit.errors import ToolExecutionError
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _type_name(value: Any) -> str:
+    """Return a readable name for a type annotation."""
+    if value is inspect.Signature.empty:
+        return "Any"
+    if hasattr(value, "__name__"):
+        return value.__name__
+    return str(value).replace("typing.", "")
+
+
+def _json_schema_type(value: Any) -> str:
+    """Map a Python annotation to a simple JSON schema type."""
+    if value is inspect.Signature.empty or value is Any:
+        return "string"
+
+    origin = get_origin(value)
+    target = origin or value
+    if target is str:
+        return "string"
+    if target is int:
+        return "integer"
+    if target is float:
+        return "number"
+    if target is bool:
+        return "boolean"
+    if target is list:
+        return "array"
+    if target is dict:
+        return "object"
+    return "string"
+
+
+def _json_schema_for_annotation(value: Any) -> dict[str, Any]:
+    """Return a compact JSON-schema-like object for one annotation."""
+    schema: dict[str, Any] = {"type": _json_schema_type(value)}
+    origin = get_origin(value)
+    args = get_args(value)
+    if (origin is list or value is list) and args:
+        schema["items"] = _json_schema_for_annotation(args[0])
+    if origin is dict and len(args) == 2:
+        schema["additionalProperties"] = _json_schema_for_annotation(args[1])
+    return schema
+
+
+@dataclass(frozen=True)
+class ToolParameter:
+    """Metadata about one tool parameter."""
+
+    name: str
+    annotation: str
+    required: bool
+    default: Any = None
+
+
+class Tool:
+    """Executable wrapper around a Python function."""
+
+    def __init__(
+        self,
+        func: Callable[..., Any],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        if not callable(func):
+            raise TypeError("Tool requires a callable.")
+        functools.update_wrapper(self, func)
+        self.func = func
+        self.name = name or func.__name__
+        self.description = description or inspect.getdoc(func) or ""
+        self.signature = inspect.signature(func)
+        self.type_hints = get_type_hints(func)
+        self.parameters = self._build_parameters()
+        self.return_type = _type_name(
+            self.type_hints.get("return", self.signature.return_annotation)
+        )
+
+    def _build_parameters(self) -> dict[str, ToolParameter]:
+        parameters: dict[str, ToolParameter] = {}
+        for name, parameter in self.signature.parameters.items():
+            annotation = self.type_hints.get(name, parameter.annotation)
+            required = parameter.default is inspect.Signature.empty
+            default = None if required else parameter.default
+            parameters[name] = ToolParameter(
+                name=name,
+                annotation=_type_name(annotation),
+                required=required,
+                default=default,
+            )
+        return parameters
+
+    @property
+    def original_function(self) -> Callable[..., Any]:
+        """Return the wrapped Python function."""
+        return self.func
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize tool metadata to a dictionary."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                name: {
+                    "type": parameter.annotation,
+                    "required": parameter.required,
+                    "default": parameter.default,
+                }
+                for name, parameter in self.parameters.items()
+            },
+            "return_type": self.return_type,
+        }
+
+    def to_schema(self) -> dict[str, Any]:
+        """Return a simple JSON-schema-compatible tool description."""
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+        for name, parameter in self.signature.parameters.items():
+            annotation = self.type_hints.get(name, parameter.annotation)
+            properties[name] = _json_schema_for_annotation(annotation)
+            if parameter.default is inspect.Signature.empty:
+                required.append(name)
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+            },
+        }
+
+    def run(self, **kwargs: Any) -> Any:
+        """Run the wrapped function with keyword arguments."""
+        try:
+            bound = self.signature.bind(**kwargs)
+            bound.apply_defaults()
+            return self.func(*bound.args, **bound.kwargs)
+        except TypeError:
+            raise
+        except Exception as exc:
+            if exc.__class__.__module__.startswith("handoffkit"):
+                raise
+            raise ToolExecutionError(f"Tool {self.name!r} failed: {exc}") from exc
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the tool like the original function."""
+        if args:
+            bound = self.signature.bind(*args, **kwargs)
+            bound.apply_defaults()
+            return self.func(*bound.args, **bound.kwargs)
+        return self.run(**kwargs)
+
+    def __repr__(self) -> str:
+        return f"Tool(name={self.name!r})"
+
+
+def tool(
+    func: F | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Tool | Callable[[F], Tool]:
+    """Convert a function into an executable Tool.
+
+    Can be used as `@tool` or `@tool(name="custom_name")`.
+    """
+
+    def decorator(inner: F) -> Tool:
+        return Tool(inner, name=name, description=description)
+
+    if func is None:
+        return decorator
+    return decorator(func)
+
+
+def ensure_tool(candidate: Tool | Callable[..., Any]) -> Tool:
+    """Return a Tool instance for a Tool or callable."""
+    if isinstance(candidate, Tool):
+        return candidate
+    if callable(candidate):
+        return Tool(candidate)
+    raise TypeError(f"Expected Tool or callable, got {type(candidate).__name__}.")

handoffkit/tools/__init__.py

@@ -0,0 +1,15 @@
+"""Included tools."""
+
+from handoffkit.tools.filesystem import file_exists, list_files, read_file, write_file
+from handoffkit.tools.shell import run_command
+from handoffkit.tools.text import extract_keywords, summarize_text
+
+__all__ = [
+    "extract_keywords",
+    "file_exists",
+    "list_files",
+    "read_file",
+    "run_command",
+    "summarize_text",
+    "write_file",
+]

handoffkit/tools/filesystem.py

@@ -0,0 +1,34 @@
+"""Filesystem tools."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from handoffkit.tool import tool
+
+
+@tool
+def read_file(path: str) -> str:
+    """Read a UTF-8 text file."""
+    return Path(path).read_text(encoding="utf-8")
+
+
+@tool
+def write_file(path: str, content: str) -> str:
+    """Write content to a UTF-8 text file."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8")
+    return str(target)
+
+
+@tool
+def list_files(path: str) -> list[str]:
+    """List files and directories in a directory."""
+    return sorted(str(item) for item in Path(path).iterdir())
+
+
+@tool
+def file_exists(path: str) -> bool:
+    """Return whether a path exists."""
+    return Path(path).exists()

handoffkit/tools/shell.py

@@ -0,0 +1,53 @@
+"""Shell command tool with a small safety policy."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from handoffkit.errors import DangerousCommandError
+from handoffkit.tool import tool
+
+DANGEROUS_PATTERNS = [
+    re.compile(r"\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-rf|-fr)\b", re.IGNORECASE),
+    re.compile(r"\bdel\s+/(s|q)\b", re.IGNORECASE),
+    re.compile(r"\brmdir\s+/(s|q)\b", re.IGNORECASE),
+    re.compile(r"\brd\s+/(s|q)\b", re.IGNORECASE),
+    re.compile(r"\bformat\b", re.IGNORECASE),
+    re.compile(r"\bshutdown\b", re.IGNORECASE),
+    re.compile(r"\breboot\b", re.IGNORECASE),
+    re.compile(r"\bmkfs(\.[a-z0-9]+)?\b", re.IGNORECASE),
+    re.compile(r"\bdiskpart\b", re.IGNORECASE),
+    re.compile(r"\bRemove-Item\b.*\b-Recurse\b", re.IGNORECASE),
+]
+
+
+def _assert_safe(command: str) -> None:
+    normalized = " ".join(command.strip().split())
+    for pattern in DANGEROUS_PATTERNS:
+        if pattern.search(normalized):
+            raise DangerousCommandError(f"Blocked dangerous command: {command}")
+
+
+@tool
+def run_command(command: str, cwd: str | None = None) -> dict[str, Any]:
+    """Run a shell command and return command, cwd, return code, stdout, and stderr."""
+    _assert_safe(command)
+    working_dir = str(Path(cwd).resolve()) if cwd else None
+    completed = subprocess.run(
+        command,
+        cwd=working_dir,
+        shell=True,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    return {
+        "command": command,
+        "cwd": working_dir,
+        "returncode": completed.returncode,
+        "stdout": completed.stdout,
+        "stderr": completed.stderr,
+    }

handoffkit/tools/text.py

@@ -0,0 +1,54 @@
+"""Small text tools."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+
+from handoffkit.tool import tool
+
+STOPWORDS = {
+    "a",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "be",
+    "by",
+    "for",
+    "from",
+    "in",
+    "is",
+    "it",
+    "of",
+    "on",
+    "or",
+    "that",
+    "the",
+    "to",
+    "with",
+}
+
+
+@tool
+def summarize_text(text: str, max_chars: int = 500) -> str:
+    """Return a compact character-limited summary."""
+    clean = " ".join(text.strip().split())
+    if len(clean) <= max_chars:
+        return clean
+    if max_chars <= 3:
+        return clean[:max_chars]
+    return clean[: max_chars - 3].rstrip() + "..."
+
+
+@tool
+def extract_keywords(text: str) -> list[str]:
+    """Extract simple frequency-based keywords."""
+    words = [
+        word.lower()
+        for word in re.findall(r"[A-Za-z][A-Za-z0-9_+-]{2,}", text)
+        if word.lower() not in STOPWORDS
+    ]
+    counts = Counter(words)
+    return [word for word, _ in counts.most_common(10)]