aip-agents-binary 0.5.21__py3-none-macosx_13_0_arm64.whl → 0.6.8__py3-none-macosx_13_0_arm64.whl

aip_agents/sandbox/e2b_runtime.py

@@ -0,0 +1,295 @@
+"""E2B Sandbox Runtime for PTC.
+
+This module provides direct E2B SDK integration for sandbox code execution.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from collections.abc import Callable
+
+from e2b_code_interpreter import AsyncSandbox, OutputMessage
+
+from aip_agents.sandbox.defaults import DEFAULT_PTC_PACKAGES, DEFAULT_PTC_TEMPLATE
+from aip_agents.sandbox.types import SandboxExecutionResult
+from aip_agents.sandbox.validation import validate_package_names
+from aip_agents.utils.logger import get_logger
+
+# Type alias for package selector callback.
+# Called after sandbox creation with actual template status (None if template failed).
+PackageSelector = Callable[[str | None], list[str] | None]
+
+logger = get_logger(__name__)
+
+SANDBOX_NOT_INITIALIZED_ERROR = "Sandbox not initialized"
+
+
+class E2BSandboxRuntime:
+    """E2B Sandbox runtime for executing code in isolated environments.
+
+    This runtime manages per-run sandbox lifecycle:
+    - Create sandbox on first execute
+    - Reuse sandbox for subsequent executes
+    - Destroy sandbox on cleanup
+
+    Example:
+        runtime = E2BSandboxRuntime()
+        result = await runtime.execute(
+            code="print('Hello')",
+            timeout=60.0,
+            files={"tools/mcp.py": "# MCP client code"},
+        )
+        await runtime.cleanup()
+    """
+
+    def __init__(
+        self,
+        template: str | None = None,
+        ptc_packages: list[str] | None = None,
+        package_selector: PackageSelector | None = None,
+    ) -> None:
+        """Initialize E2B sandbox runtime.
+
+        Args:
+            template: Optional E2B template ID for custom sandbox environments.
+            ptc_packages: Packages to install in sandbox. If None or empty, skip install.
+                Overwritten by package_selector if provided.
+            package_selector: Optional callback to select packages after sandbox creation.
+                Called with actual template (None if template failed) to enable smart
+                package selection based on whether template was successfully created.
+        """
+        self._template = template
+        self._ptc_packages = ptc_packages
+        self._package_selector = package_selector
+        self._sandbox: AsyncSandbox | None = None
+        self._sandbox_created_with_template = False
+
+    async def execute(
+        self,
+        code: str,
+        *,
+        timeout: float = 300.0,
+        files: dict[str, str] | None = None,
+        env: dict[str, str] | None = None,
+        template: str | None = None,
+    ) -> SandboxExecutionResult:
+        """Execute code inside the sandbox.
+
+        Args:
+            code: Python code to execute.
+            timeout: Execution timeout in seconds.
+            files: Files to upload to the sandbox (path -> content).
+            env: Environment variables to set.
+            template: Optional template override for this execution.
+
+        Returns:
+            SandboxExecutionResult with stdout, stderr, and exit_code.
+        """
+        # Create sandbox if not exists
+        if self._sandbox is None:
+            await self._create_sandbox(template or self._template)
+
+        # Upload files if provided
+        if files:
+            await self._upload_files(files)
+
+        # Execute code
+        return await self._run_code(code, timeout, env)
+
+    async def cleanup(self) -> None:
+        """Destroy the sandbox and release resources."""
+        if self._sandbox is not None:
+            try:
+                logger.info("Destroying E2B sandbox")
+                await self._sandbox.kill()
+            except Exception as e:
+                logger.warning(f"Error destroying sandbox: {e}")
+            finally:
+                self._sandbox = None
+
+        self._reset_async_transport()
+
+    @property
+    def is_active(self) -> bool:
+        """Check if a sandbox is currently active."""
+        return self._sandbox is not None
+
+    def _reset_async_transport(self) -> None:
+        try:
+            from e2b.api.client_async import AsyncTransportWithLogger
+
+            AsyncTransportWithLogger.singleton = None
+        except Exception:
+            return
+
+    def _should_skip_default_ptc_install(self, template: str | None) -> bool:
+        if not self._sandbox_created_with_template:
+            return False
+
+        if template != DEFAULT_PTC_TEMPLATE:
+            return False
+
+        return self._ptc_packages == list(DEFAULT_PTC_PACKAGES)
+
+    async def _create_sandbox(self, template: str | None = None) -> None:
+        """Create a new E2B sandbox.
+
+        Implements canonical runtime rules:
+        - If template provided, try creating sandbox with template
+        - On any error, fall back to default sandbox (without template)
+        - Install ptc_packages regardless of template usage (even after fallback)
+
+        Note: Package installation occurs after sandbox creation, so fallback
+        to default sandbox does not skip package installation.
+
+        Args:
+            template: Optional template ID.
+        """
+        logger.info(f"Creating E2B sandbox (template={template})")
+
+        async def create_default_sandbox() -> None:
+            self._sandbox = await AsyncSandbox.create()
+            logger.info(f"E2B sandbox created (default): {self._sandbox.sandbox_id}")
+
+        if template:
+            try:
+                self._sandbox = await AsyncSandbox.create(template=template)
+                self._sandbox_created_with_template = True
+                logger.info(f"E2B sandbox created: {self._sandbox.sandbox_id}")
+            except Exception as e:
+                logger.warning(f"Template creation failed ({template}): {e}")
+                logger.info("Falling back to default sandbox")
+                self._sandbox_created_with_template = False
+                await create_default_sandbox()
+        else:
+            self._sandbox_created_with_template = False
+            await create_default_sandbox()
+
+        # Determine packages to install
+        # If package_selector is provided, use it with actual template status
+        # This enables smart package selection based on whether template succeeded
+        if self._package_selector is not None:
+            actual_template = template if self._sandbox_created_with_template else None
+            try:
+                self._ptc_packages = self._package_selector(actual_template)
+                logger.info(
+                    f"Package selector called with actual_template={actual_template}, "
+                    f"selected packages: {self._ptc_packages}"
+                )
+            except Exception as e:
+                logger.error(f"Package selector failed: {e}")
+                await self.cleanup()
+                raise
+
+        # Install ptc_packages if non-empty
+        if self._ptc_packages:
+            if self._should_skip_default_ptc_install(template):
+                logger.info("Skipping PTC package install (default template already includes defaults)")
+            else:
+                await self._install_ptc_packages()
+
+    async def _install_ptc_packages(self) -> None:
+        """Install PTC packages in the sandbox."""
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+
+        # Validate all packages before constructing command
+        validate_package_names(self._ptc_packages)
+
+        # Note: packages_str is safe because ptc_packages is a controlled list from
+        # configuration, not user input. E2B SDK's commands.run() only accepts str,
+        # not list, so string joining is required.
+        packages_str = " ".join(self._ptc_packages)
+        logger.info(f"Installing PTC packages in sandbox: {packages_str}")
+
+        try:
+            result = await self._sandbox.commands.run(
+                f"pip install -q {packages_str}",
+                timeout=120,
+            )
+        except Exception as e:
+            logger.error(f"Error installing PTC packages: {e}")
+            raise
+
+        if result.exit_code != 0:
+            logger.error(f"Failed to install PTC packages: {result.stderr}")
+            raise RuntimeError(f"Failed to install PTC packages: {result.stderr}")
+
+        logger.info("PTC packages installed successfully")
+
+    async def _upload_files(self, files: dict[str, str]) -> None:
+        """Upload files to the sandbox.
+
+        Args:
+            files: Mapping of path -> content.
+        """
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+
+        for path, content in files.items():
+            logger.debug(f"Uploading file to sandbox: {path}")
+            await self._sandbox.files.write(path, content)
+
+    async def _run_code(
+        self,
+        code: str,
+        timeout: float,
+        env: dict[str, str] | None = None,
+    ) -> SandboxExecutionResult:
+        """Run code in the sandbox.
+
+        Args:
+            code: Python code to execute.
+            timeout: Execution timeout in seconds.
+            env: Environment variables.
+
+        Returns:
+            SandboxExecutionResult with execution output.
+        """
+        if self._sandbox is None:
+            raise RuntimeError(SANDBOX_NOT_INITIALIZED_ERROR)
+
+        stdout_lines: list[str] = []
+        stderr_lines: list[str] = []
+
+        def on_stdout(msg: OutputMessage) -> None:
+            if hasattr(msg, "line"):
+                stdout_lines.append(msg.line)
+
+        def on_stderr(msg: OutputMessage) -> None:
+            if hasattr(msg, "line"):
+                stderr_lines.append(msg.line)
+
+        try:
+            execution = await self._sandbox.run_code(
+                code=code,
+                language="python",
+                on_stdout=on_stdout,
+                on_stderr=on_stderr,
+                envs=env,
+                timeout=timeout,
+            )
+
+            # Determine exit code
+            exit_code = 0
+            if execution.error:
+                exit_code = 1
+                # Add error to stderr
+                error_msg = f"{execution.error.name}: {execution.error.value}"
+                if execution.error.traceback:
+                    error_msg = f"{execution.error.traceback}\n{error_msg}"
+                stderr_lines.append(error_msg)
+
+            return SandboxExecutionResult(
+                stdout="\n".join(stdout_lines),
+                stderr="\n".join(stderr_lines),
+                exit_code=exit_code,
+            )
+
+        except Exception as e:
+            logger.error(f"Sandbox execution failed: {e}")
+            return SandboxExecutionResult(
+                stdout="",
+                stderr=str(e),
+                exit_code=1,
+            )

aip_agents/sandbox/e2b_runtime.pyi

@@ -0,0 +1,57 @@
+from _typeshed import Incomplete
+from aip_agents.sandbox.defaults import DEFAULT_PTC_PACKAGES as DEFAULT_PTC_PACKAGES, DEFAULT_PTC_TEMPLATE as DEFAULT_PTC_TEMPLATE
+from aip_agents.sandbox.types import SandboxExecutionResult as SandboxExecutionResult
+from aip_agents.sandbox.validation import validate_package_names as validate_package_names
+from aip_agents.utils.logger import get_logger as get_logger
+from collections.abc import Callable
+
+PackageSelector = Callable[[str | None], list[str] | None]
+logger: Incomplete
+SANDBOX_NOT_INITIALIZED_ERROR: str
+
+class E2BSandboxRuntime:
+    '''E2B Sandbox runtime for executing code in isolated environments.
+
+    This runtime manages per-run sandbox lifecycle:
+    - Create sandbox on first execute
+    - Reuse sandbox for subsequent executes
+    - Destroy sandbox on cleanup
+
+    Example:
+        runtime = E2BSandboxRuntime()
+        result = await runtime.execute(
+            code="print(\'Hello\')",
+            timeout=60.0,
+            files={"tools/mcp.py": "# MCP client code"},
+        )
+        await runtime.cleanup()
+    '''
+    def __init__(self, template: str | None = None, ptc_packages: list[str] | None = None, package_selector: PackageSelector | None = None) -> None:
+        """Initialize E2B sandbox runtime.
+
+        Args:
+            template: Optional E2B template ID for custom sandbox environments.
+            ptc_packages: Packages to install in sandbox. If None or empty, skip install.
+                Overwritten by package_selector if provided.
+            package_selector: Optional callback to select packages after sandbox creation.
+                Called with actual template (None if template failed) to enable smart
+                package selection based on whether template was successfully created.
+        """
+    async def execute(self, code: str, *, timeout: float = 300.0, files: dict[str, str] | None = None, env: dict[str, str] | None = None, template: str | None = None) -> SandboxExecutionResult:
+        """Execute code inside the sandbox.
+
+        Args:
+            code: Python code to execute.
+            timeout: Execution timeout in seconds.
+            files: Files to upload to the sandbox (path -> content).
+            env: Environment variables to set.
+            template: Optional template override for this execution.
+
+        Returns:
+            SandboxExecutionResult with stdout, stderr, and exit_code.
+        """
+    async def cleanup(self) -> None:
+        """Destroy the sandbox and release resources."""
+    @property
+    def is_active(self) -> bool:
+        """Check if a sandbox is currently active."""

aip_agents/sandbox/template_builder.py

@@ -0,0 +1,131 @@
+"""Template builder for PTC sandbox templates.
+
+This module provides utilities for creating and managing E2B sandbox templates
+for programmatic tool calling (PTC) environments.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from e2b import Template, default_build_logger
+
+from aip_agents.sandbox.validation import validate_package_names
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def create_ptc_template(base_template: str, ptc_packages: list[str] | None) -> Template:
+    """Create a PTC template definition based on a base template.
+
+    Args:
+        base_template: Base template alias to build from (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+
+    Returns:
+        Template: A configured template ready to be built.
+    """
+    logger.info(f"Creating template from base: {base_template}")
+    template = Template().from_template(base_template)
+
+    if ptc_packages:
+        # Validate all packages before constructing command
+        validate_package_names(ptc_packages)
+
+        # Note: packages_str is safe because ptc_packages is a controlled list from
+        # configuration, not user input. Template.run_cmd() only accepts str.
+        packages_str = " ".join(ptc_packages)
+        logger.info(f"Installing packages: {packages_str}")
+        template.run_cmd(f"pip install -q {packages_str}")
+
+    return template
+
+
+def _template_exists(template_id: str) -> bool:
+    """Check if a template alias exists.
+
+    Args:
+        template_id: The template alias to check.
+
+    Returns:
+        bool: True if alias exists, False otherwise.
+    """
+    try:
+        return Template.exists(template_id)
+    except Exception:
+        logger.warning(f"Template exists check failed for: {template_id}")
+        return False
+
+
+def _build_template(template: Template, template_id: str) -> bool:
+    """Build a template with the given alias.
+
+    Args:
+        template: The template to build.
+        template_id: The alias to assign to the built template.
+
+    Returns:
+        bool: True if build succeeded, False otherwise.
+    """
+    try:
+        logger.info(f"Building template: {template_id}")
+        Template.build(
+            template,
+            alias=template_id,
+            on_build_logs=default_build_logger(),
+        )
+        logger.info(f"Template built successfully: {template_id}")
+        return True
+    except Exception as e:
+        logger.warning(f"Template build failed for {template_id}: {e}")
+        return False
+
+
+def ensure_ptc_template(
+    template_id: str,
+    base_template: str,
+    ptc_packages: list[str] | None,
+    force_rebuild: bool = False,
+) -> str | None:
+    """Ensure a PTC sandbox template exists, creating it if necessary.
+
+    This is an explicit helper that apps can call at startup to ensure the
+    template exists. It is never run implicitly by the SDK.
+
+    Args:
+        template_id: Unique alias for the template (e.g., "aip-agents-ptc-v1").
+        base_template: Base template alias to build from
+            (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+        force_rebuild: If True, rebuild even if alias exists.
+
+    Returns:
+        The template_id on success, None if creation failed.
+        Never raises exceptions.
+    """
+    # Fast path: template already exists and we're not forcing rebuild
+    if not force_rebuild and _template_exists(template_id):
+        logger.info(f"Template already exists: {template_id}")
+        return template_id
+
+    # Create and build the template
+    try:
+        template = create_ptc_template(base_template, ptc_packages)
+    except Exception as e:
+        logger.warning(f"Template creation failed for {template_id}: {e}")
+        return None
+
+    # Build the template
+    is_success = _build_template(template, template_id)
+    if is_success:
+        return template_id
+
+    # Build failed. Check if template exists anyway (race condition: another
+    # process may have built it while we were trying)
+    if _template_exists(template_id):
+        logger.info(f"Template already exists after failed build: {template_id}")
+        return template_id
+
+    return None

aip_agents/sandbox/template_builder.pyi

@@ -0,0 +1,36 @@
+from _typeshed import Incomplete
+from aip_agents.sandbox.validation import validate_package_names as validate_package_names
+from aip_agents.utils.logger import get_logger as get_logger
+from e2b import Template
+
+logger: Incomplete
+
+def create_ptc_template(base_template: str, ptc_packages: list[str] | None) -> Template:
+    '''Create a PTC template definition based on a base template.
+
+    Args:
+        base_template: Base template alias to build from (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+
+    Returns:
+        Template: A configured template ready to be built.
+    '''
+def ensure_ptc_template(template_id: str, base_template: str, ptc_packages: list[str] | None, force_rebuild: bool = False) -> str | None:
+    '''Ensure a PTC sandbox template exists, creating it if necessary.
+
+    This is an explicit helper that apps can call at startup to ensure the
+    template exists. It is never run implicitly by the SDK.
+
+    Args:
+        template_id: Unique alias for the template (e.g., "aip-agents-ptc-v1").
+        base_template: Base template alias to build from
+            (e.g., "code-interpreter-v1").
+        ptc_packages: List of packages to install in the template.
+            If None or empty, skips pip install step.
+        force_rebuild: If True, rebuild even if alias exists.
+
+    Returns:
+        The template_id on success, None if creation failed.
+        Never raises exceptions.
+    '''

aip_agents/sandbox/types.py

@@ -0,0 +1,24 @@
+"""Sandbox execution result types.
+
+This module defines types for sandbox execution results.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class SandboxExecutionResult:
+    """Result of a sandbox code execution.
+
+    Attributes:
+        stdout: Standard output from the execution.
+        stderr: Standard error from the execution.
+        exit_code: Exit code (0 for success, non-zero for failure).
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int

aip_agents/sandbox/types.pyi

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+
+@dataclass
+class SandboxExecutionResult:
+    """Result of a sandbox code execution.
+
+    Attributes:
+        stdout: Standard output from the execution.
+        stderr: Standard error from the execution.
+        exit_code: Exit code (0 for success, non-zero for failure).
+    """
+    stdout: str
+    stderr: str
+    exit_code: int

aip_agents/sandbox/validation.py

@@ -0,0 +1,50 @@
+"""Validation utilities for sandbox operations.
+
+This module provides validation functions for sandbox-related operations
+such as package name validation.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import re
+
+_PACKAGE_SPEC_PATTERN = re.compile(
+    r"^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?"
+    r"(?:\[[A-Za-z0-9._-]+(?:,[A-Za-z0-9._-]+)*\])?"
+    r"(?:"
+    r"(?:==|!=|<=|>=|~=|<|>)[0-9][A-Za-z0-9.*+!_-]*"
+    r"(?:,(?:==|!=|<=|>=|~=|<|>)[0-9][A-Za-z0-9.*+!_-]*)*"
+    r")?$"
+)
+
+
+def validate_package_name(package: str) -> bool:
+    """Validate package name/specifier format for pip install.
+
+    Allows standard pip formats: package, package==version, package[extra].
+
+    Args:
+        package: Package name or specifier to validate.
+
+    Returns:
+        True if package name is valid, False otherwise.
+    """
+    if not package:
+        return False
+
+    return bool(_PACKAGE_SPEC_PATTERN.fullmatch(package))
+
+
+def validate_package_names(packages: list[str]) -> None:
+    """Validate all package names in a list.
+
+    Args:
+        packages: List of package names or specifiers to validate.
+
+    Raises:
+        ValueError: If any package name is invalid.
+    """
+    for pkg in packages:
+        if not validate_package_name(pkg):
+            raise ValueError(f"Invalid package name format: {pkg}")

aip_agents/sandbox/validation.pyi

@@ -0,0 +1,20 @@
+def validate_package_name(package: str) -> bool:
+    """Validate package name/specifier format for pip install.
+
+    Allows standard pip formats: package, package==version, package[extra].
+
+    Args:
+        package: Package name or specifier to validate.
+
+    Returns:
+        True if package name is valid, False otherwise.
+    """
+def validate_package_names(packages: list[str]) -> None:
+    """Validate all package names in a list.
+
+    Args:
+        packages: List of package names or specifiers to validate.
+
+    Raises:
+        ValueError: If any package name is invalid.
+    """

aip_agents/sentry/__init__.py

@@ -1,4 +1,4 @@
-"""This module provides a centralized way to handle Sentry and OpenTelemetry configuration for BOSA SDK.
+"""This module provides a centralized way to handle Sentry and OpenTelemetry configuration for GL Connectors SDK.
 
 Authors:
     Saul Sayers (saul.sayers@gdplabs.id)