aip-agents-binary 0.5.25b9__py3-none-any.whl → 0.6.1__py3-none-any.whl

aip_agents/ptc/sandbox_bridge.pyi

@@ -0,0 +1,25 @@
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient as BaseMCPClient
+from aip_agents.ptc.mcp.sandbox_bridge import build_mcp_payload as build_mcp_payload
+from aip_agents.ptc.payload import SandboxPayload as SandboxPayload
+
+async def build_sandbox_payload(mcp_client: BaseMCPClient | None = None, default_tool_timeout: float = 60.0) -> SandboxPayload:
+    """Build sandbox payload from MCP client configuration (MCP-only).
+
+    Args:
+        mcp_client: The MCP client with configured servers.
+        default_tool_timeout: Default timeout for tool calls in seconds.
+
+    Returns:
+        SandboxPayload containing files and env vars for the sandbox.
+    """
+def wrap_ptc_code(code: str) -> str:
+    """Wrap user PTC code with necessary imports and setup (MCP-only).
+
+    This prepends sys.path setup to ensure the tools package is importable.
+
+    Args:
+        code: User-provided Python code.
+
+    Returns:
+        Wrapped code ready for sandbox execution.
+    """

aip_agents/ptc/template_utils.py

@@ -0,0 +1,33 @@
+"""Template rendering helpers for PTC payloads.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import resources
+from string import Template
+
+
+def render_template(
+    package: str,
+    template_name: str,
+    values: Mapping[str, str] | None = None,
+) -> str:
+    """Render a template from package resources with optional substitutions.
+
+    Args:
+        package: Package path containing the template.
+        template_name: Template filename.
+        values: Optional mapping of template variables.
+
+    Returns:
+        Rendered template content.
+    """
+    template_file = resources.files(package).joinpath(template_name)
+    template_text = template_file.read_text(encoding="utf-8")
+    if not values:
+        return template_text
+    return Template(template_text).substitute(values)

aip_agents/ptc/template_utils.pyi

@@ -0,0 +1,13 @@
+from collections.abc import Mapping
+
+def render_template(package: str, template_name: str, values: Mapping[str, str] | None = None) -> str:
+    """Render a template from package resources with optional substitutions.
+
+    Args:
+        package: Package path containing the template.
+        template_name: Template filename.
+        values: Optional mapping of template variables.
+
+    Returns:
+        Rendered template content.
+    """

aip_agents/ptc/templates/__init__.py

@@ -0,0 +1 @@
+"""Shared templates for PTC sandbox code generation."""

aip_agents/ptc/templates/ptc_helper.py.template

@@ -0,0 +1,134 @@
+"""PTC Discovery Helper Module.
+
+This module provides discovery functions for exploring available PTC tools
+inside the PTC sandbox. Use these functions to find packages, list tools,
+and get detailed documentation.
+
+Usage:
+    from tools.ptc_helper import list_packages, list_tools, describe_tool
+
+    # List all available packages
+    packages = list_packages()
+
+    # List tools in a package
+    tools = list_tools("package_name")
+
+    # Get tool documentation
+    doc = describe_tool("package_name", "tool_name")
+"""
+
+import difflib
+import json
+import os
+from typing import Any
+
+# Load the index at module import time
+_INDEX_PATH = os.path.join(os.path.dirname(__file__), "ptc_index.json")
+_DOCS_DIR = os.path.join(os.path.dirname(__file__), "docs")
+
+_index: dict[str, Any] = {}
+if os.path.exists(_INDEX_PATH):
+    with open(_INDEX_PATH, "r") as f:
+        _index = json.load(f)
+
+
+def _suggest_closest(name: str, valid_names: list[str], kind: str = "name") -> str:
+    """Generate a suggestion message for closest match.
+
+    Args:
+        name: The name that was not found.
+        valid_names: List of valid names to match against.
+        kind: Type of name (package or tool) for the error message.
+
+    Returns:
+        Suggestion string or empty string if no close match.
+    """
+    matches = difflib.get_close_matches(name, valid_names, n=1, cutoff=0.6)
+    if matches:
+        return f" Did you mean '{matches[0]}'?"
+    return ""
+
+
+def list_packages() -> list[str]:
+    """List all available package names.
+
+    Returns:
+        Sorted list of sanitized package names.
+    """
+    packages = _index.get("packages", {})
+    return sorted(packages.keys())
+
+
+def list_tools(package: str) -> list[dict[str, str]]:
+    """List tools available in a package.
+
+    Args:
+        package: Sanitized package name (e.g., 'deepwiki').
+
+    Returns:
+        List of tool info dicts with 'name' keys.
+
+    Raises:
+        ValueError: If package is not found.
+    """
+    packages = _index.get("packages", {})
+    if package not in packages:
+        valid = list(packages.keys())
+        suggestion = _suggest_closest(package, valid, "package")
+        raise ValueError(f"Unknown package '{package}'.{suggestion}")
+
+    pkg_data = packages[package]
+    tools = pkg_data.get("tools", [])
+    return [{"name": t["name"]} for t in tools]
+
+
+def describe_tool(package: str, tool: str) -> dict[str, Any]:
+    """Get detailed documentation for a tool.
+
+    Args:
+        package: Sanitized package name.
+        tool: Sanitized tool name.
+
+    Returns:
+        Dict with 'name', 'signature', 'doc', and 'doc_path' keys.
+
+    Raises:
+        ValueError: If package or tool is not found.
+    """
+    packages = _index.get("packages", {})
+    if package not in packages:
+        valid = list(packages.keys())
+        suggestion = _suggest_closest(package, valid, "package")
+        raise ValueError(f"Unknown package '{package}'.{suggestion}")
+
+    pkg_data = packages[package]
+    tools = pkg_data.get("tools", [])
+    tool_names = [t["name"] for t in tools]
+
+    if tool not in tool_names:
+        suggestion = _suggest_closest(tool, tool_names, "tool")
+        raise ValueError(f"Unknown tool '{tool}' in package '{package}'.{suggestion}")
+
+    tool_info = next(t for t in tools if t["name"] == tool)
+    doc_path = tool_info.get("doc_path", "")
+
+    doc_content = ""
+    if doc_path:
+        full_path = os.path.join(os.path.dirname(__file__), doc_path.replace("tools/", ""))
+        if os.path.exists(full_path):
+            with open(full_path, "r") as f:
+                doc_content = f.read()
+        else:
+            doc_content = f"# {tool}\n\n**Signature:** `{tool_info.get('signature', f'{tool}(**kwargs: Any)')}`"
+    else:
+        doc_content = f"# {tool}\n\n**Signature:** `{tool_info.get('signature', f'{tool}(**kwargs: Any)')}`"
+
+    return {
+        "name": tool,
+        "signature": tool_info.get("signature", f"{tool}(**kwargs)"),
+        "doc": doc_content,
+        "doc_path": doc_path,
+    }
+
+
+__all__ = ["list_packages", "list_tools", "describe_tool"]

aip_agents/sandbox/__init__.py

@@ -0,0 +1,43 @@
+# flake8: noqa: F401
+"""Sandbox module for isolated code execution.
+
+This module provides abstractions for running code in sandboxed environments.
+All components support lazy loading to work with optional dependencies (e2b).
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aip_agents.sandbox.e2b_runtime import E2BSandboxRuntime
+    from aip_agents.sandbox.template_builder import ensure_ptc_template
+    from aip_agents.sandbox.types import SandboxExecutionResult
+
+_IMPORT_MAP = {
+    "E2BSandboxRuntime": "aip_agents.sandbox.e2b_runtime",
+    "ensure_ptc_template": "aip_agents.sandbox.template_builder",
+    "SandboxExecutionResult": "aip_agents.sandbox.types",
+}
+
+_cache: dict[str, Any] = {}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import components on first access."""
+    if name in _cache:
+        return _cache[name]
+
+    if name in _IMPORT_MAP:
+        try:
+            module = __import__(_IMPORT_MAP[name], fromlist=[name])
+            _cache[name] = getattr(module, name)
+            return _cache[name]
+        except ImportError as e:
+            raise ImportError(f"Failed to import {name}. Install with: pip install aip-agents[local]") from e
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = list(_IMPORT_MAP.keys())

aip_agents/sandbox/__init__.pyi

@@ -0,0 +1,5 @@
+from aip_agents.sandbox.e2b_runtime import E2BSandboxRuntime as E2BSandboxRuntime
+from aip_agents.sandbox.template_builder import ensure_ptc_template as ensure_ptc_template
+from aip_agents.sandbox.types import SandboxExecutionResult as SandboxExecutionResult
+
+__all__ = ['E2BSandboxRuntime', 'ensure_ptc_template', 'SandboxExecutionResult']

aip_agents/sandbox/defaults.py

@@ -0,0 +1,9 @@
+"""Defaults for PTC sandbox templates and packages."""
+
+DEFAULT_PTC_TEMPLATE = "aip-agents-ptc-v1"
+DEFAULT_PTC_PACKAGES: tuple[str, ...] = (
+    "aip-agents-binary[local]",
+    "mcp",
+    "httpx",
+    "gllm-plugin-binary==0.0.7",
+)

aip_agents/sandbox/defaults.pyi

@@ -0,0 +1,2 @@
+DEFAULT_PTC_TEMPLATE: str
+DEFAULT_PTC_PACKAGES: tuple[str, ...]

aip_agents/sandbox/e2b_runtime.py

@@ -0,0 +1,267 @@
+"""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 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
+
+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,
+    ) -> 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.
+        """
+        self._template = template
+        self._ptc_packages = ptc_packages
+        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()
+
+        # 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,51 @@
+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
+
+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) -> 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.
+        """
+    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."""