aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/ptc/custom_tools_templates/custom_registry.py.template

@@ -0,0 +1,112 @@
+"""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
+
+_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)
+
+
+def build_runtime_config(tool_name: str) -> dict[str, Any]:
+    """Build runtime config metadata for a custom tool invocation.
+
+    Args:
+        tool_name: Sanitized tool name to look up defaults.
+
+    Returns:
+        Dict with metadata key containing flattened defaults and tool_configs.
+    """
+    defaults_by_tool = _load_defaults()
+    defaults = defaults_by_tool.get(tool_name) or {}
+    # Build metadata without aliasing the original defaults dict so a
+    # pre-existing tool_configs key in custom_defaults.json does not produce
+    # a self-referential metadata dict. Filter out tool_configs first; the
+    # merged value is rebuilt below.
+    metadata = {k: v for k, v in defaults.items() if k != "tool_configs"}
+    existing_tool_configs = defaults.get("tool_configs")
+    if isinstance(existing_tool_configs, dict):
+        tool_configs = dict(existing_tool_configs)
+    else:
+        # Tolerate malformed (non-dict) tool_configs entries without raising.
+        tool_configs = {}
+    tool_configs[tool_name] = dict(metadata)
+    metadata["tool_configs"] = tool_configs
+    return {"metadata": metadata}
+
+
+$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,87 @@
+"""Generated wrapper for custom tool: $original_name
+
+This module provides a sync wrapper for calling the tool in PTC code.
+"""
+
+import inspect
+from typing import Any
+
+from tools.custom_registry import build_$sanitized_name, build_runtime_config
+from tools.custom_invoke import run_tool
+
+_SCHEMA_TO_PARAM = $schema_to_param
+_PARAM_TO_SCHEMA = $param_to_schema
+_REQUIRED_PARAMS = $required_params
+_OPTIONAL_PARAMS = $optional_params
+
+
+def _resolve_logical_param(input_key: str) -> str | None:
+    """Resolve incoming key to logical sanitized parameter name."""
+    if input_key in _SCHEMA_TO_PARAM:
+        return _SCHEMA_TO_PARAM[input_key]
+    if input_key in _PARAM_TO_SCHEMA:
+        return input_key
+    return None
+
+
+def _normalize_arguments(args: tuple[Any, ...], kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Normalize supported call patterns into final tool arguments."""
+    if len(args) > 1:
+        raise TypeError("expected at most one positional dict")
+
+    positional_payload: dict[str, Any] = {}
+    if args:
+        first_arg = args[0]
+        if not isinstance(first_arg, dict):
+            raise TypeError("expected at most one positional dict")
+        positional_payload = first_arg
+
+    known_values: dict[str, Any] = {}
+    passthrough: dict[str, Any] = {}
+    seen_sources: dict[str, str] = {}
+
+    for source_dict in (positional_payload, kwargs):
+        for input_key, value in source_dict.items():
+            logical_param = _resolve_logical_param(input_key)
+            if logical_param is None:
+                passthrough[input_key] = value
+                continue
+
+            prior_key = seen_sources.get(logical_param)
+            if prior_key is not None:
+                raise TypeError(
+                    f"duplicate argument for {logical_param}: conflicting keys '{prior_key}' and '{input_key}'"
+                )
+
+            seen_sources[logical_param] = input_key
+            known_values[logical_param] = value
+
+    for required_param in _REQUIRED_PARAMS:
+        if required_param not in known_values:
+            raise TypeError(f"missing required argument: {required_param}")
+
+    arguments: dict[str, Any] = {}
+    for param_name, value in known_values.items():
+        if param_name in _OPTIONAL_PARAMS and value is None:
+            continue
+        schema_key = _PARAM_TO_SCHEMA.get(param_name, param_name)
+        arguments[schema_key] = value
+
+    arguments.update(passthrough)
+    return arguments
+
+
+def $sanitized_name(*args: Any, **kwargs: Any):
+    """Call $original_name with signature: ($canonical_params).
+
+    Supports kwargs and a single positional dict compatibility payload.
+    """
+    arguments = _normalize_arguments(args, kwargs)
+    return run_tool(build_$sanitized_name(), arguments, config=build_runtime_config("$sanitized_name"))
+
+
+$sanitized_name.__signature__ = inspect.Signature(
+    parameters=[
+        $runtime_signature_params
+    ]
+)

aip_agents/ptc/doc_gen.py

@@ -0,0 +1,122 @@
+"""Documentation generation utilities for PTC.
+
+Shared constants and helpers for generating tool documentation in sandbox payloads.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from typing import Any
+
+from aip_agents.ptc.naming import sanitize_function_name
+
+# Documentation limits (fixed constants per plan)
+DOC_DESC_LIMIT = 120  # Tool description trim limit
+DOC_PARAM_DESC_LIMIT = 80  # Parameter description trim limit
+
+
+def json_type_to_display(json_type: Any) -> str:
+    """Convert JSON type to display string.
+
+    Args:
+        json_type: JSON schema type.
+
+    Returns:
+        Human-readable type string.
+    """
+    if isinstance(json_type, list):
+        return "any"
+    type_map = {
+        "string": "str",
+        "integer": "int",
+        "number": "float",
+        "boolean": "bool",
+        "array": "list",
+        "object": "dict",
+        "null": "None",
+    }
+    return type_map.get(str(json_type), "any")
+
+
+def trim_text(text: str | None, limit: int) -> str:
+    """Trim text to limit with ellipsis if needed.
+
+    Args:
+        text: Text to trim.
+        limit: Maximum length before trimming.
+
+    Returns:
+        Trimmed text.
+    """
+    if not text:
+        return ""
+    if len(text) > limit:
+        return text[:limit] + "..."
+    return text
+
+
+def render_tool_doc(
+    func_name: str,
+    signature: str,
+    description: str,
+    schema: dict[str, Any],
+    is_stub: bool = False,
+    example_code: str | None = None,
+    example_heading: str = "## Example",
+) -> str:
+    """Render markdown documentation for a tool.
+
+    Args:
+        func_name: Sanitized function name.
+        signature: Full function signature.
+        description: Tool description.
+        schema: Input schema for parameters.
+        is_stub: Whether this is a stub documentation.
+        example_code: Optional example code block content (without ```python).
+        example_heading: Heading for the example section.
+
+    Returns:
+        Markdown documentation string.
+    """
+    if is_stub:
+        desc = "Details unavailable because tool definitions are not loaded yet."
+    else:
+        desc = trim_text(description, DOC_DESC_LIMIT) or "No description available."
+
+    lines = [
+        f"# {func_name}",
+        "",
+        f"**Description:** {desc}",
+        "",
+        f"**Signature:** `{signature}`",
+        "",
+    ]
+
+    # Add parameters section
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    if properties:
+        lines.append("## Parameters")
+        lines.append("")
+        for prop_name, prop_schema in sorted(properties.items()):
+            safe_param = sanitize_function_name(prop_name)
+            prop_type = json_type_to_display(prop_schema.get("type", "any"))
+            is_required = "required" if prop_name in required else "optional"
+
+            # Trim param description
+            raw_param_desc = prop_schema.get("description", "")
+            param_desc = trim_text(raw_param_desc, DOC_PARAM_DESC_LIMIT)
+
+            lines.append(f"- **{safe_param}** ({prop_type}, {is_required}): {param_desc}")
+        lines.append("")
+
+    # Add example section
+    if example_code:
+        lines.append(example_heading)
+        lines.append("")
+        lines.append("```python")
+        lines.append(example_code)
+        lines.append("```")
+
+    return "\n".join(lines)

aip_agents/ptc/exceptions.py

@@ -0,0 +1,57 @@
+"""PTC-specific exceptions.
+
+This module defines exceptions for Programmatic Tool Calling operations.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+
+class PTCError(Exception):
+    """Base exception for PTC errors."""
+
+    pass
+
+
+class PTCToolError(PTCError):
+    """Error during tool execution.
+
+    Attributes:
+        server_name: The MCP server where the error occurred.
+        tool_name: The tool that failed.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        server_name: str | None = None,
+        tool_name: str | None = None,
+    ) -> None:
+        """Initialize PTCToolError.
+
+        Args:
+            message: Error message.
+            server_name: The MCP server name (optional).
+            tool_name: The tool name (optional).
+        """
+        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