aip-agents-binary 0.5.20__py3-none-manylinux_2_31_x86_64.whl

aip_agents/agent/hitl/manager.pyi

@@ -0,0 +1,200 @@
+from _typeshed import Incomplete
+from aip_agents.agent.hitl.config import ToolApprovalConfig as ToolApprovalConfig
+from aip_agents.agent.hitl.prompt import BasePromptHandler as BasePromptHandler, DeferredPromptHandler as DeferredPromptHandler
+from aip_agents.agent.hitl.registry import hitl_registry as hitl_registry
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalLogEntry as ApprovalLogEntry, ApprovalRequest as ApprovalRequest
+from collections.abc import Callable as Callable, Iterable
+from typing import Any
+
+MAX_ARGUMENTS_PREVIEW_LENGTH: int
+DECISION_MESSAGE_MAP: Incomplete
+TOOL_EXECUTION_BLOCKING_DECISIONS: Incomplete
+
+class ApprovalManager:
+    """Manages the HITL approval workflow for tools.
+
+    This class coordinates the approval process from configuration through
+    to final decision, handling timeouts and cleanup.
+    """
+    def __init__(self, prompt_handler: BasePromptHandler | None = None) -> None:
+        """Initialize the approval manager.
+
+        Args:
+            prompt_handler: Optional prompt handler for user interaction.
+                Defaults to DeferredPromptHandler which exposes pending requests
+                for out-of-band resolution.
+        """
+    def create_approval_request(self, tool_name: str, arguments: dict[str, Any], config: ToolApprovalConfig, context: dict[str, str] | None = None) -> ApprovalRequest:
+        """Create a new approval request for a tool call.
+
+        Args:
+            tool_name: Name of the tool being called.
+            arguments: Tool arguments (will be JSON serialized).
+            config: Approval configuration for this tool.
+            context: Optional context metadata. Defaults to None.
+
+        Returns:
+            The created approval request.
+        """
+    def get_pending_request(self, request_id: str) -> ApprovalRequest | None:
+        """Get a pending approval request by ID.
+
+        Args:
+            request_id: The unique identifier of the approval request.
+
+        Returns:
+            The pending approval request if found, None otherwise.
+        """
+    def approve_request(self, request: ApprovalRequest, operator_input: str = 'approved') -> ApprovalDecision:
+        '''Record an approval decision for a request.
+
+        This method creates an approval decision, calculates latency metrics,
+        and removes the request from the active requests queue.
+
+        Args:
+            request: The approval request to approve.
+            operator_input: Raw operator input that led to this decision. Defaults to "approved".
+
+        Returns:
+            The recorded approval decision.
+        '''
+    def reject_request(self, request: ApprovalRequest, operator_input: str = 'rejected') -> ApprovalDecision:
+        '''Record a rejection decision for a request.
+
+        This method creates a rejection decision, calculates latency metrics,
+        and removes the request from the active requests queue.
+
+        Args:
+            request: The approval request to reject.
+            operator_input: Raw operator input that led to this decision. Defaults to "rejected".
+
+        Returns:
+            The recorded rejection decision.
+        '''
+    def skip_request(self, request: ApprovalRequest, operator_input: str = 'skipped') -> ApprovalDecision:
+        '''Record a skip decision for a request.
+
+        This method creates a skip decision, calculates latency metrics,
+        and removes the request from the active requests queue.
+
+        Args:
+            request: The approval request to skip.
+            operator_input: Raw operator input that led to this decision. Defaults to "skipped".
+
+        Returns:
+            The recorded skip decision.
+        '''
+    def timeout_request(self, request: ApprovalRequest, operator_input: str = 'TIMEOUT') -> ApprovalDecision:
+        '''Record a timeout decision for a request, always skipping the tool.
+
+        Args:
+            request (ApprovalRequest): The approval request that timed out.
+            operator_input (str, optional): Input from the operator (defaults to "TIMEOUT").
+
+        Returns:
+            ApprovalDecision: The timeout decision.
+        '''
+    def check_timeout(self, request: ApprovalRequest) -> ApprovalDecision | None:
+        """Check if a request has timed out and return timeout decision if so.
+
+        Args:
+            request: The approval request to check.
+
+        Returns:
+            Timeout decision if timed out, None otherwise.
+        """
+    async def prompt_for_decision(self, request: ApprovalRequest, timeout_seconds: int, context_keys: list[str] | None = None) -> ApprovalDecision:
+        """Prompt for a decision using the configured handler.
+
+        This method delegates to the configured prompt handler to obtain
+        an approval decision from the operator. The handler may be interactive
+        (CLI) or deferred (programmatic, resume-in-place).
+
+        Args:
+            request: The approval request to prompt for.
+            timeout_seconds: How long to wait for input.
+            context_keys: Optional keys to display from context. Defaults to None.
+
+        Returns:
+            The operator's decision on the request.
+        """
+    def list_pending_requests(self) -> Iterable[ApprovalRequest]:
+        """Return a snapshot of currently pending requests.
+
+        This method provides a thread-safe snapshot of all currently active
+        approval requests that are waiting for operator decisions.
+
+        Returns:
+            An iterable of all pending approval requests.
+        """
+    def resolve_pending_request(self, request_id: str, decision: str, operator_input: str = '') -> ApprovalDecision:
+        '''Resolve a pending request with an explicit decision.
+
+        Args:
+            request_id: The unique identifier of the pending approval request.
+            decision: The decision string (e.g., "approved", "rejected", "skipped").
+            operator_input: Optional raw operator input, defaults to the decision string. Defaults to "".
+
+        Returns:
+            The recorded approval decision.
+
+        Raises:
+            KeyError: If no pending request exists with the given request_id.
+            ValueError: If the decision string is not supported.
+        '''
+    def create_log_entry(self, decision: ApprovalDecision, tool_name: str, agent_id: str | None = None, thread_id: str | None = None, additional_context: dict[str, Any] | None = None) -> ApprovalLogEntry:
+        """Create a log entry for a decision.
+
+        Args:
+            decision: The approval decision.
+            tool_name: Name of the tool.
+            agent_id: Optional agent identifier. Defaults to None.
+            thread_id: Optional thread/session identifier. Defaults to None.
+            additional_context: Optional additional logging context. Defaults to None.
+
+        Returns:
+            Structured log entry.
+        """
+    def cleanup_expired_requests(self) -> int:
+        """Clean up expired requests and return count of cleaned requests.
+
+        This method removes all approval requests that have exceeded their
+        timeout period from the active requests queue. This is typically
+        called periodically to prevent memory leaks from abandoned requests.
+
+        Returns:
+            The number of expired requests that were cleaned up.
+        """
+    def register_waiter(self, request_id: str, future: Any) -> None:
+        """Register a waiter future for an approval request.
+
+        Args:
+            request_id: The id for which to wait.
+            future: An asyncio.Future that will receive a tuple(decision, operator_input).
+        """
+    def unregister_waiter(self, request_id: str) -> None:
+        """Unregister a waiter if present (used on timeout/cancellation).
+
+        Args:
+            request_id (str): The ID of the request to unregister the waiter for.
+        """
+    async def wait_for_pending_decision(self, request: ApprovalRequest, timeout_seconds: int) -> ApprovalDecision:
+        """Wait for a pending request to be resolved and return the final decision.
+
+        Args:
+            request: The pending approval request to wait for.
+            timeout_seconds: Maximum time to wait before treating as timeout.
+
+        Returns:
+            The finalized approval decision.
+        """
+    @staticmethod
+    def get_decision_message(decision: ApprovalDecision) -> str:
+        """Get the appropriate message for a HITL decision.
+
+        Args:
+            decision: The approval decision to get a message for.
+
+        Returns:
+            A human-readable message explaining the decision outcome.
+        """

aip_agents/agent/hitl/models.py

@@ -0,0 +1,18 @@
+"""Backward-compatible exports for HITL approval schema.
+
+Prefer importing from ``aip_agents.schema.hitl`` in new code.
+"""
+
+from aip_agents.schema.hitl import (
+    ApprovalDecision,
+    ApprovalDecisionType,
+    ApprovalLogEntry,
+    ApprovalRequest,
+)
+
+__all__ = [
+    "ApprovalDecisionType",
+    "ApprovalRequest",
+    "ApprovalDecision",
+    "ApprovalLogEntry",
+]

aip_agents/agent/hitl/models.pyi

@@ -0,0 +1,3 @@
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalLogEntry as ApprovalLogEntry, ApprovalRequest as ApprovalRequest
+
+__all__ = ['ApprovalDecisionType', 'ApprovalRequest', 'ApprovalDecision', 'ApprovalLogEntry']

aip_agents/agent/hitl/prompt/__init__.py

@@ -0,0 +1,9 @@
+"""Prompt handler implementations for HITL approvals."""
+
+from aip_agents.agent.hitl.prompt.base import BasePromptHandler
+from aip_agents.agent.hitl.prompt.deferred import DeferredPromptHandler
+
+__all__ = [
+    "BasePromptHandler",
+    "DeferredPromptHandler",
+]

aip_agents/agent/hitl/prompt/__init__.pyi

@@ -0,0 +1,4 @@
+from aip_agents.agent.hitl.prompt.base import BasePromptHandler as BasePromptHandler
+from aip_agents.agent.hitl.prompt.deferred import DeferredPromptHandler as DeferredPromptHandler
+
+__all__ = ['BasePromptHandler', 'DeferredPromptHandler']

aip_agents/agent/hitl/prompt/base.py

@@ -0,0 +1,42 @@
+"""Shared base classes for HITL prompt handlers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from aip_agents.schema.hitl import ApprovalDecision, ApprovalRequest
+
+if TYPE_CHECKING:  # pragma: no cover - typing-only import
+    from aip_agents.agent.hitl.manager import ApprovalManager
+
+
+class BasePromptHandler(ABC):
+    """Abstract base class for prompt handlers used in HITL flows."""
+
+    def attach_manager(self, manager: ApprovalManager) -> None:
+        """Optionally attach the ``ApprovalManager`` coordinating approvals.
+
+        Args:
+            manager (ApprovalManager): The approval manager instance to attach.
+        """
+        # Default implementation stores nothing; subclasses override as needed.
+        return None
+
+    @abstractmethod
+    async def prompt_for_decision(
+        self,
+        request: ApprovalRequest,
+        timeout_seconds: int,
+        context_keys: list[str] | None = None,
+    ) -> ApprovalDecision:
+        """Collect and return a decision for the given approval request.
+
+        Args:
+            request (ApprovalRequest): The approval request to prompt for.
+            timeout_seconds (int): Maximum time to wait for a decision in seconds.
+            context_keys (list[str] | None, optional): Optional keys for additional context. Defaults to None.
+
+        Returns:
+            ApprovalDecision: The decision made for the approval request.
+        """

aip_agents/agent/hitl/prompt/base.pyi

@@ -0,0 +1,24 @@
+from abc import ABC, abstractmethod
+from aip_agents.agent.hitl.manager import ApprovalManager as ApprovalManager
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalRequest as ApprovalRequest
+
+class BasePromptHandler(ABC):
+    """Abstract base class for prompt handlers used in HITL flows."""
+    def attach_manager(self, manager: ApprovalManager) -> None:
+        """Optionally attach the ``ApprovalManager`` coordinating approvals.
+
+        Args:
+            manager (ApprovalManager): The approval manager instance to attach.
+        """
+    @abstractmethod
+    async def prompt_for_decision(self, request: ApprovalRequest, timeout_seconds: int, context_keys: list[str] | None = None) -> ApprovalDecision:
+        """Collect and return a decision for the given approval request.
+
+        Args:
+            request (ApprovalRequest): The approval request to prompt for.
+            timeout_seconds (int): Maximum time to wait for a decision in seconds.
+            context_keys (list[str] | None, optional): Optional keys for additional context. Defaults to None.
+
+        Returns:
+            ApprovalDecision: The decision made for the approval request.
+        """

aip_agents/agent/hitl/prompt/deferred.py

@@ -0,0 +1,73 @@
+"""Deferred prompt handler that waits for external approval resolution."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from aip_agents.agent.hitl.prompt.base import BasePromptHandler
+from aip_agents.schema.hitl import ApprovalDecision, ApprovalDecisionType, ApprovalRequest
+
+if TYPE_CHECKING:  # pragma: no cover - typing-only import
+    from aip_agents.agent.hitl.manager import ApprovalManager
+
+
+class DeferredPromptHandler(BasePromptHandler):
+    """Prompt handler that defers tool execution until an external decision is received."""
+
+    def __init__(self, notify: Callable[[ApprovalRequest], None] | None = None) -> None:
+        """Initialize the deferred prompt handler.
+
+        Args:
+            notify: Optional callback function to notify when an approval request is made.
+        """
+        self._notify = notify
+        self._manager: ApprovalManager | None = None
+
+    def attach_manager(self, manager: ApprovalManager) -> None:
+        """Attach the ApprovalManager orchestrating approvals.
+
+        Args:
+            manager: The ApprovalManager instance to attach for handling approval decisions.
+        """
+        self._manager = manager
+
+    async def prompt_for_decision(
+        self,
+        request: ApprovalRequest,
+        timeout_seconds: int,
+        context_keys: list[str] | None = None,
+    ) -> ApprovalDecision:
+        """Register a waiter and return a pending decision sentinel.
+
+        Args:
+            request: The approval request containing the tool call details and context.
+            timeout_seconds: Number of seconds to wait for approval before timing out.
+            context_keys: Optional list of context keys to include in the approval request.
+
+        Returns:
+            ApprovalDecision with PENDING status and registered waiter for external resolution.
+        """
+        if self._notify:
+            try:
+                self._notify(request)
+            except Exception:
+                pass
+
+        if self._manager is None:
+            return ApprovalDecision(
+                request_id=request.request_id,
+                decision=ApprovalDecisionType.PENDING,
+                operator_input="PENDING",
+            )
+
+        loop = asyncio.get_running_loop()
+        waiter = loop.create_future()
+        self._manager.register_waiter(request.request_id, waiter)
+
+        return ApprovalDecision(
+            request_id=request.request_id,
+            decision=ApprovalDecisionType.PENDING,
+            operator_input="PENDING",
+        )

aip_agents/agent/hitl/prompt/deferred.pyi

@@ -0,0 +1,30 @@
+from aip_agents.agent.hitl.manager import ApprovalManager as ApprovalManager
+from aip_agents.agent.hitl.prompt.base import BasePromptHandler as BasePromptHandler
+from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalRequest as ApprovalRequest
+from collections.abc import Callable
+
+class DeferredPromptHandler(BasePromptHandler):
+    """Prompt handler that defers tool execution until an external decision is received."""
+    def __init__(self, notify: Callable[[ApprovalRequest], None] | None = None) -> None:
+        """Initialize the deferred prompt handler.
+
+        Args:
+            notify: Optional callback function to notify when an approval request is made.
+        """
+    def attach_manager(self, manager: ApprovalManager) -> None:
+        """Attach the ApprovalManager orchestrating approvals.
+
+        Args:
+            manager: The ApprovalManager instance to attach for handling approval decisions.
+        """
+    async def prompt_for_decision(self, request: ApprovalRequest, timeout_seconds: int, context_keys: list[str] | None = None) -> ApprovalDecision:
+        """Register a waiter and return a pending decision sentinel.
+
+        Args:
+            request: The approval request containing the tool call details and context.
+            timeout_seconds: Number of seconds to wait for approval before timing out.
+            context_keys: Optional list of context keys to include in the approval request.
+
+        Returns:
+            ApprovalDecision with PENDING status and registered waiter for external resolution.
+        """

aip_agents/agent/hitl/registry.py

@@ -0,0 +1,149 @@
+"""Registry for tracking HITL approval manager ownership across agent hierarchies.
+
+This module provides a thread-safe singleton registry that maps request IDs to their
+owning ApprovalManager instances. This enables proper decision routing in hierarchical
+agent architectures where sub-agents have HITL enabled but parents do not.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+from weakref import WeakValueDictionary
+
+if TYPE_CHECKING:
+    from aip_agents.agent.hitl.manager import ApprovalManager
+
+
+class HITLManagerRegistry:
+    """Global registry mapping request_id → owning ApprovalManager.
+
+    Uses weak references to avoid preventing manager garbage collection.
+    Thread-safe for concurrent agent execution.
+
+    This singleton registry allows the HITL decision endpoint to route decisions
+    to the correct manager in hierarchical agent setups, where a sub-agent may
+    create a pending request but the parent agent receives the decision.
+
+    Example:
+        >>> from aip_agents.agent.hitl.registry import hitl_registry
+        >>> # Manager auto-registers when creating requests
+        >>> manager.create_approval_request(...)
+        >>> # Later, decision handler looks up the owning manager
+        >>> owning_manager = hitl_registry.get_manager(request_id)
+        >>> owning_manager.resolve_pending_request(request_id, "approved")
+    """
+
+    _instance: HITLManagerRegistry | None = None
+    _lock = threading.RLock()
+    _registry: WeakValueDictionary[str, ApprovalManager]
+    _registry_lock: threading.RLock
+
+    def __new__(cls) -> HITLManagerRegistry:
+        """Ensure only one instance exists (singleton pattern).
+
+        Returns:
+            The singleton HITLManagerRegistry instance.
+        """
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    instance = super().__new__(cls)
+                    instance._registry = WeakValueDictionary()
+                    instance._registry_lock = threading.RLock()
+                    cls._instance = instance
+        return cls._instance
+
+    def register(self, request_id: str, manager: ApprovalManager) -> None:
+        """Register a pending request with its owning manager.
+
+        This method is typically called automatically by ApprovalManager when
+        creating a new pending request. It establishes the ownership mapping
+        needed for proper decision routing.
+
+        Args:
+            request_id: Unique identifier for the pending request
+            manager: ApprovalManager instance that owns this request
+
+        Example:
+            >>> hitl_registry.register("req_abc123", my_manager)
+        """
+        with self._registry_lock:
+            self._registry[request_id] = manager
+
+    def unregister(self, request_id: str) -> None:
+        """Remove a request from the registry.
+
+        This method is called when a request is resolved, times out, or expires.
+        It's important for cleanup to prevent the registry from growing unbounded.
+
+        Args:
+            request_id: Unique identifier to remove
+
+        Example:
+            >>> hitl_registry.unregister("req_abc123")
+        """
+        with self._registry_lock:
+            self._registry.pop(request_id, None)
+
+    def get_manager(self, request_id: str) -> ApprovalManager | None:
+        """Retrieve the manager owning a specific request.
+
+        This is the primary lookup method used by decision handlers to route
+        decisions to the correct manager in hierarchical agent setups.
+
+        Args:
+            request_id: Unique identifier to lookup
+
+        Returns:
+            ApprovalManager instance if found, None otherwise. None can indicate
+            the request was resolved, timed out, or the manager was garbage collected.
+
+        Example:
+            >>> manager = hitl_registry.get_manager("req_abc123")
+            >>> if manager:
+            ...     manager.resolve_pending_request("req_abc123", "approved")
+        """
+        with self._registry_lock:
+            return self._registry.get(request_id)
+
+    def clear(self) -> None:
+        """Clear all registrations.
+
+        This method is primarily intended for testing to ensure a clean state
+        between test cases. It removes all registered mappings.
+
+        Warning:
+            This should not be called in production code as it will prevent
+            pending requests from being resolved.
+
+        Example:
+            >>> hitl_registry.clear()  # For testing only
+        """
+        with self._registry_lock:
+            self._registry.clear()
+
+    def list_all(self) -> list[str]:
+        """List all currently registered request IDs.
+
+        Returns:
+            List of request IDs currently in the registry.
+
+        Note:
+            Due to weak references, managers may be garbage collected between
+            calling this method and accessing them, so the actual available
+            managers might be fewer than the returned list length.
+
+        Example:
+            >>> request_ids = hitl_registry.list_all()
+            >>> print(f"Pending requests: {request_ids}")
+        """
+        with self._registry_lock:
+            return list(self._registry.keys())
+
+
+# Global singleton instance
+hitl_registry = HITLManagerRegistry()

aip_agents/agent/hitl/registry.pyi

@@ -0,0 +1,101 @@
+from _typeshed import Incomplete
+from aip_agents.agent.hitl.manager import ApprovalManager as ApprovalManager
+
+class HITLManagerRegistry:
+    '''Global registry mapping request_id → owning ApprovalManager.
+
+    Uses weak references to avoid preventing manager garbage collection.
+    Thread-safe for concurrent agent execution.
+
+    This singleton registry allows the HITL decision endpoint to route decisions
+    to the correct manager in hierarchical agent setups, where a sub-agent may
+    create a pending request but the parent agent receives the decision.
+
+    Example:
+        >>> from aip_agents.agent.hitl.registry import hitl_registry
+        >>> # Manager auto-registers when creating requests
+        >>> manager.create_approval_request(...)
+        >>> # Later, decision handler looks up the owning manager
+        >>> owning_manager = hitl_registry.get_manager(request_id)
+        >>> owning_manager.resolve_pending_request(request_id, "approved")
+    '''
+    def __new__(cls) -> HITLManagerRegistry:
+        """Ensure only one instance exists (singleton pattern).
+
+        Returns:
+            The singleton HITLManagerRegistry instance.
+        """
+    def register(self, request_id: str, manager: ApprovalManager) -> None:
+        '''Register a pending request with its owning manager.
+
+        This method is typically called automatically by ApprovalManager when
+        creating a new pending request. It establishes the ownership mapping
+        needed for proper decision routing.
+
+        Args:
+            request_id: Unique identifier for the pending request
+            manager: ApprovalManager instance that owns this request
+
+        Example:
+            >>> hitl_registry.register("req_abc123", my_manager)
+        '''
+    def unregister(self, request_id: str) -> None:
+        '''Remove a request from the registry.
+
+        This method is called when a request is resolved, times out, or expires.
+        It\'s important for cleanup to prevent the registry from growing unbounded.
+
+        Args:
+            request_id: Unique identifier to remove
+
+        Example:
+            >>> hitl_registry.unregister("req_abc123")
+        '''
+    def get_manager(self, request_id: str) -> ApprovalManager | None:
+        '''Retrieve the manager owning a specific request.
+
+        This is the primary lookup method used by decision handlers to route
+        decisions to the correct manager in hierarchical agent setups.
+
+        Args:
+            request_id: Unique identifier to lookup
+
+        Returns:
+            ApprovalManager instance if found, None otherwise. None can indicate
+            the request was resolved, timed out, or the manager was garbage collected.
+
+        Example:
+            >>> manager = hitl_registry.get_manager("req_abc123")
+            >>> if manager:
+            ...     manager.resolve_pending_request("req_abc123", "approved")
+        '''
+    def clear(self) -> None:
+        """Clear all registrations.
+
+        This method is primarily intended for testing to ensure a clean state
+        between test cases. It removes all registered mappings.
+
+        Warning:
+            This should not be called in production code as it will prevent
+            pending requests from being resolved.
+
+        Example:
+            >>> hitl_registry.clear()  # For testing only
+        """
+    def list_all(self) -> list[str]:
+        '''List all currently registered request IDs.
+
+        Returns:
+            List of request IDs currently in the registry.
+
+        Note:
+            Due to weak references, managers may be garbage collected between
+            calling this method and accessing them, so the actual available
+            managers might be fewer than the returned list length.
+
+        Example:
+            >>> request_ids = hitl_registry.list_all()
+            >>> print(f"Pending requests: {request_ids}")
+        '''
+
+hitl_registry: Incomplete