aip-agents-binary 0.5.18__py3-none-any.whl → 0.5.19__py3-none-any.whl

aip_agents/utils/formatter_llm_client.pyi

@@ -0,0 +1,71 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from collections.abc import Awaitable as Awaitable
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+from typing import Any, TypeVar
+
+logger: Incomplete
+FORMATTER_ENV_VAR: str
+T = TypeVar('T')
+
+class FormatterInvokerUnavailableError(RuntimeError):
+    """Raised when no formatter LLM invoker can be resolved."""
+class FormatterInvocationError(RuntimeError):
+    """Raised when invoking the formatter LLM fails."""
+
+class FormatterLLMClient:
+    """Stateful helper that manages formatter invoker resolution and execution."""
+    def __init__(self) -> None:
+        """Initialize the formatter LLM client with caching and thread safety."""
+    def seed_default(self, default_model_id: str | None) -> None:
+        """Populate ``DEFAULT_MODEL_FORMATTER`` when unset.
+
+        Args:
+            default_model_id: Preferred formatter model id to use as a fallback.
+        """
+    def resolve_invoker(self, *, reset_cache: bool = False) -> BaseLMInvoker | None:
+        """Return the cached formatter invoker, optionally refreshing it.
+
+        Args:
+            reset_cache: When True, clear the cached invoker before resolving.
+
+        Returns:
+            BaseLMInvoker | None: Cached invoker if the formatter is configured, otherwise None.
+        """
+    async def invoke(self, *args: Any, invoker: BaseLMInvoker | None = None, timeout: float | None = None, **kwargs: Any) -> Any:
+        """Dispatch formatter prompts asynchronously with timeout/error handling.
+
+        Args:
+            *args: Positional arguments forwarded to the invoker.
+            invoker: Explicit invoker instance to reuse instead of resolving one.
+            timeout: Optional timeout (seconds) enforced with ``asyncio.timeout``.
+            **kwargs: Keyword arguments forwarded to the invoker.
+
+        Returns:
+            Any: Result returned by the formatter LLM.
+
+        Raises:
+            FormatterInvokerUnavailableError: If no formatter model is configured.
+            FormatterInvocationError: When the invocation fails or exceeds the timeout.
+        """
+    def invoke_blocking(self, *args: Any, invoker: BaseLMInvoker | None = None, timeout: float | None = None, **kwargs: Any) -> Any:
+        """Invoke the formatter LLM from synchronous contexts.
+
+        Args:
+            *args: Positional arguments forwarded to ``invoke``.
+            invoker: Optional invoker to reuse.
+            timeout: Optional timeout (seconds) for the async invocation.
+            **kwargs: Keyword arguments forwarded to ``invoke``.
+
+        Returns:
+            Any: Result returned by the formatter LLM.
+        """
+
+def get_formatter_llm_client() -> FormatterLLMClient:
+    """Return the process-wide formatter LLM client."""
+def seed_formatter_llm_default(default_model_id: str | None) -> None:
+    """Convenience wrapper for seeding the formatter default model.
+
+    Args:
+        default_model_id: Formatter model identifier to seed when missing.
+    """

aip_agents/utils/langgraph/__init__.pyi

@@ -0,0 +1,3 @@
+from aip_agents.utils.langgraph.converter import convert_gllm_tool_call_to_langchain_tool_call as convert_gllm_tool_call_to_langchain_tool_call, convert_langchain_messages_to_gllm_messages as convert_langchain_messages_to_gllm_messages, convert_langchain_tool_call_to_gllm_tool_call as convert_langchain_tool_call_to_gllm_tool_call, convert_lm_output_to_langchain_message as convert_lm_output_to_langchain_message
+
+__all__ = ['convert_gllm_tool_call_to_langchain_tool_call', 'convert_langchain_tool_call_to_gllm_tool_call', 'convert_lm_output_to_langchain_message', 'convert_langchain_messages_to_gllm_messages']

aip_agents/utils/langgraph/converter.pyi

@@ -0,0 +1,49 @@
+from collections.abc import Sequence
+from gllm_inference.schema import LMOutput, Message, ToolCall as GllmToolCall
+from langchain_core.messages import AIMessage, BaseMessage as BaseMessage
+from langchain_core.messages.tool import ToolCall as LangChainToolCall
+
+def convert_langchain_messages_to_gllm_messages(messages: Sequence[BaseMessage], instruction: str) -> list[Message]:
+    """Convert LangChain messages to gllm-inference Message format.
+
+    This function transforms a sequence of LangChain messages into the Message
+    format expected by LM Invoker. It handles system messages, human messages, AI messages
+    with tool calls, and tool result messages.
+
+    Args:
+        messages: Sequence of LangChain BaseMessage objects to convert.
+        instruction: System instruction to prepend if not already present in messages.
+
+    Returns:
+        List of Message objects containing the converted message sequence.
+    """
+def convert_lm_output_to_langchain_message(response: LMOutput | str) -> AIMessage:
+    """Convert LM Invoker output to LangChain AIMessage.
+
+    This function transforms the output from LM Invoker back into LangChain's
+    AIMessage format, handling both text responses and tool calls.
+
+    Args:
+        response: The response from LM Invoker (MultimodalOutput).
+
+    Returns:
+        AIMessage containing the converted response.
+    """
+def convert_langchain_tool_call_to_gllm_tool_call(lc_tool_call: LangChainToolCall) -> GllmToolCall:
+    """Convert LangChain tool call to gllm ToolCall.
+
+    Args:
+        lc_tool_call: LangChain ToolCall (TypedDict).
+
+    Returns:
+        GllmToolCall object for gllm-inference.
+    """
+def convert_gllm_tool_call_to_langchain_tool_call(gllm_tool_call: GllmToolCall) -> LangChainToolCall:
+    """Convert gllm ToolCall to LangChain ToolCall format.
+
+    Args:
+        gllm_tool_call: GllmToolCall object from gllm-inference.
+
+    Returns:
+        LangChain ToolCall (TypedDict) with proper type annotation.
+    """

aip_agents/utils/langgraph/tool_managers/__init__.pyi

@@ -0,0 +1,5 @@
+from aip_agents.utils.langgraph.tool_managers.a2a_tool_manager import A2AToolManager as A2AToolManager
+from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager as BaseLangGraphToolManager
+from aip_agents.utils.langgraph.tool_managers.delegation_tool_manager import DelegationToolManager as DelegationToolManager
+
+__all__ = ['BaseLangGraphToolManager', 'A2AToolManager', 'DelegationToolManager']

aip_agents/utils/langgraph/tool_managers/a2a_tool_manager.pyi

@@ -0,0 +1,35 @@
+from _typeshed import Incomplete
+from a2a.types import AgentCard as AgentCard
+from aip_agents.utils.a2a_connector import A2AConnector as A2AConnector
+from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager as BaseLangGraphToolManager
+from aip_agents.utils.logger import get_logger as get_logger
+from langchain_core.tools import BaseTool
+
+logger: Incomplete
+
+class A2AToolManager(BaseLangGraphToolManager):
+    """Manages A2A communication tools for LangGraph agents.
+
+    This tool manager converts A2A agent cards into LangChain tools that can
+    be used in a unified ToolNode within LangGraph agents. Each A2A agent
+    becomes a tool that the LLM can call for external communication.
+    """
+    registered_agents: list
+    def __init__(self) -> None:
+        """Initialize the A2A tool manager."""
+    created_tools: Incomplete
+    def register_resources(self, agent_cards: list[AgentCard]) -> list[BaseTool]:
+        """Register A2A agents and convert them to LangChain tools.
+
+        Args:
+            agent_cards: List of AgentCard instances for external communication.
+
+        Returns:
+            List of created A2A communication tools.
+        """
+    def get_resource_names(self) -> list[str]:
+        """Get names of all registered A2A agents.
+
+        Returns:
+            list[str]: A list of names of all registered A2A agents.
+        """

aip_agents/utils/langgraph/tool_managers/base_tool_manager.pyi

@@ -0,0 +1,48 @@
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from aip_agents.utils.logger import get_logger as get_logger
+from langchain_core.tools import BaseTool as BaseTool
+from typing import Any
+
+logger: Incomplete
+
+class BaseLangGraphToolManager(ABC):
+    """Base class for managing specialized tools in LangGraph agents.
+
+    This abstract base class provides a common interface for tool managers
+    that convert different types of capabilities into LangChain tools for
+    use in LangGraph agents.
+
+    The design follows a simple pattern:
+    1. Register resources (agents, cards, etc.)
+    2. Convert resources to LangChain tools
+    3. Provide access to created tools
+    """
+    created_tools: list[BaseTool]
+    def __init__(self) -> None:
+        """Initialize the tool manager."""
+    @abstractmethod
+    def register_resources(self, resources: list[Any]) -> list[BaseTool]:
+        """Register resources and convert them to LangChain tools.
+
+        Args:
+            resources: List of resources to convert to tools.
+
+        Returns:
+            List of created tools.
+        """
+    def get_tools(self) -> list[BaseTool]:
+        """Get all created tools.
+
+        Returns:
+            Copy of created tools list.
+        """
+    def clear_tools(self) -> None:
+        """Clear all created tools."""
+    @abstractmethod
+    def get_resource_names(self) -> list[str]:
+        """Get names of all registered resources.
+
+        Returns:
+            List of resource names.
+        """

aip_agents/utils/langgraph/tool_managers/delegation_tool_manager.pyi

@@ -0,0 +1,56 @@
+from _typeshed import Incomplete
+from aip_agents.agent.base_agent import BaseAgent as BaseAgent
+from aip_agents.schema.step_limit import MaxDelegationDepthExceededError as MaxDelegationDepthExceededError
+from aip_agents.types import A2AEvent as A2AEvent, A2AStreamEventType as A2AStreamEventType
+from aip_agents.utils.artifact_helpers import extract_artifacts_from_agent_response as extract_artifacts_from_agent_response
+from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager as BaseLangGraphToolManager
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.metadata_helper import MetadataFieldKeys as MetadataFieldKeys, get_next_step_number as get_next_step_number
+from aip_agents.utils.pii.pii_helper import anonymize_final_response_content as anonymize_final_response_content, extract_pii_mapping_from_agent_response as extract_pii_mapping_from_agent_response
+from aip_agents.utils.reference_helper import extract_references_from_agent_response as extract_references_from_agent_response
+from aip_agents.utils.step_limit_manager import StepLimitManager as StepLimitManager
+from aip_agents.utils.token_usage_helper import STEP_USAGE_KEY as STEP_USAGE_KEY, TOTAL_USAGE_KEY as TOTAL_USAGE_KEY, USAGE_METADATA_KEY as USAGE_METADATA_KEY, extract_token_usage_from_agent_response as extract_token_usage_from_agent_response
+from langchain_core.tools import BaseTool
+
+logger: Incomplete
+OUTPUT_KEY: str
+RESULT_KEY: str
+ARTIFACTS_KEY: str
+METADATA_KEY: str
+METADATA_INTERNAL_PREFIXES: Incomplete
+METADATA_INTERNAL_KEYS: Incomplete
+AGENT_RUN_A2A_STREAMING_METHOD: str
+
+class DelegationToolManager(BaseLangGraphToolManager):
+    """Manages internal agent delegation tools for LangGraph agents.
+
+    This tool manager converts internal agent instances into LangChain tools
+    that can be used for task delegation within a unified ToolNode. Each
+    delegated agent becomes a tool that the coordinator can call.
+
+    Simplified version following legacy BaseLangChainAgent patterns.
+    """
+    registered_agents: list[BaseAgent]
+    parent_agent: Incomplete
+    def __init__(self, parent_agent: BaseAgent | None = None) -> None:
+        """Initialize the delegation tool manager.
+
+        Args:
+            parent_agent: The parent agent that creates delegation tools, used for parent step lookup.
+        """
+    created_tools: Incomplete
+    def register_resources(self, agents: list[BaseAgent]) -> list[BaseTool]:
+        """Register internal agents for delegation and convert them to tools.
+
+        Args:
+            agents: List of BaseAgent instances for internal task delegation.
+
+        Returns:
+            List of created delegation tools.
+        """
+    def get_resource_names(self) -> list[str]:
+        """Get names of all registered delegation agents.
+
+        Returns:
+            list[str]: A list of names of all registered delegation agents.
+        """

aip_agents/utils/langgraph/tool_output_management.pyi

@@ -0,0 +1,292 @@
+from _typeshed import Incomplete
+from aip_agents.storage.providers.base import BaseStorageProvider as BaseStorageProvider, StorageError as StorageError
+from aip_agents.storage.providers.memory import InMemoryStorageProvider as InMemoryStorageProvider
+from aip_agents.utils.logger import get_logger as get_logger
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any
+
+logger: Incomplete
+STRING_TRUNCATION_LENGTH: int
+MAX_TOOL_ARGS_DISPLAY: int
+DATA_PREVIEW_TRUNCATION_LENGTH: int
+TOOL_OUTPUT_REFERENCE_PREFIX: str
+
+class ToolReferenceError(Exception):
+    """Specialized exception for tool output reference resolution errors.
+
+    This exception is raised when there are issues with resolving tool output references,
+    such as invalid reference syntax, missing outputs, or security violations.
+
+    Attributes:
+        reference: The original reference string that caused the error.
+        call_id: The call ID that was attempted to be resolved, if applicable.
+        details: Additional error details for debugging.
+    """
+    reference: Incomplete
+    call_id: Incomplete
+    details: Incomplete
+    def __init__(self, message: str, reference: str | None = None, call_id: str | None = None, details: dict[str, Any] | None = None) -> None:
+        """Initialize a ToolReferenceError.
+
+        Args:
+            message: Human-readable error message describing what went wrong.
+            reference: The original reference string that caused the error, if applicable.
+            call_id: The call ID that was attempted to be resolved, if applicable.
+            details: Additional error details for debugging, if applicable.
+        """
+
+@dataclass
+class ToolOutputConfig:
+    """Configuration for tool output management system.
+
+    This class defines the operational parameters for the tool output management
+    system, including storage limits, cleanup intervals, and lifecycle policies.
+
+    Attributes:
+        max_stored_outputs: Maximum number of tool outputs to store simultaneously.
+            When this limit is reached, oldest outputs are evicted. Defaults to 100.
+        max_age_minutes: Maximum age in minutes for stored outputs before they
+            become eligible for cleanup. Defaults to 60 minutes.
+        cleanup_interval: Number of tool calls between automatic cleanup operations.
+            Set to 0 to disable automatic cleanup. Defaults to 20.
+        storage_provider: Optional storage provider for persistent storage.
+            If None, uses in-memory storage (backward compatible). Defaults to None.
+    """
+    max_stored_outputs: int = ...
+    max_age_minutes: int = ...
+    cleanup_interval: int = ...
+    storage_provider: BaseStorageProvider | None = ...
+
+@dataclass
+class ToolOutput:
+    """Container for tool outputs with optional data payload.
+
+    This class represents tool output metadata and optionally the actual data.
+    When used as metadata only, the data field is None and must be retrieved
+    from storage. When loaded with data, it contains the complete output.
+
+    Attributes:
+        call_id: Unique identifier for this tool call, used for reference resolution.
+        tool_name: Name of the tool that produced this output.
+        timestamp: When this output was created and stored.
+        size_bytes: Approximate size of the stored data in bytes for memory management.
+        tool_args: Input arguments that were passed to the tool for this call.
+        data: Optional actual output data. None when used as metadata only.
+        data_description: Optional human-readable description of the data content,
+            typically provided by the tool itself.
+        tags: Optional list of tags for categorization and filtering.
+        agent_name: Name of the agent that created this output, for multi-agent context.
+    """
+    call_id: str
+    tool_name: str
+    timestamp: datetime
+    size_bytes: int
+    tool_args: dict[str, Any]
+    data: Any | None = ...
+    data_description: str | None = ...
+    tags: list[str] | None = ...
+    agent_name: str | None = ...
+    @property
+    def is_metadata_only(self) -> bool:
+        """Check if this instance contains only metadata without data."""
+    def is_expired(self, max_age: timedelta) -> bool:
+        """Check if this output has expired based on the given maximum age.
+
+        Args:
+            max_age (timedelta): The maximum age allowed before expiration.
+
+        Returns:
+            bool: True if the output has expired, False otherwise.
+        """
+    def get_data_preview(self, max_length: int = 200, storage_provider: BaseStorageProvider | None = None, thread_id: str | None = None) -> str | None:
+        """Get a truncated string representation of the stored data.
+
+        Args:
+            max_length: Maximum length of the preview string.
+            storage_provider: Required only if data is not loaded.
+            thread_id: Thread ID required for proper storage key generation.
+
+        Returns:
+            A string representation of the data, truncated if necessary. None if data is not found.
+        """
+    def with_data(self, data: Any) -> ToolOutput:
+        """Create a new instance with data populated.
+
+        Returns a new ToolOutput instance with the same metadata but with
+        data field populated. Useful for converting metadata-only instances
+        to complete instances.
+
+        Args:
+            data (Any): The actual output data to populate.
+
+        Returns:
+            ToolOutput: A new instance with data populated.
+        """
+
+@dataclass
+class StoreOutputParams:
+    """Parameters for storing tool outputs.
+
+    Reduces the number of arguments passed to store_output method.
+
+    Attributes:
+        call_id: Unique identifier for this tool call.
+        tool_name: Name of the tool that produced the output.
+        data: The actual output data to store.
+        tool_args: Input arguments used for the tool call.
+        thread_id: Thread/conversation ID to organize outputs by conversation.
+        description: Optional human-readable description of the output.
+        tags: Optional list of tags for categorization.
+        agent_name: Name of the agent that created this output.
+    """
+    call_id: str
+    tool_name: str
+    data: Any
+    tool_args: dict[str, Any]
+    thread_id: str
+    description: str | None = ...
+    tags: list[str] | None = ...
+    agent_name: str | None = ...
+
+class ToolOutputManager:
+    """Production-ready tool output manager with comprehensive lifecycle management.
+
+    This class provides centralized management of tool outputs including storage,
+    retrieval, lifecycle management, and LLM-friendly summarization. It handles
+    memory management through configurable cleanup policies and provides secure
+    access to stored outputs.
+
+    Key Features:
+    - Automatic and manual storage of tool outputs with metadata
+    - Configurable lifecycle management with age and size-based eviction
+    - LLM-friendly summary generation with data previews and context
+    - Memory management with size tracking and cleanup
+    - Thread-safe operations with proper error handling and locking
+    - Concurrent access support for multi-agent and parallel processing scenarios
+
+    Attributes:
+        config: Configuration object defining operational parameters.
+    """
+    config: Incomplete
+    def __init__(self, config: ToolOutputConfig) -> None:
+        """Initialize the ToolOutputManager with the given configuration.
+
+        Args:
+            config: Configuration object defining storage limits and cleanup policies.
+        """
+    def store_output(self, params: StoreOutputParams) -> None:
+        """Store a tool output with automatic cleanup and size management.
+
+        This method stores a tool output along with its metadata, automatically
+        handling size limits, cleanup, and memory management. If the same call_id
+        is used multiple times within the same thread, the previous output will be overwritten.
+
+        Thread-safe: This method uses internal locking to ensure safe concurrent access.
+
+        Args:
+            params: StoreOutputParams containing all necessary parameters including thread_id.
+
+        Raises:
+            Exception: If storage operation fails for any reason.
+        """
+    def get_output(self, call_id: str, thread_id: str) -> ToolOutput | None:
+        """Retrieve a stored tool output by its call ID and thread ID.
+
+        Thread-safe: This method uses internal locking to ensure safe concurrent access.
+
+        Args:
+            call_id: The unique identifier for the tool call.
+            thread_id: The thread/conversation ID to search in.
+
+        Returns:
+            The ToolOutput object with data if found, None otherwise.
+        """
+    def has_outputs(self, thread_id: str | None = None) -> bool:
+        """Check if any outputs are currently stored.
+
+        Thread-safe: This method uses internal locking to ensure safe concurrent access.
+
+        Args:
+            thread_id: Optional thread ID to check for outputs in a specific thread.
+                If None, checks across all threads.
+
+        Returns:
+            True if there are stored outputs, False otherwise.
+        """
+    def generate_summary(self, thread_id: str, max_entries: int = 10) -> str:
+        """Generate an LLM-friendly structured summary as JSON.
+
+        This method creates a comprehensive, structured summary of stored outputs that
+        can be easily parsed by LLMs and other systems. The JSON format provides rich
+        metadata and context about each tool output.
+
+        Thread-safe: This method uses internal locking to ensure safe concurrent access.
+
+        Args:
+            thread_id: Thread ID to generate summary for.
+            max_entries: Maximum number of entries to include in the summary.
+                Defaults to 10.
+
+        Returns:
+            A JSON string containing structured data about tool outputs. Always returns
+            valid JSON, even when no outputs are stored (empty entries list).
+        """
+    def clear_all(self) -> None:
+        """Clear all stored outputs from both metadata and storage.
+
+        Warning:
+            This operation is irreversible and will remove all stored tool outputs.
+        """
+    def get_storage_stats(self) -> dict[str, Any]:
+        """Get storage statistics for monitoring and debugging.
+
+        Returns:
+            Dictionary containing storage statistics.
+        """
+
+class ToolReferenceResolver:
+    """Secure and efficient tool output reference resolution system.
+
+    This class handles the resolution of tool output references in a secure manner,
+    preventing injection attacks while providing simple and reliable access to
+    stored tool outputs. It uses a whitelist approach with regex validation to
+    ensure only safe references are processed.
+
+    Security Features:
+    - Strict regex pattern matching for reference syntax
+    - Whitelist-based validation to prevent injection attacks
+    - Fail-fast error handling with detailed error messages
+    - Input sanitization and validation at multiple levels
+
+    Supported Reference Syntax:
+    - $tool_output.<call_id> - Direct reference to a tool output by call ID
+
+    Attributes:
+        config: Configuration object for operational parameters.
+    """
+    config: Incomplete
+    def __init__(self, config: ToolOutputConfig) -> None:
+        """Initialize the ToolReferenceResolver with security configuration.
+
+        Args:
+            config: Configuration object defining operational parameters.
+        """
+    def resolve_references(self, args: dict[str, Any], manager: ToolOutputManager, thread_id: str | None = None) -> dict[str, Any]:
+        """Resolve all tool output references in the given arguments dictionary.
+
+        This method recursively processes a dictionary of tool arguments, finding
+        and resolving any tool output references. It supports nested dictionaries
+        and lists, providing comprehensive reference resolution.
+
+        Args:
+            args: Dictionary of tool arguments that may contain references.
+            manager: ToolOutputManager instance to resolve references against.
+            thread_id: Optional thread ID for context-aware resolution.
+
+        Returns:
+            New dictionary with all references resolved to their actual values.
+
+        Raises:
+            ToolReferenceError: If any reference is invalid or cannot be resolved.
+        """

aip_agents/utils/logger.pyi

@@ -0,0 +1,60 @@
+import logging
+from _typeshed import Incomplete
+
+LOGGER_NAME: str
+LOG_LEVEL: Incomplete
+
+class _GoogleAdkLogFilter(logging.Filter):
+    """Suppress noisy Google ADK model registry logs.
+
+    Google ADK emits a burst of INFO logs when registering Gemini model patterns.
+    They are redundant (class is unchanged) and clutter our startup output, so we
+    drop them at the logging infrastructure level instead of touching ADK internals.
+    """
+    SUPPRESSED_PREFIX: str
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Return False when the log should be discarded.
+
+        Args:
+            record (logging.LogRecord): The log record to filter.
+
+        Returns:
+            bool: True if the log should be processed, False if it should be discarded.
+        """
+
+LOG_FILTERS: Incomplete
+logger_manager: Incomplete
+root_logger: Incomplete
+
+def get_logger(name: str = ..., level: int = ...) -> logging.Logger:
+    """Get a logger instance.
+
+    Args:
+        name (str): The name of the logger. Defaults to AIPAgentsLogger.
+        level (int): The level of the logger. Defaults to INFO.
+
+    Returns:
+        logging.Logger: The logger instance.
+    """
+
+logger: Incomplete
+THIRD_PARTY_LOGGER_NAMES: Incomplete
+
+class LoggerManager:
+    """A singleton class to manage logging configuration.
+
+    This class is deprecated and will be removed in a future version.
+    Use get_logger() function directly instead.
+    """
+    def __new__(cls):
+        """Initialize the singleton instance."""
+    def get_logger(self, name: str = ..., level: int = ...) -> logging.Logger:
+        """Get a logger instance.
+
+        Args:
+            name (str): The name of the logger. Defaults to AIPAgentsLogger.
+            level (int): The level of the logger. Defaults to INFO.
+
+        Returns:
+            logging.Logger: The logger instance.
+        """

aip_agents/utils/metadata/__init__.pyi

@@ -0,0 +1,5 @@
+from aip_agents.utils.metadata.activity_metadata_helper import DEFAULT_ACTIVITY_INFO as DEFAULT_ACTIVITY_INFO, _format_tool_or_subagent_name as _format_tool_or_subagent_name, create_tool_activity_info as create_tool_activity_info
+from aip_agents.utils.metadata.schemas import Activity as Activity, ActivityDataType as ActivityDataType, Thinking as Thinking
+from aip_agents.utils.metadata.thinking_metadata_helper import FINAL_THINKING_INFO as FINAL_THINKING_INFO
+
+__all__ = ['Activity', 'ActivityDataType', 'Thinking', 'create_tool_activity_info', 'DEFAULT_ACTIVITY_INFO', '_format_tool_or_subagent_name', 'FINAL_THINKING_INFO']

aip_agents/utils/metadata/activity_metadata_helper.pyi

@@ -0,0 +1,25 @@
+from _typeshed import Incomplete
+from aip_agents.schema.hitl import ApprovalDecisionType as ApprovalDecisionType
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.metadata.activity_narrative import ActivityNarrativeBuilder as ActivityNarrativeBuilder, DELEGATE_PREFIX as DELEGATE_PREFIX, HITL_DECISION_MESSAGES as HITL_DECISION_MESSAGES, HITL_PENDING_DESCRIPTION as HITL_PENDING_DESCRIPTION, HITL_PENDING_TITLE as HITL_PENDING_TITLE
+from aip_agents.utils.metadata.schemas.activity_schema import Activity as Activity
+from typing import Any
+
+logger: Incomplete
+DEFAULT_ACTIVITY_MESSAGE: str
+TOOL_EXECUTION_RUNNING_TEMPLATE: str
+TOOL_EXECUTION_COMPLETE_TEMPLATE: str
+SUBAGENT_DELEGATION_TEMPLATE: str
+SUBAGENT_COMPLETE_TEMPLATE: str
+MIXED_EXECUTION_TEMPLATE: str
+DEFAULT_ACTIVITY_INFO: Incomplete
+
+def create_tool_activity_info(original_metadata: dict[str, Any] | None) -> dict[str, str]:
+    '''Create activity info payload with optional LLM narrative overrides.
+
+    Args:
+        original_metadata: The original metadata dictionary containing tool_info and hitl data.
+
+    Returns:
+        A dict with data_type="activity" and data_value as a JSON string.
+    '''

aip_agents/utils/metadata/activity_narrative/__init__.pyi

@@ -0,0 +1,7 @@
+from aip_agents.utils.metadata.activity_narrative.builder import ActivityNarrativeBuilder as ActivityNarrativeBuilder, _formatter_llm_client as _formatter_llm_client
+from aip_agents.utils.metadata.activity_narrative.constants import DELEGATE_PREFIX as DELEGATE_PREFIX, HITL_DECISION_MESSAGES as HITL_DECISION_MESSAGES, HITL_PENDING_DESCRIPTION as HITL_PENDING_DESCRIPTION, HITL_PENDING_TITLE as HITL_PENDING_TITLE, OUTPUT_EXCERPT_MAX_CHARS as OUTPUT_EXCERPT_MAX_CHARS, SYSTEM_PROMPT as SYSTEM_PROMPT
+from aip_agents.utils.metadata.activity_narrative.context import ActivityContext as ActivityContext, ActivityPhase as ActivityPhase
+from aip_agents.utils.metadata.activity_narrative.formatters import ArgsFormatter as ArgsFormatter, OutputFormatter as OutputFormatter, SensitiveInfoFilter as SensitiveInfoFilter
+from aip_agents.utils.metadata.activity_narrative.utils import _format_tool_or_subagent_name as _format_tool_or_subagent_name
+
+__all__ = ['ActivityNarrativeBuilder', 'ActivityContext', 'ActivityPhase', 'ArgsFormatter', 'OutputFormatter', 'SensitiveInfoFilter', 'DELEGATE_PREFIX', 'HITL_DECISION_MESSAGES', 'HITL_PENDING_DESCRIPTION', 'HITL_PENDING_TITLE', 'OUTPUT_EXCERPT_MAX_CHARS', 'SYSTEM_PROMPT', '_format_tool_or_subagent_name', '_formatter_llm_client']