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

@@ -0,0 +1,184 @@
+from _typeshed import Incomplete
+from aip_agents.ptc.exceptions import PTCError as PTCError
+from aip_agents.ptc.naming import is_valid_identifier as is_valid_identifier, sanitize_function_name as sanitize_function_name
+from aip_agents.utils.logger import get_logger as get_logger
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, TypedDict
+
+logger: Incomplete
+
+class PTCPackageToolDef(TypedDict, total=False):
+    '''Definition for a package-based tool.
+
+    Required fields:
+        name: Tool name (used for imports and config lookup).
+        kind: Must be "package".
+        import_path: Dotted import path (e.g., "aip_agents.tools.time_tool").
+        class_name: Class name to import (e.g., "TimeTool").
+
+    Optional fields:
+        package_path: Path to source directory to bundle.
+            If omitted, the tool must already be available in sandbox (e.g., from site-packages).
+        description: Tool description (derived from tool object at construction time).
+        input_schema: JSON schema for tool input (derived from tool object at construction time).
+    '''
+    name: str
+    kind: Literal['package']
+    import_path: str
+    class_name: str
+    package_path: str
+    description: str
+    input_schema: dict
+
+class PTCFileToolDef(TypedDict, total=False):
+    '''Definition for a single-file tool.
+
+    Required fields:
+        name: Tool name (used for imports and config lookup).
+        kind: Must be "file".
+        file_path: Path to the Python file containing the tool.
+        class_name: Class name to import from the file.
+
+    Optional fields:
+        description: Tool description (derived from tool object at construction time).
+        input_schema: JSON schema for tool input (derived from tool object at construction time).
+    '''
+    name: str
+    kind: Literal['file']
+    file_path: str
+    class_name: str
+    description: str
+    input_schema: dict
+PTCToolDef = PTCPackageToolDef | PTCFileToolDef
+
+class PTCCustomToolValidationError(PTCError):
+    """Error raised when custom tool configuration is invalid."""
+
+@dataclass
+class PTCCustomToolConfig:
+    '''Configuration for custom LangChain tools in PTC sandbox.
+
+    This config controls which user-defined LangChain tools are available
+    in the sandbox for use by PTC code.
+
+    Attributes:
+        enabled: Whether custom tools are enabled.
+        bundle_roots: List of allowed root directories for bundling tool sources.
+            Paths outside these roots will cause validation errors.
+        requirements: List of pip requirements to install in sandbox.
+        tools: List of tool definitions (package or file tools).
+
+    Example:
+        >>> config = PTCCustomToolConfig(
+        ...     enabled=True,
+        ...     bundle_roots=["/app/tools"],
+        ...     requirements=["pydantic>=2.0"],
+        ...     tools=[
+        ...         {
+        ...             "name": "time_tool",
+        ...             "kind": "package",
+        ...             "import_path": "aip_agents.tools.time_tool",
+        ...             "class_name": "TimeTool",
+        ...         },
+        ...     ],
+        ... )
+    '''
+    enabled: bool = ...
+    bundle_roots: list[str] = field(default_factory=list)
+    requirements: list[str] = field(default_factory=list)
+    tools: list[PTCToolDef] = field(default_factory=list)
+
+def validate_tool_def(tool: PTCToolDef) -> None:
+    """Validate a tool definition has required fields.
+
+    Args:
+        tool: Tool definition to validate.
+
+    Raises:
+        PTCCustomToolValidationError: If tool definition is invalid.
+    """
+def validate_path_within_bundle_roots(path: str | Path, bundle_roots: list[str], tool_name: str) -> None:
+    """Validate that a path is within one of the bundle roots.
+
+    Args:
+        path: Path to validate.
+        bundle_roots: List of allowed root directories.
+        tool_name: Tool name for error messages.
+
+    Raises:
+        PTCCustomToolValidationError: If path is outside all bundle roots.
+    """
+def detect_relative_imports(file_path: str | Path) -> list[str]:
+    """Detect relative imports in a Python file using AST.
+
+    Args:
+        file_path: Path to the Python file to scan.
+
+    Returns:
+        List of relative import statements found.
+
+    Raises:
+        PTCCustomToolValidationError: If file cannot be read or parsed.
+    """
+def check_name_collisions(tools: list[PTCToolDef]) -> None:
+    """Check for tool name collisions after sanitization.
+
+    Args:
+        tools: List of tool definitions.
+
+    Raises:
+        PTCCustomToolValidationError: If two tools sanitize to the same name.
+    """
+def validate_custom_tool_config(config: PTCCustomToolConfig) -> None:
+    """Validate the complete custom tool configuration.
+
+    This runs all validation checks:
+    - Tool definitions have required fields
+    - Paths are within bundle roots
+    - File tools don't use relative imports
+    - No name collisions
+
+    Args:
+        config: Custom tool configuration to validate.
+
+    Raises:
+        PTCCustomToolValidationError: If configuration is invalid.
+    """
+def extract_tool_metadata(tool: object) -> dict:
+    '''Extract metadata from a LangChain BaseTool instance.
+
+    Extracts name, description, and input_schema from the tool object.
+    This is called at agent construction time to populate tool definitions.
+
+    Args:
+        tool: A LangChain BaseTool instance (or compatible object).
+
+    Returns:
+        Dict with keys:
+        - name: str (tool name)
+        - description: str (tool description, empty if not available)
+        - input_schema: dict (JSON schema, empty object schema if not available)
+
+    Note:
+        If schema inference fails, returns an empty object schema
+        ({"type": "object", "properties": {}}) so prompt/index output
+        falls back to tool(**kwargs).
+    '''
+def enrich_tool_def_with_metadata(tool_def: PTCToolDef, tool: object) -> PTCToolDef:
+    """Enrich a tool definition with metadata extracted from the tool object.
+
+    Always derives description and input_schema from the tool object, overwriting
+    any user-supplied values. This ensures the tool object is the source of truth.
+    Called at agent construction time.
+
+    Args:
+        tool_def: The tool definition to enrich.
+        tool: The LangChain BaseTool instance.
+
+    Returns:
+        The tool definition with description and input_schema populated from the tool object.
+
+    Raises:
+        PTCCustomToolValidationError: If tool name in metadata does not match tool_def name.
+    """

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.as_posix()}"
+            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]