aip-agents-binary 0.5.25b1__py3-none-macosx_13_0_arm64.whl

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.py

@@ -0,0 +1,195 @@
+"""Defines a logger for logging.
+
+Example of displayed logs using simple format:
+    [2025-11-27T15:50:03+0700.643 uvicorn.error INFO] Application startup complete.
+
+Example of displayed logs using JSON format:
+    {"timestamp": "2025-11-27T15:51:00+0700", "name": "uvicorn.error", "level": "INFO", "message": "Application startup complete."}
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+
+References:
+    [1] https://github.com/GDP-ADMIN/gsdp
+    [2] https://docs.google.com/document/d/1RnXbiAGc6vCFt03YPMM8UleRy0h_pRjzqobdb_u8ty0/edit?tab=t.0
+        (Proposal for Standardized Log Format)
+    [3] https://github.com/GDP-ADMIN/glchat/blob/main/applications/glchat-be/glchat_be/utils/logger.py
+"""
+
+import logging
+import os
+import threading
+import warnings
+
+from dotenv import load_dotenv
+from gllm_core.utils.logger_manager import LoggerManager
+
+load_dotenv()
+
+LOGGER_NAME = "AIPAgentsLogger"
+
+LOG_LEVEL = os.getenv("LOG_LEVEL", logging.INFO)
+if isinstance(LOG_LEVEL, str):
+    try:
+        LOG_LEVEL = getattr(logging, LOG_LEVEL.upper())
+    except AttributeError:
+        LOG_LEVEL = logging.INFO
+
+
+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 = "Updating LLM class for"
+
+    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.
+        """
+        if not record.name.startswith("google.adk"):
+            return True
+
+        try:
+            message = record.getMessage()
+        except Exception:  # pragma: no cover - defensive fallback
+            message = str(record.msg)
+
+        if isinstance(message, str) and message.startswith(self.SUPPRESSED_PREFIX):
+            return False
+
+        return True
+
+
+LOG_FILTERS = [_GoogleAdkLogFilter()]
+
+logger_manager = LoggerManager()
+root_logger = logger_manager.get_logger()
+
+_LOGGER_LOCK = threading.Lock()
+
+_LOG_FILTERS_CONFIGURED = False
+
+
+def _configure_log_filters() -> None:
+    """Configure log filters to be applied to all handlers."""
+    global _LOG_FILTERS_CONFIGURED
+
+    with _LOGGER_LOCK:
+        if _LOG_FILTERS_CONFIGURED:
+            return
+
+        for log_filter in LOG_FILTERS:
+            root_logger.addFilter(log_filter)
+            for handler in root_logger.handlers:
+                handler.addFilter(log_filter)
+
+        _LOG_FILTERS_CONFIGURED = True
+
+
+_configure_log_filters()
+
+
+def get_logger(name: str = LOGGER_NAME, level: int = LOG_LEVEL) -> 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.
+    """
+    with _LOGGER_LOCK:
+        if not name:
+            name = LOGGER_NAME
+        if logging._levelToName.get(level) is None:
+            level = LOG_LEVEL
+
+        logger = logger_manager.get_logger(name)
+        logger.setLevel(level)
+        logger.propagate = False
+
+        if not logger.hasHandlers():
+            logger.handlers = root_logger.handlers
+
+        return logger
+
+
+logger = get_logger()
+
+THIRD_PARTY_LOGGER_NAMES = [
+    "uvicorn",
+    "uvicorn.access",
+    "uvicorn.error",
+    "apscheduler",
+    "apscheduler.scheduler",
+    "apscheduler.executors.default",
+    "apscheduler.jobstores.default",
+]
+
+_THIRD_PARTY_LOGGERS_CONFIGURED = False
+
+
+def _configure_third_party_loggers() -> None:
+    """Configure third-party loggers to use the same handlers and settings."""
+    global _THIRD_PARTY_LOGGERS_CONFIGURED
+
+    with _LOGGER_LOCK:
+        if _THIRD_PARTY_LOGGERS_CONFIGURED:
+            return
+
+        for name in THIRD_PARTY_LOGGER_NAMES:
+            third_party_logger = logging.getLogger(name)
+            third_party_logger.handlers = logger.handlers
+            third_party_logger.setLevel(logger.level)
+            third_party_logger.propagate = logger.propagate
+
+        _THIRD_PARTY_LOGGERS_CONFIGURED = True
+
+
+_configure_third_party_loggers()
+
+
+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.
+    """
+
+    _instance = None
+    _lock = threading.Lock()
+
+    def __new__(cls):
+        """Initialize the singleton instance."""
+        warnings.warn(
+            "LoggerManager is deprecated and will be removed in a future version. "
+            "Use get_logger() function directly instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        with cls._lock:
+            if cls._instance is None:
+                cls._instance = super().__new__(cls)
+            return cls._instance
+
+    def get_logger(self, name: str = LOGGER_NAME, level: int = LOG_LEVEL) -> 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.
+        """
+        return get_logger(name, level)

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__.py

@@ -0,0 +1,27 @@
+"""Metadata utilities module.
+
+This module contains utilities for creating and handling metadata for A2A communication.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from aip_agents.utils.metadata.activity_metadata_helper import (
+    DEFAULT_ACTIVITY_INFO,
+    _format_tool_or_subagent_name,
+    create_tool_activity_info,
+)
+from aip_agents.utils.metadata.schemas import Activity, ActivityDataType, Thinking
+from aip_agents.utils.metadata.thinking_metadata_helper import (
+    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/__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']