deepagents 0.2.7__py3-none-any.whl → 0.3.0__py3-none-any.whl

deepagents/backends/protocol.py

@@ -5,14 +5,87 @@ must follow. Backends can store files in different locations (state, filesystem,
 database, etc.) and provide a uniform interface for file operations.
 """
 
+import abc
+import asyncio
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any, Protocol, TypeAlias, TypedDict, runtime_checkable
+from typing import Any, Literal, NotRequired, TypeAlias
 
 from langchain.tools import ToolRuntime
+from typing_extensions import TypedDict
+
+FileOperationError = Literal[
+    "file_not_found",  # Download: file doesn't exist
+    "permission_denied",  # Both: access denied
+    "is_directory",  # Download: tried to download directory as file
+    "invalid_path",  # Both: path syntax malformed (parent dir missing, invalid chars)
+]
+"""Standardized error codes for file upload/download operations.
+
+These represent common, recoverable errors that an LLM can understand and potentially fix:
+- file_not_found: The requested file doesn't exist (download)
+- parent_not_found: The parent directory doesn't exist (upload)
+- permission_denied: Access denied for the operation
+- is_directory: Attempted to download a directory as a file
+- invalid_path: Path syntax is malformed or contains invalid characters
+"""
+
+
+@dataclass
+class FileDownloadResponse:
+    """Result of a single file download operation.
+
+    The response is designed to allow partial success in batch operations.
+    The errors are standardized using FileOperationError literals
+    for certain recoverable conditions for use cases that involve
+    LLMs performing file operations.
+
+    Attributes:
+        path: The file path that was requested. Included for easy correlation
+            when processing batch results, especially useful for error messages.
+        content: File contents as bytes on success, None on failure.
+        error: Standardized error code on failure, None on success.
+            Uses FileOperationError literal for structured, LLM-actionable error reporting.
+
+    Examples:
+        >>> # Success
+        >>> FileDownloadResponse(path="/app/config.json", content=b"{...}", error=None)
+        >>> # Failure
+        >>> FileDownloadResponse(path="/wrong/path.txt", content=None, error="file_not_found")
+    """
+
+    path: str
+    content: bytes | None = None
+    error: FileOperationError | None = None
+
 
+@dataclass
+class FileUploadResponse:
+    """Result of a single file upload operation.
+
+    The response is designed to allow partial success in batch operations.
+    The errors are standardized using FileOperationError literals
+    for certain recoverable conditions for use cases that involve
+    LLMs performing file operations.
+
+    Attributes:
+        path: The file path that was requested. Included for easy correlation
+            when processing batch results and for clear error messages.
+        error: Standardized error code on failure, None on success.
+            Uses FileOperationError literal for structured, LLM-actionable error reporting.
+
+    Examples:
+        >>> # Success
+        >>> FileUploadResponse(path="/app/data.txt", error=None)
+        >>> # Failure
+        >>> FileUploadResponse(path="/readonly/file.txt", error="permission_denied")
+    """
 
-class FileInfo(TypedDict, total=False):
+    path: str
+    error: FileOperationError | None = None
+
+
+class FileInfo(TypedDict):
     """Structured file listing info.
 
     Minimal contract used across backends. Only "path" is required.
@@ -20,9 +93,9 @@ class FileInfo(TypedDict, total=False):
     """
 
     path: str
-    is_dir: bool
-    size: int  # bytes (approx)
-    modified_at: str  # ISO timestamp if known
+    is_dir: NotRequired[bool]
+    size: NotRequired[int]  # bytes (approx)
+    modified_at: NotRequired[str]  # ISO timestamp if known
 
 
 class GrepMatch(TypedDict):
@@ -85,8 +158,7 @@ class EditResult:
     occurrences: int | None = None
 
 
-@runtime_checkable
-class BackendProtocol(Protocol):
+class BackendProtocol(abc.ABC):
     """Protocol for pluggable memory backends (single, unified).
 
     Backends can store files in different locations (state, filesystem, database, etc.)
@@ -94,15 +166,30 @@ class BackendProtocol(Protocol):
 
     All file data is represented as dicts with the following structure:
     {
-        "content": list[str],      # Lines of text content
-        "created_at": str,         # ISO format timestamp
-        "modified_at": str,        # ISO format timestamp
+        "content": list[str], # Lines of text content
+        "created_at": str, # ISO format timestamp
+        "modified_at": str, # ISO format timestamp
     }
     """
 
     def ls_info(self, path: str) -> list["FileInfo"]:
-        """Structured listing with file metadata."""
-        ...
+        """List all files in a directory with metadata.
+
+        Args:
+            path: Absolute path to the directory to list. Must start with '/'.
+
+        Returns:
+            List of FileInfo dicts containing file metadata:
+
+            - `path` (required): Absolute file path
+            - `is_dir` (optional): True if directory
+            - `size` (optional): File size in bytes
+            - `modified_at` (optional): ISO 8601 timestamp
+        """
+
+    async def als_info(self, path: str) -> list["FileInfo"]:
+        """Async version of ls_info."""
+        return await asyncio.to_thread(self.ls_info, path)
 
     def read(
         self,
@@ -110,8 +197,35 @@ class BackendProtocol(Protocol):
         offset: int = 0,
         limit: int = 2000,
     ) -> str:
-        """Read file content with line numbers or an error string."""
-        ...
+        """Read file content with line numbers.
+
+        Args:
+            file_path: Absolute path to the file to read. Must start with '/'.
+            offset: Line number to start reading from (0-indexed). Default: 0.
+            limit: Maximum number of lines to read. Default: 2000.
+
+        Returns:
+            String containing file content formatted with line numbers (cat -n format),
+            starting at line 1. Lines longer than 2000 characters are truncated.
+
+            Returns an error string if the file doesn't exist or can't be read.
+
+        !!! note
+            - Use pagination (offset/limit) for large files to avoid context overflow
+            - First scan: `read(path, limit=100)` to see file structure
+            - Read more: `read(path, offset=100, limit=200)` for next section
+            - ALWAYS read a file before editing it
+            - If file exists but is empty, you'll receive a system reminder warning
+        """
+
+    async def aread(
+        self,
+        file_path: str,
+        offset: int = 0,
+        limit: int = 2000,
+    ) -> str:
+        """Async version of read."""
+        return await asyncio.to_thread(self.read, file_path, offset, limit)
 
     def grep_raw(
         self,
@@ -119,20 +233,94 @@ class BackendProtocol(Protocol):
         path: str | None = None,
         glob: str | None = None,
     ) -> list["GrepMatch"] | str:
-        """Structured search results or error string for invalid input."""
-        ...
+        """Search for a literal text pattern in files.
+
+        Args:
+            pattern: Literal string to search for (NOT regex).
+                     Performs exact substring matching within file content.
+                     Example: "TODO" matches any line containing "TODO"
+
+            path: Optional directory path to search in.
+                  If None, searches in current working directory.
+                  Example: "/workspace/src"
+
+            glob: Optional glob pattern to filter which FILES to search.
+                  Filters by filename/path, not content.
+                  Supports standard glob wildcards:
+                  - `*` matches any characters in filename
+                  - `**` matches any directories recursively
+                  - `?` matches single character
+                  - `[abc]` matches one character from set
+
+        Examples:
+                  - "*.py" - only search Python files
+                  - "**/*.txt" - search all .txt files recursively
+                  - "src/**/*.js" - search JS files under src/
+                  - "test[0-9].txt" - search test0.txt, test1.txt, etc.
+
+        Returns:
+            On success: list[GrepMatch] with structured results containing:
+                - path: Absolute file path
+                - line: Line number (1-indexed)
+                - text: Full line content containing the match
+
+            On error: str with error message (e.g., invalid path, permission denied)
+        """
+
+    async def agrep_raw(
+        self,
+        pattern: str,
+        path: str | None = None,
+        glob: str | None = None,
+    ) -> list["GrepMatch"] | str:
+        """Async version of grep_raw."""
+        return await asyncio.to_thread(self.grep_raw, pattern, path, glob)
 
     def glob_info(self, pattern: str, path: str = "/") -> list["FileInfo"]:
-        """Structured glob matching returning FileInfo dicts."""
-        ...
+        """Find files matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern with wildcards to match file paths.
+                     Supports standard glob syntax:
+                     - `*` matches any characters within a filename/directory
+                     - `**` matches any directories recursively
+                     - `?` matches a single character
+                     - `[abc]` matches one character from set
+
+            path: Base directory to search from. Default: "/" (root).
+                  The pattern is applied relative to this path.
+
+        Returns:
+            list of FileInfo
+        """
+
+    async def aglob_info(self, pattern: str, path: str = "/") -> list["FileInfo"]:
+        """Async version of glob_info."""
+        return await asyncio.to_thread(self.glob_info, pattern, path)
 
     def write(
         self,
         file_path: str,
         content: str,
     ) -> WriteResult:
-        """Create a new file. Returns WriteResult; error populated on failure."""
-        ...
+        """Write content to a new file in the filesystem, error if file exists.
+
+        Args:
+            file_path: Absolute path where the file should be created.
+                       Must start with '/'.
+            content: String content to write to the file.
+
+        Returns:
+            WriteResult
+        """
+
+    async def awrite(
+        self,
+        file_path: str,
+        content: str,
+    ) -> WriteResult:
+        """Async version of write."""
+        return await asyncio.to_thread(self.write, file_path, content)
 
     def edit(
         self,
@@ -141,8 +329,78 @@ class BackendProtocol(Protocol):
         new_string: str,
         replace_all: bool = False,
     ) -> EditResult:
-        """Edit a file by replacing string occurrences. Returns EditResult."""
-        ...
+        """Perform exact string replacements in an existing file.
+
+        Args:
+            file_path: Absolute path to the file to edit. Must start with '/'.
+            old_string: Exact string to search for and replace.
+                       Must match exactly including whitespace and indentation.
+            new_string: String to replace old_string with.
+                       Must be different from old_string.
+            replace_all: If True, replace all occurrences. If False (default),
+                        old_string must be unique in the file or the edit fails.
+
+        Returns:
+            EditResult
+        """
+
+    async def aedit(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False,
+    ) -> EditResult:
+        """Async version of edit."""
+        return await asyncio.to_thread(self.edit, file_path, old_string, new_string, replace_all)
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Upload multiple files to the sandbox.
+
+        This API is designed to allow developers to use it either directly or
+        by exposing it to LLMs via custom tools.
+
+        Args:
+            files: List of (path, content) tuples to upload.
+
+        Returns:
+            List of FileUploadResponse objects, one per input file.
+            Response order matches input order (response[i] for files[i]).
+            Check the error field to determine success/failure per file.
+
+        Examples:
+            ```python
+            responses = sandbox.upload_files(
+                [
+                    ("/app/config.json", b"{...}"),
+                    ("/app/data.txt", b"content"),
+                ]
+            )
+            ```
+        """
+
+    async def aupload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Async version of upload_files."""
+        return await asyncio.to_thread(self.upload_files, files)
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Download multiple files from the sandbox.
+
+        This API is designed to allow developers to use it either directly or
+        by exposing it to LLMs via custom tools.
+
+        Args:
+            paths: List of file paths to download.
+
+        Returns:
+            List of FileDownloadResponse objects, one per input path.
+            Response order matches input order (response[i] for paths[i]).
+            Check the error field to determine success/failure per file.
+        """
+
+    async def adownload_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Async version of download_files."""
+        return await asyncio.to_thread(self.download_files, paths)
 
 
 @dataclass
@@ -162,8 +420,7 @@ class ExecuteResponse:
     """Whether the output was truncated due to backend limitations."""
 
 
-@runtime_checkable
-class SandboxBackendProtocol(BackendProtocol, Protocol):
+class SandboxBackendProtocol(BackendProtocol):
     """Protocol for sandboxed backends with isolated runtime.
 
     Sandboxed backends run in isolated environments (e.g., separate processes,
@@ -184,12 +441,17 @@ class SandboxBackendProtocol(BackendProtocol, Protocol):
         Returns:
             ExecuteResponse with combined output, exit code, optional signal, and truncation flag.
         """
-        ...
+
+    async def aexecute(
+        self,
+        command: str,
+    ) -> ExecuteResponse:
+        """Async version of execute."""
+        return await asyncio.to_thread(self.execute, command)
 
     @property
     def id(self) -> str:
-        """Unique identifier for the sandbox backend."""
-        ...
+        """Unique identifier for the sandbox backend instance."""
 
 
 BackendFactory: TypeAlias = Callable[[ToolRuntime], BackendProtocol]

deepagents/backends/sandbox.py

@@ -9,12 +9,15 @@ from __future__ import annotations
 
 import base64
 import json
+import shlex
 from abc import ABC, abstractmethod
 
 from deepagents.backends.protocol import (
     EditResult,
     ExecuteResponse,
+    FileDownloadResponse,
     FileInfo,
+    FileUploadResponse,
     GrepMatch,
     SandboxBackendProtocol,
     WriteResult,
@@ -270,10 +273,10 @@ except PermissionError:
         glob: str | None = None,
     ) -> list[GrepMatch] | str:
         """Structured search results or error string for invalid input."""
-        search_path = path or "."
+        search_path = shlex.quote(path or ".")
 
         # Build grep command to get structured output
-        grep_opts = "-rHn"  # recursive, with filename, with line number
+        grep_opts = "-rHnF"  # recursive, with filename, with line number, fixed-strings (literal)
 
         # Add glob pattern if specified
         glob_pattern = ""
@@ -281,9 +284,9 @@ except PermissionError:
             glob_pattern = f"--include='{glob}'"
 
         # Escape pattern for shell
-        pattern_escaped = pattern.replace("'", "'\\\\''")
+        pattern_escaped = shlex.quote(pattern)
 
-        cmd = f"grep {grep_opts} {glob_pattern} -e '{pattern_escaped}' '{search_path}' 2>/dev/null || true"
+        cmd = f"grep {grep_opts} {glob_pattern} -e {pattern_escaped} {search_path} 2>/dev/null || true"
         result = self.execute(cmd)
 
         output = result.output.rstrip()
@@ -338,4 +341,20 @@ except PermissionError:
     @property
     @abstractmethod
     def id(self) -> str:
-        """Unique identifier for this backend instance."""
+        """Unique identifier for the sandbox backend."""
+
+    @abstractmethod
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Upload multiple files to the sandbox.
+
+        Implementations must support partial success - catch exceptions per-file
+        and return errors in FileUploadResponse objects rather than raising.
+        """
+
+    @abstractmethod
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Download multiple files from the sandbox.
+
+        Implementations must support partial success - catch exceptions per-file
+        and return errors in FileDownloadResponse objects rather than raising.
+        """

deepagents/backends/state.py

@@ -90,8 +90,6 @@ class StateBackend(BackendProtocol):
         infos.sort(key=lambda x: x.get("path", ""))
         return infos
 
-    # Removed legacy ls() convenience to keep lean surface
-
     def read(
         self,
         file_path: str,
@@ -101,9 +99,11 @@ class StateBackend(BackendProtocol):
         """Read file content with line numbers.
 
         Args:
-            file_path: Absolute file path
-            offset: Line offset to start reading from (0-indexed)
-            limit: Maximum number of lines to readReturns:
+            file_path: Absolute file path.
+            offset: Line offset to start reading from (0-indexed).
+            limit: Maximum number of lines to read.
+
+        Returns:
             Formatted file content with line numbers, or error message.
         """
         files = self.runtime.state.get("files", {})
@@ -156,8 +156,6 @@ class StateBackend(BackendProtocol):
         new_file_data = update_file_data(file_data, new_content)
         return EditResult(path=file_path, files_update={file_path: new_file_data}, occurrences=int(occurrences))
 
-    # Removed legacy grep() convenience to keep lean surface
-
     def grep_raw(
         self,
         pattern: str,
@@ -168,6 +166,7 @@ class StateBackend(BackendProtocol):
         return grep_matches_from_files(files, pattern, path, glob)
 
     def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
+        """Get FileInfo for files matching glob pattern."""
         files = self.runtime.state.get("files", {})
         result = _glob_search_files(files, pattern, path)
         if result == "No files found":
@@ -186,6 +185,3 @@ class StateBackend(BackendProtocol):
                 }
             )
         return infos
-
-
-# Provider classes removed: prefer callables like `lambda rt: StateBackend(rt)`

deepagents/backends/store.py

@@ -5,7 +5,15 @@ from typing import Any
 from langgraph.config import get_config
 from langgraph.store.base import BaseStore, Item
 
-from deepagents.backends.protocol import BackendProtocol, EditResult, FileInfo, GrepMatch, WriteResult
+from deepagents.backends.protocol import (
+    BackendProtocol,
+    EditResult,
+    FileDownloadResponse,
+    FileInfo,
+    FileUploadResponse,
+    GrepMatch,
+    WriteResult,
+)
 from deepagents.backends.utils import (
     _glob_search_files,
     create_file_data,
@@ -30,17 +38,18 @@ class StoreBackend(BackendProtocol):
         """Initialize StoreBackend with runtime.
 
         Args:
+            runtime: The ToolRuntime instance providing store access and configuration.
         """
         self.runtime = runtime
 
     def _get_store(self) -> BaseStore:
         """Get the store instance.
 
-        Args:Returns:
-            BaseStore instance
+        Returns:
+            BaseStore instance from the runtime.
 
         Raises:
-            ValueError: If no store is available or runtime not provided
+            ValueError: If no store is available in the runtime.
         """
         store = self.runtime.store
         if store is None:
@@ -240,8 +249,6 @@ class StoreBackend(BackendProtocol):
         infos.sort(key=lambda x: x.get("path", ""))
         return infos
 
-    # Removed legacy ls() convenience to keep lean surface
-
     def read(
         self,
         file_path: str,
@@ -251,8 +258,9 @@ class StoreBackend(BackendProtocol):
         """Read file content with line numbers.
 
         Args:
-            file_path: Absolute file path
-            offset: Line offset to start reading from (0-indexed)limit: Maximum number of lines to read
+            file_path: Absolute file path.
+            offset: Line offset to start reading from (0-indexed).
+            limit: Maximum number of lines to read.
 
         Returns:
             Formatted file content with line numbers, or error message.
@@ -376,3 +384,59 @@ class StoreBackend(BackendProtocol):
                 }
             )
         return infos
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Upload multiple files to the store.
+
+        Args:
+            files: List of (path, content) tuples where content is bytes.
+
+        Returns:
+            List of FileUploadResponse objects, one per input file.
+            Response order matches input order.
+        """
+        store = self._get_store()
+        namespace = self._get_namespace()
+        responses: list[FileUploadResponse] = []
+
+        for path, content in files:
+            content_str = content.decode("utf-8")
+            # Create file data
+            file_data = create_file_data(content_str)
+            store_value = self._convert_file_data_to_store_value(file_data)
+
+            # Store the file
+            store.put(namespace, path, store_value)
+            responses.append(FileUploadResponse(path=path, error=None))
+
+        return responses
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Download multiple files from the store.
+
+        Args:
+            paths: List of file paths to download.
+
+        Returns:
+            List of FileDownloadResponse objects, one per input path.
+            Response order matches input order.
+        """
+        store = self._get_store()
+        namespace = self._get_namespace()
+        responses: list[FileDownloadResponse] = []
+
+        for path in paths:
+            item = store.get(namespace, path)
+
+            if item is None:
+                responses.append(FileDownloadResponse(path=path, content=None, error="file_not_found"))
+                continue
+
+            file_data = self._convert_store_item_to_file_data(item)
+            # Convert file data to bytes
+            content_str = file_data_to_string(file_data)
+            content_bytes = content_str.encode("utf-8")
+
+            responses.append(FileDownloadResponse(path=path, content=content_bytes, error=None))
+
+        return responses

deepagents/graph.py

@@ -98,6 +98,18 @@ def create_deep_agent(
     if model is None:
         model = get_default_model()
 
+    if (
+        model.profile is not None
+        and isinstance(model.profile, dict)
+        and "max_input_tokens" in model.profile
+        and isinstance(model.profile["max_input_tokens"], int)
+    ):
+        trigger = ("fraction", 0.85)
+        keep = ("fraction", 0.10)
+    else:
+        trigger = ("tokens", 170000)
+        keep = ("messages", 6)
+
     deepagent_middleware = [
         TodoListMiddleware(),
         FilesystemMiddleware(backend=backend),
@@ -110,8 +122,9 @@ def create_deep_agent(
                 FilesystemMiddleware(backend=backend),
                 SummarizationMiddleware(
                     model=model,
-                    max_tokens_before_summary=170000,
-                    messages_to_keep=6,
+                    trigger=trigger,
+                    keep=keep,
+                    trim_tokens_to_summarize=None,
                 ),
                 AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
                 PatchToolCallsMiddleware(),
@@ -121,8 +134,9 @@ def create_deep_agent(
         ),
         SummarizationMiddleware(
             model=model,
-            max_tokens_before_summary=170000,
-            messages_to_keep=6,
+            trigger=trigger,
+            keep=keep,
+            trim_tokens_to_summarize=None,
         ),
         AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
         PatchToolCallsMiddleware(),