base-agentkit 0.1.0__py3-none-any.whl

agentkit/tools/library/word_count.py

@@ -0,0 +1,138 @@
+"""word_count tool implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentkit.errors import WorkspaceError
+from agentkit.tools.base import FunctionTool, Tool
+from agentkit.tools.types import ToolInvocation
+from agentkit.workspace.fs import WorkspaceFS
+
+from ._fs_common import (
+    count_text_metrics,
+    error_payload,
+    format_count,
+    format_path_workspace_error,
+    is_probably_binary,
+    path_details,
+    resolve_existing_file,
+)
+
+
+def build_word_count_tool(fs: WorkspaceFS) -> Tool:
+    """Build the workspace-bound ``word_count`` tool."""
+    return FunctionTool(
+        name="word_count",
+        description=(
+            "Count the number of words and lines in a workspace text file.\n"
+            "\n"
+            "USE THIS TOOL WHEN you need to:\n"
+            "- Verify whether a draft meets a minimum or maximum word count.\n"
+            "- Report text metrics after writing or revising.\n"
+            "\n"
+            "RETURNS:\n"
+            "- `word_count`: number of words.\n"
+            "- `line_count`: the total number of lines in the file.\n"
+            "\n"
+            "LIMITATIONS:\n"
+            "- Only works on text files in the workspace. Binary files are rejected.\n"
+            "- The file must be valid UTF-8."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": (
+                        "A short explanation of WHY you need the word count. Be specific. "
+                        "Good: 'Verify the revised draft meets the 3,000-word target'. "
+                        "Bad: 'count words'."
+                    ),
+                },
+                "path": {
+                    "type": "string",
+                    "description": (
+                        "Relative path (from workspace root) to the text file to count. "
+                        "Must be an existing text file (not a directory, not a binary file). "
+                        "Example: 'draft.md', 'report.md'."
+                    ),
+                },
+            },
+            "required": ["description", "path"],
+            "additionalProperties": False,
+        },
+        handler=lambda args: _word_count(fs, args),
+        success_formatter=_format_word_count_output,
+        error_formatter=_format_word_count_error,
+    )
+
+
+def _word_count(fs: WorkspaceFS, args: dict[str, Any]) -> dict[str, Any]:
+    """Count text metrics for an existing UTF-8 workspace file."""
+    path = args["path"]
+    target = resolve_existing_file(fs, path)
+    data = target.read_bytes()
+    if is_probably_binary(data):
+        raise WorkspaceError(f"Binary file is not supported for word_count: {path}")
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise WorkspaceError(f"File is not valid UTF-8 text: {path}") from exc
+    return {
+        "path": path,
+        **count_text_metrics(text),
+    }
+
+
+def _format_word_count_output(output: Any, invocation: ToolInvocation) -> Any:
+    """Render the human-facing count summary shown back to the model."""
+    del invocation
+    if not isinstance(output, dict):
+        return output
+    path = output.get("path")
+    word_count = output.get("word_count")
+    line_count = output.get("line_count")
+    if (
+        isinstance(path, str)
+        and isinstance(word_count, int)
+        and isinstance(line_count, int)
+    ):
+        return (
+            f"The file {path} has {format_count(word_count, 'word')} "
+            f"across {format_count(line_count, 'line')}."
+        )
+    return {"output": output}
+
+
+def _format_word_count_error(
+    error: Exception, invocation: ToolInvocation
+) -> dict[str, Any]:
+    """Translate ``word_count`` failures into stable model-facing errors."""
+    common = format_path_workspace_error(
+        error,
+        invocation,
+        missing_message="The file to count does not exist in the workspace.",
+        missing_hint="Choose an existing text file path inside the workspace.",
+        not_file_message="word_count only works on files.",
+    )
+    if common is not None:
+        return common
+
+    message = str(error)
+    details = path_details(invocation)
+    if message.startswith("Binary file is not supported for word_count: "):
+        return error_payload(
+            "binary_file",
+            "word_count only works on text files, not binary files.",
+            hint="Choose a text file such as .md, .txt, or another UTF-8 document.",
+            details=details,
+        )
+    if message.startswith("File is not valid UTF-8 text: "):
+        return error_payload(
+            "invalid_text_encoding",
+            "word_count requires valid UTF-8 text for exact counting.",
+            hint="Convert the file to UTF-8 and retry.",
+            details=details,
+        )
+    return error_payload("word_count_failed", message, details=details)

agentkit/tools/loader.py

@@ -0,0 +1,81 @@
+"""Automatic tool loading from the tool library directory."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import pkgutil
+from typing import Any, Iterable
+
+from agentkit.errors import ToolError
+from agentkit.tools.base import Tool
+from agentkit.workspace.fs import WorkspaceFS
+
+TOOLS_LIBRARY_PACKAGE = "agentkit.tools.library"
+
+
+def load_tools_from_library(fs: WorkspaceFS) -> list[Tool]:
+    """Load all tools exposed by modules under ``agentkit.tools.library``.
+
+    Tool modules can expose tools via:
+    - ``build_tools(fs)`` (or ``build_tools()``)
+    - ``TOOLS`` module variable
+
+    Args:
+        fs: Workspace filesystem injected into callable tool factories.
+
+    Returns:
+        list[Tool]: Flattened list of tools from all library modules.
+    """
+    package = importlib.import_module(TOOLS_LIBRARY_PACKAGE)
+    package_path = getattr(package, "__path__", None)
+    if package_path is None:
+        return []
+
+    loaded: list[Tool] = []
+    for module_info in sorted(pkgutil.iter_modules(package_path), key=lambda m: m.name):
+        if module_info.name.startswith("_"):
+            continue
+        module_name = f"{TOOLS_LIBRARY_PACKAGE}.{module_info.name}"
+        module = importlib.import_module(module_name)
+        loaded.extend(_load_from_module(module, fs, module_name=module_name))
+    return loaded
+
+
+def _load_from_module(module: Any, fs: WorkspaceFS, *, module_name: str) -> list[Tool]:
+    """Extract tools from one library module."""
+    if hasattr(module, "build_tools"):
+        return _coerce_to_tools(getattr(module, "build_tools"), fs, module_name)
+    if hasattr(module, "TOOLS"):
+        return _coerce_to_tools(getattr(module, "TOOLS"), fs, module_name)
+    return []
+
+
+def _coerce_to_tools(candidate: Any, fs: WorkspaceFS, module_name: str) -> list[Tool]:
+    """Normalize supported tool declarations into ``list[Tool]``."""
+    if isinstance(candidate, Tool):
+        return [candidate]
+
+    if callable(candidate):
+        built: Any
+        try:
+            signature = inspect.signature(candidate)
+            if len(signature.parameters) == 0:
+                built = candidate()
+            else:
+                built = candidate(fs)
+        except ValueError:
+            built = candidate(fs)
+        return _coerce_to_tools(built, fs, module_name)
+
+    if isinstance(candidate, Iterable) and not isinstance(
+        candidate, (str, bytes, dict)
+    ):
+        tools = list(candidate)
+        if all(isinstance(item, Tool) for item in tools):
+            return tools
+
+    raise ToolError(
+        f"Module '{module_name}' must expose Tool, Iterable[Tool], build_tools(...), or TOOLS."
+    )
+

agentkit/tools/registry.py

@@ -0,0 +1,284 @@
+"""Tool registration, validation, and execution."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Iterable
+
+from agentkit.errors import ToolError
+from agentkit.tools.base import Tool
+from agentkit.tools.types import ToolCallOutcome, ToolInvocation, ToolModelError
+
+_JSON_TYPE_MAP: dict[str, tuple[type, ...]] = {
+    "string": (str,),
+    "number": (int, float),
+    "integer": (int,),
+    "boolean": (bool,),
+    "object": (dict,),
+    "array": (list, tuple),
+}
+
+
+class ToolRegistry:
+    """Store, validate, and execute named tools."""
+
+    def __init__(self) -> None:
+        """Initialize an empty tool registry.
+
+        Returns:
+            None
+        """
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        """Register a single tool by name.
+
+        Args:
+            tool: Tool instance to add.
+
+        Returns:
+            None
+
+        Raises:
+            agentkit.errors.ToolError: If tool name is invalid or duplicated.
+        """
+        if "." in tool.name:
+            raise ToolError(f"Tool name cannot contain '.': {tool.name}")
+        if tool.name in self._tools:
+            raise ToolError(f"Duplicate tool name: {tool.name}")
+        self._tools[tool.name] = tool
+
+    def register_many(self, tools: Iterable[Tool]) -> None:
+        """Register multiple tools.
+
+        Args:
+            tools: Iterable of tools to register.
+
+        Returns:
+            None
+
+        Raises:
+            agentkit.errors.ToolError: If any tool fails validation or duplicates an
+                existing name.
+        """
+        for tool in tools:
+            self.register(tool)
+
+    def get(self, name: str) -> Tool:
+        """Retrieve a registered tool by name.
+
+        Args:
+            name: Tool name.
+
+        Returns:
+            Tool: Registered tool instance.
+
+        Raises:
+            agentkit.errors.ToolError: If the tool is not registered.
+        """
+        tool = self._tools.get(name)
+        if tool is None:
+            raise ToolError(f"Tool not found: {name}")
+        return tool
+
+    def list_names(self) -> list[str]:
+        """Return all registered tool names in sorted order.
+
+        Returns:
+            list[str]: Sorted tool names.
+        """
+        return sorted(self._tools.keys())
+
+    def schemas(self, allowed: Iterable[str] | None = None) -> list[dict[str, Any]]:
+        """Build model-facing schemas for registered tools.
+
+        Args:
+            allowed: Optional iterable of allowed tool names.
+
+        Returns:
+            list[dict[str, Any]]: Tool schema dictionaries.
+        """
+        if allowed is None:
+            names = self.list_names()
+        else:
+            names = [name for name in allowed if name in self._tools]
+        return [self._tools[name].schema() for name in names]
+
+    def execute(self, invocation: ToolInvocation) -> ToolCallOutcome:
+        """Execute a tool and wrap success/failure in ``ToolCallOutcome``.
+
+        Args:
+            invocation: Tool invocation including name, arguments, and optional
+                correlation id.
+
+        Returns:
+            ToolCallOutcome: Outcome including arguments, latency, and errors.
+        """
+        start = time.perf_counter()
+        tool: Tool | None = None
+        try:
+            tool = self.get(invocation.name)
+            self._validate_arguments(tool.parameters, invocation.arguments)
+            output = tool.run(invocation.arguments)
+            duration_ms = (time.perf_counter() - start) * 1000
+            return ToolCallOutcome(
+                call_id=invocation.call_id,
+                name=invocation.name,
+                arguments=self._normalize_arguments(invocation.arguments),
+                output=output,
+                model_payload=self._normalize_model_payload(
+                    tool.format_output_for_model(output, invocation),
+                    fallback={"output": output},
+                ),
+                duration_ms=duration_ms,
+            )
+        except Exception as exc:
+            duration_ms = (time.perf_counter() - start) * 1000
+            return ToolCallOutcome(
+                call_id=invocation.call_id,
+                name=invocation.name,
+                arguments=self._normalize_arguments(invocation.arguments),
+                error=str(exc),
+                model_payload=self._format_error_payload(
+                    exc,
+                    invocation=invocation,
+                    tool=tool,
+                ),
+                duration_ms=duration_ms,
+            )
+
+    def _normalize_arguments(self, arguments: Any) -> dict[str, Any]:
+        """Return a defensive copy of invocation arguments when they are object-like."""
+        if isinstance(arguments, dict):
+            return dict(arguments)
+        return {}
+
+    def _normalize_model_payload(self, payload: Any, *, fallback: Any) -> Any:
+        """Normalize formatter output into a stable payload shape."""
+        if payload is None:
+            return fallback
+        if isinstance(payload, dict):
+            return dict(payload)
+        return payload
+
+    def _format_error_payload(
+        self,
+        exc: Exception,
+        *,
+        invocation: ToolInvocation,
+        tool: Tool | None,
+    ) -> Any:
+        """Build the model-facing error payload for execution or registry failures."""
+        fallback = {
+            "error": {
+                "code": "tool_execution_failed",
+                "message": f"The tool '{invocation.name}' failed unexpectedly.",
+            }
+        }
+        if tool is not None:
+            payload = tool.format_error_for_model(exc, invocation)
+            return self._normalize_model_payload(payload, fallback=fallback)
+        return self._format_registry_error(exc, invocation)
+
+    def _format_registry_error(
+        self, exc: Exception, invocation: ToolInvocation
+    ) -> dict[str, Any]:
+        """Translate registry/validation failures into stable error codes."""
+        if isinstance(exc, ToolModelError):
+            return exc.to_model_payload()
+        if isinstance(exc, ToolError):
+            # Keep these codes stable so providers and downstream tooling can rely on
+            # them without parsing free-form exception strings.
+            message = str(exc)
+            if message.startswith("Tool not found: "):
+                return {
+                    "error": {
+                        "code": "tool_not_found",
+                        "message": f"Tool '{invocation.name}' is not registered.",
+                    }
+                }
+            if message == "Tool arguments must be an object.":
+                return {
+                    "error": {
+                        "code": "invalid_arguments",
+                        "message": "Tool arguments must be a JSON object.",
+                    }
+                }
+            if message.startswith("Missing required argument: "):
+                key = message.removeprefix("Missing required argument: ")
+                return {
+                    "error": {
+                        "code": "missing_argument",
+                        "message": f"Missing required argument '{key}'.",
+                        "hint": f"Call the tool again and include '{key}'.",
+                    }
+                }
+            if message.startswith("Unexpected argument: "):
+                key = message.removeprefix("Unexpected argument: ")
+                return {
+                    "error": {
+                        "code": "unexpected_argument",
+                        "message": f"Argument '{key}' is not accepted by this tool.",
+                    }
+                }
+            if message.startswith("Invalid type for '"):
+                return {
+                    "error": {
+                        "code": "invalid_argument_type",
+                        "message": message,
+                    }
+                }
+            return {
+                "error": {
+                    "code": "tool_invocation_invalid",
+                    "message": message,
+                }
+            }
+        return {
+            "error": {
+                "code": "tool_execution_failed",
+                "message": f"The tool '{invocation.name}' failed unexpectedly.",
+            }
+        }
+
+    def _validate_arguments(
+        self, schema: dict[str, Any], arguments: dict[str, Any]
+    ) -> None:
+        """Validate runtime arguments against a JSON-schema subset.
+
+        Args:
+            schema: Tool parameter schema.
+            arguments: Runtime argument object.
+
+        Returns:
+            None
+
+        Raises:
+            agentkit.errors.ToolError: If required keys are missing, unexpected keys
+                are disallowed, or value types mismatch declared schema types.
+        """
+        if not isinstance(arguments, dict):
+            raise ToolError("Tool arguments must be an object.")
+
+        required = schema.get("required", [])
+        for key in required:
+            if key not in arguments:
+                raise ToolError(f"Missing required argument: {key}")
+
+        properties = schema.get("properties", {})
+        additional_allowed = schema.get("additionalProperties", True)
+
+        for key, value in arguments.items():
+            if key not in properties:
+                if additional_allowed is False:
+                    raise ToolError(f"Unexpected argument: {key}")
+                continue
+
+            expected_type = properties[key].get("type")
+            if expected_type is None:
+                continue
+            py_types = _JSON_TYPE_MAP.get(expected_type)
+            if py_types and not isinstance(value, py_types):
+                raise ToolError(
+                    f"Invalid type for '{key}': expected {expected_type}, got {type(value).__name__}"
+                )

agentkit/tools/types.py

@@ -0,0 +1,98 @@
+"""Tool-related invocation and outcome types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class ToolModelError(Exception):
+    """Tool-defined model-facing error payload.
+
+    Tool authors can raise this directly from custom tools when they want the model
+    to receive a stable, structured error description instead of a raw exception
+    string.
+    """
+
+    code: str
+    message: str
+    hint: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Initialize the underlying ``Exception`` with the human-readable message."""
+        Exception.__init__(self, self.message)
+
+    def __str__(self) -> str:
+        """Return the message so generic exception handling stays readable."""
+        return self.message
+
+    def to_model_payload(self) -> dict[str, Any]:
+        """Serialize the structured error into the canonical model payload shape."""
+        error: dict[str, Any] = {
+            "code": self.code,
+            "message": self.message,
+        }
+        if self.hint:
+            error["hint"] = self.hint
+        if self.details:
+            error["details"] = dict(self.details)
+        return {"error": error}
+
+
+@dataclass(slots=True)
+class ToolInvocation:
+    """Structured request to execute one tool.
+
+    Attributes:
+        name: Tool name.
+        arguments: Parsed argument mapping supplied by the caller.
+        call_id: Optional provider-assigned tool call identifier.
+    """
+
+    name: str
+    arguments: Any
+    call_id: str | None = None
+
+
+@dataclass(slots=True)
+class ToolCallOutcome:
+    """Canonical outcome of a single tool call.
+
+    Attributes:
+        call_id: Optional provider-assigned tool call identifier.
+        name: Tool name.
+        arguments: Validated argument mapping when available.
+        output: Successful output payload.
+        error: Failure message when execution failed.
+        model_payload: Model-facing payload derived from tool-specific success/error
+            formatting hooks.
+        duration_ms: Execution latency in milliseconds.
+    """
+
+    call_id: str | None
+    name: str
+    arguments: dict[str, Any]
+    output: Any = None
+    error: str | None = None
+    model_payload: Any = None
+    duration_ms: float | None = None
+
+    @property
+    def is_error(self) -> bool:
+        """Return ``True`` when the tool finished with an error message."""
+        return self.error is not None
+
+    def to_event_payload(self) -> dict[str, Any]:
+        """Serialize the stable run-event payload for this tool outcome."""
+        return {
+            "call_id": self.call_id,
+            "name": self.name,
+            "is_error": self.is_error,
+            "arguments": dict(self.arguments),
+            "output": self.output,
+            "error": self.error,
+            "model_payload": self.model_payload,
+            "duration_ms": self.duration_ms,
+        }

agentkit/workspace/__init__.py

@@ -0,0 +1,6 @@
+"""Public workspace filesystem exports."""
+
+from .fs import WorkspaceFS
+from .layout import init_workspace_layout
+
+__all__ = ["WorkspaceFS", "init_workspace_layout"]