aip-agents-binary 0.4.8__cp312-cp312-win_amd64.whl → 0.5.4__cp312-cp312-win_amd64.whl

aip_agents/utils/artifact_helpers.pyi

@@ -11,9 +11,33 @@ class ArtifactHandler:
     def __init__(self) -> None:
         """Initialize the ArtifactHandler."""
     def create_file_artifact(self, result: str, artifact_data: bytes | str, artifact_name: str, artifact_description: str = '', mime_type: str | None = None, enable_deduplication: bool = True) -> dict[str, Any]:
-        """Deprecated. Use create_artifact instead."""
+        '''Deprecated. Use create_artifact instead.
+
+        Args:
+            result (str): The message/result to show to the agent.
+            artifact_data (bytes | str): The binary data for the artifact.
+            artifact_name (str): The name for the artifact file.
+            artifact_description (str, optional): Description of the artifact. Defaults to "".
+            mime_type (str | None, optional): MIME type of the artifact. If None, will be auto-detected.
+            enable_deduplication (bool, optional): Whether to deduplicate by content hash. Defaults to True.
+
+        Returns:
+            dict[str, Any]: Dictionary with \'result\' and \'artifact\' keys.
+        '''
     def create_text_artifact(self, result: str, artifact_text: str, artifact_name: str, artifact_description: str = '', mime_type: str | None = None, enable_deduplication: bool = True) -> dict[str, Any]:
-        """Deprecated. Use create_artifact instead."""
+        '''Deprecated. Use create_artifact instead.
+
+        Args:
+            result (str): The message/result to show to the agent.
+            artifact_text (str): The text content for the artifact.
+            artifact_name (str): The name for the artifact file.
+            artifact_description (str, optional): Description of the artifact. Defaults to "".
+            mime_type (str | None, optional): MIME type of the artifact. If None, will be auto-detected.
+            enable_deduplication (bool, optional): Whether to deduplicate by content hash. Defaults to True.
+
+        Returns:
+            dict[str, Any]: Dictionary with \'result\' and \'artifact\' keys.
+        '''
     def create_artifact(self, result: str, data: bytes | str, artifact_name: str, artifact_description: str = '', mime_type: str | None = None, enable_deduplication: bool = True) -> dict[str, Any]:
         """Create an artifact with automatic text/binary handling.
 

aip_agents/utils/constants.pyi

@@ -0,0 +1,10 @@
+from enum import StrEnum
+from uuid import UUID
+
+__all__ = ['DefaultTimezone', 'DEFAULT_PII_TAG_NAMESPACE']
+
+class DefaultTimezone(StrEnum):
+    """Default timezone constants used across the application."""
+    JAKARTA: str
+
+DEFAULT_PII_TAG_NAMESPACE: UUID

aip_agents/utils/datetime/__init__.pyi

@@ -0,0 +1,4 @@
+from aip_agents.utils.datetime.normalization import format_created_updated_label as format_created_updated_label, is_valid_date_string as is_valid_date_string, next_day_iso as next_day_iso, normalize_timestamp_to_date as normalize_timestamp_to_date
+from aip_agents.utils.datetime.timezone import ensure_utc_datetime as ensure_utc_datetime, get_timezone_aware_now as get_timezone_aware_now
+
+__all__ = ['normalize_timestamp_to_date', 'format_created_updated_label', 'is_valid_date_string', 'next_day_iso', 'ensure_utc_datetime', 'get_timezone_aware_now']

aip_agents/utils/datetime/normalization.pyi

@@ -0,0 +1,95 @@
+from typing import Any
+
+__all__ = ['normalize_timestamp_to_date', 'format_created_updated_label', 'is_valid_date_string', 'next_day_iso']
+
+def normalize_timestamp_to_date(value: Any) -> str | None:
+    '''Normalize various timestamp representations into a YYYY-MM-DD string.
+
+    This function handles multiple input types and formats, converting them to
+    a standardized ISO date string. It gracefully handles invalid inputs by
+    returning None or the string representation.
+
+    Args:
+        value: The timestamp value to normalize. Can be:
+            - None or empty string: Returns None
+            - int/float: Unix timestamp (seconds since epoch)
+            - str: ISO format, datetime string, or other string representation
+            - Other types: Converted to string representation
+
+    Returns:
+        str | None: A YYYY-MM-DD formatted date string, or None if the input
+            cannot be parsed as a valid date.
+
+    Raises:
+        ValueError: If the timestamp value is invalid (e.g., negative timestamp).
+
+    Examples:
+        >>> normalize_timestamp_to_date(1640995200)  # Unix timestamp
+        \'2022-01-01\'
+        >>> normalize_timestamp_to_date("2022-01-01T12:00:00")
+        \'2022-01-01\'
+        >>> normalize_timestamp_to_date("invalid")
+        \'invalid\'
+        >>> normalize_timestamp_to_date(None)
+        None
+    '''
+def format_created_updated_label(created_at: Any | None, updated_at: Any | None) -> str | None:
+    '''Build a compact label combining created/updated timestamps when available.
+
+    Creates a human-readable label that shows creation and update timestamps
+    in a compact format. If both dates are the same, only shows one date.
+
+    Args:
+        created_at: The creation timestamp (any format supported by normalize_timestamp_to_date).
+        updated_at: The update timestamp (any format supported by normalize_timestamp_to_date).
+
+    Returns:
+        str | None: A formatted label string, or None if both inputs are invalid/empty.
+            Examples: "2022-01-01", "2022-01-01 (updated 2022-01-02)", "updated 2022-01-01"
+
+    Examples:
+        >>> format_created_updated_label("2022-01-01", "2022-01-02")
+        \'2022-01-01 (updated 2022-01-02)\'
+        >>> format_created_updated_label("2022-01-01", "2022-01-01")
+        \'2022-01-01\'
+        >>> format_created_updated_label(None, "2022-01-01")
+        \'updated 2022-01-01\'
+        >>> format_created_updated_label("2022-01-01", None)
+        \'2022-01-01\'
+    '''
+def is_valid_date_string(date_str: str, fmt: str = ...) -> bool:
+    '''Validate that a date string matches the provided strftime format.
+
+    Args:
+        date_str: The date string to validate. Must be a non-empty string.
+        fmt: The strftime format pattern to validate against.
+            Defaults to YYYY-MM-DD format.
+
+    Returns:
+        bool: True if the date string matches the format, False otherwise.
+
+    Raises:
+        ValueError: If the format string is empty or invalid, or if date_str is not a string.
+
+    Examples:
+        >>> is_valid_date_string("2022-01-01")
+        True
+        >>> is_valid_date_string("2022-13-01")
+        False
+        >>> is_valid_date_string("01-01-2022", "%m-%d-%Y")
+        True
+        >>> is_valid_date_string("", "%Y-%m-%d")
+        False
+    '''
+def next_day_iso(date_str: str) -> str:
+    """Return the ISO date string for the day after the given ``YYYY-MM-DD`` date.
+
+    Args:
+        date_str: A date string in ``YYYY-MM-DD`` format.
+
+    Returns:
+        str: The next day's date in ``YYYY-MM-DD`` format.
+
+    Raises:
+        ValueError: If ``date_str`` is not a valid ``YYYY-MM-DD`` date string.
+    """

aip_agents/utils/datetime/timezone.pyi

@@ -0,0 +1,48 @@
+from datetime import datetime
+
+__all__ = ['get_timezone_aware_now', 'ensure_utc_datetime']
+
+def get_timezone_aware_now(timezone: str, fallback_timezone: str = 'UTC') -> tuple[datetime, str, bool]:
+    '''Return a timezone-aware datetime alongside a timezone label.
+
+    This function creates a timezone-aware datetime object using the modern
+    zoneinfo module (Python 3.9+). It gracefully falls back to UTC if the
+    requested timezone is invalid.
+
+    Args:
+        timezone: Desired timezone name in IANA format (e.g., "America/New_York",
+            "Europe/London", "Asia/Tokyo"). Must be a non-empty string.
+        fallback_timezone: Fallback timezone name to use when the primary
+            timezone is invalid. Defaults to "UTC". Must be a non-empty string.
+
+    Returns:
+        tuple[datetime, str, bool]: A 3-tuple containing:
+            - now: A timezone-aware datetime object representing the current time
+            - timezone_label: A human-readable timezone label (e.g., "EST", "UTC")
+            - used_fallback: Boolean indicating whether the fallback timezone was used
+
+    Raises:
+        ValueError: If timezone or fallback_timezone are empty/invalid, or if both
+            the requested timezone and fallback timezone are invalid.
+
+    Examples:
+        >>> now, label, fallback = get_timezone_aware_now("America/New_York")
+        >>> print(f"Current time: {now}, Timezone: {label}, Used fallback: {fallback}")
+        Current time: 2024-01-15 10:30:00-05:00, Timezone: EST, Used fallback: False
+
+        >>> now, label, fallback = get_timezone_aware_now("Invalid/Timezone")
+        >>> print(f"Used fallback: {fallback}, Label: {label}")
+        Used fallback: True, Label: UTC
+    '''
+def ensure_utc_datetime(value: datetime) -> datetime:
+    """Normalize a datetime to UTC (attaching UTC to naive values).
+
+    Args:
+        value: Datetime to normalize.
+
+    Returns:
+        datetime: Timezone-aware datetime expressed in UTC.
+
+    Raises:
+        TypeError: If ``value`` is not a ``datetime`` instance.
+    """

aip_agents/utils/env_loader.pyi

@@ -3,8 +3,8 @@ from _typeshed import Incomplete
 logger: Incomplete
 
 def load_local_env(override: bool = True) -> None:
-    """Load .env from the current working directory or its parents.
+    """Load environment variables from a .env file if python-dotenv is available.
 
     Args:
-        override: Whether to override existing environment variables.
+        override (bool, optional): Whether to override existing environment variables. Defaults to True.
     """

aip_agents/utils/event_handler_registry.pyi

@@ -0,0 +1,23 @@
+from _typeshed import Incomplete
+from aip_agents.schema.a2a import A2AStreamEventType as A2AStreamEventType
+from aip_agents.utils.logger import get_logger as get_logger
+from typing import Any
+
+logger: Incomplete
+
+class EventHandlerRegistry:
+    """Registry for tracking known streaming events with pass-through behaviour."""
+    def __init__(self) -> None:
+        """Initialize the event handler registry with known event types."""
+    def handle(self, event_type: A2AStreamEventType | str | None, payload: dict[str, Any]) -> dict[str, Any]:
+        """Return the payload unchanged while logging unknown events.
+
+        Args:
+            event_type (A2AStreamEventType | str | None): The type of the streaming event.
+            payload (dict[str, Any]): The event payload data.
+
+        Returns:
+            dict[str, Any]: The payload unchanged (pass-through).
+        """
+
+DEFAULT_EVENT_HANDLER_REGISTRY: Incomplete

aip_agents/utils/final_response_builder.pyi

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+__all__ = ['FinalResponseMetadataOptions', 'assemble_final_response']
+
+@dataclass(slots=True)
+class FinalResponseMetadataOptions:
+    """Container for optional metadata fields on final response events."""
+    step_id: str | None = ...
+    previous_step_ids: list[str] | None = ...
+    tool_info: dict[str, Any] | None = ...
+    thinking_and_activity_info: dict[str, Any] | None = ...
+    completion_reason: str | None = ...
+    timeout_seconds: float | None = ...
+    message: dict[str, Any] | None = ...
+    partial_result: str | None = ...
+    metadata_extra: dict[str, Any] | None = ...
+
+def assemble_final_response(*, content: str, artifacts: list[dict[str, Any]] | None = None, metadata_options: FinalResponseMetadataOptions | None = None, status: str = 'success', task_state: str = 'completed', extra_fields: dict[str, Any] | None = None, timestamp: datetime | None = None) -> dict[str, Any]:
+    '''Create a final response event with optional artifacts and overrides.
+
+    Args:
+        content: Human readable message for the final response.
+        artifacts: Optional list of artifact dictionaries to attach.
+        metadata_options: Metadata overrides passed through to the underlying builder.
+        status: Top-level status string; defaults to ``"success"``.
+        task_state: State string describing the task; defaults to ``"completed"``.
+        extra_fields: Additional top-level fields to merge onto the event.
+        timestamp: Explicit timestamp for the event. Defaults to ``datetime.now(UTC)``.
+
+    Returns:
+        dict[str, Any]: Final response event payload ready for downstream streaming.
+    '''

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

@@ -1,7 +1,7 @@
+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
-from typing import Sequence
 
 def convert_langchain_messages_to_gllm_messages(messages: Sequence[BaseMessage], instruction: str) -> list[Message]:
     """Convert LangChain messages to gllm-inference Message format.

aip_agents/utils/langgraph/tool_managers/a2a_tool_manager.pyi

@@ -2,8 +2,8 @@ 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_manager import LoggerManager as LoggerManager
-from langchain_core.tools import BaseTool as BaseTool
+from aip_agents.utils.logger import get_logger as get_logger
+from langchain_core.tools import BaseTool
 
 logger: Incomplete
 

aip_agents/utils/langgraph/tool_managers/base_tool_manager.pyi

@@ -1,13 +1,12 @@
-import abc
 from _typeshed import Incomplete
 from abc import ABC, abstractmethod
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+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, metaclass=abc.ABCMeta):
+class BaseLangGraphToolManager(ABC):
     """Base class for managing specialized tools in LangGraph agents.
 
     This abstract base class provides a common interface for tool managers

aip_agents/utils/langgraph/tool_managers/delegation_tool_manager.pyi

@@ -1,15 +1,16 @@
 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_manager import LoggerManager as LoggerManager
-from aip_agents.utils.metadata_helper import MetadataFieldKeys as MetadataFieldKeys
+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.token_usage_helper import 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.runnables import RunnableConfig as RunnableConfig
-from langchain_core.tools import BaseTool as BaseTool
-from langgraph.types import StreamWriter as StreamWriter
+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
@@ -30,8 +31,13 @@ class DelegationToolManager(BaseLangGraphToolManager):
     Simplified version following legacy BaseLangChainAgent patterns.
     """
     registered_agents: list[BaseAgent]
-    def __init__(self) -> None:
-        """Initialize the delegation tool manager."""
+    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.

aip_agents/utils/langgraph/tool_output_management.pyi

@@ -1,7 +1,7 @@
 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_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 from dataclasses import dataclass
 from datetime import datetime, timedelta
 from typing import Any
@@ -91,7 +91,14 @@ class ToolOutput:
     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."""
+        """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.
 
@@ -109,6 +116,12 @@ class ToolOutput:
         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

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']

aip_agents/utils/metadata/activity_narrative/builder.pyi

@@ -0,0 +1,35 @@
+from _typeshed import Incomplete
+from aip_agents.schema.hitl import ApprovalDecisionType as ApprovalDecisionType, HitlMetadata as HitlMetadata
+from aip_agents.utils.formatter_llm_client import FormatterInvocationError as FormatterInvocationError, FormatterInvokerUnavailableError as FormatterInvokerUnavailableError, get_formatter_llm_client as get_formatter_llm_client
+from aip_agents.utils.logger import get_logger as get_logger
+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 typing import Any
+
+logger: Incomplete
+
+class ActivityNarrativeBuilder:
+    """Generate structured activity payloads via formatter LLM.
+
+    High-level flow:
+    1. Gather raw metadata about a tool/delegate event and normalize it into an ``ActivityContext``.
+    2. Sanitize arguments and outputs so no sensitive values reach downstream renderers or the formatter model.
+    3. Prompt the shared formatter with phase-specific instructions (e.g., describe intent on start, summarize results on end).
+    4. If the formatter responds with usable heading/body text, surface it; otherwise fall back to deterministic templates
+       built from the sanitized context.
+
+    This approach keeps SSE activity cards readable when the formatter is healthy while still providing sensible copy when
+    the formatter is unavailable or returns low-quality text.
+    """
+    def __init__(self) -> None:
+        """Initialize the activity narrative builder."""
+    def build_payload(self, metadata: dict[str, Any] | None) -> dict[str, Any] | None:
+        """Build enriched payload for the provided metadata.
+
+        Args:
+            metadata: The metadata dictionary containing tool_info, hitl, and other context.
+
+        Returns:
+            Dictionary payload with a rendered message, or None when not available.
+        """

aip_agents/utils/metadata/activity_narrative/constants.pyi

@@ -0,0 +1,10 @@
+from aip_agents.schema.hitl import ApprovalDecisionType
+
+__all__ = ['SYSTEM_PROMPT', 'DELEGATE_PREFIX', 'OUTPUT_EXCERPT_MAX_CHARS', 'HITL_PENDING_TITLE', 'HITL_PENDING_DESCRIPTION', 'HITL_DECISION_MESSAGES']
+
+SYSTEM_PROMPT: str
+DELEGATE_PREFIX: str
+OUTPUT_EXCERPT_MAX_CHARS: int
+HITL_PENDING_TITLE: str
+HITL_PENDING_DESCRIPTION: str
+HITL_DECISION_MESSAGES: dict[ApprovalDecisionType, tuple[str, str]]

aip_agents/utils/metadata/activity_narrative/context.pyi

@@ -0,0 +1,32 @@
+from aip_agents.schema.hitl import ApprovalDecisionType, HitlMetadata
+from dataclasses import dataclass
+from enum import StrEnum
+
+__all__ = ['ActivityContext', 'ActivityPhase']
+
+class ActivityPhase(StrEnum):
+    """Lifecycle phases for tool, delegate, and HITL events."""
+    TOOL_START: str
+    TOOL_END: str
+    DELEGATE_START: str
+    DELEGATE_END: str
+    HITL_PENDING: str
+    HITL_RESOLVED: str
+JSONScalar = str | int | float | bool | None
+
+@dataclass
+class ActivityContext:
+    """Structured representation of an activity event."""
+    phase: ActivityPhase
+    agent_name: str | None
+    subject_name: str | None
+    sanitized_args: dict[str, JSONValue] | None
+    sanitized_output: JSONValue | None
+    arguments_excerpt: str | None
+    output_excerpt: str | None
+    error_excerpt: str | None
+    step_id: str | None = ...
+    is_delegate: bool = ...
+    hitl_metadata: HitlMetadata | None = ...
+    hitl_decision: ApprovalDecisionType | None = ...
+    default_heading: str | None = ...