aip-agents-binary 0.5.25__py3-none-any.whl → 0.5.25b8__py3-none-any.whl

aip_agents/utils/event_handler_registry.pyi

@@ -1,23 +0,0 @@
-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/file_prompt_utils.pyi

@@ -1,21 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.utils.logger import get_logger as get_logger
-
-logger: Incomplete
-FILE_PATH_SYSTEM_NOTE: str
-FILE_PATH_INACCESSIBLE_NOTE: str
-FILE_URL_SYSTEM_NOTE: str
-
-def augment_query_with_file_paths(query: str, files: list[str | dict[str, object]]) -> str:
-    """Augment query with file path system notes.
-
-    Args:
-        query: The original user query string.
-        files: List of local filesystem paths or file metadata dicts to include.
-
-    Returns:
-        The query with system notes appended for each file path.
-
-    Raises:
-        ValueError: If files is not a list of strings or metadata dicts.
-    """

aip_agents/utils/final_response_builder.pyi

@@ -1,34 +0,0 @@
-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

@@ -1,71 +0,0 @@
-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

@@ -1,3 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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

@@ -1,5 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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

@@ -1,56 +0,0 @@
-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

@@ -1,292 +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 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.
-        """