aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/middleware/backends/protocol.py

@@ -0,0 +1,353 @@
+"""Backend protocol and types for filesystem middleware.
+
+This module defines the BackendProtocol interface and data types
+for filesystem backend implementations. These are self-contained
+definitions that do not depend on external packages like deepagents.
+
+Migration note for deepagents: replace this entire file with:
+    from deepagents.backends.protocol import (
+        BackendProtocol,
+        FileInfo,
+        WriteResult,
+        EditResult,
+        GrepMatch,
+    )
+
+Note: deepagents set_files/get_files are NOT in their protocol - they are
+our extensions for state synchronization. Keep those as extensions.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, TypedDict
+
+
+class FileInfo(TypedDict):
+    """Information about a file in the filesystem.
+
+    Attributes:
+        path: Absolute path to the file.
+        type: File type, either "file" or "directory".
+        size: Size of the file in bytes (optional).
+    """
+
+    path: str
+    type: str  # "file" or "directory"
+    size: int | None
+
+
+class WriteResult:
+    """Result of a write operation.
+
+    Attributes:
+        path: Path that was written.
+        success: Whether the write succeeded.
+        error: Error message if write failed (None if success).
+    """
+
+    def __init__(
+        self,
+        path: str,
+        success: bool = True,
+        error: str | None = None,
+    ) -> None:
+        """Initialize write result.
+
+        Args:
+            path: Path that was written.
+            success: Whether write succeeded. Defaults to True.
+            error: Error message if failed. Defaults to None.
+        """
+        self.path = path
+        self.success = success
+        self.error = error
+
+
+class EditResult:
+    """Result of an edit operation.
+
+    Attributes:
+        path: Path that was edited.
+        occurrences: Number of replacements made.
+        success: Whether the edit succeeded.
+        error: Error message if edit failed (None if success).
+    """
+
+    def __init__(
+        self,
+        path: str,
+        occurrences: int = 0,
+        success: bool = True,
+        error: str | None = None,
+    ) -> None:
+        """Initialize edit result.
+
+        Args:
+            path: Path that was edited.
+            occurrences: Number of replacements. Defaults to 0.
+            success: Whether edit succeeded. Defaults to True.
+            error: Error message if failed. Defaults to None.
+        """
+        self.path = path
+        self.occurrences = occurrences
+        self.success = success
+        self.error = error
+
+
+class GrepMatch:
+    """A match from a grep search.
+
+    Attributes:
+        path: File path where match was found.
+        line_number: Line number of the match (1-indexed).
+        content: The matching line content.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        line_number: int,
+        content: str,
+    ) -> None:
+        """Initialize grep match.
+
+        Args:
+            path: File path where match was found.
+            line_number: Line number (1-indexed).
+            content: The matching line content.
+        """
+        self.path = path
+        self.line_number = line_number
+        self.content = content
+
+
+@dataclass(frozen=True)
+class ExecuteResult:
+    """Result of command execution.
+
+    Attributes:
+        stdout: Standard output from the command.
+        stderr: Standard error from the command.
+        exit_code: Process exit code (0 for success, non-zero for failure).
+        truncated: Whether output was truncated due to size limits.
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int
+    truncated: bool = False
+
+
+class BackendProtocol(Protocol):
+    """Protocol for filesystem backend implementations.
+
+    This protocol defines the interface that all filesystem backends
+    must implement. It provides methods for file operations like
+    reading, writing, editing, and searching.
+
+    Implementations:
+        - InMemoryBackend: Stores files in memory (for testing/single-session)
+        - Future: SandboxBackend for isolated execution
+        - Future: PersistentBackend for cross-session storage
+
+    Example:
+        >>> class MyBackend:
+        ...     def read(self, file_path: str, line_offset: int = 0, limit: int = 2000) -> str:
+        ...         return "file content"
+        ...     # ... implement other methods
+    """
+
+    def ls_info(self, path: str) -> list[FileInfo]:
+        """List files in a directory.
+
+        Args:
+            path: Directory path to list (absolute).
+
+        Returns:
+            List of FileInfo objects for files in the directory.
+
+        Raises:
+            FileNotFoundError: If path does not exist.
+            NotADirectoryError: If path is not a directory.
+        """
+        ...
+
+    def read(
+        self,
+        file_path: str,
+        line_offset: int = 0,
+        limit: int = 2000,
+        *,
+        offset: int | None = None,
+        thread_id: str = "default",
+    ) -> str:
+        """Read a file's contents by lines.
+
+        Args:
+            file_path: Path to the file (absolute).
+            line_offset: Line number to start from (0-indexed). Defaults to 0.
+            limit: Maximum number of lines to read. Defaults to 2000.
+            offset: Deprecated alias for ``line_offset``.
+            thread_id: Optional thread identifier for thread-aware backends.
+
+        Returns:
+            File content as string with line numbers.
+
+        Raises:
+            FileNotFoundError: If file does not exist.
+        """
+        ...
+
+    def read_chars(
+        self,
+        file_path: str,
+        char_offset: int = 0,
+        max_chars: int = 20000,
+    ) -> str:
+        """Read a file's contents by character position.
+
+        Provides character-based pagination for reading large files
+        that may have very long single lines which would exceed API
+        token limits when read using line-based pagination.
+
+        Args:
+            file_path: Path to the file (absolute).
+            char_offset: Character position to start from (0-indexed). Defaults to 0.
+            max_chars: Maximum number of characters to read. Defaults to 20000.
+
+        Returns:
+            File content as string (without line numbers).
+
+        Raises:
+            FileNotFoundError: If file does not exist.
+        """
+        ...
+
+    def read_bytes(self, file_path: str) -> bytes:
+        """Read a file's contents as raw bytes.
+
+        Args:
+            file_path: Path to the file (absolute).
+
+        Returns:
+            File content as raw bytes (no formatting, no line numbers).
+
+        Raises:
+            FileNotFoundError: If file does not exist.
+            IsADirectoryError: If path is a directory.
+        """
+        ...
+
+    def write(self, file_path: str, content: str) -> WriteResult:
+        """Write content to a file.
+
+        Args:
+            file_path: Path where to write (absolute).
+            content: Content to write.
+
+        Returns:
+            WriteResult indicating success/failure.
+        """
+        ...
+
+    def write_bytes(self, file_path: str, content: bytes) -> WriteResult:
+        """Write raw bytes to a file.
+
+        Args:
+            file_path: Path where to write (absolute).
+            content: Raw bytes to write.
+
+        Returns:
+            WriteResult indicating success/failure.
+        """
+        ...
+
+    def edit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        """Edit a file by replacing old_string with new_string.
+
+        Args:
+            file_path: Path to the file (absolute).
+            old_string: String to find and replace.
+            new_string: String to replace with.
+            replace_all: Whether to replace all occurrences. If False,
+                old_string must appear exactly once. Defaults to False.
+
+        Returns:
+            EditResult with replacement count on success, or error message on failure.
+        """
+        ...
+
+    def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
+        """Find files matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern (e.g., "**/*.py", "*.txt").
+            path: Base directory to search from. Defaults to "/".
+
+        Returns:
+            List of FileInfo objects for matching files.
+        """
+        ...
+
+    def grep_raw(
+        self,
+        pattern: str,
+        path: str | None = None,
+    ) -> list[GrepMatch] | str:
+        """Search for text pattern across files.
+
+        Args:
+            pattern: Text pattern to search (literal string, not regex).
+            path: Directory to search in. Defaults to None (search all).
+
+        Returns:
+            List of GrepMatch objects, or error string.
+        """
+        ...
+
+    # State synchronization methods (for middleware integration)
+    def set_files(self, files: dict[str, Any], thread_id: str = "default") -> None:
+        """Load files from state for a specific thread.
+
+        Called by FilesystemMiddleware.before_model to restore files
+        from checkpointed state into the backend.
+
+        Args:
+            files: Dictionary mapping file paths to file data.
+            thread_id: Thread identifier for isolation. Defaults to "default".
+        """
+        ...
+
+    def get_files(self, thread_id: str = "default") -> dict[str, Any]:
+        """Get files for a specific thread.
+
+        Called by FilesystemMiddleware.after_model to save files
+        from backend into state for checkpointing.
+
+        Args:
+            thread_id: Thread identifier for isolation. Defaults to "default".
+
+        Returns:
+            Dictionary mapping file paths to file data.
+        """
+        ...
+
+
+__all__ = [
+    "BackendProtocol",
+    "ExecuteResult",
+    "FileInfo",
+    "WriteResult",
+    "EditResult",
+    "GrepMatch",
+]