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

aip_agents/middleware/backends/__init__.py

@@ -0,0 +1,72 @@
+"""Backend implementations for filesystem middleware.
+
+This package provides backend implementations for filesystem storage,
+including in-memory storage and protocol definitions.
+
+Migration note for deepagents:
+  1. Replace protocol imports with deepagents.backends.protocol
+  2. Replace utils imports with deepagents.backends.utils
+  3. InMemoryBackend can stay or be replaced with StateBackend
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from aip_agents.middleware.backends.in_memory import InMemoryBackend
+from aip_agents.middleware.backends.local_disk import LocalDiskBackend
+from aip_agents.middleware.backends.protocol import (
+    BackendProtocol,
+    EditResult,
+    FileInfo,
+    GrepMatch,
+    WriteResult,
+)
+
+if TYPE_CHECKING:
+    from aip_agents.middleware.backends.sandbox import SandboxBackend
+
+from aip_agents.middleware.backends.utils import (
+    ensure_absolute_path,
+    format_content_with_line_numbers,
+    format_grep_matches,
+    perform_string_replacement,
+    sanitize_tool_call_id,
+    truncate_if_too_long,
+)
+
+__all__ = [
+    "InMemoryBackend",
+    "LocalDiskBackend",
+    "SandboxBackend",
+    "BackendProtocol",
+    "FileInfo",
+    "WriteResult",
+    "EditResult",
+    "GrepMatch",
+    "ensure_absolute_path",
+    "format_content_with_line_numbers",
+    "perform_string_replacement",
+    "format_grep_matches",
+    "truncate_if_too_long",
+    "sanitize_tool_call_id",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "SandboxBackend":
+        try:
+            from aip_agents.middleware.backends.sandbox import (
+                SandboxBackend as SandboxBackendType,
+            )
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(
+                "SandboxBackend requires the E2B optional dependency. Install with: pip install 'aip-agents[local]'"
+            ) from exc
+        return SandboxBackendType
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

aip_agents/middleware/backends/in_memory.py

@@ -0,0 +1,578 @@
+"""In-memory filesystem backend implementation.
+
+This module provides InMemoryBackend, a BackendProtocol implementation
+that stores files in memory with thread-isolated storage.
+
+Migration note for deepagents:
+  1. Import BackendProtocol and types from deepagents.backends.protocol
+  2. Import utility functions from deepagents.backends.utils (same API)
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+import time
+from base64 import b64decode, b64encode
+from typing import Any
+
+from aip_agents.middleware.backends.protocol import (
+    BackendProtocol,
+    EditResult,
+    FileInfo,
+    GrepMatch,
+    WriteResult,
+)
+from aip_agents.middleware.backends.utils import (
+    format_content_with_line_numbers,
+    perform_string_replacement,
+)
+
+__all__ = ["InMemoryBackend"]
+
+_TIMESTAMP_FORMAT = "%Y-%m-%dT%H:%M:%S"
+_BINARY_CONTENT_ENCODING = "base64"
+
+
+class InMemoryBackend(BackendProtocol):
+    """In-memory filesystem backend.
+
+    Explicitly implements BackendProtocol with thread-isolated storage.
+    Stores files in memory per thread_id, making it suitable for
+    agent conversations where each thread needs isolated file storage.
+
+    Thread Safety:
+        All operations are protected by threading.RLock to ensure
+        thread-safe access to the shared storage.
+
+    Attributes:
+        _storage: Dictionary mapping thread_id to {path: FileData}.
+        _storage_lock: RLock protecting concurrent access to _storage.
+
+    Example:
+        >>> backend = InMemoryBackend()
+        >>> files = {"/test.txt": {"content": ["Hello"], "created_at": "2024-01-01", "modified_at": "2024-01-01"}}
+        >>> backend.set_files(files, thread_id="thread-1")
+        >>> retrieved = backend.get_files(thread_id="thread-1")
+        >>> "/test.txt" in retrieved
+        True
+    """
+
+    def __init__(self) -> None:
+        """Initialize with empty storage."""
+        self._storage: dict[str, dict[str, Any]] = {}
+        self._storage_lock = threading.RLock()
+
+    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 FileData.
+            thread_id: Thread identifier for isolation. Defaults to "default".
+
+        Note:
+            Makes a copy of the files dict to prevent external modifications
+            affecting internal storage.
+        """
+        with self._storage_lock:
+            self._storage[thread_id] = {
+                path: self._deserialize_file_data(file_data) for path, file_data in files.items()
+            }
+
+    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 FileData, or empty dict
+            if no files for this thread.
+
+        Note:
+            Returns a copy to prevent external modifications affecting
+            internal storage.
+        """
+        with self._storage_lock:
+            return {
+                path: self._serialize_file_data(file_data)
+                for path, file_data in self._storage.get(thread_id, {}).items()
+            }
+
+    @staticmethod
+    def _serialize_file_data(file_data: Any) -> Any:
+        """Return JSON-safe checkpoint data for one stored file entry."""
+        if not isinstance(file_data, dict):
+            return file_data  # pragma: no cover
+        serialized = file_data.copy()
+        content = serialized.get("content")
+        if isinstance(content, bytes):
+            serialized["content"] = b64encode(content).decode("ascii")
+            serialized["encoding"] = _BINARY_CONTENT_ENCODING
+        return serialized
+
+    @staticmethod
+    def _deserialize_file_data(file_data: Any) -> Any:
+        """Restore one stored file entry from checkpoint data."""
+        if not isinstance(file_data, dict):
+            return file_data  # pragma: no cover
+        restored = file_data.copy()
+        if restored.get("encoding") == _BINARY_CONTENT_ENCODING and isinstance(restored.get("content"), str):
+            restored["content"] = b64decode(restored["content"])
+            restored.pop("encoding", None)
+            restored["binary"] = True
+        return restored
+
+    def _get_thread_storage(self, thread_id: str = "default") -> dict[str, Any]:
+        """Get or create storage for a thread.
+
+        Args:
+            thread_id: Thread identifier.
+
+        Returns:
+            Storage dictionary for the thread.
+        """
+        with self._storage_lock:
+            if thread_id not in self._storage:
+                self._storage[thread_id] = {}
+            return self._storage[thread_id]
+
+    def _normalize_path(self, path: str) -> str:
+        """Normalize a path to absolute form.
+
+        Args:
+            path: Path to normalize.
+
+        Returns:
+            Normalized absolute path.
+        """
+        if not path.startswith("/"):
+            path = "/" + path
+        # Remove trailing slashes except for root
+        path = path.rstrip("/") or "/"
+        return path
+
+    @staticmethod
+    def _content_to_lines(content: Any) -> list[str]:
+        if isinstance(content, bytes):
+            raise ValueError("Binary content cannot be read as text")  # pragma: no cover
+        if isinstance(content, str):
+            return content.split("\n")  # pragma: no cover
+        return [str(line) for line in content]
+
+    @staticmethod
+    def _is_binary_entry(file_data: Any) -> bool:
+        """Return whether a stored file entry contains byte-backed content."""
+        if not isinstance(file_data, dict):
+            return False  # pragma: no cover
+        return bool(file_data.get("binary")) or isinstance(file_data.get("content"), bytes)
+
+    @staticmethod
+    def _content_to_bytes(content: Any) -> bytes:
+        if isinstance(content, bytes):
+            return content
+        if isinstance(content, str):
+            return content.encode("utf-8")  # pragma: no cover
+        return "\n".join(str(line) for line in content).encode("utf-8")
+
+    def write(
+        self,
+        file_path: str,
+        content: str | list[str],
+        thread_id: str = "default",
+    ) -> WriteResult:
+        """Write content to a file.
+
+        Args:
+            file_path: Path where to write the file.
+            content: Content to write (string or list of strings).
+            thread_id: Thread identifier for isolation. Defaults to "default".
+
+        Returns:
+            WriteResult indicating success.
+        """
+        path = self._normalize_path(file_path)
+        storage = self._get_thread_storage(thread_id)
+
+        # Normalize content to list of strings
+        if isinstance(content, str):
+            lines = content.split("\n")
+        else:
+            lines = list(content)
+
+        now = time.strftime(_TIMESTAMP_FORMAT)
+
+        with self._storage_lock:
+            is_new = path not in storage
+            storage[path] = {
+                "content": lines,
+                "binary": False,
+                "created_at": storage.get(path, {}).get("created_at", now) if not is_new else now,
+                "modified_at": now,
+            }
+
+        return WriteResult(path=path, success=True)
+
+    def write_bytes(
+        self,
+        file_path: str,
+        content: bytes,
+        thread_id: str = "default",
+    ) -> WriteResult:
+        """Write raw bytes to a file."""
+        path = self._normalize_path(file_path)
+        storage = self._get_thread_storage(thread_id)
+        now = time.strftime(_TIMESTAMP_FORMAT)
+
+        with self._storage_lock:
+            is_new = path not in storage
+            storage[path] = {
+                "content": bytes(content),
+                "binary": True,
+                "created_at": storage.get(path, {}).get("created_at", now) if not is_new else now,
+                "modified_at": now,
+            }
+
+        return WriteResult(path=path, success=True)
+
+    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 with line numbers.
+
+        Args:
+            file_path: Path to the file.
+            line_offset: Line number to start reading from (0-indexed).
+            limit: Maximum number of lines to read.
+            thread_id: Thread identifier for isolation. Defaults to "default".
+            offset: Deprecated alias for ``line_offset``.
+
+        Returns:
+            File content formatted with line numbers.
+
+        Raises:
+            FileNotFoundError: If file does not exist.
+        """
+        path = self._normalize_path(file_path)
+        storage = self._get_thread_storage(thread_id)
+
+        if offset is not None:
+            if line_offset != 0 and line_offset != offset:
+                raise ValueError("Conflicting values provided for line_offset and offset")
+            line_offset = offset
+
+        with self._storage_lock:
+            if path not in storage:
+                raise FileNotFoundError(f"File not found: {file_path}")
+
+            file_data = storage[path]
+            if self._is_binary_entry(file_data):
+                raise ValueError(f"File is binary and cannot be read as text: {file_path}")
+            lines = self._content_to_lines(file_data.get("content", []))
+
+            # Apply offset and limit
+            start = max(0, line_offset)
+            end = min(len(lines), start + limit)
+            selected_lines = lines[start:end]
+
+            content = "\n".join(selected_lines)
+            if not content:
+                return ""
+            return format_content_with_line_numbers(content, offset=start)
+
+    def read_bytes(self, file_path: str, thread_id: str = "default") -> bytes:
+        """Read a file's contents as raw bytes.
+
+        Args:
+            file_path: Path to the file.
+            thread_id: Thread identifier for isolation. Defaults to "default".
+
+        Returns:
+            File content as raw bytes (no formatting, no line numbers).
+
+        Raises:
+            FileNotFoundError: If file does not exist.
+            IsADirectoryError: If path is a directory (not supported in memory backend).
+        """
+        path = self._normalize_path(file_path)
+        storage = self._get_thread_storage(thread_id)
+
+        with self._storage_lock:
+            if path not in storage:
+                raise FileNotFoundError(f"File not found: {file_path}")
+
+            file_data = storage[path]
+            return self._content_to_bytes(file_data.get("content", []))
+
+    def read_chars(
+        self,
+        file_path: str,
+        char_offset: int = 0,
+        max_chars: int = 20000,
+        thread_id: str = "default",
+    ) -> str:
+        """Read a file's contents by character position.
+
+        Provides character-based pagination for reading large files
+        that may have very long single lines.
+
+        Args:
+            file_path: Path to the file.
+            char_offset: Character position to start from (0-indexed).
+            max_chars: Maximum number of characters to read.
+            thread_id: Thread identifier for isolation. Defaults to "default".
+
+        Returns:
+            File content without line numbers (raw characters).
+
+        Raises:
+            FileNotFoundError: If file does not exist.
+        """
+        path = self._normalize_path(file_path)
+        storage = self._get_thread_storage(thread_id)
+
+        with self._storage_lock:
+            if path not in storage:
+                raise FileNotFoundError(f"File not found: {file_path}")
+
+            file_data = storage[path]
+            if self._is_binary_entry(file_data):
+                raise ValueError(f"File is binary and cannot be read as text: {file_path}")
+            lines = self._content_to_lines(file_data.get("content", []))
+            full_content = "\n".join(lines)
+
+            # Apply char_offset and max_chars
+            start = max(0, char_offset)
+            if len(full_content) == 0:
+                return ""
+            if start >= len(full_content):
+                return "[End of file reached]"
+            end = min(len(full_content), start + max_chars)
+            selected_content = full_content[start:end]
+
+            return selected_content
+
+    def ls_info(self, path: str, thread_id: str = "default") -> list[FileInfo]:
+        """List files in a directory.
+
+        Args:
+            path: Directory path to list.
+            thread_id: Thread identifier for isolation. Defaults to "default".
+
+        Returns:
+            List of FileInfo objects.
+
+        Raises:
+            FileNotFoundError: If directory does not exist (treats root as always existing).
+        """
+        path = self._normalize_path(path)
+        storage = self._get_thread_storage(thread_id)
+
+        with self._storage_lock:
+            if path == "/":
+                # List all files (we don't have directories, just files)
+                result = []
+                for file_path, file_data in storage.items():
+                    size = len(self._content_to_bytes(file_data.get("content", [])))
+                    result.append(FileInfo(path=file_path, type="file", size=size))
+                return result
+            else:
+                # For non-root, check if any files exist with this prefix
+                prefix = path if path.endswith("/") else path + "/"
+                matching_files = [fp for fp in storage.keys() if fp.startswith(prefix) or fp == path]
+
+                if not matching_files:
+                    raise FileNotFoundError(f"Directory not found: {path}")
+
+                result = []
+                for file_path in matching_files:
+                    file_data = storage[file_path]
+                    size = len(self._content_to_bytes(file_data.get("content", [])))
+                    result.append(FileInfo(path=file_path, type="file", size=size))
+                return result
+
+    def _get_files_to_search(self, storage: dict[str, Any], path: str | None) -> list[str]:
+        """Get list of files to search based on path filter.
+
+        Args:
+            storage: Storage dictionary for the thread.
+            path: Directory to search in, or None for all files.
+
+        Returns:
+            List of file paths to search.
+
+        Raises:
+            FileNotFoundError: If path is specified but directory does not exist.
+        """
+        if path is None or path == "/":
+            return list(storage.keys())
+
+        normalized_path = self._normalize_path(path)
+        prefix = normalized_path if normalized_path.endswith("/") else normalized_path + "/"
+        files_to_search = [fp for fp in storage.keys() if fp.startswith(prefix) or fp == normalized_path]
+
+        if normalized_path != "/" and not files_to_search:
+            raise FileNotFoundError(f"Path not found: {path}")
+
+        return files_to_search
+
+    def _compile_pattern(self, pattern: str) -> re.Pattern[str]:
+        """Compile pattern as regex, falling back to literal if invalid.
+
+        Args:
+            pattern: Pattern to compile.
+
+        Returns:
+            Compiled regex pattern.
+        """
+        try:
+            return re.compile(pattern, re.IGNORECASE)
+        except re.error:
+            return re.compile(re.escape(pattern), re.IGNORECASE)
+
+    def grep(
+        self,
+        pattern: str,
+        path: str | None = None,
+        thread_id: str = "default",
+    ) -> list[GrepMatch]:
+        """Search for text pattern across files.
+
+        Args:
+            pattern: Text pattern to search for (literal string, not regex).
+            path: Directory to search in. Defaults to None (search all).
+            thread_id: Thread identifier for isolation. Defaults to "default".
+
+        Returns:
+            List of GrepMatch objects.
+
+        Raises:
+            FileNotFoundError: If path is specified but directory does not exist.
+        """
+        storage = self._get_thread_storage(thread_id)
+        matches = []
+
+        with self._storage_lock:
+            files_to_search = self._get_files_to_search(storage, path)
+            regex = self._compile_pattern(pattern)
+
+            for file_path in files_to_search:
+                file_data = storage.get(file_path, {})
+                if self._is_binary_entry(file_data):
+                    continue
+                lines = self._content_to_lines(file_data.get("content", []))
+
+                for line_num, line in enumerate(lines, start=1):
+                    if regex.search(line):
+                        matches.append(
+                            GrepMatch(
+                                path=file_path,
+                                line_number=line_num,
+                                content=line,
+                            )
+                        )
+
+        return matches
+
+    # Alias grep_raw to grep for protocol compatibility
+    grep_raw = grep
+
+    def edit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+        thread_id: str = "default",
+    ) -> EditResult:
+        """Edit a file by replacing old_string with new_string.
+
+        Args:
+            file_path: Path to the file to edit.
+            old_string: String to find and replace.
+            new_string: String to replace with.
+            replace_all: If True, replace all occurrences. If False,
+                old_string must appear exactly once. Defaults to False.
+            thread_id: Thread identifier for isolation. Defaults to "default".
+
+        Returns:
+            EditResult with number of replacements.
+
+        Notes:
+            Returns errors via EditResult.error to match deepagents-style tool flow.
+        """
+        path = self._normalize_path(file_path)
+        storage = self._get_thread_storage(thread_id)
+
+        with self._storage_lock:
+            if path not in storage:
+                return EditResult(path=path, error=f"Error: File '{file_path}' not found", success=False)
+
+            file_data = storage[path]
+            if self._is_binary_entry(file_data):
+                return EditResult(
+                    path=path, error=f"Error: '{file_path}' is binary and cannot be edited", success=False
+                )
+            lines = self._content_to_lines(file_data.get("content", []))
+            content = "\n".join(lines)
+
+            replacement = perform_string_replacement(content, old_string, new_string, replace_all)
+            if isinstance(replacement, str):
+                return EditResult(path=path, error=replacement, success=False)
+
+            new_content, occurrences = replacement
+            new_lines = new_content.split("\n")
+
+            # Update file
+            file_data["content"] = new_lines
+            file_data["binary"] = False
+            file_data["modified_at"] = time.strftime(_TIMESTAMP_FORMAT)
+
+            return EditResult(
+                path=path,
+                occurrences=occurrences,
+                success=True,
+            )
+
+    def glob_info(self, pattern: str, path: str = "/", thread_id: str = "default") -> list[FileInfo]:
+        """Find files matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern to match (e.g., "**/*.py").
+            path: Base directory to search from. Defaults to "/".
+            thread_id: Thread identifier for isolation. Defaults to "default".
+
+        Returns:
+            List of FileInfo objects for matching files.
+        """
+        import fnmatch
+
+        storage = self._get_thread_storage(thread_id)
+        matches = []
+
+        # Convert glob pattern to something we can match
+        # Simple implementation: just check if filename matches
+        with self._storage_lock:
+            for file_path, file_data in storage.items():
+                # Check if file matches pattern
+                filename = file_path.split("/")[-1] if "/" in file_path else file_path
+                if fnmatch.fnmatch(filename, pattern) or fnmatch.fnmatch(file_path, pattern):
+                    size = len(self._content_to_bytes(file_data.get("content", [])))
+                    matches.append(FileInfo(path=file_path, type="file", size=size))
+
+        return matches