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/ptc/doc_gen.py

@@ -0,0 +1,122 @@
+"""Documentation generation utilities for PTC.
+
+Shared constants and helpers for generating tool documentation in sandbox payloads.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from typing import Any
+
+from aip_agents.ptc.naming import sanitize_function_name
+
+# Documentation limits (fixed constants per plan)
+DOC_DESC_LIMIT = 120  # Tool description trim limit
+DOC_PARAM_DESC_LIMIT = 80  # Parameter description trim limit
+
+
+def json_type_to_display(json_type: Any) -> str:
+    """Convert JSON type to display string.
+
+    Args:
+        json_type: JSON schema type.
+
+    Returns:
+        Human-readable type string.
+    """
+    if isinstance(json_type, list):
+        return "any"
+    type_map = {
+        "string": "str",
+        "integer": "int",
+        "number": "float",
+        "boolean": "bool",
+        "array": "list",
+        "object": "dict",
+        "null": "None",
+    }
+    return type_map.get(str(json_type), "any")
+
+
+def trim_text(text: str | None, limit: int) -> str:
+    """Trim text to limit with ellipsis if needed.
+
+    Args:
+        text: Text to trim.
+        limit: Maximum length before trimming.
+
+    Returns:
+        Trimmed text.
+    """
+    if not text:
+        return ""
+    if len(text) > limit:
+        return text[:limit] + "..."
+    return text
+
+
+def render_tool_doc(
+    func_name: str,
+    signature: str,
+    description: str,
+    schema: dict[str, Any],
+    is_stub: bool = False,
+    example_code: str | None = None,
+    example_heading: str = "## Example",
+) -> str:
+    """Render markdown documentation for a tool.
+
+    Args:
+        func_name: Sanitized function name.
+        signature: Full function signature.
+        description: Tool description.
+        schema: Input schema for parameters.
+        is_stub: Whether this is a stub documentation.
+        example_code: Optional example code block content (without ```python).
+        example_heading: Heading for the example section.
+
+    Returns:
+        Markdown documentation string.
+    """
+    if is_stub:
+        desc = "Details unavailable because tool definitions are not loaded yet."
+    else:
+        desc = trim_text(description, DOC_DESC_LIMIT) or "No description available."
+
+    lines = [
+        f"# {func_name}",
+        "",
+        f"**Description:** {desc}",
+        "",
+        f"**Signature:** `{signature}`",
+        "",
+    ]
+
+    # Add parameters section
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    if properties:
+        lines.append("## Parameters")
+        lines.append("")
+        for prop_name, prop_schema in sorted(properties.items()):
+            safe_param = sanitize_function_name(prop_name)
+            prop_type = json_type_to_display(prop_schema.get("type", "any"))
+            is_required = "required" if prop_name in required else "optional"
+
+            # Trim param description
+            raw_param_desc = prop_schema.get("description", "")
+            param_desc = trim_text(raw_param_desc, DOC_PARAM_DESC_LIMIT)
+
+            lines.append(f"- **{safe_param}** ({prop_type}, {is_required}): {param_desc}")
+        lines.append("")
+
+    # Add example section
+    if example_code:
+        lines.append(example_heading)
+        lines.append("")
+        lines.append("```python")
+        lines.append(example_code)
+        lines.append("```")
+
+    return "\n".join(lines)

aip_agents/ptc/doc_gen.pyi

@@ -0,0 +1,40 @@
+from aip_agents.ptc.naming import sanitize_function_name as sanitize_function_name
+from typing import Any
+
+DOC_DESC_LIMIT: int
+DOC_PARAM_DESC_LIMIT: int
+
+def json_type_to_display(json_type: Any) -> str:
+    """Convert JSON type to display string.
+
+    Args:
+        json_type: JSON schema type.
+
+    Returns:
+        Human-readable type string.
+    """
+def trim_text(text: str | None, limit: int) -> str:
+    """Trim text to limit with ellipsis if needed.
+
+    Args:
+        text: Text to trim.
+        limit: Maximum length before trimming.
+
+    Returns:
+        Trimmed text.
+    """
+def render_tool_doc(func_name: str, signature: str, description: str, schema: dict[str, Any], is_stub: bool = False, example_code: str | None = None, example_heading: str = '## Example') -> str:
+    """Render markdown documentation for a tool.
+
+    Args:
+        func_name: Sanitized function name.
+        signature: Full function signature.
+        description: Tool description.
+        schema: Input schema for parameters.
+        is_stub: Whether this is a stub documentation.
+        example_code: Optional example code block content (without ```python).
+        example_heading: Heading for the example section.
+
+    Returns:
+        Markdown documentation string.
+    """

aip_agents/ptc/exceptions.py

@@ -0,0 +1,57 @@
+"""PTC-specific exceptions.
+
+This module defines exceptions for Programmatic Tool Calling operations.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+
+class PTCError(Exception):
+    """Base exception for PTC errors."""
+
+    pass
+
+
+class PTCToolError(PTCError):
+    """Error during tool execution.
+
+    Attributes:
+        server_name: The MCP server where the error occurred.
+        tool_name: The tool that failed.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        server_name: str | None = None,
+        tool_name: str | None = None,
+    ) -> None:
+        """Initialize PTCToolError.
+
+        Args:
+            message: Error message.
+            server_name: The MCP server name (optional).
+            tool_name: The tool name (optional).
+        """
+        super().__init__(message)
+        self.server_name = server_name
+        self.tool_name = tool_name
+
+
+class PTCPayloadConflictError(PTCError):
+    """Error when merging payloads with conflicting file paths.
+
+    Attributes:
+        conflicts: Set of conflicting file paths.
+    """
+
+    def __init__(self, message: str, conflicts: set[str]) -> None:
+        """Initialize PTCPayloadConflictError.
+
+        Args:
+            message: Error message.
+            conflicts: Set of conflicting file paths.
+        """
+        super().__init__(message)
+        self.conflicts = conflicts

aip_agents/ptc/exceptions.pyi

@@ -0,0 +1,37 @@
+from _typeshed import Incomplete
+
+class PTCError(Exception):
+    """Base exception for PTC errors."""
+
+class PTCToolError(PTCError):
+    """Error during tool execution.
+
+    Attributes:
+        server_name: The MCP server where the error occurred.
+        tool_name: The tool that failed.
+    """
+    server_name: Incomplete
+    tool_name: Incomplete
+    def __init__(self, message: str, server_name: str | None = None, tool_name: str | None = None) -> None:
+        """Initialize PTCToolError.
+
+        Args:
+            message: Error message.
+            server_name: The MCP server name (optional).
+            tool_name: The tool name (optional).
+        """
+
+class PTCPayloadConflictError(PTCError):
+    """Error when merging payloads with conflicting file paths.
+
+    Attributes:
+        conflicts: Set of conflicting file paths.
+    """
+    conflicts: Incomplete
+    def __init__(self, message: str, conflicts: set[str]) -> None:
+        """Initialize PTCPayloadConflictError.
+
+        Args:
+            message: Error message.
+            conflicts: Set of conflicting file paths.
+        """

aip_agents/ptc/executor.py

@@ -0,0 +1,261 @@
+"""PTC Executor implementations.
+
+This module provides the sandboxed executor for Programmatic Tool Calling.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient
+from aip_agents.ptc.custom_tools import PTCCustomToolConfig
+from aip_agents.ptc.exceptions import PTCToolError
+from aip_agents.ptc.prompt_builder import PromptConfig
+from aip_agents.sandbox.defaults import DEFAULT_PTC_PACKAGES, DEFAULT_PTC_TEMPLATE
+from aip_agents.utils.logger import get_logger
+
+# Lazy import to avoid circular dependencies
+# These are only needed for PTCSandboxExecutor
+try:
+    from aip_agents.ptc.sandbox_bridge import build_sandbox_payload, wrap_ptc_code
+    from aip_agents.sandbox.e2b_runtime import E2BSandboxRuntime
+    from aip_agents.sandbox.types import SandboxExecutionResult
+
+    _SANDBOX_DEPS_AVAILABLE = True
+except ImportError:
+    _SANDBOX_DEPS_AVAILABLE = False
+
+logger = get_logger(__name__)
+
+if TYPE_CHECKING:
+    from aip_agents.ptc.payload import SandboxPayload
+
+
+@dataclass
+class PTCSandboxConfig:
+    """Configuration for PTC sandbox executor.
+
+    Attributes:
+        enabled: Whether PTC is enabled. When False, PTC is disabled.
+        default_tool_timeout: Default timeout per tool call in seconds.
+        sandbox_template: Optional E2B sandbox template ID.
+        sandbox_timeout: Sandbox execution timeout in seconds (hard cap/TTL).
+        ptc_packages: List of packages to install in sandbox. Defaults to DEFAULT_PTC_PACKAGES.
+        prompt: Prompt configuration for PTC usage guidance.
+        custom_tools: Configuration for custom LangChain tools in sandbox.
+    """
+
+    enabled: bool = False
+    default_tool_timeout: float = 60.0
+    sandbox_template: str | None = DEFAULT_PTC_TEMPLATE
+    sandbox_timeout: float = 300.0
+    ptc_packages: list[str] | None = field(default_factory=lambda: list(DEFAULT_PTC_PACKAGES))
+    prompt: PromptConfig = field(default_factory=PromptConfig)
+    custom_tools: PTCCustomToolConfig = field(default_factory=PTCCustomToolConfig)
+
+
+class PTCSandboxExecutor:
+    r"""Executes PTC code inside an E2B sandbox.
+
+    This executor is used for LLM-generated code that requires sandboxing.
+    It builds a sandbox payload (MCP server config + generated tool modules)
+    and executes the code using the E2B runtime.
+
+    Static bundle caching:
+        The executor tracks whether the static bundle (wrappers, registry, sources)
+        has been uploaded. On the first run, it uploads the full payload. On subsequent
+        runs, it only uploads per-run files (e.g., tools/custom_defaults.json) to
+        reduce upload overhead.
+
+        If the sandbox is destroyed/recreated, call reset_static_bundle() to force
+        a full re-upload on the next execution.
+
+    Thread-safety:
+        The static bundle upload is guarded by an asyncio.Lock. Concurrent calls will
+        serialize while the initial upload completes. After the bundle is cached,
+        executions proceed without locking.
+
+    Example:
+        runtime = E2BSandboxRuntime()
+        executor = PTCSandboxExecutor(mcp_client, runtime)
+        result = await executor.execute_code("from tools.yfinance import get_stock\\nprint(get_stock('AAPL'))")
+    """
+
+    def __init__(
+        self,
+        mcp_client: BaseMCPClient | None,
+        runtime: E2BSandboxRuntime,
+        config: PTCSandboxConfig | None = None,
+    ) -> None:
+        """Initialize PTCSandboxExecutor.
+
+        Args:
+            mcp_client: The MCP client with configured servers. Can be None for custom-only configs.
+            runtime: The E2B sandbox runtime instance.
+            config: Optional sandbox executor configuration.
+
+        Raises:
+            ImportError: If sandbox dependencies are not available.
+        """
+        if not _SANDBOX_DEPS_AVAILABLE:
+            raise ImportError(
+                "Sandbox dependencies not available. "
+                "PTCSandboxExecutor requires sandbox_bridge and e2b_runtime modules."
+            )
+
+        self._mcp_client = mcp_client
+        self._runtime = runtime
+        self._config = config or PTCSandboxConfig()
+        self._static_bundle_uploaded = False
+        self._bundle_lock = asyncio.Lock()
+
+    def _reset_bundle_state_if_inactive(self) -> None:
+        """Reset cached bundle state when the runtime is inactive."""
+        if self._runtime.is_active:
+            return
+        if not self._static_bundle_uploaded:
+            return
+
+        logger.info("Runtime is inactive, resetting static bundle state")
+        self._static_bundle_uploaded = False
+
+    def _should_include_packages_path(self) -> bool:
+        """Check if the packages path should be added to sys.path."""
+        custom_tools = self._config.custom_tools
+        if not custom_tools.enabled or not custom_tools.tools:
+            return False
+
+        return any(tool.get("package_path") or tool.get("kind") == "file" for tool in custom_tools.tools)
+
+    async def _build_payload(self, tool_configs: dict[str, dict] | None) -> SandboxPayload:
+        """Build the sandbox payload for execution."""
+        logger.info("Building sandbox payload")
+        return await build_sandbox_payload(
+            self._mcp_client,
+            self._config.default_tool_timeout,
+            custom_tools_config=self._config.custom_tools,
+            tool_configs=tool_configs,
+        )
+
+    def _wrap_code(self, code: str) -> str:
+        """Wrap code with required imports and setup."""
+        logger.info("Wrapping PTC code")
+        return wrap_ptc_code(code, include_packages_path=self._should_include_packages_path())
+
+    async def _execute_payload(
+        self,
+        payload: SandboxPayload,
+        wrapped_code: str,
+        *,
+        upload_static_bundle: bool,
+    ) -> SandboxExecutionResult:
+        """Execute the wrapped code with the provided payload."""
+        if upload_static_bundle:
+            logger.info("Uploading static bundle and per-run files")
+            files_to_upload = {**payload.files, **payload.per_run_files}
+        else:
+            logger.debug("Static bundle already uploaded, uploading only per-run files")
+            files_to_upload = payload.per_run_files
+
+        logger.info(f"Executing code in sandbox (timeout: {self._config.sandbox_timeout}s)")
+        return await self._runtime.execute(
+            code=wrapped_code,
+            timeout=self._config.sandbox_timeout,
+            files=files_to_upload if files_to_upload else None,
+            env=payload.env,
+            template=self._config.sandbox_template,
+        )
+
+    async def _execute_with_bundle(
+        self,
+        payload: SandboxPayload,
+        wrapped_code: str,
+    ) -> SandboxExecutionResult:
+        """Execute code using the cached static bundle when possible."""
+        if self._static_bundle_uploaded:
+            return await self._execute_payload(
+                payload,
+                wrapped_code,
+                upload_static_bundle=False,
+            )
+
+        async with self._bundle_lock:
+            if self._static_bundle_uploaded:
+                return await self._execute_payload(
+                    payload,
+                    wrapped_code,
+                    upload_static_bundle=False,
+                )
+
+            result = await self._execute_payload(
+                payload,
+                wrapped_code,
+                upload_static_bundle=True,
+            )
+            self._update_static_bundle_cache(result)
+            return result
+
+    def _update_static_bundle_cache(self, result: SandboxExecutionResult) -> None:
+        """Update cached bundle state after a successful upload."""
+        if result.exit_code != 0:
+            return
+
+        self._static_bundle_uploaded = True
+        logger.debug("Static bundle successfully uploaded and cached")
+
+    def _log_execution_result(self, result: SandboxExecutionResult) -> None:
+        """Log execution results based on exit status."""
+        if result.exit_code == 0:
+            logger.info("Sandbox execution completed successfully")
+        else:
+            logger.warning(f"Sandbox execution failed with exit code {result.exit_code}")
+
+    async def execute_code(
+        self,
+        code: str,
+        tool_configs: dict[str, dict] | None = None,
+    ) -> SandboxExecutionResult:
+        """Execute code inside the sandbox with MCP access.
+
+        This method:
+        1. Builds the sandbox payload (MCP config + generated tool modules + custom tools)
+        2. Wraps the user code with necessary imports and setup
+        3. Executes the code in the E2B sandbox
+        4. Returns the execution result (stdout/stderr/exit_code)
+
+        Args:
+            code: Python code to execute in the sandbox.
+            tool_configs: Optional per-tool config values for custom LangChain tools.
+                These are merged with agent defaults and written to custom_defaults.json.
+
+        Returns:
+            SandboxExecutionResult with stdout, stderr, and exit_code.
+
+        Raises:
+            PTCToolError: If sandbox execution fails.
+        """
+        try:
+            self._reset_bundle_state_if_inactive()
+            payload = await self._build_payload(tool_configs)
+            wrapped_code = self._wrap_code(code)
+            result = await self._execute_with_bundle(payload, wrapped_code)
+            self._log_execution_result(result)
+            return result
+
+        except Exception as exc:
+            logger.error(f"Sandbox execution failed: {exc}")
+            raise PTCToolError(f"Sandbox execution failed: {exc}") from exc
+
+    def reset_static_bundle(self) -> None:
+        """Reset the static bundle upload state.
+
+        Call this method when the sandbox is destroyed/recreated to force
+        a full re-upload of the static bundle on the next execution.
+        """
+        self._static_bundle_uploaded = False
+        logger.debug("Static bundle state reset, next execution will re-upload full payload")

aip_agents/ptc/executor.pyi

@@ -0,0 +1,99 @@
+from _typeshed import Incomplete
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient as BaseMCPClient
+from aip_agents.ptc.custom_tools import PTCCustomToolConfig as PTCCustomToolConfig
+from aip_agents.ptc.exceptions import PTCToolError as PTCToolError
+from aip_agents.ptc.payload import SandboxPayload as SandboxPayload
+from aip_agents.ptc.prompt_builder import PromptConfig as PromptConfig
+from aip_agents.ptc.sandbox_bridge import build_sandbox_payload as build_sandbox_payload, wrap_ptc_code as wrap_ptc_code
+from aip_agents.sandbox.defaults import DEFAULT_PTC_PACKAGES as DEFAULT_PTC_PACKAGES, DEFAULT_PTC_TEMPLATE as DEFAULT_PTC_TEMPLATE
+from aip_agents.sandbox.e2b_runtime import E2BSandboxRuntime as E2BSandboxRuntime
+from aip_agents.sandbox.types import SandboxExecutionResult as SandboxExecutionResult
+from aip_agents.utils.logger import get_logger as get_logger
+from dataclasses import dataclass, field
+
+logger: Incomplete
+
+@dataclass
+class PTCSandboxConfig:
+    """Configuration for PTC sandbox executor.
+
+    Attributes:
+        enabled: Whether PTC is enabled. When False, PTC is disabled.
+        default_tool_timeout: Default timeout per tool call in seconds.
+        sandbox_template: Optional E2B sandbox template ID.
+        sandbox_timeout: Sandbox execution timeout in seconds (hard cap/TTL).
+        ptc_packages: List of packages to install in sandbox. Defaults to DEFAULT_PTC_PACKAGES.
+        prompt: Prompt configuration for PTC usage guidance.
+        custom_tools: Configuration for custom LangChain tools in sandbox.
+    """
+    enabled: bool = ...
+    default_tool_timeout: float = ...
+    sandbox_template: str | None = ...
+    sandbox_timeout: float = ...
+    ptc_packages: list[str] | None = field(default_factory=Incomplete)
+    prompt: PromptConfig = field(default_factory=PromptConfig)
+    custom_tools: PTCCustomToolConfig = field(default_factory=PTCCustomToolConfig)
+
+class PTCSandboxExecutor:
+    '''Executes PTC code inside an E2B sandbox.
+
+    This executor is used for LLM-generated code that requires sandboxing.
+    It builds a sandbox payload (MCP server config + generated tool modules)
+    and executes the code using the E2B runtime.
+
+    Static bundle caching:
+        The executor tracks whether the static bundle (wrappers, registry, sources)
+        has been uploaded. On the first run, it uploads the full payload. On subsequent
+        runs, it only uploads per-run files (e.g., tools/custom_defaults.json) to
+        reduce upload overhead.
+
+        If the sandbox is destroyed/recreated, call reset_static_bundle() to force
+        a full re-upload on the next execution.
+
+    Thread-safety:
+        The static bundle upload is guarded by an asyncio.Lock. Concurrent calls will
+        serialize while the initial upload completes. After the bundle is cached,
+        executions proceed without locking.
+
+    Example:
+        runtime = E2BSandboxRuntime()
+        executor = PTCSandboxExecutor(mcp_client, runtime)
+        result = await executor.execute_code("from tools.yfinance import get_stock\\\\nprint(get_stock(\'AAPL\'))")
+    '''
+    def __init__(self, mcp_client: BaseMCPClient | None, runtime: E2BSandboxRuntime, config: PTCSandboxConfig | None = None) -> None:
+        """Initialize PTCSandboxExecutor.
+
+        Args:
+            mcp_client: The MCP client with configured servers. Can be None for custom-only configs.
+            runtime: The E2B sandbox runtime instance.
+            config: Optional sandbox executor configuration.
+
+        Raises:
+            ImportError: If sandbox dependencies are not available.
+        """
+    async def execute_code(self, code: str, tool_configs: dict[str, dict] | None = None) -> SandboxExecutionResult:
+        """Execute code inside the sandbox with MCP access.
+
+        This method:
+        1. Builds the sandbox payload (MCP config + generated tool modules + custom tools)
+        2. Wraps the user code with necessary imports and setup
+        3. Executes the code in the E2B sandbox
+        4. Returns the execution result (stdout/stderr/exit_code)
+
+        Args:
+            code: Python code to execute in the sandbox.
+            tool_configs: Optional per-tool config values for custom LangChain tools.
+                These are merged with agent defaults and written to custom_defaults.json.
+
+        Returns:
+            SandboxExecutionResult with stdout, stderr, and exit_code.
+
+        Raises:
+            PTCToolError: If sandbox execution fails.
+        """
+    def reset_static_bundle(self) -> None:
+        """Reset the static bundle upload state.
+
+        Call this method when the sandbox is destroyed/recreated to force
+        a full re-upload of the static bundle on the next execution.
+        """

aip_agents/ptc/mcp/__init__.py

@@ -0,0 +1,45 @@
+"""Programmatic Tool Calling (PTC) module for MCP tools.
+
+This module provides programmatic tool calling capabilities for MCP tools,
+allowing code-based tool invocation instead of JSON tool calls.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from aip_agents.ptc.exceptions import PTCError, PTCToolError
+from aip_agents.ptc.mcp.sandbox_bridge import (
+    ServerConfig,
+    build_mcp_payload,
+)
+from aip_agents.ptc.naming import (
+    json_type_to_python,
+    sanitize_function_name,
+    sanitize_module_name,
+    sanitize_param_name,
+    schema_to_params,
+)
+from aip_agents.ptc.payload import SandboxPayload
+from aip_agents.ptc.prompt_builder import (
+    build_ptc_prompt,
+    compute_ptc_prompt_hash,
+)
+
+__all__ = [
+    # Exceptions
+    "PTCError",
+    "PTCToolError",
+    # Naming utilities
+    "json_type_to_python",
+    "sanitize_function_name",
+    "sanitize_module_name",
+    "sanitize_param_name",
+    "schema_to_params",
+    # Prompt builder
+    "build_ptc_prompt",
+    "compute_ptc_prompt_hash",
+    # Sandbox Bridge
+    "SandboxPayload",
+    "ServerConfig",
+    "build_mcp_payload",
+]

aip_agents/ptc/mcp/__init__.pyi

@@ -0,0 +1,7 @@
+from aip_agents.ptc.exceptions import PTCError as PTCError, PTCToolError as PTCToolError
+from aip_agents.ptc.mcp.sandbox_bridge import ServerConfig as ServerConfig, build_mcp_payload as build_mcp_payload
+from aip_agents.ptc.naming import json_type_to_python as json_type_to_python, sanitize_function_name as sanitize_function_name, sanitize_module_name as sanitize_module_name, sanitize_param_name as sanitize_param_name, schema_to_params as schema_to_params
+from aip_agents.ptc.payload import SandboxPayload as SandboxPayload
+from aip_agents.ptc.prompt_builder import build_ptc_prompt as build_ptc_prompt, compute_ptc_prompt_hash as compute_ptc_prompt_hash
+
+__all__ = ['PTCError', 'PTCToolError', 'json_type_to_python', 'sanitize_function_name', 'sanitize_module_name', 'sanitize_param_name', 'schema_to_params', 'build_ptc_prompt', 'compute_ptc_prompt_hash', 'SandboxPayload', 'ServerConfig', 'build_mcp_payload']