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

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/resilience/__init__.py

@@ -0,0 +1,10 @@
+"""Resilience execution utilities.
+
+Author:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from aip_agents.resilience.base import BaseResilienceExecutor, ResilienceRequest
+from aip_agents.resilience.tool import ToolResilienceExecutor
+
+__all__ = ["BaseResilienceExecutor", "ResilienceRequest", "ToolResilienceExecutor"]

aip_agents/resilience/base.py

@@ -0,0 +1,46 @@
+"""Reusable resilience primitives for async operation execution.
+
+Author:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+InvokeWithTimeout = Callable[[float], Awaitable[Any]]
+
+
+@dataclass(frozen=True)
+class ResilienceRequest:
+    """Execution request shared by resilience executors.
+
+    Attributes:
+        operation_name: Stable operation identity, for example a tool name.
+        operation_source: Source label used in diagnostics and user metadata.
+        metadata: Optional runtime metadata containing resilience overrides.
+        invoke_with_timeout: Async callable that executes one attempt with an effective timeout.
+    """
+
+    operation_name: str
+    operation_source: str
+    metadata: dict[str, Any] | None
+    invoke_with_timeout: InvokeWithTimeout
+
+
+class BaseResilienceExecutor(ABC):
+    """Base contract for reusable resilience executors."""
+
+    @abstractmethod
+    async def execute(self, request: ResilienceRequest) -> Any:
+        """Execute one operation request with resilience behavior.
+
+        Args:
+            request: Shared execution request with metadata and invocation callback.
+
+        Returns:
+            Operation output or structured error payload.
+        """