deepagents 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

deepagents/__init__.py

@@ -2,6 +2,14 @@
 
 from deepagents.graph import create_deep_agent
 from deepagents.middleware.filesystem import FilesystemMiddleware
+from deepagents.middleware.memory import MemoryMiddleware
 from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
 
-__all__ = ["CompiledSubAgent", "FilesystemMiddleware", "SubAgent", "SubAgentMiddleware", "create_deep_agent"]
+__all__ = [
+    "CompiledSubAgent",
+    "FilesystemMiddleware",
+    "MemoryMiddleware",
+    "SubAgent",
+    "SubAgentMiddleware",
+    "create_deep_agent",
+]

deepagents/backends/composite.py

@@ -1,4 +1,22 @@
-"""CompositeBackend: Route operations to different backends based on path prefix."""
+"""Composite backend that routes file operations by path prefix.
+
+Routes operations to different backends based on path prefixes. Use this when you
+need different storage strategies for different paths (e.g., state for temp files,
+persistent store for memories).
+
+Examples:
+    ```python
+    from deepagents.backends.composite import CompositeBackend
+    from deepagents.backends.state import StateBackend
+    from deepagents.backends.store import StoreBackend
+
+    runtime = make_runtime()
+    composite = CompositeBackend(default=StateBackend(runtime), routes={"/memories/": StoreBackend(runtime)})
+
+    composite.write("/temp.txt", "ephemeral")
+    composite.write("/memories/note.md", "persistent")
+    ```
+"""
 
 from collections import defaultdict
 
@@ -16,12 +34,38 @@ from deepagents.backends.protocol import (
 from deepagents.backends.state import StateBackend
 
 
-class CompositeBackend:
+class CompositeBackend(BackendProtocol):
+    """Routes file operations to different backends by path prefix.
+
+    Matches paths against route prefixes (longest first) and delegates to the
+    corresponding backend. Unmatched paths use the default backend.
+
+    Attributes:
+        default: Backend for paths that don't match any route.
+        routes: Map of path prefixes to backends (e.g., {"/memories/": store_backend}).
+        sorted_routes: Routes sorted by length (longest first) for correct matching.
+
+    Examples:
+        ```python
+        composite = CompositeBackend(default=StateBackend(runtime), routes={"/memories/": StoreBackend(runtime), "/cache/": StoreBackend(runtime)})
+
+        composite.write("/temp.txt", "data")
+        composite.write("/memories/note.txt", "data")
+        ```
+    """
+
     def __init__(
         self,
         default: BackendProtocol | StateBackend,
         routes: dict[str, BackendProtocol],
     ) -> None:
+        """Initialize composite backend.
+
+        Args:
+            default: Backend for paths that don't match any route.
+            routes: Map of path prefixes to backends. Prefixes must start with "/"
+                and should end with "/" (e.g., "/memories/").
+        """
         # Default backend
         self.default = default
 
@@ -32,14 +76,14 @@ class CompositeBackend:
         self.sorted_routes = sorted(routes.items(), key=lambda x: len(x[0]), reverse=True)
 
     def _get_backend_and_key(self, key: str) -> tuple[BackendProtocol, str]:
-        """Determine which backend handles this key and strip prefix.
+        """Get backend for path and strip route prefix.
 
         Args:
-            key: Original file path
+            key: File path to route.
 
         Returns:
-            Tuple of (backend, stripped_key) where stripped_key has the route
-            prefix removed (but keeps leading slash).
+            Tuple of (backend, stripped_path). The stripped path has the route
+            prefix removed but keeps the leading slash.
         """
         # Check routes in order of length (longest first)
         for prefix, backend in self.sorted_routes:
@@ -53,14 +97,23 @@ class CompositeBackend:
         return self.default, key
 
     def ls_info(self, path: str) -> list[FileInfo]:
-        """List files and directories in the specified directory (non-recursive).
+        """List directory contents (non-recursive).
+
+        If path matches a route, lists only that backend. If path is "/", aggregates
+        default backend plus virtual route directories. Otherwise lists default backend.
 
         Args:
-            path: Absolute path to directory.
+            path: Absolute directory path starting with "/".
 
         Returns:
-            List of FileInfo-like dicts with route prefixes added, for files and directories directly in the directory.
-            Directories have a trailing / in their path and is_dir=True.
+            List of FileInfo dicts. Directories have trailing "/" and is_dir=True.
+            Route prefixes are restored in returned paths.
+
+        Examples:
+            ```python
+            infos = composite.ls_info("/")
+            infos = composite.ls_info("/memories/")
+            ```
         """
         # Check if path matches a specific route
         for route_prefix, backend in self.sorted_routes:
@@ -169,6 +222,28 @@ class CompositeBackend:
         path: str | None = None,
         glob: str | None = None,
     ) -> list[GrepMatch] | str:
+        """Search files for regex pattern.
+
+        Routes to backends based on path: specific route searches one backend,
+        "/" or None searches all backends, otherwise searches default backend.
+
+        Args:
+            pattern: Regex pattern to search for.
+            path: Directory to search. None searches all backends.
+            glob: Glob pattern to filter files (e.g., "*.py", "**/*.txt").
+                Filters by filename, not content.
+
+        Returns:
+            List of GrepMatch dicts with path (route prefix restored), line
+            (1-indexed), and text. Returns error string on failure.
+
+        Examples:
+            ```python
+            matches = composite.grep_raw("TODO", path="/memories/")
+            matches = composite.grep_raw("error", path="/")
+            matches = composite.grep_raw("import", path="/", glob="*.py")
+            ```
+        """
         # If path targets a specific route, search only that backend
         for route_prefix, backend in self.sorted_routes:
             if path is not None and path.startswith(route_prefix.rstrip("/")):
@@ -178,22 +253,26 @@ class CompositeBackend:
                     return raw
                 return [{**m, "path": f"{route_prefix[:-1]}{m['path']}"} for m in raw]
 
-        # Otherwise, search default and all routed backends and merge
-        all_matches: list[GrepMatch] = []
-        raw_default = self.default.grep_raw(pattern, path, glob)  # type: ignore[attr-defined]
-        if isinstance(raw_default, str):
-            # This happens if error occurs
-            return raw_default
-        all_matches.extend(raw_default)
-
-        for route_prefix, backend in self.routes.items():
-            raw = backend.grep_raw(pattern, "/", glob)
-            if isinstance(raw, str):
+        # If path is None or "/", search default and all routed backends and merge
+        # Otherwise, search only the default backend
+        if path is None or path == "/":
+            all_matches: list[GrepMatch] = []
+            raw_default = self.default.grep_raw(pattern, path, glob)  # type: ignore[attr-defined]
+            if isinstance(raw_default, str):
                 # This happens if error occurs
-                return raw
-            all_matches.extend({**m, "path": f"{route_prefix[:-1]}{m['path']}"} for m in raw)
+                return raw_default
+            all_matches.extend(raw_default)
 
-        return all_matches
+            for route_prefix, backend in self.routes.items():
+                raw = backend.grep_raw(pattern, "/", glob)
+                if isinstance(raw, str):
+                    # This happens if error occurs
+                    return raw
+                all_matches.extend({**m, "path": f"{route_prefix[:-1]}{m['path']}"} for m in raw)
+
+            return all_matches
+        # Path specified but doesn't match a route - search only default
+        return self.default.grep_raw(pattern, path, glob)  # type: ignore[attr-defined]
 
     async def agrep_raw(
         self,
@@ -201,7 +280,10 @@ class CompositeBackend:
         path: str | None = None,
         glob: str | None = None,
     ) -> list[GrepMatch] | str:
-        """Async version of grep_raw."""
+        """Async version of grep_raw.
+
+        See grep_raw() for detailed documentation on routing behavior and parameters.
+        """
         # If path targets a specific route, search only that backend
         for route_prefix, backend in self.sorted_routes:
             if path is not None and path.startswith(route_prefix.rstrip("/")):
@@ -211,22 +293,26 @@ class CompositeBackend:
                     return raw
                 return [{**m, "path": f"{route_prefix[:-1]}{m['path']}"} for m in raw]
 
-        # Otherwise, search default and all routed backends and merge
-        all_matches: list[GrepMatch] = []
-        raw_default = await self.default.agrep_raw(pattern, path, glob)  # type: ignore[attr-defined]
-        if isinstance(raw_default, str):
-            # This happens if error occurs
-            return raw_default
-        all_matches.extend(raw_default)
-
-        for route_prefix, backend in self.routes.items():
-            raw = await backend.agrep_raw(pattern, "/", glob)
-            if isinstance(raw, str):
+        # If path is None or "/", search default and all routed backends and merge
+        # Otherwise, search only the default backend
+        if path is None or path == "/":
+            all_matches: list[GrepMatch] = []
+            raw_default = await self.default.agrep_raw(pattern, path, glob)  # type: ignore[attr-defined]
+            if isinstance(raw_default, str):
                 # This happens if error occurs
-                return raw
-            all_matches.extend({**m, "path": f"{route_prefix[:-1]}{m['path']}"} for m in raw)
+                return raw_default
+            all_matches.extend(raw_default)
+
+            for route_prefix, backend in self.routes.items():
+                raw = await backend.agrep_raw(pattern, "/", glob)
+                if isinstance(raw, str):
+                    # This happens if error occurs
+                    return raw
+                all_matches.extend({**m, "path": f"{route_prefix[:-1]}{m['path']}"} for m in raw)
 
-        return all_matches
+            return all_matches
+        # Path specified but doesn't match a route - search only default
+        return await self.default.agrep_raw(pattern, path, glob)  # type: ignore[attr-defined]
 
     def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]:
         results: list[FileInfo] = []
@@ -379,19 +465,23 @@ class CompositeBackend:
         self,
         command: str,
     ) -> ExecuteResponse:
-        """Execute a command via the default backend.
-
-        Execution is not path-specific, so it always delegates to the default backend.
-        The default backend must implement SandboxBackendProtocol for this to work.
+        """Execute shell command via default backend.
 
         Args:
-            command: Full shell command string to execute.
+            command: Shell command to execute.
 
         Returns:
-            ExecuteResponse with combined output, exit code, and truncation flag.
+            ExecuteResponse with output, exit code, and truncation flag.
 
         Raises:
-            NotImplementedError: If default backend doesn't support execution.
+            NotImplementedError: If default backend doesn't implement SandboxBackendProtocol.
+
+        Examples:
+            ```python
+            composite = CompositeBackend(default=FilesystemBackend(root_dir="/tmp"), routes={"/memories/": StoreBackend(runtime)})
+
+            result = composite.execute("ls -la")
+            ```
         """
         if isinstance(self.default, SandboxBackendProtocol):
             return self.default.execute(command)

deepagents/backends/state.py

@@ -2,7 +2,15 @@
 
 from typing import TYPE_CHECKING
 
-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,
@@ -185,3 +193,44 @@ class StateBackend(BackendProtocol):
                 }
             )
         return infos
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Upload multiple files to state.
+
+        Args:
+            files: List of (path, content) tuples to upload
+
+        Returns:
+            List of FileUploadResponse objects, one per input file
+        """
+        raise NotImplementedError(
+            "StateBackend does not support upload_files yet. You can upload files "
+            "directly by passing them in invoke if you're storing files in the memory."
+        )
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Download multiple files from state.
+
+        Args:
+            paths: List of file paths to download
+
+        Returns:
+            List of FileDownloadResponse objects, one per input path
+        """
+        state_files = self.runtime.state.get("files", {})
+        responses: list[FileDownloadResponse] = []
+
+        for path in paths:
+            file_data = state_files.get(path)
+
+            if file_data is None:
+                responses.append(FileDownloadResponse(path=path, content=None, error="file_not_found"))
+                continue
+
+            # 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

@@ -8,6 +8,7 @@ from langchain.agents.middleware import HumanInTheLoopMiddleware, InterruptOnCon
 from langchain.agents.middleware.summarization import SummarizationMiddleware
 from langchain.agents.middleware.types import AgentMiddleware
 from langchain.agents.structured_output import ResponseFormat
+from langchain.chat_models import init_chat_model
 from langchain_anthropic import ChatAnthropic
 from langchain_anthropic.middleware import AnthropicPromptCachingMiddleware
 from langchain_core.language_models import BaseChatModel
@@ -17,9 +18,12 @@ from langgraph.graph.state import CompiledStateGraph
 from langgraph.store.base import BaseStore
 from langgraph.types import Checkpointer
 
+from deepagents.backends import StateBackend
 from deepagents.backends.protocol import BackendFactory, BackendProtocol
 from deepagents.middleware.filesystem import FilesystemMiddleware
+from deepagents.middleware.memory import MemoryMiddleware
 from deepagents.middleware.patch_tool_calls import PatchToolCallsMiddleware
+from deepagents.middleware.skills import SkillsMiddleware
 from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
 
 BASE_AGENT_PROMPT = "In order to complete the objective that the user asks of you, you have access to a number of standard tools."
@@ -44,6 +48,8 @@ def create_deep_agent(
     system_prompt: str | None = None,
     middleware: Sequence[AgentMiddleware] = (),
     subagents: list[SubAgent | CompiledSubAgent] | None = None,
+    skills: list[str] | None = None,
+    memory: list[str] | None = None,
     response_format: ResponseFormat | None = None,
     context_schema: type[Any] | None = None,
     checkpointer: Checkpointer | None = None,
@@ -79,6 +85,16 @@ def create_deep_agent(
                 - (optional) `model` (either a LanguageModelLike instance or dict
                   settings)
                 - (optional) `middleware` (list of AgentMiddleware)
+        skills: Optional list of skill source paths (e.g., ["/skills/user/", "/skills/project/"]).
+            Paths must be specified using POSIX conventions (forward slashes) and are relative
+            to the backend's root. When using StateBackend (default), provide skill files via
+            `invoke(files={...})`. With FilesystemBackend, skills are loaded from disk relative
+            to the backend's root_dir. Later sources override earlier ones for skills with the
+            same name (last one wins).
+        memory: Optional list of memory file paths (AGENTS.md files) to load
+            (e.g., ["/memory/AGENTS.md"]). Display names
+            are automatically derived from paths. Memory is loaded at agent startup and
+            added into the system prompt.
         response_format: A structured output response format to use for the agent.
         context_schema: The schema of the deep agent.
         checkpointer: Optional checkpointer for persisting agent state between runs.
@@ -97,6 +113,8 @@ def create_deep_agent(
     """
     if model is None:
         model = get_default_model()
+    elif isinstance(model, str):
+        model = init_chat_model(model)
 
     if (
         model.profile is not None
@@ -110,37 +128,58 @@ def create_deep_agent(
         trigger = ("tokens", 170000)
         keep = ("messages", 6)
 
-    deepagent_middleware = [
+    # Build middleware stack for subagents (includes skills if provided)
+    subagent_middleware: list[AgentMiddleware] = [
         TodoListMiddleware(),
-        FilesystemMiddleware(backend=backend),
-        SubAgentMiddleware(
-            default_model=model,
-            default_tools=tools,
-            subagents=subagents if subagents is not None else [],
-            default_middleware=[
-                TodoListMiddleware(),
-                FilesystemMiddleware(backend=backend),
-                SummarizationMiddleware(
-                    model=model,
-                    trigger=trigger,
-                    keep=keep,
-                    trim_tokens_to_summarize=None,
-                ),
-                AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
-                PatchToolCallsMiddleware(),
-            ],
-            default_interrupt_on=interrupt_on,
-            general_purpose_agent=True,
-        ),
-        SummarizationMiddleware(
-            model=model,
-            trigger=trigger,
-            keep=keep,
-            trim_tokens_to_summarize=None,
-        ),
-        AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
-        PatchToolCallsMiddleware(),
     ]
+
+    backend = backend if backend is not None else (lambda rt: StateBackend(rt))
+
+    if skills is not None:
+        subagent_middleware.append(SkillsMiddleware(backend=backend, sources=skills))
+    subagent_middleware.extend(
+        [
+            FilesystemMiddleware(backend=backend),
+            SummarizationMiddleware(
+                model=model,
+                trigger=trigger,
+                keep=keep,
+                trim_tokens_to_summarize=None,
+            ),
+            AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
+            PatchToolCallsMiddleware(),
+        ]
+    )
+
+    # Build main agent middleware stack
+    deepagent_middleware: list[AgentMiddleware] = [
+        TodoListMiddleware(),
+    ]
+    if memory is not None:
+        deepagent_middleware.append(MemoryMiddleware(backend=backend, sources=memory))
+    if skills is not None:
+        deepagent_middleware.append(SkillsMiddleware(backend=backend, sources=skills))
+    deepagent_middleware.extend(
+        [
+            FilesystemMiddleware(backend=backend),
+            SubAgentMiddleware(
+                default_model=model,
+                default_tools=tools,
+                subagents=subagents if subagents is not None else [],
+                default_middleware=subagent_middleware,
+                default_interrupt_on=interrupt_on,
+                general_purpose_agent=True,
+            ),
+            SummarizationMiddleware(
+                model=model,
+                trigger=trigger,
+                keep=keep,
+                trim_tokens_to_summarize=None,
+            ),
+            AnthropicPromptCachingMiddleware(unsupported_model_behavior="ignore"),
+            PatchToolCallsMiddleware(),
+        ]
+    )
     if middleware:
         deepagent_middleware.extend(middleware)
     if interrupt_on is not None:

deepagents/middleware/__init__.py

@@ -1,11 +1,15 @@
 """Middleware for the DeepAgent."""
 
 from deepagents.middleware.filesystem import FilesystemMiddleware
+from deepagents.middleware.memory import MemoryMiddleware
+from deepagents.middleware.skills import SkillsMiddleware
 from deepagents.middleware.subagents import CompiledSubAgent, SubAgent, SubAgentMiddleware
 
 __all__ = [
     "CompiledSubAgent",
     "FilesystemMiddleware",
+    "MemoryMiddleware",
+    "SkillsMiddleware",
     "SubAgent",
     "SubAgentMiddleware",
 ]