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/tool_def_helpers.pyi

@@ -0,0 +1,38 @@
+from aip_agents.ptc.custom_tools import PTCFileToolDef as PTCFileToolDef, PTCPackageToolDef as PTCPackageToolDef
+from typing import Any
+
+def package_tool(name: str, *, import_path: str, class_name: str, package_path: str | None = None, description: str | None = None, input_schema: dict[str, Any] | None = None) -> PTCPackageToolDef:
+    '''Create a package-based tool definition.
+
+    Args:
+        name: Tool name (will be sanitized for Python compatibility).
+        import_path: Python import path (e.g., "aip_agents.tools.time_tool").
+        class_name: Tool class name to instantiate.
+        package_path: Optional local package path for bundling.
+        description: Optional tool description (auto-derived from tool if not provided).
+        input_schema: Optional JSON schema (auto-derived from tool if not provided).
+
+    Returns:
+        PTCPackageToolDef dict ready for use in PTCCustomToolConfig.tools.
+
+    Example:
+        >>> package_tool("time_tool", import_path="aip_agents.tools.time_tool", class_name="TimeTool")
+        {\'name\': \'time_tool\', \'kind\': \'package\', \'import_path\': \'aip_agents.tools.time_tool\', \'class_name\': \'TimeTool\'}
+    '''
+def file_tool(name: str, *, file_path: str, class_name: str, description: str | None = None, input_schema: dict[str, Any] | None = None) -> PTCFileToolDef:
+    '''Create a file-based tool definition.
+
+    Args:
+        name: Tool name (will be sanitized for Python compatibility).
+        file_path: Absolute path to the Python file containing the tool.
+        class_name: Tool class name to instantiate.
+        description: Optional tool description (auto-derived from tool if not provided).
+        input_schema: Optional JSON schema (auto-derived from tool if not provided).
+
+    Returns:
+        PTCFileToolDef dict ready for use in PTCCustomToolConfig.tools.
+
+    Example:
+        >>> file_tool("multiply", file_path="/path/to/multiply_tool.py", class_name="MultiplyTool")
+        {\'name\': \'multiply\', \'kind\': \'file\', \'file_path\': \'/path/to/multiply_tool.py\', \'class_name\': \'MultiplyTool\'}
+    '''

aip_agents/ptc/tool_enrichment.py

@@ -0,0 +1,163 @@
+"""Tool metadata enrichment utilities.
+
+This module provides functions to enrich custom tool definitions with metadata
+from actual tool objects (name, description, input_schema).
+
+Author: Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from aip_agents.ptc.custom_tools import (
+    PTCToolDef,
+    enrich_tool_def_with_metadata,
+)
+from aip_agents.ptc.naming import sanitize_function_name
+
+if TYPE_CHECKING:
+    from aip_agents.ptc import PTCCustomToolConfig
+
+logger = logging.getLogger(__name__)
+
+
+def build_tool_lookup(tools: list[object]) -> dict[str, object]:
+    """Build a lookup map from tool objects for name-based matching.
+
+    Creates entries for both original and sanitized names to support
+    fuzzy matching (e.g., "web-search" matches "web_search").
+
+    Args:
+        tools: List of tool objects with `name` attribute.
+
+    Returns:
+        Dict mapping tool names (and sanitized names) to tool objects.
+
+    Example:
+        >>> tools = [TimeTool(), WebSearchTool()]  # names: "time_tool", "web-search"
+        >>> lookup = build_tool_lookup(tools)
+        >>> lookup.keys()
+        dict_keys(['time_tool', 'web-search', 'web_search'])
+    """
+    tool_lookup: dict[str, object] = {}
+
+    for tool in tools:
+        if not hasattr(tool, "name"):
+            continue
+
+        tool_name = tool.name
+        if not tool_name:  # Skip None or empty string names
+            continue
+        tool_name = str(tool_name)
+        tool_lookup[tool_name] = tool
+
+        # Also add sanitized name for fuzzy matching
+        sanitized = sanitize_function_name(tool_name)
+        if sanitized != tool_name:
+            tool_lookup[sanitized] = tool
+
+    return tool_lookup
+
+
+def match_tool_by_name(
+    tool_def: PTCToolDef,
+    tool_lookup: dict[str, object],
+) -> tuple[object | None, str | None]:
+    """Find a matching tool object for a tool definition.
+
+    Tries exact name match first, then falls back to sanitized name.
+
+    Args:
+        tool_def: Tool definition dict with "name" key.
+        tool_lookup: Lookup map from build_tool_lookup().
+
+    Returns:
+        Tuple of (matching_tool, canonical_name) or (None, None) if no match.
+        canonical_name is the tool object's actual name (may differ from tool_def name).
+    """
+    def_name = tool_def.get("name", "")
+    sanitized_def_name = sanitize_function_name(def_name)
+
+    # Try exact match first, then sanitized
+    matching_tool = tool_lookup.get(def_name) or tool_lookup.get(sanitized_def_name)
+
+    if matching_tool is None:
+        return None, None
+
+    # Get canonical name from tool object
+    canonical_name = str(getattr(matching_tool, "name", ""))
+
+    # Treat empty canonical name as no match
+    if not canonical_name:
+        return None, None
+
+    return matching_tool, canonical_name
+
+
+def enrich_custom_tools_from_agent(
+    custom_tools_config: PTCCustomToolConfig,
+    agent_tools: list[object],
+    agent_name: str = "",
+) -> int:
+    """Enrich custom tool definitions with metadata from agent's tool objects.
+
+    Matches custom tool definitions with actual tool objects by name (including
+    sanitized name matching) and enriches them with description and input_schema.
+
+    Note: This function modifies custom_tools_config.tools in-place.
+
+    Args:
+        custom_tools_config: The PTCCustomToolConfig to enrich.
+        agent_tools: List of tool objects from the agent.
+        agent_name: Agent name for logging context.
+
+    Returns:
+        Number of tools that were enriched.
+
+    Example:
+        >>> config = PTCCustomToolConfig(enabled=True, tools=[{"name": "multiply", ...}])
+        >>> count = enrich_custom_tools_from_agent(config, [MultiplyTool()], "my_agent")
+        >>> count
+        1
+    """
+    if not custom_tools_config.enabled:
+        return 0
+
+    if not custom_tools_config.tools:
+        return 0
+
+    # Build lookup map
+    tool_lookup = build_tool_lookup(agent_tools)
+
+    # Enrich each tool definition
+    enriched_count = 0
+    log_prefix = f"Agent '{agent_name}': " if agent_name else ""
+
+    for i, tool_def in enumerate(custom_tools_config.tools):
+        def_name = tool_def.get("name", "")
+        matching_tool, canonical_name = match_tool_by_name(tool_def, tool_lookup)
+
+        if matching_tool is None:
+            logger.debug(
+                f"{log_prefix}No matching tool object found for custom tool '{def_name}', using existing definition"
+            )
+            continue
+
+        # Handle name correction if matched by sanitized name
+        if canonical_name and canonical_name != def_name:
+            tool_def_copy = dict(tool_def)
+            tool_def_copy["name"] = canonical_name
+            enriched = enrich_tool_def_with_metadata(tool_def_copy, matching_tool)
+        else:
+            enriched = enrich_tool_def_with_metadata(tool_def, matching_tool)
+
+        custom_tools_config.tools[i] = enriched
+        enriched_count += 1
+        logger.debug(f"{log_prefix}Enriched custom tool '{def_name}' with metadata")
+
+    if enriched_count > 0:
+        logger.info(f"{log_prefix}Enriched {enriched_count} custom tool(s) with metadata")
+
+    return enriched_count

aip_agents/ptc/tool_enrichment.pyi

@@ -0,0 +1,60 @@
+from _typeshed import Incomplete
+from aip_agents.ptc import PTCCustomToolConfig as PTCCustomToolConfig
+from aip_agents.ptc.custom_tools import PTCToolDef as PTCToolDef, enrich_tool_def_with_metadata as enrich_tool_def_with_metadata
+from aip_agents.ptc.naming import sanitize_function_name as sanitize_function_name
+
+logger: Incomplete
+
+def build_tool_lookup(tools: list[object]) -> dict[str, object]:
+    '''Build a lookup map from tool objects for name-based matching.
+
+    Creates entries for both original and sanitized names to support
+    fuzzy matching (e.g., "web-search" matches "web_search").
+
+    Args:
+        tools: List of tool objects with `name` attribute.
+
+    Returns:
+        Dict mapping tool names (and sanitized names) to tool objects.
+
+    Example:
+        >>> tools = [TimeTool(), WebSearchTool()]  # names: "time_tool", "web-search"
+        >>> lookup = build_tool_lookup(tools)
+        >>> lookup.keys()
+        dict_keys([\'time_tool\', \'web-search\', \'web_search\'])
+    '''
+def match_tool_by_name(tool_def: PTCToolDef, tool_lookup: dict[str, object]) -> tuple[object | None, str | None]:
+    '''Find a matching tool object for a tool definition.
+
+    Tries exact name match first, then falls back to sanitized name.
+
+    Args:
+        tool_def: Tool definition dict with "name" key.
+        tool_lookup: Lookup map from build_tool_lookup().
+
+    Returns:
+        Tuple of (matching_tool, canonical_name) or (None, None) if no match.
+        canonical_name is the tool object\'s actual name (may differ from tool_def name).
+    '''
+def enrich_custom_tools_from_agent(custom_tools_config: PTCCustomToolConfig, agent_tools: list[object], agent_name: str = '') -> int:
+    '''Enrich custom tool definitions with metadata from agent\'s tool objects.
+
+    Matches custom tool definitions with actual tool objects by name (including
+    sanitized name matching) and enriches them with description and input_schema.
+
+    Note: This function modifies custom_tools_config.tools in-place.
+
+    Args:
+        custom_tools_config: The PTCCustomToolConfig to enrich.
+        agent_tools: List of tool objects from the agent.
+        agent_name: Agent name for logging context.
+
+    Returns:
+        Number of tools that were enriched.
+
+    Example:
+        >>> config = PTCCustomToolConfig(enabled=True, tools=[{"name": "multiply", ...}])
+        >>> count = enrich_custom_tools_from_agent(config, [MultiplyTool()], "my_agent")
+        >>> count
+        1
+    '''

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,205 @@
+"""Defaults for PTC sandbox templates and packages."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from aip_agents.mcp.client.base_mcp_client import BaseMCPClient
+    from aip_agents.ptc.custom_tools import PTCCustomToolConfig
+
+DEFAULT_PTC_TEMPLATE = "aip-agents-ptc-v1"
+AIP_AGENTS_BINARY_LOCAL = "aip-agents-binary[local]"
+DEFAULT_PTC_PACKAGES: tuple[str, ...] = (
+    AIP_AGENTS_BINARY_LOCAL,
+    "mcp",
+    "httpx",
+    "gllm-plugin-binary==0.0.7",
+)
+
+
+def _has_mcp_tools(mcp_client: BaseMCPClient | None) -> bool:
+    """Check if MCP tools are present.
+
+    Args:
+        mcp_client: The MCP client to check.
+
+    Returns:
+        True if MCP client has servers configured.
+    """
+    return mcp_client is not None and bool(getattr(mcp_client, "servers", None))
+
+
+def _has_custom_tools(custom_tools_config: PTCCustomToolConfig | None) -> bool:
+    """Check if custom tools are present and enabled.
+
+    Args:
+        custom_tools_config: The custom tools configuration to check.
+
+    Returns:
+        True if custom tools are enabled and tools list is non-empty.
+    """
+    return custom_tools_config is not None and custom_tools_config.enabled and bool(custom_tools_config.tools)
+
+
+def _has_native_aip_tools(custom_tools_config: PTCCustomToolConfig | None) -> bool:
+    """Check if native AIP tools are present.
+
+    Native AIP tools are package-based custom tools with import_path starting with "aip_agents.tools.".
+
+    Args:
+        custom_tools_config: The custom tools configuration to check.
+
+    Returns:
+        True if at least one native AIP tool is found.
+    """
+    if not _has_custom_tools(custom_tools_config):
+        return False
+
+    assert custom_tools_config is not None
+    for tool in custom_tools_config.tools:
+        if tool.get("kind") == "package":
+            import_path = tool.get("import_path", "")
+            if import_path.startswith("aip_agents.tools."):
+                return True
+
+    return False
+
+
+def _merge_requirements(packages: list[str], requirements: list[str]) -> None:
+    """Merge requirements into packages list, avoiding duplicates.
+
+    Args:
+        packages: Target list to merge into (modified in place).
+        requirements: Requirements to merge.
+    """
+    for req in requirements:
+        if req not in packages:
+            packages.append(req)
+
+
+def _merge_custom_requirements(
+    packages: list[str],
+    custom_tools_config: PTCCustomToolConfig | None,
+) -> None:
+    """Merge custom tool requirements into packages list.
+
+    Args:
+        packages: Target list to merge into (modified in place).
+        custom_tools_config: Custom tools configuration.
+    """
+    if not _has_custom_tools(custom_tools_config):
+        return
+
+    assert custom_tools_config is not None
+    if custom_tools_config.requirements:
+        _merge_requirements(packages, custom_tools_config.requirements)
+
+
+def _packages_for_default_template(
+    custom_tools_config: PTCCustomToolConfig | None,
+    user_ptc_packages: list[str] | None,
+) -> list[str] | None:
+    """Build package list when using the default template.
+
+    Args:
+        custom_tools_config: Custom tools configuration.
+        user_ptc_packages: Explicitly provided packages by user (None if not set).
+
+    Returns:
+        List of packages to install, or None to skip installation.
+    """
+    packages = list(user_ptc_packages) if user_ptc_packages is not None else []
+    _merge_custom_requirements(packages, custom_tools_config)
+    return packages if packages else None
+
+
+def _packages_for_other_templates(
+    *,
+    mcp_client: BaseMCPClient | None,
+    custom_tools_config: PTCCustomToolConfig | None,
+    user_ptc_packages: list[str] | None,
+) -> list[str] | None:
+    """Build package list when using a non-default template.
+
+    Args:
+        mcp_client: The MCP client (check if has servers for MCP tools).
+        custom_tools_config: Custom tools configuration.
+        user_ptc_packages: Explicitly provided packages by user (None if not set).
+
+    Returns:
+        List of packages to install, or None to skip installation.
+    """
+    packages = list(user_ptc_packages) if user_ptc_packages is not None else []
+    base_packages = _build_base_packages(mcp_client=mcp_client, custom_tools_config=custom_tools_config)
+    _merge_requirements(packages, base_packages)
+    _merge_custom_requirements(packages, custom_tools_config)
+    return packages if packages else None
+
+
+def _build_base_packages(
+    *,
+    mcp_client: BaseMCPClient | None,
+    custom_tools_config: PTCCustomToolConfig | None,
+) -> list[str]:
+    """Build base package list based on tool types.
+
+    Args:
+        mcp_client: The MCP client (check if has servers for MCP tools).
+        custom_tools_config: Custom tools configuration.
+
+    Returns:
+        List of base packages needed for the tool types present.
+    """
+    packages: list[str] = []
+
+    if _has_mcp_tools(mcp_client):
+        packages.extend(["mcp", "httpx"])
+
+    if _has_custom_tools(custom_tools_config):
+        packages.extend(["langchain", "gllm-plugin-binary==0.0.7"])
+
+    if _has_native_aip_tools(custom_tools_config):
+        if AIP_AGENTS_BINARY_LOCAL not in packages:
+            packages.append(AIP_AGENTS_BINARY_LOCAL)
+
+    return packages
+
+
+def select_sandbox_packages(
+    *,
+    mcp_client: BaseMCPClient | None,
+    custom_tools_config: PTCCustomToolConfig | None,
+    template: str | None,
+    user_ptc_packages: list[str] | None,
+) -> list[str] | None:
+    """Select minimal packages to install in sandbox based on tool types.
+
+    This function implements the smart package selection logic:
+    - DEFAULT_PTC_TEMPLATE + no user packages: Skip install (template has all deps)
+    - DEFAULT_PTC_TEMPLATE + user packages: User packages + PTCCustomToolConfig.requirements
+    - Other template + no user packages: Build packages from tool types
+    - Other template + user packages: User packages + tool-type packages + PTCCustomToolConfig.requirements
+
+    Key principle: Tools won't work without their required packages. Always ensure:
+    - MCP tools → mcp + httpx installed
+    - Custom LangChain tools → langchain + gllm-plugin-binary installed
+    - Native AIP tools → aip-agents-binary[local] installed
+
+    Args:
+        mcp_client: The MCP client (check if has servers for MCP tools).
+        custom_tools_config: Custom tools configuration (includes tools list and .requirements field).
+        template: Sandbox template being used.
+        user_ptc_packages: Explicitly provided packages by user (None if not set).
+
+    Returns:
+        List of packages to install, or None to skip installation.
+    """
+    if template == DEFAULT_PTC_TEMPLATE:
+        return _packages_for_default_template(custom_tools_config, user_ptc_packages)
+
+    return _packages_for_other_templates(
+        mcp_client=mcp_client,
+        custom_tools_config=custom_tools_config,
+        user_ptc_packages=user_ptc_packages,
+    )

aip_agents/sandbox/defaults.pyi

@@ -0,0 +1,30 @@
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient as BaseMCPClient
+from aip_agents.ptc.custom_tools import PTCCustomToolConfig as PTCCustomToolConfig
+
+DEFAULT_PTC_TEMPLATE: str
+AIP_AGENTS_BINARY_LOCAL: str
+DEFAULT_PTC_PACKAGES: tuple[str, ...]
+
+def select_sandbox_packages(*, mcp_client: BaseMCPClient | None, custom_tools_config: PTCCustomToolConfig | None, template: str | None, user_ptc_packages: list[str] | None) -> list[str] | None:
+    """Select minimal packages to install in sandbox based on tool types.
+
+    This function implements the smart package selection logic:
+    - DEFAULT_PTC_TEMPLATE + no user packages: Skip install (template has all deps)
+    - DEFAULT_PTC_TEMPLATE + user packages: User packages + PTCCustomToolConfig.requirements
+    - Other template + no user packages: Build packages from tool types
+    - Other template + user packages: User packages + tool-type packages + PTCCustomToolConfig.requirements
+
+    Key principle: Tools won't work without their required packages. Always ensure:
+    - MCP tools → mcp + httpx installed
+    - Custom LangChain tools → langchain + gllm-plugin-binary installed
+    - Native AIP tools → aip-agents-binary[local] installed
+
+    Args:
+        mcp_client: The MCP client (check if has servers for MCP tools).
+        custom_tools_config: Custom tools configuration (includes tools list and .requirements field).
+        template: Sandbox template being used.
+        user_ptc_packages: Explicitly provided packages by user (None if not set).
+
+    Returns:
+        List of packages to install, or None to skip installation.
+    """