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

@@ -0,0 +1,59 @@
+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.naming import example_value_from_schema as example_value_from_schema, sanitize_function_name as sanitize_function_name, sanitize_module_name_with_reserved as sanitize_module_name_with_reserved, sanitize_param_name as sanitize_param_name, schema_to_params as schema_to_params
+from aip_agents.utils.logger import get_logger as get_logger
+from dataclasses import dataclass
+
+logger: Incomplete
+PromptMode: Incomplete
+PYTHON_BLOCK_START: str
+
+@dataclass
+class PromptConfig:
+    """Configuration for PTC prompt generation.
+
+    Attributes:
+        mode: Prompt mode - minimal, index, full, or auto.
+        auto_threshold: Total tool count threshold for auto mode (default 10).
+        include_example: Whether to include example code in prompt.
+    """
+    mode: PromptMode = ...
+    auto_threshold: int = ...
+    include_example: bool = ...
+
+PTC_USAGE_RULES: str
+
+def build_ptc_prompt(mcp_client: BaseMCPClient | None = None, config: PromptConfig | None = None, custom_tools_config: PTCCustomToolConfig | None = None) -> str:
+    """Build PTC usage guidance prompt from MCP and custom tool configurations.
+
+    Generates a short usage block that includes:
+    - The import patterns: MCP (`from tools.<server> import <tool>`) and
+      custom (`from tools.custom import <tool>`)
+    - Rule: use `print()`; only printed output returns
+    - Rule: parameter names are sanitized to lowercase/underscored
+    - Prompt mode content (minimal/index/full)
+    - Examples based on the resolved prompt mode
+
+    Args:
+        mcp_client: The MCP client with configured servers. Can be None if only custom tools.
+        config: Prompt configuration. If None, uses default PromptConfig.
+        custom_tools_config: Optional custom LangChain tools configuration.
+
+    Returns:
+        PTC usage guidance prompt string.
+    """
+def compute_ptc_prompt_hash(mcp_client: BaseMCPClient | None = None, config: PromptConfig | None = None, custom_tools_config: PTCCustomToolConfig | None = None) -> str:
+    """Compute a hash of the MCP and custom tool configuration for change detection.
+
+    Includes PromptConfig fields, allowed_tools, and custom tools in hash computation
+    so prompt updates re-sync correctly when configuration changes.
+
+    Args:
+        mcp_client: MCP client instance. Can be None if only custom tools.
+        config: Prompt configuration. If None, uses default PromptConfig.
+        custom_tools_config: Optional custom LangChain tools configuration.
+
+    Returns:
+        Hash string representing current configuration.
+    """

aip_agents/ptc/ptc_helper.py

@@ -0,0 +1,16 @@
+"""PTC helper module generation utilities."""
+
+from __future__ import annotations
+
+from aip_agents.ptc.template_utils import render_template
+
+_TEMPLATE_PACKAGE = "aip_agents.ptc.templates"
+
+
+def _generate_ptc_helper_module() -> str:
+    """Generate the tools/ptc_helper.py discovery module.
+
+    Returns:
+        Python source code for the PTC helper module.
+    """
+    return render_template(_TEMPLATE_PACKAGE, "ptc_helper.py.template")

aip_agents/ptc/ptc_helper.pyi

@@ -0,0 +1 @@
+from aip_agents.ptc.template_utils import render_template as render_template

aip_agents/ptc/sandbox_bridge.py

@@ -0,0 +1,256 @@
+"""Top-level PTC Sandbox Bridge.
+
+This module provides the unified entry point for building sandbox payloads
+across different tool sources (MCP, custom tools, etc.).
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient
+from aip_agents.ptc.custom_tools import (
+    PTCCustomToolConfig,
+    validate_custom_tool_config,
+)
+from aip_agents.ptc.custom_tools_payload import build_custom_tools_payload
+from aip_agents.ptc.doc_gen import (
+    render_tool_doc,
+)
+from aip_agents.ptc.exceptions import PTCPayloadConflictError
+from aip_agents.ptc.mcp.sandbox_bridge import build_mcp_payload
+from aip_agents.ptc.naming import sanitize_function_name, schema_to_params
+from aip_agents.ptc.payload import SandboxPayload
+from aip_agents.ptc.ptc_helper import _generate_ptc_helper_module
+
+
+async def build_sandbox_payload(
+    mcp_client: BaseMCPClient | None = None,
+    default_tool_timeout: float = 60.0,
+    custom_tools_config: PTCCustomToolConfig | None = None,
+    tool_configs: dict[str, dict] | None = None,
+) -> SandboxPayload:
+    """Build sandbox payload from all configured tool sources.
+
+    Composes MCP and custom LangChain tool payloads into a single payload.
+
+    Args:
+        mcp_client: The MCP client with configured servers. Can be None if only custom tools.
+        default_tool_timeout: Default timeout for tool calls in seconds.
+        custom_tools_config: Optional custom LangChain tools configuration.
+        tool_configs: Optional per-tool config values for custom tools.
+
+    Returns:
+        SandboxPayload containing files and env vars for the sandbox.
+    """
+    # Build MCP payload
+    mcp_payload = SandboxPayload()
+    if mcp_client:
+        mcp_payload = await build_mcp_payload(mcp_client, default_tool_timeout)
+
+    # Build custom tools payload if enabled
+    custom_payload = SandboxPayload()
+    if custom_tools_config and custom_tools_config.enabled:
+        # Validate config before building payload (fail fast)
+        validate_custom_tool_config(custom_tools_config)
+        result = build_custom_tools_payload(custom_tools_config, tool_configs)
+        custom_payload = result.payload
+
+    # Check for conflicts before merging payloads
+    _check_payload_conflicts(mcp_payload, custom_payload)
+
+    # Merge payloads (custom tools files should not conflict with MCP files)
+    merged = SandboxPayload()
+    merged.files.update(mcp_payload.files)
+    merged.files.update(custom_payload.files)
+    merged.per_run_files.update(mcp_payload.per_run_files)
+    merged.per_run_files.update(custom_payload.per_run_files)
+    merged.env.update(mcp_payload.env)
+    merged.env.update(custom_payload.env)
+
+    # Merge custom tools into ptc_index.json
+    if custom_tools_config and custom_tools_config.enabled and custom_tools_config.tools:
+        merged.files["tools/ptc_index.json"] = _merge_custom_tools_into_index(
+            merged.files.get("tools/ptc_index.json"),
+            custom_tools_config,
+        )
+        if "tools/ptc_helper.py" not in merged.files:
+            merged.files["tools/ptc_helper.py"] = _generate_ptc_helper_module()
+        # Generate documentation for custom tools
+        custom_docs = _generate_custom_tool_docs(custom_tools_config)
+        merged.files.update(custom_docs)
+
+    return merged
+
+
+def _check_payload_conflicts(
+    mcp_payload: SandboxPayload,
+    custom_payload: SandboxPayload,
+) -> None:
+    """Check for conflicts between MCP and custom tool payloads.
+
+    Args:
+        mcp_payload: Payload from MCP tool configuration.
+        custom_payload: Payload from custom tool configuration.
+
+    Raises:
+        PTCPayloadConflictError: If any conflicts are detected in files,
+            per-run files, or environment variables.
+    """
+    mcp_files = set(mcp_payload.files.keys())
+    custom_files = set(custom_payload.files.keys())
+    file_conflicts = mcp_files & custom_files
+
+    mcp_per_run = set(mcp_payload.per_run_files.keys())
+    custom_per_run = set(custom_payload.per_run_files.keys())
+    per_run_conflicts = mcp_per_run & custom_per_run
+
+    mcp_env_keys = set(mcp_payload.env.keys())
+    custom_env_keys = set(custom_payload.env.keys())
+    env_conflicts = mcp_env_keys & custom_env_keys
+
+    all_conflicts = file_conflicts | per_run_conflicts | env_conflicts
+    if all_conflicts:
+        raise PTCPayloadConflictError(
+            f"Conflicts detected when merging MCP and custom tool payloads. "
+            f"Files: {sorted(file_conflicts)}, "
+            f"Per-run files: {sorted(per_run_conflicts)}, "
+            f"Environment variables: {sorted(env_conflicts)}",
+            conflicts=all_conflicts,
+        )
+
+
+def _merge_custom_tools_into_index(
+    existing_index_json: str | None,
+    custom_tools_config: PTCCustomToolConfig,
+) -> str:
+    """Merge custom tools into the ptc_index.json.
+
+    Args:
+        existing_index_json: Existing ptc_index.json content (may be None).
+        custom_tools_config: Custom tools configuration.
+
+    Returns:
+        Updated JSON string with custom tools included.
+    """
+    # Parse existing index or create new one
+    if existing_index_json:
+        index = json.loads(existing_index_json)
+    else:
+        index = {"packages": {}}
+
+    # Add custom tools package
+    tool_entries = []
+    for tool_def in sorted(custom_tools_config.tools, key=lambda t: sanitize_function_name(t.get("name", ""))):
+        name = tool_def.get("name", "")
+        func_name = sanitize_function_name(name)
+        schema = tool_def.get("input_schema", {"type": "object", "properties": {}})
+        signature = f"{func_name}({schema_to_params(schema)})"
+
+        tool_entries.append(
+            {
+                "name": func_name,
+                "signature": signature,
+                "doc_path": f"tools/docs/custom/{func_name}.md",
+            }
+        )
+
+    index["packages"]["custom"] = {"tools": tool_entries}
+
+    return json.dumps(index, indent=2, sort_keys=True)
+
+
+def _generate_custom_tool_docs(custom_tools_config: PTCCustomToolConfig) -> dict[str, str]:
+    """Generate documentation files for custom tools.
+
+    Args:
+        custom_tools_config: Custom tools configuration.
+
+    Returns:
+        Dict mapping file path to content.
+    """
+    docs: dict[str, str] = {}
+
+    for tool_def in sorted(custom_tools_config.tools, key=lambda t: sanitize_function_name(t.get("name", ""))):
+        name = tool_def.get("name", "")
+        func_name = sanitize_function_name(name)
+        description = tool_def.get("description", "")
+        schema = tool_def.get("input_schema", {"type": "object", "properties": {}})
+
+        doc_content = _generate_tool_doc_content(func_name, description, schema)
+        docs[f"tools/docs/custom/{func_name}.md"] = doc_content
+
+    return docs
+
+
+def _generate_tool_doc_content(
+    func_name: str,
+    description: str,
+    schema: dict[str, Any],
+) -> str:
+    """Generate markdown documentation for a single tool.
+
+    Args:
+        func_name: Sanitized function name.
+        description: Tool description.
+        schema: JSON schema for tool input.
+
+    Returns:
+        Markdown documentation string.
+    """
+    # Use schema_to_params for consistent signatures
+    params = schema_to_params(schema)
+    signature = f"{func_name}({params})"
+
+    example_code = f"from tools.custom import {func_name}\nresult = {func_name}(...)\nprint(result)"
+
+    return render_tool_doc(
+        func_name=func_name,
+        signature=signature,
+        description=description,
+        schema=schema,
+        example_code=example_code,
+    )
+
+
+def wrap_ptc_code(code: str, include_packages_path: bool = False) -> str:
+    """Wrap user PTC code with necessary imports and setup.
+
+    This prepends sys.path setup to ensure the tools package is importable.
+    When custom tools with bundled package sources are enabled, also adds
+    the packages/ directory to sys.path.
+
+    Args:
+        code: User-provided Python code.
+        include_packages_path: If True, also add packages/ dir to sys.path
+            for bundled package sources from custom LangChain tools.
+
+    Returns:
+        Wrapped code ready for sandbox execution.
+    """
+    preamble = """# PTC Code Wrapper - Auto-generated
+import sys
+import os
+
+# Add tools package to path
+_tools_dir = os.path.dirname(os.path.abspath(__file__)) if "__file__" in dir() else os.getcwd()
+if _tools_dir not in sys.path:
+    sys.path.insert(0, _tools_dir)
+"""
+
+    if include_packages_path:
+        preamble += """
+# Add packages directory to path for bundled custom tool sources
+_packages_dir = os.path.join(_tools_dir, "packages")
+if os.path.isdir(_packages_dir) and _packages_dir not in sys.path:
+    sys.path.insert(0, _packages_dir)
+"""
+
+    preamble += """
+# User code below
+"""
+    return preamble + code

aip_agents/ptc/sandbox_bridge.pyi

@@ -0,0 +1,38 @@
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient as BaseMCPClient
+from aip_agents.ptc.custom_tools import PTCCustomToolConfig as PTCCustomToolConfig, validate_custom_tool_config as validate_custom_tool_config
+from aip_agents.ptc.custom_tools_payload import build_custom_tools_payload as build_custom_tools_payload
+from aip_agents.ptc.doc_gen import render_tool_doc as render_tool_doc
+from aip_agents.ptc.exceptions import PTCPayloadConflictError as PTCPayloadConflictError
+from aip_agents.ptc.mcp.sandbox_bridge import build_mcp_payload as build_mcp_payload
+from aip_agents.ptc.naming import sanitize_function_name as sanitize_function_name, schema_to_params as schema_to_params
+from aip_agents.ptc.payload import SandboxPayload as SandboxPayload
+
+async def build_sandbox_payload(mcp_client: BaseMCPClient | None = None, default_tool_timeout: float = 60.0, custom_tools_config: PTCCustomToolConfig | None = None, tool_configs: dict[str, dict] | None = None) -> SandboxPayload:
+    """Build sandbox payload from all configured tool sources.
+
+    Composes MCP and custom LangChain tool payloads into a single payload.
+
+    Args:
+        mcp_client: The MCP client with configured servers. Can be None if only custom tools.
+        default_tool_timeout: Default timeout for tool calls in seconds.
+        custom_tools_config: Optional custom LangChain tools configuration.
+        tool_configs: Optional per-tool config values for custom tools.
+
+    Returns:
+        SandboxPayload containing files and env vars for the sandbox.
+    """
+def wrap_ptc_code(code: str, include_packages_path: bool = False) -> str:
+    """Wrap user PTC code with necessary imports and setup.
+
+    This prepends sys.path setup to ensure the tools package is importable.
+    When custom tools with bundled package sources are enabled, also adds
+    the packages/ directory to sys.path.
+
+    Args:
+        code: User-provided Python code.
+        include_packages_path: If True, also add packages/ dir to sys.path
+            for bundled package sources from custom LangChain tools.
+
+    Returns:
+        Wrapped code ready for sandbox execution.
+    """

aip_agents/ptc/template_utils.py

@@ -0,0 +1,33 @@
+"""Template rendering helpers for PTC payloads.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import resources
+from string import Template
+
+
+def render_template(
+    package: str,
+    template_name: str,
+    values: Mapping[str, str] | None = None,
+) -> str:
+    """Render a template from package resources with optional substitutions.
+
+    Args:
+        package: Package path containing the template.
+        template_name: Template filename.
+        values: Optional mapping of template variables.
+
+    Returns:
+        Rendered template content.
+    """
+    template_file = resources.files(package).joinpath(template_name)
+    template_text = template_file.read_text(encoding="utf-8")
+    if not values:
+        return template_text
+    return Template(template_text).substitute(values)

aip_agents/ptc/template_utils.pyi

@@ -0,0 +1,13 @@
+from collections.abc import Mapping
+
+def render_template(package: str, template_name: str, values: Mapping[str, str] | None = None) -> str:
+    """Render a template from package resources with optional substitutions.
+
+    Args:
+        package: Package path containing the template.
+        template_name: Template filename.
+        values: Optional mapping of template variables.
+
+    Returns:
+        Rendered template content.
+    """

aip_agents/ptc/templates/__init__.py

@@ -0,0 +1 @@
+"""Shared templates for PTC sandbox code generation."""

aip_agents/ptc/templates/ptc_helper.py.template

@@ -0,0 +1,134 @@
+"""PTC Discovery Helper Module.
+
+This module provides discovery functions for exploring available PTC tools
+inside the PTC sandbox. Use these functions to find packages, list tools,
+and get detailed documentation.
+
+Usage:
+    from tools.ptc_helper import list_packages, list_tools, describe_tool
+
+    # List all available packages
+    packages = list_packages()
+
+    # List tools in a package
+    tools = list_tools("package_name")
+
+    # Get tool documentation
+    doc = describe_tool("package_name", "tool_name")
+"""
+
+import difflib
+import json
+import os
+from typing import Any
+
+# Load the index at module import time
+_INDEX_PATH = os.path.join(os.path.dirname(__file__), "ptc_index.json")
+_DOCS_DIR = os.path.join(os.path.dirname(__file__), "docs")
+
+_index: dict[str, Any] = {}
+if os.path.exists(_INDEX_PATH):
+    with open(_INDEX_PATH, "r") as f:
+        _index = json.load(f)
+
+
+def _suggest_closest(name: str, valid_names: list[str], kind: str = "name") -> str:
+    """Generate a suggestion message for closest match.
+
+    Args:
+        name: The name that was not found.
+        valid_names: List of valid names to match against.
+        kind: Type of name (package or tool) for the error message.
+
+    Returns:
+        Suggestion string or empty string if no close match.
+    """
+    matches = difflib.get_close_matches(name, valid_names, n=1, cutoff=0.6)
+    if matches:
+        return f" Did you mean '{matches[0]}'?"
+    return ""
+
+
+def list_packages() -> list[str]:
+    """List all available package names.
+
+    Returns:
+        Sorted list of sanitized package names.
+    """
+    packages = _index.get("packages", {})
+    return sorted(packages.keys())
+
+
+def list_tools(package: str) -> list[dict[str, str]]:
+    """List tools available in a package.
+
+    Args:
+        package: Sanitized package name (e.g., 'deepwiki').
+
+    Returns:
+        List of tool info dicts with 'name' keys.
+
+    Raises:
+        ValueError: If package is not found.
+    """
+    packages = _index.get("packages", {})
+    if package not in packages:
+        valid = list(packages.keys())
+        suggestion = _suggest_closest(package, valid, "package")
+        raise ValueError(f"Unknown package '{package}'.{suggestion}")
+
+    pkg_data = packages[package]
+    tools = pkg_data.get("tools", [])
+    return [{"name": t["name"]} for t in tools]
+
+
+def describe_tool(package: str, tool: str) -> dict[str, Any]:
+    """Get detailed documentation for a tool.
+
+    Args:
+        package: Sanitized package name.
+        tool: Sanitized tool name.
+
+    Returns:
+        Dict with 'name', 'signature', 'doc', and 'doc_path' keys.
+
+    Raises:
+        ValueError: If package or tool is not found.
+    """
+    packages = _index.get("packages", {})
+    if package not in packages:
+        valid = list(packages.keys())
+        suggestion = _suggest_closest(package, valid, "package")
+        raise ValueError(f"Unknown package '{package}'.{suggestion}")
+
+    pkg_data = packages[package]
+    tools = pkg_data.get("tools", [])
+    tool_names = [t["name"] for t in tools]
+
+    if tool not in tool_names:
+        suggestion = _suggest_closest(tool, tool_names, "tool")
+        raise ValueError(f"Unknown tool '{tool}' in package '{package}'.{suggestion}")
+
+    tool_info = next(t for t in tools if t["name"] == tool)
+    doc_path = tool_info.get("doc_path", "")
+
+    doc_content = ""
+    if doc_path:
+        full_path = os.path.join(os.path.dirname(__file__), doc_path.replace("tools/", ""))
+        if os.path.exists(full_path):
+            with open(full_path, "r") as f:
+                doc_content = f.read()
+        else:
+            doc_content = f"# {tool}\n\n**Signature:** `{tool_info.get('signature', f'{tool}(**kwargs: Any)')}`"
+    else:
+        doc_content = f"# {tool}\n\n**Signature:** `{tool_info.get('signature', f'{tool}(**kwargs: Any)')}`"
+
+    return {
+        "name": tool,
+        "signature": tool_info.get("signature", f"{tool}(**kwargs)"),
+        "doc": doc_content,
+        "doc_path": doc_path,
+    }
+
+
+__all__ = ["list_packages", "list_tools", "describe_tool"]

aip_agents/ptc/tool_def_helpers.py

@@ -0,0 +1,101 @@
+"""Helper functions for constructing PTC tool definitions.
+
+Author: Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+
+These helpers provide a cleaner API for defining custom tools in PTCCustomToolConfig.
+They return properly-typed dictionaries that can be used in PTCCustomToolConfig.tools.
+
+Example:
+    >>> from aip_agents.ptc import package_tool, file_tool, PTCCustomToolConfig
+    >>> config = PTCCustomToolConfig(
+    ...     enabled=True,
+    ...     tools=[
+    ...         package_tool("time_tool", import_path="aip_agents.tools.time_tool", class_name="TimeTool"),
+    ...         file_tool("multiply", file_path="/path/to/multiply.py", class_name="MultiplyTool"),
+    ...     ]
+    ... )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aip_agents.ptc.custom_tools import PTCFileToolDef, PTCPackageToolDef
+
+
+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'}
+    """
+    result: PTCPackageToolDef = {
+        "name": name,
+        "kind": "package",
+        "import_path": import_path,
+        "class_name": class_name,
+    }
+    if package_path is not None:
+        result["package_path"] = package_path
+    if description is not None:
+        result["description"] = description
+    if input_schema is not None:
+        result["input_schema"] = input_schema
+    return result
+
+
+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'}
+    """
+    result: PTCFileToolDef = {
+        "name": name,
+        "kind": "file",
+        "file_path": file_path,
+        "class_name": class_name,
+    }
+    if description is not None:
+        result["description"] = description
+    if input_schema is not None:
+        result["input_schema"] = input_schema
+    return result