aip-agents-binary 0.0.0b2__py3-none-any.whl → 0.5.12__py3-none-any.whl

aip_agents/utils/langgraph/tool_output_management.pyi

@@ -1,310 +0,0 @@
-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 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."""
-    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.
-        """
-
-@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 get_stats(self) -> dict[str, Any]:
-        """Get thread-safe statistics about the current state of the manager.
-
-        Args:
-            thread_id: Thread ID to generate summary for.
-            max_entries: Maximum number of entries to include in the summary.
-            Defaults to 10.
-
-        Returns:
-            Dictionary containing current statistics including output count,
-            total size, call count, and thread information.
-        """
-    def clear_all_outputs(self) -> int:
-        """Clear all stored outputs and reset counters.
-
-        Thread-safe: This method uses internal locking to ensure safe concurrent access.
-
-        Returns:
-            Number of outputs that were cleared.
-        """
-    def clear_thread_outputs(self, thread_id: str) -> int:
-        """Clear all stored outputs for a specific thread.
-
-        Thread-safe: This method uses internal locking to ensure safe concurrent access.
-
-        Args:
-            thread_id: The thread ID to clear outputs for.
-
-        Returns:
-            Number of outputs that were cleared for the thread.
-        """
-    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_manager.pyi

@@ -1,151 +0,0 @@
-import logging
-from _typeshed import Incomplete
-
-BOSA_CORE_AVAILABLE: bool
-DEFAULT_LOG_FORMAT: Incomplete
-DEFAULT_DATE_FORMAT: str
-LOG_COLORS: Incomplete
-MAX_LOG_COLORS_LENGTH: Incomplete
-TRUNCATED_MESSAGE: str
-MAX_MESSAGE_LENGTH: Incomplete
-
-class StandardizedFormatter(logging.Formatter):
-    """Custom formatter that outputs logs in standardized JSON format with colors.
-
-    Follows the standardized log format:
-    - level: string (e.g., INFO, ERROR)
-    - timestamp: ISO 8601 with timezone (e.g., 2025-07-23T00:29:05.091Z)
-    - message: string (the content of the log) (max 500000 context length)
-    - error: object (for error logs only)
-        - message: string (the error message)
-        - code: string (specific error code)
-        - stacktrace: string (the stack trace for debugging)
-    """
-    def format(self, record: logging.LogRecord) -> str:
-        """Format the log record in standardized JSON format with colors.
-
-        Args:
-            record (logging.LogRecord): The log record to be formatted.
-
-        Returns:
-            str: The formatted log message in JSON format.
-        """
-
-class ColoredFormatter(logging.Formatter):
-    """Custom formatter to add colors based on log level."""
-    def format(self, record: logging.LogRecord) -> str:
-        """Format the log record with colors based on log level.
-
-        Args:
-            record (logging.LogRecord): The log record to be formatted.
-
-        Returns:
-            str: The formatted log message with color codes.
-        """
-
-class LoggerManager:
-    '''A singleton class to manage logging configuration.
-
-    This class ensures that the root logger is initialized only once and is used across the application.
-    Supports both traditional colored output and standardized format with colors.
-
-    Example to get and use the logger:
-    ```python
-    manager = LoggerManager()
-
-    logger = manager.get_logger()
-
-    logger.info("This is an info message")
-    ```
-
-    Example to set logging configuration:
-    ```python
-    manager = LoggerManager()
-
-    manager.set_level(logging.DEBUG)
-    manager.set_output_format("traditional")  # or "standardized"
-    ```
-
-    Example to add a custom handler:
-    ```python
-    manager = LoggerManager()
-
-    handler = logging.FileHandler("app.log")
-    manager.add_handler(handler)
-    ```
-
-    Output format examples:
-
-    Traditional format:
-    ```python
-    [16/04/2025 15:08:18.323 GDPLabsGenAILogger INFO] Loading prompt_builder catalog for chatbot `general-purpose`
-    ```
-
-    Standardized format:
-    ```json
-    {
-        "level": "INFO",
-        "timestamp": "2025-07-23T00:29:05.091Z",
-        "message": "Loading prompt_builder catalog for chatbot `general-purpose`"
-    }
-    ```
-
-    Error standardized format:
-    ```json
-    {
-        "level": "ERROR",
-        "timestamp": "2025-07-23T00:29:05.091Z",
-        "message": "Failed to load configuration",
-        "error": {
-            "message": "Configuration file not found",
-            "code": "CONFIG_NOT_FOUND",
-            "stacktrace": "Traceback (most recent call last):..."
-        }
-    }
-    ```
-    '''
-    def __new__(cls):
-        """Initialize the singleton instance."""
-    def get_logger(self, name: str | None = None) -> logging.Logger:
-        """Get a logger instance.
-
-        This method returns a logger instance that is a child of the root logger. If name is not provided,
-        the root logger will be returned instead.
-
-        Args:
-            name (str | None, optional): The name of the child logger.
-                If None, the root logger will be returned. Defaults to None.
-
-        Returns:
-            logging.Logger: Configured logger instance.
-        """
-    def set_level(self, level: int) -> None:
-        """Set logging level for all loggers in the hierarchy.
-
-        Args:
-            level (int): The logging level to set (e.g., logging.INFO, logging.DEBUG).
-        """
-    def set_output_format(self, output_format: str) -> None:
-        '''Set the output format for all loggers in the hierarchy.
-
-        Args:
-            output_format (str): The output format to set. Must be either "standardized" or "traditional".
-        '''
-    def set_log_format(self, log_format: str) -> None:
-        """Set logging format for all loggers in the hierarchy (traditional mode only).
-
-        Args:
-            log_format (str): The log format to set.
-        """
-    def set_date_format(self, date_format: str) -> None:
-        """Set date format for all loggers in the hierarchy (traditional mode only).
-
-        Args:
-            date_format (str): The date format to set.
-        """
-    def add_handler(self, handler: logging.Handler) -> None:
-        """Add a custom handler to the root logger.
-
-        Args:
-            handler (logging.Handler): The handler to add to the root logger.
-        """

aip_agents/utils/metadata_helper.pyi

@@ -1,110 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
-from aip_agents.utils.token_usage_helper import STEP_USAGE_KEY as STEP_USAGE_KEY, TOTAL_USAGE_KEY as TOTAL_USAGE_KEY
-from enum import StrEnum
-from typing import Any
-
-logger: Incomplete
-THINKING_DATA_TYPE: str
-DEFAULT_STEP_INDICATOR_MESSAGE: str
-FINAL_AGENT_THINKING_FINISHED_CONTENT: str
-FINAL_THINKING_AND_ACTIVITY_INFO: Incomplete
-DEFAULT_THINKING_AND_ACTIVITY_INFO: Incomplete
-TOOL_EXECUTION_RUNNING_TEMPLATE: str
-TOOL_EXECUTION_COMPLETE_TEMPLATE: str
-SUBAGENT_DELEGATION_TEMPLATE: str
-SUBAGENT_COMPLETE_TEMPLATE: str
-MIXED_EXECUTION_TEMPLATE: str
-DELEGATE_PREFIX: str
-
-class Kind(StrEnum):
-    """Constants for metadata kind values."""
-    AGENT_STEP = 'agent_step'
-    AGENT_THINKING_STEP = 'agent_thinking_step'
-    FINAL_RESPONSE = 'final_response'
-    FINAL_THINKING_STEP = 'final_agent_thinking_step'
-    AGENT_DEFAULT = 'agent_default'
-
-class Status(StrEnum):
-    """Constants for metadata status values."""
-    RUNNING = 'running'
-    FINISHED = 'finished'
-    STOPPED = 'stopped'
-
-class MetadataFieldKeys(StrEnum):
-    """Enumeration of standard metadata field keys used in A2A events."""
-    KIND = 'kind'
-    STATUS = 'status'
-    TIME = 'time'
-    MESSAGE = 'message'
-    TOOL_INFO = 'tool_info'
-    REFERENCES = 'references'
-    THINKING_AND_ACTIVITY_INFO = 'thinking_and_activity_info'
-    STEP_USAGE = STEP_USAGE_KEY
-    TOTAL_USAGE = TOTAL_USAGE_KEY
-
-class MetadataTimeTracker:
-    """Tracks cumulative execution time across agent steps for final response metadata.
-
-    This class provides a clean way to accumulate execution times from individual
-    agent steps and apply the total time to final response metadata.
-    """
-    def __init__(self) -> None:
-        """Initialize the time tracker with zero accumulated time."""
-    def update_response_metadata(self, response: dict[str, Any]) -> dict[str, Any]:
-        """Update response metadata with accumulated time tracking.
-
-        Args:
-            response: Response dictionary containing metadata
-
-        Returns:
-            Response with updated metadata for final responses. If any error occurs,
-            returns the original response unchanged.
-        """
-
-def detect_agent_step_content(content: str, default_kind: str, tool_calls: Any | None = None) -> str:
-    """Detect if content corresponds to agent step patterns from LangGraph.
-
-    Args:
-        content: The content to detect.
-        default_kind: The default kind to return if the content does not match any of the patterns.
-        tool_calls: The tool calls to detect.
-
-    Returns:
-        The kind of the content.
-    """
-def create_metadata(content: str = '', kind: Kind = ..., status: Status = ..., tool_calls: Any | None = None, is_final: bool = False, time: float | None = None, existing_metadata: dict[str, Any] | None = None) -> dict[str, Any]:
-    """Create metadata for A2A responses with content-based message.
-
-    Args:
-        content: The content to create metadata for.
-        kind: The kind of the content.
-        status: The status of the content.
-        tool_calls: The tool calls to create metadata for.
-        is_final: Whether the content is final.
-        time: The time of the content.
-        existing_metadata: Optional existing metadata to merge with. Existing metadata
-            takes precedence over generated metadata for conflicting keys.
-
-    Returns:
-        The metadata for the content, merged with existing metadata if provided.
-    """
-def create_tool_processing_metadata(original_metadata: dict[str, Any] | None = None) -> dict[str, Any]:
-    """Create metadata for tool processing events (tool_call and tool_result).
-
-    Args:
-        original_metadata: Optional original metadata to merge with.
-
-    Returns:
-        Metadata dictionary with agent_thinking_step kind and no message/time/status.
-    """
-def create_status_update_metadata(content: str, custom_metadata: dict[str, Any] | None = None) -> dict[str, Any]:
-    """Create metadata for status update events with content-based rules.
-
-    Args:
-        content: The content of the status update.
-        custom_metadata: Optional custom metadata to merge with.
-
-    Returns:
-        Metadata dictionary following the specific rules for different content types.
-    """

aip_agents/utils/name_preprocessor/__init__.pyi

@@ -1,6 +0,0 @@
-from aip_agents.utils.name_preprocessor.base_name_preprocessor import BaseNamePreprocessor as BaseNamePreprocessor
-from aip_agents.utils.name_preprocessor.google_name_preprocessor import GoogleNamePreprocessor as GoogleNamePreprocessor
-from aip_agents.utils.name_preprocessor.name_preprocessor import NamePreprocessor as NamePreprocessor
-from aip_agents.utils.name_preprocessor.openai_name_preprocessor import OpenAINamePreprocessor as OpenAINamePreprocessor
-
-__all__ = ['GoogleNamePreprocessor', 'OpenAINamePreprocessor', 'BaseNamePreprocessor', 'NamePreprocessor']

aip_agents/utils/name_preprocessor/google_name_preprocessor.pyi

@@ -1,38 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
-from aip_agents.utils.name_preprocessor import BaseNamePreprocessor as BaseNamePreprocessor
-
-logger: Incomplete
-
-class GoogleNamePreprocessor(BaseNamePreprocessor):
-    """Concrete implementation of NamePreprocessor according to Google's name requirements."""
-    NAME_SETTINGS: Incomplete
-    CUT_OFF_INDEX: int
-    def sanitize_agent_name(self, name: str) -> str:
-        """Preprocess an input name according to Google's name requirements for agents.
-
-        Args:
-            name: The input name to preprocess.
-
-        Returns:
-            A name that is valid for Google.
-
-        Notes:
-            Name should start with a letter (a-z, A-Z) or an underscore (_),
-            and can only contain letters, digits (0-9), and underscores.
-            It has no length limit. ( based on experiment )
-        """
-    def sanitize_tool_name(self, name: str) -> str:
-        """Preprocess an input name according to Google's name requirements for tools.
-
-        Args:
-            name: The input name to preprocess.
-
-        Returns:
-            A name that is valid for Google.
-
-        Notes:
-            Name should start with a letter (a-z, A-Z) or an underscore (_),
-            and can only contain letters, digits (0-9), underscores, and dashes.
-            It has a length limit of 64 characters, but google throws error if the length is exactly 64, so cut to 63.
-        """

aip_agents/utils/name_preprocessor/name_preprocessor.pyi

@@ -1,41 +0,0 @@
-from .base_name_preprocessor import BaseNamePreprocessor as BaseNamePreprocessor
-from .google_name_preprocessor import GoogleNamePreprocessor as GoogleNamePreprocessor
-from .openai_name_preprocessor import OpenAINamePreprocessor as OpenAINamePreprocessor
-from _typeshed import Incomplete
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
-
-logger: Incomplete
-
-class NamePreprocessor:
-    """Name Preprocessor for Google ADK and OpenAI compatible models.
-
-    Args:
-        provider: The provider of the model.
-    """
-    PROVIDER_TO_NAME_PREPROCESSOR_MAP: Incomplete
-    provider: Incomplete
-    preprocessor: Incomplete
-    def __init__(self, provider: str) -> None:
-        """Initialize the name preprocessor.
-
-        Args:
-            provider: The provider of the model.
-        """
-    def sanitize_agent_name(self, name: str) -> str:
-        """Preprocess an input name according to the rules of the name processor.
-
-        Args:
-            name: The input name to preprocess.
-
-        Returns:
-            A name that is valid for the name processor.
-        """
-    def sanitize_tool_name(self, name: str) -> str:
-        """Preprocess an input name according to the rules of the name processor.
-
-        Args:
-            name: The input name to preprocess.
-
-        Returns:
-            A name that is valid for the name processor.
-        """