aip-agents-binary 0.6.5__py3-none-macosx_13_0_arm64.whl → 0.6.7__py3-none-macosx_13_0_arm64.whl

aip_agents/ptc/custom_tools_payload.py

@@ -0,0 +1,400 @@
+"""Custom LangChain tools payload generation for PTC sandbox.
+
+This module generates the sandbox payload (wrapper modules, registry, sources)
+that allows LLM-generated code to call custom LangChain tools inside the sandbox.
+
+The payload includes:
+- tools/custom/__init__.py: Package init re-exporting all tool wrappers
+- tools/custom/<tool_name>.py: Per-tool wrapper module with sync call function
+- tools/custom_sources/__init__.py: Package init for file tool sources
+- tools/custom_sources/<tool_name>/__init__.py: File tool source (copied from user)
+- tools/custom_registry.py: Factory functions to build tool instances
+- tools/custom_invoke.py: Safe invoke helper for calling tool.ainvoke
+- tools/custom_defaults.json: Per-run tool config (uploaded each run)
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from aip_agents.ptc.custom_tools import (
+    PTCCustomToolConfig,
+    PTCToolDef,
+)
+from aip_agents.ptc.naming import sanitize_function_name
+from aip_agents.ptc.payload import SandboxPayload
+from aip_agents.ptc.template_utils import render_template
+from aip_agents.utils.logger import get_logger
+
+_TEMPLATE_PACKAGE = "aip_agents.ptc.custom_tools_templates"
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class CustomToolPayloadResult:
+    """Result of custom tool payload generation.
+
+    Attributes:
+        payload: The sandbox payload with files to upload.
+        tool_names: List of sanitized tool names available in sandbox.
+    """
+
+    payload: SandboxPayload
+    tool_names: list[str] = field(default_factory=list)
+
+
+def _validate_tool_configs(
+    tool_configs: dict[str, dict] | None,
+    configured_tools: list[PTCToolDef],
+) -> dict[str, dict]:
+    """Validate tool_configs and return sanitized values.
+
+    Args:
+        tool_configs: Optional per-tool config values to validate.
+        configured_tools: List of configured tool definitions.
+
+    Returns:
+        Validated tool_configs with only known tools and JSON-serializable dict values.
+    """
+    if not tool_configs:
+        return {}
+
+    if not isinstance(tool_configs, dict):
+        logger.warning("tool_configs must be a dict mapping tool names to dict values")
+        return {}
+
+    configured_names = {t.get("name", "") for t in configured_tools}
+    validated: dict[str, dict] = {}
+
+    for tool_name, tool_config in tool_configs.items():
+        if not isinstance(tool_name, str):
+            logger.warning(f"tool_configs contains non-string tool name: {tool_name!r}")
+            continue
+        if tool_name not in configured_names:
+            logger.warning(f"tool_configs contains config for unknown tool: {tool_name}")
+            continue
+        if not isinstance(tool_config, dict):
+            logger.warning(f"tool_configs for tool '{tool_name}' must be a dict")
+            continue
+        if any(not isinstance(key, str) for key in tool_config.keys()):
+            logger.warning(f"tool_configs for tool '{tool_name}' must use string keys")
+            continue
+        try:
+            json.dumps(tool_config)
+        except (TypeError, ValueError) as exc:
+            logger.warning(f"tool_configs for tool '{tool_name}' must be JSON-serializable: {exc}")
+            continue
+        validated[tool_name] = tool_config
+
+    return validated
+
+
+def build_custom_tools_payload(
+    config: PTCCustomToolConfig,
+    tool_configs: dict[str, dict] | None = None,
+) -> CustomToolPayloadResult:
+    """Build sandbox payload for custom LangChain tools.
+
+    Args:
+        config: Custom tool configuration with tool definitions.
+        tool_configs: Optional per-tool config values to write to defaults.json.
+
+    Returns:
+        CustomToolPayloadResult with payload and available tool names.
+    """
+    result = CustomToolPayloadResult(payload=SandboxPayload())
+
+    if not config.enabled or not config.tools:
+        return result
+
+    # Collect sanitized tool names
+    sanitized_tools: list[tuple[str, PTCToolDef]] = []
+    for tool in config.tools:
+        name = tool.get("name", "")
+        sanitized_name = sanitize_function_name(name)
+        sanitized_tools.append((sanitized_name, tool))
+
+    # Sort for deterministic output
+    sanitized_tools.sort(key=lambda x: x[0])
+    result.tool_names = [name for name, _ in sanitized_tools]
+
+    validated_tool_configs = _validate_tool_configs(tool_configs, config.tools)
+
+    # Generate tools/custom/__init__.py
+    result.payload.files["tools/custom/__init__.py"] = _generate_custom_init(sanitized_tools)
+
+    # Generate tools/custom/<tool_name>.py for each tool
+    for sanitized_name, tool in sanitized_tools:
+        wrapper_content = _generate_tool_wrapper(sanitized_name, tool)
+        result.payload.files[f"tools/custom/{sanitized_name}.py"] = wrapper_content
+
+    # Generate tools/custom_sources/__init__.py
+    file_tools = [(name, tool) for name, tool in sanitized_tools if tool.get("kind") == "file"]
+    result.payload.files["tools/custom_sources/__init__.py"] = _generate_custom_sources_init(file_tools)
+
+    # Generate tools/custom_sources/<tool_name>/__init__.py for file tools
+    for sanitized_name, tool in file_tools:
+        source_content = _read_file_tool_source(tool)
+        result.payload.files[f"tools/custom_sources/{sanitized_name}/__init__.py"] = source_content
+
+    # Generate tools/custom_registry.py
+    result.payload.files["tools/custom_registry.py"] = _generate_registry(sanitized_tools)
+
+    # Generate tools/custom_invoke.py
+    result.payload.files["tools/custom_invoke.py"] = _generate_invoke_helper()
+
+    # Generate tools/custom_defaults.json (per-run file, always re-uploaded)
+    defaults = validated_tool_configs
+    result.payload.per_run_files["tools/custom_defaults.json"] = json.dumps(defaults, indent=2)
+
+    # Bundle package sources from package_path
+    for sanitized_name, tool in sanitized_tools:
+        if tool.get("kind") == "package":
+            package_path = tool.get("package_path")
+            if package_path:
+                _bundle_package_source(result.payload, package_path, config.bundle_roots)
+
+    return result
+
+
+def _generate_custom_init(sanitized_tools: list[tuple[str, PTCToolDef]]) -> str:
+    """Generate tools/custom/__init__.py content.
+
+    Args:
+        sanitized_tools: List of (sanitized_name, tool_def) tuples.
+
+    Returns:
+        Python source code for the __init__.py module.
+    """
+    # Sort for deterministic output
+    sorted_names = sorted(name for name, _ in sanitized_tools)
+
+    imports = "\n".join(f"from tools.custom.{name} import {name}" for name in sorted_names)
+    all_list = ", ".join(f'"{name}"' for name in sorted_names)
+
+    return render_template(
+        _TEMPLATE_PACKAGE,
+        "custom_init.py.template",
+        {
+            "imports": imports,
+            "all_list": all_list,
+        },
+    )
+
+
+def _generate_tool_wrapper(sanitized_name: str, tool: PTCToolDef) -> str:
+    """Generate tools/custom/<tool_name>.py wrapper module.
+
+    Args:
+        sanitized_name: Sanitized tool name for function/module.
+        tool: Tool definition.
+
+    Returns:
+        Python source code for the wrapper module.
+    """
+    original_name = tool.get("name", sanitized_name)
+
+    return render_template(
+        _TEMPLATE_PACKAGE,
+        "custom_wrapper.py.template",
+        {
+            "original_name": original_name,
+            "sanitized_name": sanitized_name,
+        },
+    )
+
+
+def _generate_custom_sources_init(file_tools: list[tuple[str, PTCToolDef]]) -> str:
+    """Generate tools/custom_sources/__init__.py content.
+
+    Args:
+        file_tools: List of (sanitized_name, tool_def) tuples for file tools.
+
+    Returns:
+        Python source code for the __init__.py module.
+    """
+    sorted_names = sorted(name for name, _ in file_tools)
+    all_list = ", ".join(f'"{name}"' for name in sorted_names)
+
+    return render_template(
+        _TEMPLATE_PACKAGE,
+        "custom_sources_init.py.template",
+        {"all_list": all_list},
+    )
+
+
+def _read_file_tool_source(tool: PTCToolDef) -> str:
+    """Read source code from a file tool.
+
+    Args:
+        tool: File tool definition with file_path.
+
+    Returns:
+        Source code content.
+
+    Raises:
+        FileNotFoundError: If file does not exist.
+    """
+    file_path = tool.get("file_path", "")
+    path = Path(file_path)
+    return path.read_text(encoding="utf-8")
+
+
+def _generate_registry(sanitized_tools: list[tuple[str, PTCToolDef]]) -> str:
+    """Generate tools/custom_registry.py content.
+
+    Args:
+        sanitized_tools: List of (sanitized_name, tool_def) tuples.
+
+    Returns:
+        Python source code for the registry module.
+    """
+    # Generate import statements
+    imports: list[str] = []
+    build_functions: list[str] = []
+
+    for sanitized_name, tool in sorted(sanitized_tools, key=lambda x: x[0]):
+        kind = tool.get("kind")
+        class_name = tool.get("class_name", "")
+
+        if kind == "package":
+            import_path = tool.get("import_path", "")
+            imports.append(f"from {import_path} import {class_name}")
+        elif kind == "file":
+            imports.append(f"from tools.custom_sources.{sanitized_name} import {class_name}")
+
+        # Generate build function
+        build_func = _generate_build_function(sanitized_name, class_name)
+        build_functions.append(build_func)
+
+    imports_str = "\n".join(imports)
+    build_functions_str = "\n\n".join(build_functions)
+
+    return render_template(
+        _TEMPLATE_PACKAGE,
+        "custom_registry.py.template",
+        {
+            "imports": imports_str,
+            "build_functions": build_functions_str,
+        },
+    )
+
+
+def _generate_build_function(sanitized_name: str, class_name: str) -> str:
+    """Generate a build function for a single tool.
+
+    Args:
+        sanitized_name: Sanitized tool name.
+        class_name: Tool class name.
+
+    Returns:
+        Python source code for the build function.
+    """
+    return render_template(
+        _TEMPLATE_PACKAGE,
+        "custom_build_function.py.template",
+        {
+            "sanitized_name": sanitized_name,
+            "class_name": class_name,
+        },
+    )
+
+
+def _generate_invoke_helper() -> str:
+    """Generate tools/custom_invoke.py content.
+
+    Returns:
+        Python source code for the invoke helper module.
+    """
+    return render_template(_TEMPLATE_PACKAGE, "custom_invoke.py.template")
+
+
+def _bundle_package_source(
+    payload: SandboxPayload,
+    package_path: str,
+    bundle_roots: list[str],
+) -> None:
+    """Bundle package source files into payload.
+
+    Copies Python files from package_path into the payload, preserving
+    the directory structure relative to the source root.
+
+    For standard layouts, files are relative to the bundle root.
+    For src/ layouts, files are relative to the src/ directory so that
+    imports work correctly (e.g., `from my_pkg import ...`).
+
+    Args:
+        payload: Sandbox payload to add files to.
+        package_path: Path to the package directory.
+        bundle_roots: List of allowed bundle roots.
+    """
+    pkg_path = Path(package_path).resolve()
+
+    # Find which bundle root contains this path
+    bundle_root = None
+    for root in bundle_roots:
+        root_path = Path(root).resolve()
+        try:
+            pkg_path.relative_to(root_path)
+            bundle_root = root_path
+            break
+        except ValueError:
+            continue
+
+    if bundle_root is None:
+        # Path validation should have caught this earlier
+        return
+
+    # Check for src/ subdirectory (common package layout)
+    # When src/ exists, use it as the base for relative paths so imports work
+    src_path = pkg_path / "src"
+    if src_path.is_dir():
+        # For src/ layout: copy from src/ and calculate paths relative to src/
+        # This ensures `from my_pkg import ...` works when packages/ is on sys.path
+        _copy_python_files(payload, src_path, src_path)
+    else:
+        # For flat layout: copy from pkg_path relative to bundle_root
+        _copy_python_files(payload, pkg_path, bundle_root)
+
+
+def _copy_python_files(
+    payload: SandboxPayload,
+    source_dir: Path,
+    bundle_root: Path,
+) -> None:
+    """Copy Python files from source directory to payload.
+
+    Args:
+        payload: Sandbox payload to add files to.
+        source_dir: Source directory to copy from.
+        bundle_root: Bundle root for relative path calculation.
+    """
+    for py_file in source_dir.rglob("*.py"):
+        # Skip __pycache__ and similar
+        if "__pycache__" in py_file.parts:
+            continue
+        if ".egg-info" in str(py_file):
+            continue
+
+        # Calculate relative path from bundle root
+        try:
+            rel_path = py_file.relative_to(bundle_root)
+        except ValueError:
+            # File is not under bundle root
+            continue
+
+        # Read and add to payload
+        try:
+            content = py_file.read_text(encoding="utf-8")
+            # Use packages/ prefix for bundled sources
+            payload_path = f"packages/{rel_path}"
+            payload.files[payload_path] = content
+        except Exception as exc:
+            logger.warning(f"Skipping unreadable file '{py_file}': {exc}")
+            continue

aip_agents/ptc/custom_tools_payload.pyi

@@ -0,0 +1,31 @@
+from _typeshed import Incomplete
+from aip_agents.ptc.custom_tools import PTCCustomToolConfig as PTCCustomToolConfig, PTCToolDef as PTCToolDef
+from aip_agents.ptc.naming import sanitize_function_name as sanitize_function_name
+from aip_agents.ptc.payload import SandboxPayload as SandboxPayload
+from aip_agents.ptc.template_utils import render_template as render_template
+from aip_agents.utils.logger import get_logger as get_logger
+from dataclasses import dataclass, field
+
+logger: Incomplete
+
+@dataclass
+class CustomToolPayloadResult:
+    """Result of custom tool payload generation.
+
+    Attributes:
+        payload: The sandbox payload with files to upload.
+        tool_names: List of sanitized tool names available in sandbox.
+    """
+    payload: SandboxPayload
+    tool_names: list[str] = field(default_factory=list)
+
+def build_custom_tools_payload(config: PTCCustomToolConfig, tool_configs: dict[str, dict] | None = None) -> CustomToolPayloadResult:
+    """Build sandbox payload for custom LangChain tools.
+
+    Args:
+        config: Custom tool configuration with tool definitions.
+        tool_configs: Optional per-tool config values to write to defaults.json.
+
+    Returns:
+        CustomToolPayloadResult with payload and available tool names.
+    """

aip_agents/ptc/custom_tools_templates/__init__.py

@@ -0,0 +1 @@
+"""Templates for custom LangChain tool payload generation."""

aip_agents/ptc/custom_tools_templates/custom_build_function.py.template

@@ -0,0 +1,23 @@
+def build_$sanitized_name() -> BaseTool:
+    """Build an instance of $class_name.
+
+    Returns:
+        Configured tool instance.
+    """
+    # Check if the class is already an instance (module-level singleton)
+    tool_or_class = $class_name
+    if isinstance(tool_or_class, BaseTool):
+        tool = tool_or_class
+    else:
+        try:
+            tool = tool_or_class()
+        except TypeError as e:
+            raise TypeError(
+                f"Failed to instantiate $class_name(). "
+                "Constructor args are not supported in MVP. "
+                "Use tool_config_schema for runtime configuration. "
+                f"Original error: {e}"
+            ) from e
+
+    _configure_tool(tool, "$sanitized_name")
+    return tool

aip_agents/ptc/custom_tools_templates/custom_init.py.template

@@ -0,0 +1,15 @@
+"""Generated custom tools package for PTC sandbox execution.
+
+This package provides access to custom LangChain tools configured for this agent.
+Import tools directly:
+
+    from tools.custom import tool_name
+
+Or from specific modules:
+
+    from tools.custom.tool_name import tool_name
+"""
+
+$imports
+
+__all__ = [$all_list]

aip_agents/ptc/custom_tools_templates/custom_invoke.py.template

@@ -0,0 +1,60 @@
+"""Safe invoke helper for custom tools.
+
+This module provides a sync wrapper around tool.ainvoke for use in PTC code.
+"""
+
+import asyncio
+from typing import Any
+
+from langchain_core.tools import BaseTool
+
+
+def run_tool(tool: BaseTool, kwargs: dict[str, Any]) -> Any:
+    """Run a tool's ainvoke method synchronously.
+
+    Args:
+        tool: Tool instance to invoke.
+        kwargs: Arguments to pass to the tool.
+
+    Returns:
+        Tool execution result.
+    """
+    return _run_async_safely(tool.ainvoke(kwargs))
+
+
+def _run_async_safely(coro) -> Any:
+    """Run an async coroutine safely in sync context.
+
+    Handles the case where we may or may not be in an async context.
+
+    Args:
+        coro: Coroutine to run.
+
+    Returns:
+        Result of the coroutine.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        # No running loop - create new one
+        return asyncio.run(coro)
+
+    # Already in async context - run in a separate thread with a new loop
+    import concurrent.futures
+
+    def run_in_new_loop():
+        """Run coroutine in a new event loop in a thread."""
+        new_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(new_loop)
+        try:
+            result = new_loop.run_until_complete(coro)
+            new_loop.run_until_complete(new_loop.shutdown_asyncgens())
+            if hasattr(new_loop, "shutdown_default_executor"):
+                new_loop.run_until_complete(new_loop.shutdown_default_executor())
+            return result
+        finally:
+            new_loop.close()
+
+    with concurrent.futures.ThreadPoolExecutor() as executor:
+        future = executor.submit(run_in_new_loop)
+        return future.result()

aip_agents/ptc/custom_tools_templates/custom_registry.py.template

@@ -0,0 +1,87 @@
+"""Generated registry for custom tools.
+
+This module provides factory functions to build tool instances from metadata.
+"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from langchain_core.tools import BaseTool
+
+$imports
+
+_DEFAULTS_PATH = Path(__file__).with_name("custom_defaults.json")
+
+# Attribute name for tool config schema
+TOOL_CONFIG_SCHEMA_ATTR = "tool_config_schema"
+
+
+def _load_defaults() -> dict[str, Any]:
+    """Load tool config defaults from JSON file."""
+    if not _DEFAULTS_PATH.exists():
+        return {}
+    return json.loads(_DEFAULTS_PATH.read_text(encoding="utf-8"))
+
+
+def _inject_config_methods(tool: BaseTool, config_schema: type) -> None:
+    """Inject configuration methods into a tool instance.
+
+    Args:
+        tool: Tool instance to inject methods into.
+        config_schema: Pydantic model class for configuration validation.
+    """
+    CONFIG_SCHEMA_ATTR = "_config_schema"
+    CONFIG_ATTR = "_config"
+
+    # Add configuration attributes
+    object.__setattr__(tool, CONFIG_SCHEMA_ATTR, config_schema)
+    object.__setattr__(tool, CONFIG_ATTR, None)
+
+    def set_tool_config(config: Any) -> None:
+        """Set the tool's agent-level default configuration with validation."""
+        if config is None:
+            object.__setattr__(tool, CONFIG_ATTR, None)
+            return
+
+        config_schema_obj = getattr(tool, CONFIG_SCHEMA_ATTR)
+        if isinstance(config, dict):
+            object.__setattr__(tool, CONFIG_ATTR, config_schema_obj(**config))
+        elif isinstance(config, config_schema_obj):
+            object.__setattr__(tool, CONFIG_ATTR, config)
+        else:
+            raise ValueError(f"Config must be an instance of {config_schema_obj.__name__} or dict")
+
+    def get_tool_config(config: Any = None) -> Any:
+        """Get the effective tool configuration."""
+        return getattr(tool, CONFIG_ATTR)
+
+    # Inject methods
+    object.__setattr__(tool, "set_tool_config", set_tool_config)
+    object.__setattr__(tool, "get_tool_config", get_tool_config)
+
+
+def _configure_tool(tool: BaseTool, tool_name: str) -> None:
+    """Configure tool with defaults if it has tool_config_schema.
+
+    Args:
+        tool: Tool instance to configure.
+        tool_name: Name of the tool for defaults lookup.
+    """
+    defaults_by_tool = _load_defaults()
+    has_defaults = tool_name in defaults_by_tool
+    defaults = defaults_by_tool.get(tool_name)
+
+    # Check if tool has tool_config_schema
+    if hasattr(tool, TOOL_CONFIG_SCHEMA_ATTR):
+        # Inject config methods if not present
+        if not hasattr(tool, "get_tool_config"):
+            config_schema = getattr(tool, TOOL_CONFIG_SCHEMA_ATTR)
+            _inject_config_methods(tool, config_schema)
+
+        # Set tool config when defaults explicitly provided (even empty dict)
+        if has_defaults and hasattr(tool, "set_tool_config"):
+            tool.set_tool_config(defaults)
+
+
+$build_functions

aip_agents/ptc/custom_tools_templates/custom_sources_init.py.template

@@ -0,0 +1,7 @@
+"""Generated custom tool sources package.
+
+This package contains the source code for file-based custom tools.
+Each tool is in its own subpackage.
+"""
+
+__all__ = [$all_list]

aip_agents/ptc/custom_tools_templates/custom_wrapper.py.template

@@ -0,0 +1,19 @@
+"""Generated wrapper for custom tool: $original_name
+
+This module provides a sync wrapper for calling the tool in PTC code.
+"""
+
+from tools.custom_registry import build_$sanitized_name
+from tools.custom_invoke import run_tool
+
+
+def $sanitized_name(**kwargs):
+    """Call the $original_name tool.
+
+    Args:
+        **kwargs: Arguments to pass to the tool.
+
+    Returns:
+        Tool execution result.
+    """
+    return run_tool(build_$sanitized_name(), kwargs)

aip_agents/ptc/exceptions.py

@@ -37,3 +37,21 @@ class PTCToolError(PTCError):
         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

@@ -20,3 +20,18 @@ class PTCToolError(PTCError):
             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.
+        """