aip-agents-binary 0.6.0__py3-none-any.whl → 0.6.2__py3-none-any.whl

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/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/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/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.alias_exists(template_id)
+    except Exception:
+        logger.warning(f"Template alias 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/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/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/tools/__init__.py

@@ -46,8 +46,10 @@ _register_optional("aip_agents.tools.code_sandbox", "E2BCodeSandboxTool")
 _register_optional("aip_agents.tools.document_loader", "DocxReaderTool")
 _register_optional("aip_agents.tools.document_loader", "ExcelReaderTool")
 _register_optional("aip_agents.tools.document_loader", "PDFReaderTool")
+_register_optional("aip_agents.tools.execute_ptc_code", "create_execute_ptc_code_tool")
 
 if TYPE_CHECKING:
     from aip_agents.tools.browser_use import BrowserUseTool
     from aip_agents.tools.code_sandbox import E2BCodeSandboxTool
     from aip_agents.tools.document_loader import DocxReaderTool, ExcelReaderTool, PDFReaderTool
+    from aip_agents.tools.execute_ptc_code import create_execute_ptc_code_tool