agentpool 2.1.9__py3-none-any.whl → 2.5.0__py3-none-any.whl

agentpool/tool_impls/download_file/__init__.py

@@ -0,0 +1,80 @@
+"""Download file tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from agentpool.tool_impls.download_file.tool import DownloadFileTool
+from agentpool_config.tools import ToolHints
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+__all__ = ["DownloadFileTool", "create_download_file_tool"]
+
+# Tool metadata defaults
+NAME = "download_file"
+DESCRIPTION = """Download a file from a URL to the filesystem.
+
+Supports:
+- HTTP/HTTPS downloads
+- Progress tracking
+- Speed monitoring
+- Automatic directory creation
+- Configurable chunk size and timeout"""
+CATEGORY: Literal["read"] = "read"
+HINTS = ToolHints(open_world=True)
+
+
+def create_download_file_tool(
+    *,
+    env: ExecutionEnvironment | None = None,
+    cwd: str | None = None,
+    chunk_size: int = 8192,
+    timeout: float = 30.0,
+    name: str = NAME,
+    description: str = DESCRIPTION,
+    requires_confirmation: bool = False,
+) -> DownloadFileTool:
+    """Create a configured DownloadFileTool instance.
+
+    Args:
+        env: Execution environment to use. Falls back to agent.env if not set.
+        cwd: Working directory for resolving relative paths.
+        chunk_size: Size of chunks to download in bytes (default: 8192).
+        timeout: Request timeout in seconds (default: 30.0).
+        name: Tool name override.
+        description: Tool description override.
+        requires_confirmation: Whether tool execution needs confirmation.
+
+    Returns:
+        Configured DownloadFileTool instance.
+
+    Example:
+        # Basic usage
+        download = create_download_file_tool()
+
+        # With custom settings
+        download = create_download_file_tool(
+            chunk_size=16384,
+            timeout=60.0,
+        )
+
+        # With specific environment
+        download = create_download_file_tool(
+            env=my_env,
+            cwd="/workspace/downloads",
+        )
+    """
+    return DownloadFileTool(
+        name=name,
+        description=description,
+        category=CATEGORY,
+        hints=HINTS,
+        env=env,
+        cwd=cwd,
+        chunk_size=chunk_size,
+        timeout=timeout,
+        requires_confirmation=requires_confirmation,
+    )

agentpool/tool_impls/download_file/tool.py

@@ -0,0 +1,183 @@
+"""Download file tool implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import time
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+import anyio
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.log import get_logger
+from agentpool.tools.base import Tool
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from exxec import ExecutionEnvironment
+    from fsspec.asyn import AsyncFileSystem
+
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class DownloadFileTool(Tool[dict[str, Any]]):
+    """Download files from URLs to the filesystem.
+
+    A standalone tool for downloading files with:
+    - HTTP/HTTPS URL downloads
+    - Progress tracking
+    - Configurable chunk size
+    - Speed monitoring
+    - Automatic directory creation
+
+    Use create_download_file_tool() factory for convenient instantiation.
+    """
+
+    # Tool-specific configuration
+    env: ExecutionEnvironment | None = None
+    """Execution environment to use. Falls back to agent.env if not set."""
+
+    cwd: str | None = None
+    """Working directory for resolving relative paths."""
+
+    chunk_size: int = 8192
+    """Size of chunks to download (bytes)."""
+
+    timeout: float = 30.0
+    """Request timeout in seconds."""
+
+    def get_callable(self) -> Callable[..., Awaitable[dict[str, Any]]]:
+        """Return the download_file method as the callable."""
+        return self._download_file
+
+    def _get_fs(self, ctx: AgentContext) -> AsyncFileSystem:
+        """Get filesystem from env, falling back to agent's env if not set."""
+        from fsspec.asyn import AsyncFileSystem
+        from fsspec.implementations.asyn_wrapper import AsyncFileSystemWrapper
+
+        if self.env is not None:
+            fs = self.env.get_fs()
+            return fs if isinstance(fs, AsyncFileSystem) else AsyncFileSystemWrapper(fs)
+        fs = ctx.agent.env.get_fs()
+        return fs if isinstance(fs, AsyncFileSystem) else AsyncFileSystemWrapper(fs)
+
+    def _resolve_path(self, path: str, ctx: AgentContext) -> str:
+        """Resolve a potentially relative path to an absolute path."""
+        cwd: str | None = None
+        if self.cwd:
+            cwd = self.cwd
+        elif self.env and self.env.cwd:
+            cwd = self.env.cwd
+        elif ctx.agent.env and ctx.agent.env.cwd:
+            cwd = ctx.agent.env.cwd
+
+        if cwd and not (path.startswith("/") or (len(path) > 1 and path[1] == ":")):
+            return str(Path(cwd) / path)
+        return path
+
+    async def _write(self, ctx: AgentContext, path: str, content: bytes) -> None:
+        """Write bytes to a file."""
+        await self._get_fs(ctx)._pipe_file(path, content)
+
+    async def _download_file(
+        self,
+        ctx: AgentContext,
+        url: str,
+        target_dir: str = "downloads",
+        chunk_size: int | None = None,
+    ) -> dict[str, Any]:
+        """Download a file from URL to the filesystem.
+
+        Args:
+            ctx: Agent context for event emission and filesystem access
+            url: URL to download from
+            target_dir: Directory to save the file (relative to cwd if set)
+            chunk_size: Size of chunks to download (overrides default)
+
+        Returns:
+            Status information about the download
+        """
+        import httpx
+
+        effective_chunk_size = chunk_size or self.chunk_size
+        start_time = time.time()
+
+        # Resolve target directory
+        target_dir = self._resolve_path(target_dir, ctx)
+
+        msg = f"Downloading: {url}"
+        await ctx.events.tool_call_start(title=msg, kind="read", locations=[url])
+
+        # Extract filename from URL
+        filename = Path(urlparse(url).path).name or "downloaded_file"
+        full_path = f"{target_dir.rstrip('/')}/{filename}"
+
+        try:
+            fs = self._get_fs(ctx)
+            # Ensure target directory exists
+            await fs._makedirs(target_dir, exist_ok=True)
+
+            async with (
+                httpx.AsyncClient(verify=False) as client,
+                client.stream("GET", url, timeout=self.timeout) as response,
+            ):
+                response.raise_for_status()
+
+                total = (
+                    int(response.headers["Content-Length"])
+                    if "Content-Length" in response.headers
+                    else None
+                )
+
+                # Collect all data
+                data = bytearray()
+                async for chunk in response.aiter_bytes(effective_chunk_size):
+                    data.extend(chunk)
+                    size = len(data)
+
+                    if total and (size % (effective_chunk_size * 100) == 0 or size == total):
+                        progress = size / total * 100
+                        speed_mbps = (size / 1_048_576) / (time.time() - start_time)
+                        progress_msg = f"\r{filename}: {progress:.1f}% ({speed_mbps:.1f} MB/s)"
+                        await ctx.events.progress(progress, 100, progress_msg)
+                        await anyio.sleep(0)
+
+                # Write to filesystem
+                await self._write(ctx, full_path, bytes(data))
+
+            duration = time.time() - start_time
+            size_mb = len(data) / 1_048_576
+
+            await ctx.events.file_operation("read", path=full_path, success=True)
+
+            return {
+                "path": full_path,
+                "filename": filename,
+                "size_bytes": len(data),
+                "size_mb": round(size_mb, 2),
+                "duration_seconds": round(duration, 2),
+                "speed_mbps": round(size_mb / duration, 2) if duration > 0 else 0,
+            }
+
+        except httpx.ConnectError as e:
+            error_msg = f"Connection error downloading {url}: {e}"
+            await ctx.events.file_operation("read", path=url, success=False, error=error_msg)
+            return {"error": error_msg}
+        except httpx.TimeoutException:
+            error_msg = f"Timeout downloading {url}"
+            await ctx.events.file_operation("read", path=url, success=False, error=error_msg)
+            return {"error": error_msg}
+        except httpx.HTTPStatusError as e:
+            error_msg = f"HTTP error {e.response.status_code} downloading {url}"
+            await ctx.events.file_operation("read", path=url, success=False, error=error_msg)
+            return {"error": error_msg}
+        except Exception as e:  # noqa: BLE001
+            error_msg = f"Error downloading {url}: {e!s}"
+            await ctx.events.file_operation("read", path=url, success=False, error=error_msg)
+            return {"error": error_msg}

agentpool/tool_impls/execute_code/__init__.py

@@ -0,0 +1,55 @@
+"""Python code execution tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from agentpool.tool_impls.execute_code.tool import ExecuteCodeTool
+from agentpool_config.tools import ToolHints
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+__all__ = ["ExecuteCodeTool", "create_execute_code_tool"]
+
+# Tool metadata defaults
+NAME = "execute_code"
+DESCRIPTION = "Execute Python code and return the result."
+CATEGORY: Literal["execute"] = "execute"
+HINTS = ToolHints()
+
+
+def create_execute_code_tool(
+    *,
+    env: ExecutionEnvironment | None = None,
+    name: str = NAME,
+    description: str = DESCRIPTION,
+    requires_confirmation: bool = False,
+) -> ExecuteCodeTool:
+    """Create a configured ExecuteCodeTool instance.
+
+    Args:
+        env: Execution environment to use. Falls back to agent.env if not set.
+        name: Tool name override.
+        description: Tool description override.
+        requires_confirmation: Whether tool execution needs confirmation.
+
+    Returns:
+        Configured ExecuteCodeTool instance.
+
+    Example:
+        # Basic
+        exec_code = create_execute_code_tool()
+
+        # Require confirmation
+        exec_code = create_execute_code_tool(requires_confirmation=True)
+    """
+    return ExecuteCodeTool(
+        name=name,
+        description=description,
+        category=CATEGORY,
+        hints=HINTS,
+        env=env,
+        requires_confirmation=requires_confirmation,
+    )

agentpool/tool_impls/execute_code/tool.py

@@ -0,0 +1,163 @@
+"""Python code execution tool."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+import json
+from typing import TYPE_CHECKING
+import uuid
+
+from exxec.events import (
+    OutputEvent,
+    ProcessCompletedEvent,
+    ProcessErrorEvent,
+    ProcessStartedEvent,
+)
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.log import get_logger
+from agentpool.tools.base import Tool
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from exxec import ExecutionEnvironment
+    from fsspec.asyn import AsyncFileSystem
+
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class ExecuteCodeTool(Tool[str]):
+    """Execute Python code and return the result.
+
+    A standalone tool for executing Python code in a sandboxed environment.
+
+    Use create_execute_code_tool() factory for convenient instantiation with defaults.
+    """
+
+    # Tool-specific configuration
+    env: ExecutionEnvironment | None = None
+    """Execution environment to use. Falls back to agent.env if not set."""
+
+    def __post_init__(self) -> None:
+        """Initialize filesystem for script history after dataclass init."""
+        from fsspec.implementations.asyn_wrapper import AsyncFileSystemWrapper
+        from fsspec.implementations.memory import MemoryFileSystem
+
+        self._memory_fs = MemoryFileSystem()
+        self._fs = AsyncFileSystemWrapper(self._memory_fs)
+
+    def get_callable(self) -> Callable[..., Awaitable[str]]:
+        """Return the execute method as the callable."""
+        return self._execute
+
+    def _get_env(self, ctx: AgentContext) -> ExecutionEnvironment:
+        """Get execution environment, falling back to agent's env."""
+        if self.env is not None:
+            return self.env
+        return ctx.agent.env
+
+    def get_fs(self) -> AsyncFileSystem:
+        """Get filesystem view of script history.
+
+        Returns:
+            AsyncFileSystem containing:
+            - scripts/{timestamp}_{title}.py - Executed scripts
+            - scripts/{timestamp}_{title}.json - Execution metadata
+        """
+        return self._fs
+
+    async def _execute(
+        self,
+        ctx: AgentContext,
+        code: str,
+        title: str,
+    ) -> str:
+        """Execute Python code and return the result.
+
+        Args:
+            ctx: Agent context for event emission and environment access
+            code: Python code to execute
+            title: Short descriptive title for this script (3-4 words)
+        """
+        process_id: str | None = None
+        output_parts: list[str] = []
+        exit_code: int | None = None
+        error_msg: str | None = None
+
+        # Check if we're running in ACP - terminal streams client-side
+        from exxec.acp_provider import ACPExecutionEnvironment
+
+        env = self._get_env(ctx)
+        is_acp = isinstance(env, ACPExecutionEnvironment)
+
+        try:
+            async for event in env.stream_code(code):
+                match event:
+                    case ProcessStartedEvent(process_id=pid, command=cmd):
+                        process_id = pid
+                        await ctx.events.process_started(pid, cmd, success=True)
+
+                    case OutputEvent(data=data):
+                        output_parts.append(data)
+                        # Skip progress events for ACP - terminal streams client-side
+                        if process_id and not is_acp:
+                            await ctx.events.process_output(process_id, data)
+
+                    case ProcessCompletedEvent(exit_code=code_):
+                        exit_code = code_
+                        # Skip exit event for ACP - completion handled by FunctionToolResultEvent
+                        if process_id and not is_acp:
+                            out = "".join(output_parts)
+                            await ctx.events.process_exit(process_id, exit_code, final_output=out)
+
+                    case ProcessErrorEvent(error=err, exit_code=code_):
+                        error_msg = err
+                        exit_code = code_
+                        # Skip exit event for ACP - completion handled by FunctionToolResultEvent
+                        if process_id and not is_acp:
+                            await ctx.events.process_exit(
+                                process_id, exit_code or 1, final_output=err
+                            )
+
+            combined_output = "".join(output_parts)
+
+            # Format error response
+            if error_msg:
+                result_str = f"{combined_output}\n\nError: {error_msg}\nExit code: {exit_code}"
+            elif exit_code and exit_code != 0:
+                result_str = f"{combined_output}\n\nExit code: {exit_code}"
+            else:
+                result_str = combined_output
+
+        except Exception as e:  # noqa: BLE001
+            error_id = process_id or f"code_{uuid.uuid4().hex[:8]}"
+            await ctx.events.process_started(error_id, "execute_code", success=False, error=str(e))
+            exit_code = 1
+            error_msg = str(e)
+            result_str = f"Error executing code: {e}"
+        finally:
+            # Save to filesystem
+            end_time = datetime.now(UTC)
+            timestamp = end_time.strftime("%Y%m%d_%H%M%S")
+
+            # Write script file
+            script_path = f"scripts/{timestamp}_{title}.py"
+            self._memory_fs.pipe(script_path, code.encode("utf-8"))
+
+            # Write metadata file
+            metadata = {
+                "title": title,
+                "timestamp": end_time.isoformat(),
+                "exit_code": exit_code or 0,
+                "result": result_str,
+                "error": error_msg,
+            }
+            metadata_path = f"scripts/{timestamp}_{title}.json"
+            self._memory_fs.pipe(metadata_path, json.dumps(metadata, indent=2).encode("utf-8"))
+
+        return result_str

agentpool/tool_impls/grep/__init__.py

@@ -0,0 +1,80 @@
+"""Grep search tool."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from agentpool.tool_impls.grep.tool import GrepTool
+from agentpool_config.tools import ToolHints
+
+
+if TYPE_CHECKING:
+    from exxec import ExecutionEnvironment
+
+__all__ = ["GrepTool", "create_grep_tool"]
+
+# Tool metadata defaults
+NAME = "grep"
+DESCRIPTION = """Search file contents for patterns using grep.
+
+Supports:
+- Regex pattern matching
+- File filtering with glob patterns
+- Context lines before/after matches
+- Fast subprocess grep (ripgrep/grep) with Python fallback
+- Case-sensitive and case-insensitive search"""
+CATEGORY: Literal["search"] = "search"
+HINTS = ToolHints(read_only=True, idempotent=True)
+
+
+def create_grep_tool(
+    *,
+    env: ExecutionEnvironment | None = None,
+    cwd: str | None = None,
+    max_output_kb: int = 64,
+    use_subprocess_grep: bool = True,
+    name: str = NAME,
+    description: str = DESCRIPTION,
+    requires_confirmation: bool = False,
+) -> GrepTool:
+    """Create a configured GrepTool instance.
+
+    Args:
+        env: Execution environment to use. Falls back to agent.env if not set.
+        cwd: Working directory for resolving relative paths.
+        max_output_kb: Maximum output size in KB (default: 64KB).
+        use_subprocess_grep: Use ripgrep/grep subprocess if available (default: True).
+        name: Tool name override.
+        description: Tool description override.
+        requires_confirmation: Whether tool execution needs confirmation.
+
+    Returns:
+        Configured GrepTool instance.
+
+    Example:
+        # Basic usage
+        grep = create_grep_tool()
+
+        # With custom limits
+        grep = create_grep_tool(
+            max_output_kb=128,
+            use_subprocess_grep=False,  # Force Python implementation
+        )
+
+        # With specific environment
+        grep = create_grep_tool(
+            env=my_env,
+            cwd="/workspace",
+        )
+    """
+    return GrepTool(
+        name=name,
+        description=description,
+        category=CATEGORY,
+        hints=HINTS,
+        env=env,
+        cwd=cwd,
+        max_output_kb=max_output_kb,
+        use_subprocess_grep=use_subprocess_grep,
+        requires_confirmation=requires_confirmation,
+    )