aip-agents-binary 0.5.25b1__py3-none-macosx_13_0_arm64.whl

aip_agents/tools/browser_use/types.py

@@ -0,0 +1,78 @@
+"""Shared data structures for the browser-use tool.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+class BrowserUseFatalError(RuntimeError):
+    """Raised when the Browser Use session must terminate immediately."""
+
+
+@dataclass
+class ToolCallInfo:
+    """Structured information for a single tool call."""
+
+    name: str
+    args: dict[str, Any]
+    output: str
+
+
+@dataclass
+class StreamingResponse:
+    """Standardized streaming response structure."""
+
+    event_type: str
+    content: str
+    thinking_and_activity_info: dict
+    is_final: bool
+    tool_info: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary format for yielding."""
+        return {
+            "event_type": self.event_type,
+            "content": self.content,
+            "thinking_and_activity_info": self.thinking_and_activity_info,
+            "tool_info": self.tool_info,
+            "is_final": self.is_final,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class StreamingState:
+    """State management for streaming operations."""
+
+    debug_url: str
+    recording_url: str
+    step_count: int = 0
+    is_complete: bool = False
+    session_id: str | None = None
+    terminal_error: str | None = None
+    recording_started: bool = False
+
+
+@dataclass
+class RetryDecision:
+    """Encapsulate retry metadata when Steel sessions need to be restarted."""
+
+    retries_remaining: int
+    attempted_retries: int
+    message: str
+    delay: float
+
+
+__all__ = [
+    "BrowserUseFatalError",
+    "RetryDecision",
+    "StreamingResponse",
+    "StreamingState",
+    "ToolCallInfo",
+]

aip_agents/tools/browser_use/types.pyi

@@ -0,0 +1,45 @@
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = ['BrowserUseFatalError', 'RetryDecision', 'StreamingResponse', 'StreamingState', 'ToolCallInfo']
+
+class BrowserUseFatalError(RuntimeError):
+    """Raised when the Browser Use session must terminate immediately."""
+
+@dataclass
+class ToolCallInfo:
+    """Structured information for a single tool call."""
+    name: str
+    args: dict[str, Any]
+    output: str
+
+@dataclass
+class StreamingResponse:
+    """Standardized streaming response structure."""
+    event_type: str
+    content: str
+    thinking_and_activity_info: dict
+    is_final: bool
+    tool_info: dict[str, Any] | None = ...
+    metadata: dict[str, Any] | None = ...
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary format for yielding."""
+
+@dataclass
+class StreamingState:
+    """State management for streaming operations."""
+    debug_url: str
+    recording_url: str
+    step_count: int = ...
+    is_complete: bool = ...
+    session_id: str | None = ...
+    terminal_error: str | None = ...
+    recording_started: bool = ...
+
+@dataclass
+class RetryDecision:
+    """Encapsulate retry metadata when Steel sessions need to be restarted."""
+    retries_remaining: int
+    attempted_retries: int
+    message: str
+    delay: float

aip_agents/tools/code_sandbox/__init__.py

@@ -0,0 +1,26 @@
+# flake8: noqa: F401
+"""Code Sandbox Tools for AI Agents.
+
+This package provides code execution capabilities for AI agents through integration
+with E2B Cloud Sandbox environment.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import warnings
+
+try:
+    import e2b
+
+    from aip_agents.tools.code_sandbox.e2b_sandbox_tool import E2BCodeSandboxTool
+
+    __all__ = ["E2BCodeSandboxTool"]
+
+except ImportError:
+    warnings.warn(
+        "Code sandbox tools not available. Install with: pip install aip-agents[local]",
+        ImportWarning,
+        stacklevel=2,
+    )
+    __all__ = []

aip_agents/tools/code_sandbox/__init__.pyi

@@ -0,0 +1,3 @@
+from aip_agents.tools.code_sandbox.e2b_sandbox_tool import E2BCodeSandboxTool as E2BCodeSandboxTool
+
+__all__ = ['E2BCodeSandboxTool']

aip_agents/tools/code_sandbox/constant.py

@@ -0,0 +1,13 @@
+"""Constants for Code Sandbox tool.
+
+Authors:
+    Komang Elang Surya Prawira (komang.e.s.prawira@gdplabs.id)
+"""
+
+# The filename `data.csv` is used as a hard-coded value because we currently lack a mechanism
+# to dynamically determine the actual filename. This static filename is used for saving files
+# inside the sandbox, and any pre-population steps will need to read from this filename.
+# Code interacting with the sandbox can directly access the content of the file using the pre-defined variable,
+# eliminating the need to load the file again. Agents or LLMs do not need to be aware of this filename.
+DATA_FILE_NAME = "data.csv"
+DATA_FILE_PATH = f"/files/{DATA_FILE_NAME}"

aip_agents/tools/code_sandbox/constant.pyi

@@ -0,0 +1,4 @@
+from _typeshed import Incomplete
+
+DATA_FILE_NAME: str
+DATA_FILE_PATH: Incomplete

aip_agents/tools/code_sandbox/e2b_cloud_sandbox_extended.py

@@ -0,0 +1,306 @@
+"""Tool for E2B Cloud Sandbox code execution.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+    Komang Elang Surya Prawira (komang.e.s.prawira@gdplabs.id)
+"""
+
+import asyncio
+import time
+from http import HTTPStatus
+from typing import Any
+
+import requests
+from e2b_code_interpreter import Sandbox
+from gllm_inference.schema import Attachment
+from gllm_tools.code_interpreter.code_sandbox.e2b_sandbox import E2BSandbox
+from gllm_tools.code_interpreter.code_sandbox.models import ExecutionResult, ExecutionStatus
+from gllm_tools.code_interpreter.code_sandbox.utils import calculate_duration_ms
+
+from aip_agents.tools.code_sandbox.constant import DATA_FILE_PATH
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class SandboxFileWatcher:
+    """File watcher for monitoring file creation in sandbox environments."""
+
+    def __init__(self, sandbox: Any):
+        """Initialize the file watcher with a sandbox instance.
+
+        Args:
+            sandbox (Any): The sandbox instance to monitor.
+        """
+        self.sandbox = sandbox
+        self._created_files: list[str] = []
+        self._watchers_with_dirs: list[tuple[Any, str]] = []
+
+    def setup_monitoring(self) -> None:
+        """Set up filesystem watchers for monitoring file creation.
+
+        Note: /tmp/output is a sandbox-isolated directory, not a shared system /tmp.
+        This directory is scoped to the E2B sandbox instance and is safe for use.
+        """
+        output_dirs = [
+            "/tmp/output",  # NOSONAR: python:S5443 - Sandbox-isolated directory, safe for temp outputs
+        ]
+
+        self._watchers_with_dirs = []
+
+        for output_dir in output_dirs:
+            try:
+                # Create the directory if it doesn't exist
+                # NOSONAR: python:S5443 - Sandbox-isolated directory, safe for use
+                self.sandbox.files.make_dir(output_dir)
+
+                # Watch the directory for new files
+                watcher = self.sandbox.files.watch_dir(output_dir, recursive=True)
+                self._watchers_with_dirs.append((watcher, output_dir))
+
+                logger.debug(f"Set up file watcher for directory: {output_dir}")
+
+            except Exception as e:
+                logger.debug(f"Could not set up watcher for {output_dir}: {str(e)}")
+                continue
+
+    def _process_single_event(self, event: Any, output_dir: str) -> None:
+        """Process a single filesystem event and add created files to the list.
+
+        Args:
+            event: The filesystem event to process.
+            output_dir: The directory being watched.
+        """
+        if not (hasattr(event, "name") and hasattr(event, "type")):
+            return
+
+        if str(event.type) != "FilesystemEventType.CREATE":
+            logger.debug(f"Ignored filesystem event: {event.type} - {event.name}")
+            return
+
+        # Construct full path by combining output_dir with filename
+        full_path = f"{output_dir}/{event.name}".replace("//", "/")
+        logger.info(f"New file created: {full_path}")
+        if full_path not in self._created_files:
+            self._created_files.append(full_path)
+
+    def _process_watcher_events(self, watcher: Any, output_dir: str) -> None:
+        """Process all events from a single watcher.
+
+        Args:
+            watcher: The filesystem watcher instance.
+            output_dir: The directory being watched.
+        """
+        try:
+            events = watcher.get_new_events()
+            for event in events:
+                logger.debug(f"Event: {event}")
+                self._process_single_event(event, output_dir)
+            watcher.stop()
+        except Exception as e:
+            logger.debug(f"Error processing watcher events: {str(e)}")
+
+    async def process_events(self) -> None:
+        """Process filesystem events from watchers and update created files list."""
+        # Poll for file system events (allow time for events to be generated)
+        await asyncio.sleep(0.5)
+
+        for watcher, output_dir in self._watchers_with_dirs:
+            self._process_watcher_events(watcher, output_dir)
+
+    def reset_created_files(self) -> None:
+        """Reset the list of created files."""
+        self._created_files = []
+
+    def get_created_files(self) -> list[str]:
+        """Get the list of files created during monitoring.
+
+        Returns:
+            list[str]: List of file paths that were created.
+        """
+        return self._created_files.copy()
+
+
+class MyE2BCloudSandbox(E2BSandbox):
+    """Extended E2B sandbox with filesystem monitoring capabilities.
+
+    Use `create()` in production to build a fully initialized sandbox wrapper.
+    Direct construction is intentionally blocked to prevent partially initialized
+    instances that lack the underlying E2B sandbox clients.
+    """
+
+    def __init__(self, language: str = "python", *, _unsafe_allow_init: bool = False) -> None:
+        """Initialize the sandbox wrapper.
+
+        Args:
+            language (str): Language to execute inside the sandbox.
+            _unsafe_allow_init (bool): Escape hatch for tests/mocks only.
+
+        Raises:
+            RuntimeError: When instantiated directly without `create()`.
+        """
+        if not _unsafe_allow_init:
+            raise RuntimeError("Use MyE2BCloudSandbox.create(...) to initialize a sandbox instance.")
+        super().__init__(language=language)
+        self.file_watcher: SandboxFileWatcher | None = None
+
+    @classmethod
+    async def create(
+        cls,
+        api_key: str,
+        domain: str | None = None,
+        template: str | None = None,
+        language: str = "python",
+        additional_packages: list[str] | None = None,
+        **kwargs: Any,
+    ) -> "MyE2BCloudSandbox":
+        """Create a fully initialized sandbox wrapper.
+
+        This is the supported construction path for production usage. It wires
+        the E2B sandbox instance and its filesystem/command clients, then
+        installs language dependencies.
+        """
+        sandbox = Sandbox.create(api_key=api_key, domain=domain, template=template, **kwargs)
+
+        instance = cls(language=language, _unsafe_allow_init=True)
+        instance.sandbox = sandbox
+        instance.files = sandbox.files
+        instance.commands = sandbox.commands
+        instance.additional_packages = additional_packages or []
+
+        instance._install_language_dependencies()
+
+        return instance
+
+    async def execute_code(
+        self,
+        code: str,
+        timeout: int = 30,
+        files: list[Attachment] | None = None,
+        **kwargs: Any,
+    ) -> ExecutionResult:
+        """Execute code in the E2B Cloud sandbox with filesystem monitoring.
+
+        This override fixes the Pydantic validation error by ensuring execution.error
+        is converted to string. Always enables filesystem monitoring to track
+        created files.
+
+        Args:
+            code (str): The code to execute.
+            timeout (int, optional): Maximum execution time in seconds. Defaults to 30.
+            files (list[Attachment] | None, optional): List of Attachment objects with file details. Defaults to None.
+            **kwargs (Any): Additional execution parameters.
+
+        Returns:
+            ExecutionResult: Structured result of the execution.
+
+        Raises:
+            RuntimeError: If sandbox is not initialized.
+        """
+        if not self.sandbox or not self.files or not self.commands:
+            raise RuntimeError("Sandbox is not initialized")
+
+        start_time = time.time()
+        try:
+            # Initialize filesystem monitoring
+            self.file_watcher = SandboxFileWatcher(self.sandbox)
+            self.file_watcher.reset_created_files()
+            self.file_watcher.setup_monitoring()
+
+            self._upload_files(files)
+            # Pre-populate the variable `df` for direct use in the code
+            if files:
+                logger.info("Pre-populating the variable `df` with the data from the file.")
+                self.sandbox.run_code(
+                    f"import pandas as pd; df = pd.read_csv('{DATA_FILE_PATH}')",
+                    language=self.language,
+                    timeout=timeout,
+                )
+            execution = self.sandbox.run_code(code, language=self.language, timeout=timeout)
+            duration_ms = calculate_duration_ms(start_time)
+            status = ExecutionStatus.ERROR if execution.error else ExecutionStatus.SUCCESS
+
+            # Process filesystem events
+            if self.file_watcher:
+                await self.file_watcher.process_events()
+                created_files_count = len(self.file_watcher.get_created_files())
+                logger.info(f"File monitoring detected {created_files_count} newly created files")
+
+            # Fix: Convert execution.error to string
+            return ExecutionResult.create(
+                status=status,
+                code=code,
+                stdout=("\n".join(execution.logs.stdout) if execution.logs and execution.logs.stdout else ""),
+                stderr=("\n".join(execution.logs.stderr) if execution.logs and execution.logs.stderr else ""),
+                error=(str(execution.error) if execution.error else ""),  # Convert to string here
+                duration_ms=duration_ms,
+            )
+        except Exception as e:
+            logger.warning(f"Error executing code in {self.language} sandbox: {str(e)}")
+            return ExecutionResult.create(
+                status=ExecutionStatus.ERROR,
+                code=code,
+                error=str(e),
+                duration_ms=calculate_duration_ms(start_time),
+            )
+
+    def get_created_files(self) -> list[str]:
+        """Get the list of files created during the last monitored execution.
+
+        Returns:
+            list[str]: List of file paths that were created.
+        """
+        if self.file_watcher:
+            return self.file_watcher.get_created_files()
+        return []
+
+    def download_file(self, file_path: str) -> bytes | None:
+        """Download file content from the sandbox.
+
+        Uses download_url when available to avoid binary corruption issues.
+        Falls back to the filesystem API when download_url fails or is unavailable.
+
+        Args:
+            file_path (str): Path to the file in the sandbox.
+
+        Returns:
+            bytes | None: File content as bytes, or None if download fails.
+
+        Raises:
+            RuntimeError: If sandbox is not initialized.
+        """
+        if not self.sandbox:
+            raise RuntimeError("Sandbox is not initialized")
+
+        try:
+            if hasattr(self.sandbox, "download_url"):
+                logger.info(f"Downloading {file_path} via download_url method")
+
+                try:
+                    url = self.sandbox.download_url(file_path)
+                except Exception as e:
+                    logger.warning(f"Failed to get download URL: {str(e)}")
+                else:
+                    logger.debug(f"Got download URL: {url}")
+
+                    try:
+                        response = requests.get(url, timeout=30)
+                    except Exception as e:
+                        logger.warning(f"URL download failed with error: {str(e)}")
+                    else:
+                        if response.status_code == HTTPStatus.OK:
+                            content = response.content
+                            logger.info(f"Successfully downloaded {len(content)} bytes via URL")
+                            return content
+                        logger.warning(f"URL download failed with status {response.status_code}")
+
+            if self.files:
+                logger.info(f"Downloading {file_path} via filesystem API")
+                content = self.files.read(file_path, format="bytes")
+                return bytes(content)
+
+            return None
+
+        except Exception as e:
+            logger.warning(f"Failed to download file {file_path}: {str(e)}")
+            return None

aip_agents/tools/code_sandbox/e2b_cloud_sandbox_extended.pyi

@@ -0,0 +1,102 @@
+from _typeshed import Incomplete
+from aip_agents.tools.code_sandbox.constant import DATA_FILE_PATH as DATA_FILE_PATH
+from aip_agents.utils.logger import get_logger as get_logger
+from gllm_inference.schema import Attachment as Attachment
+from gllm_tools.code_interpreter.code_sandbox.e2b_sandbox import E2BSandbox
+from gllm_tools.code_interpreter.code_sandbox.models import ExecutionResult
+from typing import Any
+
+logger: Incomplete
+
+class SandboxFileWatcher:
+    """File watcher for monitoring file creation in sandbox environments."""
+    sandbox: Incomplete
+    def __init__(self, sandbox: Any) -> None:
+        """Initialize the file watcher with a sandbox instance.
+
+        Args:
+            sandbox (Any): The sandbox instance to monitor.
+        """
+    def setup_monitoring(self) -> None:
+        """Set up filesystem watchers for monitoring file creation.
+
+        Note: /tmp/output is a sandbox-isolated directory, not a shared system /tmp.
+        This directory is scoped to the E2B sandbox instance and is safe for use.
+        """
+    async def process_events(self) -> None:
+        """Process filesystem events from watchers and update created files list."""
+    def reset_created_files(self) -> None:
+        """Reset the list of created files."""
+    def get_created_files(self) -> list[str]:
+        """Get the list of files created during monitoring.
+
+        Returns:
+            list[str]: List of file paths that were created.
+        """
+
+class MyE2BCloudSandbox(E2BSandbox):
+    """Extended E2B sandbox with filesystem monitoring capabilities.
+
+    Use `create()` in production to build a fully initialized sandbox wrapper.
+    Direct construction is intentionally blocked to prevent partially initialized
+    instances that lack the underlying E2B sandbox clients.
+    """
+    file_watcher: SandboxFileWatcher | None
+    def __init__(self, language: str = 'python', *, _unsafe_allow_init: bool = False) -> None:
+        """Initialize the sandbox wrapper.
+
+        Args:
+            language (str): Language to execute inside the sandbox.
+            _unsafe_allow_init (bool): Escape hatch for tests/mocks only.
+
+        Raises:
+            RuntimeError: When instantiated directly without `create()`.
+        """
+    @classmethod
+    async def create(cls, api_key: str, domain: str | None = None, template: str | None = None, language: str = 'python', additional_packages: list[str] | None = None, **kwargs: Any) -> MyE2BCloudSandbox:
+        """Create a fully initialized sandbox wrapper.
+
+        This is the supported construction path for production usage. It wires
+        the E2B sandbox instance and its filesystem/command clients, then
+        installs language dependencies.
+        """
+    async def execute_code(self, code: str, timeout: int = 30, files: list[Attachment] | None = None, **kwargs: Any) -> ExecutionResult:
+        """Execute code in the E2B Cloud sandbox with filesystem monitoring.
+
+        This override fixes the Pydantic validation error by ensuring execution.error
+        is converted to string. Always enables filesystem monitoring to track
+        created files.
+
+        Args:
+            code (str): The code to execute.
+            timeout (int, optional): Maximum execution time in seconds. Defaults to 30.
+            files (list[Attachment] | None, optional): List of Attachment objects with file details. Defaults to None.
+            **kwargs (Any): Additional execution parameters.
+
+        Returns:
+            ExecutionResult: Structured result of the execution.
+
+        Raises:
+            RuntimeError: If sandbox is not initialized.
+        """
+    def get_created_files(self) -> list[str]:
+        """Get the list of files created during the last monitored execution.
+
+        Returns:
+            list[str]: List of file paths that were created.
+        """
+    def download_file(self, file_path: str) -> bytes | None:
+        """Download file content from the sandbox.
+
+        Uses download_url when available to avoid binary corruption issues.
+        Falls back to the filesystem API when download_url fails or is unavailable.
+
+        Args:
+            file_path (str): Path to the file in the sandbox.
+
+        Returns:
+            bytes | None: File content as bytes, or None if download fails.
+
+        Raises:
+            RuntimeError: If sandbox is not initialized.
+        """