base-agentkit 0.1.0__py3-none-any.whl

agentkit/tools/base.py

@@ -0,0 +1,139 @@
+"""Tool abstractions."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+from agentkit.errors import ToolError, WorkspaceError
+from agentkit.tools.types import ToolInvocation, ToolModelError
+
+ModelSuccessFormatter = Callable[[Any, ToolInvocation], Any]
+ModelErrorFormatter = Callable[[Exception, ToolInvocation], Any]
+
+
+class Tool(ABC):
+    """Abstract base class for agent tools."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+
+    def schema(self) -> dict[str, Any]:
+        """Return this tool's model-facing function schema.
+
+        Returns:
+            dict[str, Any]: JSON-schema style tool descriptor.
+        """
+        return {
+            "type": "function",
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.parameters,
+        }
+
+    @abstractmethod
+    def run(self, arguments: dict[str, Any]) -> Any:
+        """Execute the tool with validated arguments.
+
+        Args:
+            arguments: Already validated tool arguments.
+
+        Returns:
+            Any: Tool-specific output payload.
+
+        Raises:
+            Exception: Implementations may raise when execution fails.
+        """
+
+    def format_output_for_model(
+        self, output: Any, invocation: ToolInvocation
+    ) -> Any:
+        """Render a successful tool result into a model-facing payload."""
+        del invocation
+        return {"output": output}
+
+    def format_error_for_model(
+        self, error: Exception, invocation: ToolInvocation
+    ) -> Any:
+        """Render a failed tool result into a model-facing payload."""
+        del invocation
+        if isinstance(error, ToolModelError):
+            return error.to_model_payload()
+        if isinstance(error, (ToolError, WorkspaceError)):
+            return {
+                "error": {
+                    "code": "tool_use_failed",
+                    "message": str(error),
+                }
+            }
+        return {
+            "error": {
+                "code": "tool_execution_failed",
+                "message": f"The tool '{self.name}' failed unexpectedly.",
+                "hint": "Review the arguments and retry. If the issue persists, inspect the run log.",
+            }
+        }
+
+
+class FunctionTool(Tool):
+    """Simple tool wrapper backed by a Python callable."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        parameters: dict[str, Any],
+        handler: Callable[[dict[str, Any]], Any],
+        success_formatter: ModelSuccessFormatter | None = None,
+        error_formatter: ModelErrorFormatter | None = None,
+    ) -> None:
+        """Create a callable-backed tool implementation.
+
+        Args:
+            name: Stable tool name shown to the model.
+            description: Human-readable tool description.
+            parameters: JSON-schema argument definition.
+            handler: Callable that executes tool logic.
+            success_formatter: Optional hook that converts successful tool output
+                into the model-facing payload stored in conversation history.
+            error_formatter: Optional hook that converts an exception into the
+                model-facing payload stored in conversation history.
+
+        Returns:
+            None
+        """
+        self.name = name
+        self.description = description
+        self.parameters = parameters
+        self._handler = handler
+        self._success_formatter = success_formatter
+        self._error_formatter = error_formatter
+
+    def run(self, arguments: dict[str, Any]) -> Any:
+        """Delegate execution to the wrapped handler.
+
+        Args:
+            arguments: Validated tool arguments.
+
+        Returns:
+            Any: Value returned by the wrapped handler.
+        """
+        return self._handler(arguments)
+
+    def format_output_for_model(
+        self, output: Any, invocation: ToolInvocation
+    ) -> Any:
+        """Delegate successful model formatting to the custom formatter when set."""
+        if self._success_formatter is not None:
+            return self._success_formatter(output, invocation)
+        return super().format_output_for_model(output, invocation)
+
+    def format_error_for_model(
+        self, error: Exception, invocation: ToolInvocation
+    ) -> Any:
+        """Delegate error formatting to the custom formatter when set."""
+        if self._error_formatter is not None:
+            return self._error_formatter(error, invocation)
+        return super().format_error_for_model(error, invocation)

agentkit/tools/library/__init__.py

@@ -0,0 +1,8 @@
+"""Concrete tool modules.
+
+Developers can add new files under this directory and expose tools using one of:
+
+- ``build_tools(fs)`` function returning ``Tool`` or ``Iterable[Tool]``
+- ``TOOLS`` module variable containing ``Tool`` or ``Iterable[Tool]``
+"""
+

agentkit/tools/library/_fs_common.py

@@ -0,0 +1,330 @@
+"""Shared helpers for workspace-scoped filesystem tools."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from agentkit.errors import ToolError, WorkspaceError
+from agentkit.tools.types import ToolInvocation, ToolModelError
+from agentkit.workspace.fs import WorkspaceFS
+
+_MAX_VIEW_DEPTH = 2
+_BINARY_CHECK_SIZE = 8192
+_ALLOWED_TEXT_CONTROL_BYTES = {9, 10, 12, 13}
+_SKIP_NAMES: frozenset[str] = frozenset({"node_modules", "__pycache__"})
+_COUNTED_CJK_IDEOGRAPH_RANGES: tuple[tuple[int, int], ...] = (
+    (0x3400, 0x4DBF),
+    (0x4E00, 0x9FFF),
+    (0xF900, 0xFAFF),
+    (0x20000, 0x2A6DF),
+    (0x2A700, 0x2B73F),
+    (0x2B740, 0x2B81F),
+    (0x2B820, 0x2CEAF),
+    (0x2CEB0, 0x2EBEF),
+    (0x2F800, 0x2FA1F),
+)
+_COUNTED_CJK_PUNCTUATION_RANGES: tuple[tuple[int, int], ...] = (
+    (0x3000, 0x303F),
+    (0xFE30, 0xFE4F),
+    (0xFF01, 0xFF0F),
+    (0xFF1A, 0xFF20),
+    (0xFF3B, 0xFF40),
+    (0xFF5B, 0xFF65),
+)
+_EXCLUDED_PLATFORM_COUNT_RANGES: tuple[tuple[int, int], ...] = (
+    (0x1100, 0x11FF),
+    (0x3040, 0x309F),
+    (0x30A0, 0x30FF),
+    (0x31F0, 0x31FF),
+    (0xA960, 0xA97F),
+    (0xAC00, 0xD7AF),
+    (0xD7B0, 0xD7FF),
+    (0xFF65, 0xFF9F),
+)
+
+
+def error_payload(
+    code: str,
+    message: str,
+    *,
+    hint: str | None = None,
+    details: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build the canonical structured error payload returned to the model."""
+    error: dict[str, Any] = {
+        "code": code,
+        "message": message,
+    }
+    if hint:
+        error["hint"] = hint
+    if details:
+        error["details"] = dict(details)
+    return {"error": error}
+
+
+def path_details(invocation: ToolInvocation) -> dict[str, Any]:
+    """Extract path context from invocation arguments when it is available."""
+    path = invocation.arguments.get("path") if isinstance(invocation.arguments, dict) else None
+    if isinstance(path, str) and path:
+        return {"path": path}
+    return {}
+
+
+def format_path_workspace_error(
+    error: Exception,
+    invocation: ToolInvocation,
+    *,
+    missing_message: str,
+    missing_hint: str,
+    not_file_message: str | None = None,
+    not_dir_or_file_message: str | None = None,
+) -> dict[str, Any] | None:
+    """Translate common workspace path failures into stable tool error payloads."""
+    if isinstance(error, ToolModelError):
+        return error.to_model_payload()
+    message = str(error)
+    details = path_details(invocation)
+    if message.startswith("Path escapes workspace: "):
+        return error_payload(
+            "path_outside_workspace",
+            "The path must stay inside the workspace.",
+            hint="Use a relative path inside the workspace root.",
+            details=details,
+        )
+    if message.startswith("Path does not exist: ") or message.startswith("File does not exist: "):
+        return error_payload(
+            "path_not_found",
+            missing_message,
+            hint=missing_hint,
+            details=details,
+        )
+    if not_dir_or_file_message and message.startswith("Not a file or directory: "):
+        return error_payload(
+            "invalid_path_kind",
+            not_dir_or_file_message,
+            hint="Choose an existing file or directory path that matches the tool's requirements.",
+            details=details,
+        )
+    if not_file_message and message.startswith("Not a file: "):
+        return error_payload(
+            "not_a_file",
+            not_file_message,
+            hint="Choose an existing file path, not a directory.",
+            details=details,
+        )
+    return None
+
+
+def resolve_existing_file(fs: WorkspaceFS, path: str) -> Path:
+    """Resolve ``path`` and ensure it exists as a regular file."""
+    target = fs.resolve_path(path)
+    if not target.exists():
+        raise WorkspaceError(f"File does not exist: {path}")
+    if not target.is_file():
+        raise WorkspaceError(f"Not a file: {path}")
+    return target
+
+
+def read_utf8_text_for_edit(fs: WorkspaceFS, path: str) -> str:
+    """Read an editable UTF-8 file or raise a workspace-scoped error."""
+    target = resolve_existing_file(fs, path)
+    try:
+        return target.read_bytes().decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise WorkspaceError(f"File is not valid UTF-8 text: {path}") from exc
+
+
+def decode_text_for_view(data: bytes) -> tuple[str, str]:
+    """Decode file bytes for viewing, escaping undecodable bytes when needed."""
+    try:
+        return data.decode("utf-8"), "utf-8"
+    except UnicodeDecodeError:
+        return data.decode("utf-8", errors="backslashreplace"), "utf-8/backslashreplace"
+
+
+def normalize_view_range(view_range: Any, total_lines: int) -> tuple[int, int]:
+    """Validate and normalize a 1-based inclusive file line range."""
+    if view_range is None:
+        if total_lines == 0:
+            return 1, 0
+        return 1, total_lines
+    if not isinstance(view_range, (list, tuple)) or len(view_range) != 2:
+        raise ToolError("view_range must be a two-item array: [start_line, end_line].")
+    start_line, end_line = view_range
+    if not isinstance(start_line, int) or not isinstance(end_line, int):
+        raise ToolError("view_range values must both be integers.")
+    if start_line < 1:
+        raise ToolError("start_line must be >= 1.")
+    if end_line < -1:
+        raise ToolError("end_line must be -1 or >= start_line.")
+    if total_lines == 0:
+        raise WorkspaceError("Cannot apply view_range to an empty file.")
+    if start_line > total_lines:
+        raise WorkspaceError(
+            f"start_line {start_line} is beyond the end of file ({total_lines} lines)."
+        )
+    if end_line == -1 or end_line > total_lines:
+        end_line = total_lines
+    if end_line < start_line:
+        raise WorkspaceError(
+            f"end_line {end_line} must be -1 or >= start_line {start_line}."
+        )
+    return start_line, end_line
+
+
+def split_lines(text: str) -> list[str]:
+    """Split text into logical lines without inventing a trailing empty line."""
+    return text.splitlines() if text else []
+
+
+def format_numbered_lines(
+    lines: list[str], *, start_line: int, total_lines: int | None = None
+) -> str:
+    """Prefix lines with right-aligned 1-based line numbers."""
+    if not lines:
+        return ""
+
+    last_line_number = start_line + len(lines) - 1
+    max_line_number = (
+        max(total_lines, last_line_number, 1)
+        if total_lines is not None
+        else max(last_line_number, 1)
+    )
+    number_width = len(str(max_line_number))
+    return "\n".join(
+        f"{line_number:>{number_width}}: {line}"
+        for line_number, line in enumerate(lines, start=start_line)
+    )
+
+
+def format_human_size(size_bytes: int) -> str:
+    """Format a byte count for compact human-facing output."""
+    if size_bytes < 1024:
+        return f"{size_bytes}B"
+    size = float(size_bytes)
+    for unit in ("KB", "MB", "GB", "TB"):
+        size /= 1024.0
+        if size < 1024 or unit == "TB":
+            return f"{size:.1f}{unit}"
+    return f"{size_bytes}B"
+
+
+def format_count(value: int, singular: str, plural: str | None = None) -> str:
+    """Format a singular/plural count phrase for status messages."""
+    if value == 1:
+        return f"1 {singular}"
+    return f"{value} {plural or singular + 's'}"
+
+
+def list_directory_entries(fs: WorkspaceFS, root: Path) -> list[dict[str, Any]]:
+    """Collect directory entries up to the shared view depth limit."""
+    entries: list[dict[str, Any]] = []
+    _walk_directory(fs, root, root, depth=1, entries=entries)
+    return sorted(entries, key=lambda entry: str(entry["path"]))
+
+
+def _walk_directory(
+    fs: WorkspaceFS,
+    root: Path,
+    current: Path,
+    *,
+    depth: int,
+    entries: list[dict[str, Any]],
+) -> None:
+    """Recursively collect workspace-safe directory entries for tree rendering."""
+    if depth > _MAX_VIEW_DEPTH:
+        return
+    for child in sorted(current.iterdir(), key=lambda item: item.name):
+        if _should_skip_name(child.name):
+            continue
+        if not _is_within_workspace(child.resolve(strict=False), fs.root):
+            continue
+        rel_path = child.relative_to(root).as_posix()
+        kind = "directory" if child.is_dir() else "file"
+        entries.append({"path": rel_path, "kind": kind, "depth": depth})
+        if child.is_dir():
+            _walk_directory(fs, root, child, depth=depth + 1, entries=entries)
+
+
+def _should_skip_name(name: str) -> bool:
+    """Return whether a file or directory should be hidden from tool output."""
+    return name.startswith(".") or name in _SKIP_NAMES
+
+
+def _is_within_workspace(path: Path, root: Path) -> bool:
+    """Return whether a resolved path stays under the workspace root."""
+    return path.is_relative_to(root)
+
+
+def is_probably_binary(data: bytes) -> bool:
+    """Heuristically reject binary files before attempting text rendering."""
+    if not data:
+        return False
+    sample = data[:_BINARY_CHECK_SIZE]
+    if b"\x00" in sample:
+        return True
+    disallowed_controls = sum(
+        1 for byte in sample if byte < 32 and byte not in _ALLOWED_TEXT_CONTROL_BYTES
+    )
+    return (disallowed_controls / len(sample)) > 0.05
+
+
+def classify_counted_character(char: str) -> str | None:
+    """Classify a character according to the platform-aligned count heuristic."""
+    if char.isspace():
+        return None
+
+    code_point = ord(char)
+    # Some scripts and punctuation are intentionally excluded because downstream
+    # product metrics do not count them toward the "word_count" surfaced to users.
+    if _is_in_code_point_ranges(code_point, _EXCLUDED_PLATFORM_COUNT_RANGES):
+        return None
+    if 0x21 <= code_point <= 0x7E:
+        return "ascii_visible"
+    if _is_in_code_point_ranges(code_point, _COUNTED_CJK_IDEOGRAPH_RANGES):
+        return "cjk_ideograph"
+    if _is_in_code_point_ranges(code_point, _COUNTED_CJK_PUNCTUATION_RANGES):
+        return "cjk_punctuation"
+    return None
+
+
+def count_text_metrics(text: str) -> dict[str, int]:
+    """Compute the text metrics returned by filesystem-oriented tools."""
+    ascii_visible_char_count = 0
+    cjk_ideograph_count = 0
+    cjk_punctuation_count = 0
+    for char in text:
+        category = classify_counted_character(char)
+        if category == "ascii_visible":
+            ascii_visible_char_count += 1
+        elif category == "cjk_ideograph":
+            cjk_ideograph_count += 1
+        elif category == "cjk_punctuation":
+            cjk_punctuation_count += 1
+    lines = split_lines(text)
+    # The exposed "word_count" matches product expectations rather than natural
+    # language tokenization: ASCII-visible characters and selected CJK code
+    # points count individually, while unsupported scripts are tracked separately.
+    word_count = (
+        ascii_visible_char_count + cjk_ideograph_count + cjk_punctuation_count
+    )
+    non_whitespace_char_count = sum(1 for char in text if not char.isspace())
+    return {
+        "word_count": word_count,
+        "char_count": len(text),
+        "non_whitespace_char_count": non_whitespace_char_count,
+        "line_count": len(lines),
+        "paragraph_count": sum(1 for line in lines if line.strip()),
+        "unsupported_non_whitespace_char_count": non_whitespace_char_count - word_count,
+        "ascii_visible_char_count": ascii_visible_char_count,
+        "cjk_ideograph_count": cjk_ideograph_count,
+        "cjk_punctuation_count": cjk_punctuation_count,
+    }
+
+
+def _is_in_code_point_ranges(
+    code_point: int, ranges: tuple[tuple[int, int], ...]
+) -> bool:
+    """Return whether ``code_point`` falls inside any inclusive range."""
+    return any(start <= code_point <= end for start, end in ranges)

agentkit/tools/library/create_file.py

@@ -0,0 +1,168 @@
+"""create_file tool implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+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_human_size,
+    format_path_workspace_error,
+    path_details,
+)
+
+
+def build_create_file_tool(fs: WorkspaceFS) -> Tool:
+    """Build the workspace-bound ``create_file`` tool."""
+    return FunctionTool(
+        name="create_file",
+        description=(
+            "Create a new file or completely overwrite an existing file with the provided text content.\n"
+            "\n"
+            "USE THIS TOOL WHEN you need to:\n"
+            "- Create a brand-new document: a draft, outline, translation, summary, report, etc.\n"
+            "- Completely rewrite an existing file when the changes are so extensive that making "
+            "individual edits with `str_replace` would be impractical.\n"
+            "\n"
+            "BEHAVIOR:\n"
+            "- Writes the exact content of `file_text` as UTF-8. Parent directories are created automatically.\n"
+            "- If the file already exists, it is FULLY OVERWRITTEN — all previous content is lost.\n"
+            "- Returns file metrics after writing, including line count and platform word count.\n"
+            "\n"
+            "IMPORTANT GUIDELINES:\n"
+            "- PREFER `str_replace` over this tool when only a localized revision is needed. "
+            "Overwriting an entire document to change a few sentences risks introducing unintended changes.\n"
+            "- The content in `file_text` must be COMPLETE and ready to use. "
+            "Do not leave placeholders like '[TODO]' or '[continue here]' unless the user explicitly asks for them.\n"
+            "\n"
+            "LIMITATIONS:\n"
+            "- Only UTF-8 text is supported.\n"
+            "- The path must resolve to a location inside the workspace."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": (
+                        "A short explanation of WHY you are creating or overwriting this file. Be specific. "
+                        "Good: 'Create the first draft of the project proposal based on the outline'. "
+                        "Bad: 'create file'."
+                    ),
+                },
+                "path": {
+                    "type": "string",
+                    "description": (
+                        "Relative path (from workspace root) for the file to create or overwrite. "
+                        "Parent directories will be created if they don't exist. "
+                        "Examples: 'chapters/03.md', 'report-v2.md'."
+                    ),
+                },
+                "file_text": {
+                    "type": "string",
+                    "description": (
+                        "The COMPLETE text content to write into the file. "
+                        "This must be the full desired file content — not a partial fragment or a diff. "
+                        "Include proper formatting, paragraph breaks, and structure as appropriate."
+                    ),
+                },
+            },
+            "required": ["description", "path", "file_text"],
+            "additionalProperties": False,
+        },
+        handler=lambda args: _create_file(fs, args),
+        success_formatter=_format_create_file_output,
+        error_formatter=_format_create_file_error,
+    )
+
+
+def _create_file(fs: WorkspaceFS, args: dict[str, Any]) -> dict[str, Any]:
+    """Create or overwrite a text file and return post-write metrics."""
+    path = args["path"]
+    file_text = args["file_text"]
+    target = fs.resolve_path(path)
+    previous_meta: dict[str, Any] | None = None
+    # Preserve the previous file size/line count so the model can see that an
+    # overwrite replaced existing content rather than creating a new file.
+    if target.exists() and target.is_file():
+        previous_bytes = target.read_bytes()
+        previous_meta = {
+            "line_count": len(previous_bytes.splitlines()) if previous_bytes else 0,
+            "size_bytes": len(previous_bytes),
+        }
+    fs.write_text(path, file_text, overwrite=True)
+    size_bytes = len(file_text.encode("utf-8"))
+    metrics = count_text_metrics(file_text)
+    return {
+        "path": path,
+        "chars_written": len(file_text),
+        "line_count": metrics["line_count"],
+        "word_count": metrics["word_count"],
+        "size_bytes": size_bytes,
+        "operation": "overwritten" if previous_meta is not None else "created",
+        "previous_file": previous_meta,
+    }
+
+
+def _format_create_file_output(output: Any, invocation: ToolInvocation) -> Any:
+    """Render a concise summary of the create or overwrite operation."""
+    del invocation
+    if not isinstance(output, dict):
+        return output
+
+    path = output.get("path")
+    line_count = output.get("line_count")
+    size_bytes = output.get("size_bytes")
+    word_count = output.get("word_count")
+    operation = output.get("operation")
+    previous_file = output.get("previous_file")
+    if not (
+        isinstance(path, str)
+        and isinstance(line_count, int)
+        and isinstance(size_bytes, int)
+        and isinstance(word_count, int)
+        and operation in {"created", "overwritten"}
+    ):
+        return {"output": output}
+
+    prefix = "File created" if operation == "created" else "File overwritten"
+    message = (
+        f"{prefix}: {path} "
+        f"({format_count(line_count, 'line')}, {format_human_size(size_bytes)}, "
+        f"{format_count(word_count, 'word')})"
+    )
+    if operation == "overwritten" and isinstance(previous_file, dict):
+        previous_line_count = previous_file.get("line_count")
+        previous_size_bytes = previous_file.get("size_bytes")
+        if isinstance(previous_line_count, int) and isinstance(
+            previous_size_bytes, int
+        ):
+            message += (
+                "\n"
+                f"Note: Previous file ({format_count(previous_line_count, 'line')}, "
+                f"{format_human_size(previous_size_bytes)}) was replaced."
+            )
+    return message
+
+
+def _format_create_file_error(
+    error: Exception, invocation: ToolInvocation
+) -> dict[str, Any]:
+    """Translate ``create_file`` failures into stable model-facing errors."""
+    common = format_path_workspace_error(
+        error,
+        invocation,
+        missing_message="The target path could not be prepared inside the workspace.",
+        missing_hint="Choose a writable path inside the workspace.",
+    )
+    if common is not None:
+        return common
+    return error_payload(
+        "create_file_failed", str(error), details=path_details(invocation)
+    )

agentkit/tools/library/fs_tools.py

@@ -0,0 +1,21 @@
+"""Workspace-scoped filesystem tool bundle."""
+
+from __future__ import annotations
+
+from agentkit.tools.base import Tool
+from agentkit.workspace.fs import WorkspaceFS
+
+from .create_file import build_create_file_tool
+from .str_replace import build_str_replace_tool
+from .view import build_view_tool
+from .word_count import build_word_count_tool
+
+
+def build_tools(fs: WorkspaceFS) -> list[Tool]:
+    """Create filesystem tools scoped to the workspace."""
+    return [
+        build_view_tool(fs),
+        build_create_file_tool(fs),
+        build_str_replace_tool(fs),
+        build_word_count_tool(fs),
+    ]