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

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']