aip-agents-binary 0.6.1__py3-none-any.whl → 0.6.2__py3-none-any.whl

aip_agents/mcp/client/persistent_session.pyi

@@ -1,122 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.mcp.client.connection_manager import MCPConnectionManager as MCPConnectionManager
-from aip_agents.mcp.utils.config_validator import validate_allowed_tools_list as validate_allowed_tools_list
-from aip_agents.utils.logger import get_logger as get_logger
-from collections.abc import Awaitable as Awaitable
-from gllm_tools.mcp.client.config import MCPConfiguration
-from mcp import ClientSession
-from mcp.types import CallToolResult, Tool as Tool
-from typing import Any
-
-logger: Incomplete
-
-class PersistentMCPSession:
-    """Persistent MCP session that reuses connections.
-
-    This session wrapper manages the connection lifecycle and caches tools
-    to avoid repeated initialization overhead. It provides automatic reconnection
-    and thread-safe operations.
-
-    Tool Filtering:
-        When allowed_tools is configured, tools are filtered inline during list_tools()
-        and permission checked in call_tool() using set lookup.
-    """
-    server_name: Incomplete
-    config: Incomplete
-    connection_manager: Incomplete
-    client_session: ClientSession | None
-    tools: list[Tool]
-    def __init__(self, server_name: str, config: MCPConfiguration, allowed_tools: list[str] | None = None) -> None:
-        """Initialize persistent session.
-
-        Args:
-            server_name: Name of the MCP server
-            config: MCP server configuration
-            allowed_tools: Optional list of tool names to allow. None or empty means all tools allowed.
-        """
-    async def initialize(self) -> None:
-        """Initialize session once and cache tools.
-
-        This method is idempotent and can be called multiple times safely.
-
-        Raises:
-            Exception: If session initialization fails
-        """
-    async def call_tool(self, name: str, arguments: dict[str, Any]) -> CallToolResult:
-        """Call MCP tool using persistent session.
-
-        Args:
-            name (str): Tool name
-            arguments (dict[str, Any]): Tool arguments
-
-        Returns:
-            CallToolResult: Tool call result
-
-        Raises:
-            Exception: If tool call fails
-        """
-    async def read_resource(self, uri: str) -> Any:
-        """Read an MCP resource using persistent session.
-
-        Args:
-            uri (str): The URI of the resource to read
-
-        Returns:
-            Any: The resource content
-
-        Raises:
-            Exception: If resource reading fails
-        """
-    async def list_tools(self) -> list[Tool]:
-        """Get cached tools list with allowed tools filtering applied.
-
-        Returns:
-            list[Tool]: a copy of list of available tools, filtered to only allowed tools if configured
-        """
-    def get_tools_count(self) -> int:
-        """Get count of allowed tools.
-
-        Returns:
-            Count of allowed tools
-        """
-    async def ensure_connected(self) -> None:
-        """Ensure connection is healthy, reconnect if needed.
-
-        This method provides automatic reconnection capability.
-
-        Raises:
-            Exception: If reconnection fails
-        """
-    async def disconnect(self) -> None:
-        """Disconnect session gracefully.
-
-        This method cleans up all resources and connections.
-        Always succeeds, even if the session was already in an error state.
-        """
-    @property
-    def is_initialized(self) -> bool:
-        """Check if session is initialized.
-
-        Returns:
-            bool: True if initialized and connected, False otherwise
-        """
-    @property
-    def allowed_tools(self) -> list[str] | None:
-        """Return the configured allowed tools, sorted if present.
-
-        Returns:
-            Sorted list of allowed tool names, or None if unrestricted.
-        """
-    def update_allowed_tools(self, allowed_tools: list[str] | None) -> bool:
-        """Update the list of allowed tools for this session.
-
-        Args:
-            allowed_tools: New list of allowed tool names or None for no restriction.
-                None and empty list both mean 'no restrictions, allow all tools'.
-
-        Returns:
-            bool: True if the configuration changed, False otherwise.
-
-        Raises:
-            ValueError: If allowed_tools contains invalid entries.
-        """

aip_agents/mcp/client/session_pool.pyi

@@ -1,101 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.mcp.client.persistent_session import PersistentMCPSession as PersistentMCPSession
-from aip_agents.mcp.utils.config_validator import validate_allowed_tools_config as validate_allowed_tools_config, validate_allowed_tools_list as validate_allowed_tools_list
-from aip_agents.utils.logger import get_logger as get_logger
-from gllm_tools.mcp.client.config import MCPConfiguration
-from mcp.types import Tool as Tool
-
-logger: Incomplete
-
-class MCPSessionPool:
-    """Manages pool of persistent MCP sessions.
-
-    This pool provides centralized management of MCP sessions, including
-    initialization, tool collection, and resource cleanup. Sessions are
-    reused across the agent lifecycle.
-    """
-    sessions: dict[str, PersistentMCPSession]
-    def __init__(self) -> None:
-        """Initialize empty session pool."""
-    async def get_or_create_session(self, server_name: str, config: MCPConfiguration, allowed_tools: list[str] | None = None) -> PersistentMCPSession:
-        """Get existing session or create new one.
-
-        Args:
-            server_name (str): Name of the MCP server
-            config (MCPConfiguration): MCP server configuration
-            allowed_tools (list[str] | None): Optional list of tool names to allow. None means all tools allowed.
-
-        Returns:
-            PersistentMCPSession: Persistent MCP session
-
-        Raises:
-            Exception: If session creation fails
-        """
-    async def initialize_all_sessions(self, server_configs: dict[str, MCPConfiguration]) -> None:
-        """Initialize all sessions and cache tools.
-
-        This method initializes all configured MCP servers concurrently
-        for better performance.
-
-        Args:
-            server_configs (dict[str, MCPConfiguration]): Dictionary of server configurations
-
-        Raises:
-            Exception: If any session initialization fails
-        """
-    def get_all_active_sessions(self) -> dict[str, PersistentMCPSession]:
-        """Get all active sessions.
-
-        Returns:
-            dict[str, PersistentMCPSession]: Dictionary of active sessions by server name
-        """
-    @property
-    def active_sessions(self) -> list[str]:
-        """Get list of active session names.
-
-        Returns:
-            list[str]: List of active session names
-        """
-    async def get_all_tools(self) -> list[Tool]:
-        """Get all cached tools from all active sessions.
-
-        Returns:
-            list[Tool]: List of all available tools across all sessions
-        """
-    async def close_session(self, server_name: str) -> None:
-        """Close specific session.
-
-        Args:
-            server_name (str): Name of the server session to close
-        """
-    async def close_all_sessions(self) -> None:
-        """Close all sessions gracefully.
-
-        This method ensures all resources are cleaned up properly.
-        """
-    @property
-    def is_initialized(self) -> bool:
-        """Check if session pool is initialized.
-
-        Returns:
-            bool: True if initialized, False otherwise
-        """
-    @property
-    def session_count(self) -> int:
-        """Get number of active sessions.
-
-        Returns:
-            int: Number of active sessions
-        """
-    def get_session(self, server_name: str) -> PersistentMCPSession:
-        """Get specific session by name.
-
-        Args:
-            server_name (str): Name of the server
-
-        Returns:
-            PersistentMCPSession: The requested session
-
-        Raises:
-            KeyError: If session doesn't exist
-        """

aip_agents/mcp/client/transports.pyi

@@ -1,132 +0,0 @@
-from _typeshed import Incomplete
-from abc import ABC, abstractmethod
-from aip_agents.utils.logger import get_logger as get_logger
-from collections.abc import AsyncIterator as AsyncIterator
-from enum import StrEnum
-from gllm_tools.mcp.client.config import MCPConfiguration
-from typing import Any, Protocol
-
-class TransportContext(Protocol):
-    """Protocol defining the interface for async context managers used in MCP transport connections."""
-    async def __aenter__(self) -> None:
-        """Enter the async context, establishing the connection and returning read/write streams."""
-    async def __aexit__(self, _exc_type, _exc_val, _exc_tb) -> None:
-        """Exit the async context, performing cleanup and closing the connection.
-
-        Args:
-            _exc_type: Exception type if an exception occurred.
-            _exc_val: Exception value if an exception occurred.
-            _exc_tb: Exception traceback if an exception occurred.
-        """
-
-logger: Incomplete
-DEFAULT_TIMEOUT: float
-
-class TransportType(StrEnum):
-    """Enum for supported MCP transport types."""
-    HTTP: str
-    SSE: str
-    STDIO: str
-
-class Transport(ABC):
-    """Abstract base class for MCP transports."""
-    server_name: Incomplete
-    config: Incomplete
-    ctx: Any
-    def __init__(self, server_name: str, config: MCPConfiguration) -> None:
-        """Initialize the transport.
-
-        Args:
-            server_name (str): Name of the MCP server.
-            config (MCPConfiguration): Configuration for the transport.
-        """
-    @abstractmethod
-    async def connect(self) -> tuple[AsyncIterator[bytes], AsyncIterator[bytes], TransportContext]:
-        """Establish connection and return read/write streams and context manager.
-
-        Returns:
-            tuple[AsyncIterator[bytes], AsyncIterator[bytes], Any]:
-                (read_stream, write_stream, ctx)
-            Where:
-                - read_stream: AsyncIterator[bytes] for reading from the server.
-                - write_stream: AsyncIterator[bytes] for writing to the server.
-                - ctx: The async context manager instance for cleanup via __aexit__.
-
-        Raises:
-            ValueError: If required config (e.g., URL or command) is missing.
-            ConnectionError: If connection establishment fails.
-        """
-    async def close(self) -> None:
-        """Clean up the transport connection."""
-
-class SSETransport(Transport):
-    """SSE transport handler."""
-    ctx: Incomplete
-    async def connect(self) -> tuple[AsyncIterator[bytes], AsyncIterator[bytes], TransportContext]:
-        """Connect using SSE transport.
-
-        Builds SSE URL from config, initializes client with timeout, and enters context.
-
-        Returns:
-            tuple[AsyncIterator[bytes], AsyncIterator[bytes], Any]: (read_stream, write_stream, ctx)
-
-        Raises:
-            ValueError: If URL is missing.
-            ConnectionError: If SSE connection fails.
-        """
-
-class HTTPTransport(Transport):
-    """Streamable HTTP transport handler."""
-    def __init__(self, server_name: str, config: MCPConfiguration) -> None:
-        """Initialize the HTTP transport.
-
-        Args:
-            server_name (str): Name of the MCP server.
-            config (MCPConfiguration): Configuration for the transport.
-        """
-    async def close(self) -> None:
-        """Clean up the transport connection and any owned HTTP client."""
-    ctx: Incomplete
-    async def connect(self) -> tuple[AsyncIterator[bytes], AsyncIterator[bytes], TransportContext]:
-        """Connect using streamable HTTP transport.
-
-        Builds MCP URL from config, initializes client with timeout, and enters context.
-
-        Returns:
-            tuple[AsyncIterator[bytes], AsyncIterator[bytes], Any]: (read_stream, write_stream, ctx)
-
-        Raises:
-            ValueError: If URL is missing.
-            ConnectionError: If HTTP connection fails.
-        """
-
-class StdioTransport(Transport):
-    """STDIO transport handler."""
-    ctx: Incomplete
-    async def connect(self) -> tuple[AsyncIterator[bytes], AsyncIterator[bytes], TransportContext]:
-        """Connect using STDIO transport.
-
-        Initializes stdio client from command/args/env in config and enters context.
-
-        Returns:
-            tuple[AsyncIterator[bytes], AsyncIterator[bytes], Any]: (read_stream, write_stream, ctx)
-
-        Raises:
-            ValueError: If command is missing.
-            ConnectionError: If STDIO connection fails.
-        """
-
-def create_transport(server_name: str, config: MCPConfiguration, transport_type: TransportType | str) -> Transport:
-    """Factory to create the appropriate transport instance.
-
-    Args:
-        server_name (str): Server name
-        config (MCPConfiguration): Config
-        transport_type (str): Transport type ('http', 'sse', 'stdio')
-
-    Returns:
-        Transport: Concrete transport instance
-
-    Raises:
-        ValueError: If transport_type is unsupported.
-    """

aip_agents/mcp/utils/config_validator.pyi

@@ -1,82 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.utils.logger import get_logger as get_logger
-from typing import Any
-
-logger: Incomplete
-
-def validate_allowed_tools_list(allowed_tools: list[str] | None, context: str) -> list[str] | None:
-    '''Validate that allowed_tools is a list of strings or None.
-
-    This function validates the type and contents of allowed_tools parameter.
-    It can be used to validate allowed_tools from any source (config dict, function parameter, etc).
-
-    Args:
-        allowed_tools: The allowed_tools value to validate (can be any type)
-        context: Context string for error messages (e.g., "Server \'my_server\'", "\'allowed_tools\' parameter")
-
-    Returns:
-        Validated list of allowed tool names, or None if allowed_tools is None or empty.
-        None/empty means no restriction (all tools allowed).
-
-    Raises:
-        ValueError: If allowed_tools is not None/list or contains non-string elements
-
-    Examples:
-        >>> validate_allowed_tools_list(None, "test")
-        None
-        >>> validate_allowed_tools_list([], "test")
-        None
-        >>> validate_allowed_tools_list(["tool1", "tool2"], "test")
-        [\'tool1\', \'tool2\']
-        >>> validate_allowed_tools_list("invalid", "test")  # doctest: +SKIP
-        ValueError: test: \'allowed_tools\' must be a list of strings, got str
-    '''
-def validate_allowed_tools_config(config: dict[str, Any], server_name: str) -> list[str] | None:
-    '''Validate and extract allowed_tools configuration from server config.
-
-    This function validates that the allowed_tools field, if present, is a list of strings.
-    It returns a normalized list of allowed tool names, or None if not specified/empty.
-
-    Args:
-        config: Server configuration dictionary that may contain \'allowed_tools\' field
-        server_name: Name of the server (for error messages)
-
-    Returns:
-        List of allowed tool names, or None if allowed_tools is not specified or is empty.
-        None means no restriction (all tools allowed).
-
-    Raises:
-        ValueError: If allowed_tools is present but not a list
-        ValueError: If allowed_tools contains non-string elements
-
-    Examples:
-        >>> validate_allowed_tools_config({"url": "..."}, "my_server")
-        None
-        >>> validate_allowed_tools_config({"url": "...", "allowed_tools": []}, "my_server")
-        None
-        >>> validate_allowed_tools_config({"url": "...", "allowed_tools": ["tool1", "tool2"]}, "my_server")
-        [\'tool1\', \'tool2\']
-    '''
-def validate_mcp_server_config(config: dict[str, Any], server_name: str) -> dict[str, Any]:
-    '''Validate complete MCP server configuration including allowed_tools.
-
-    This function performs comprehensive validation on an MCP server configuration,
-    ensuring all required fields are present and allowed_tools (if present) is valid.
-    Unknown configuration fields (such as any leftover disabled_tools) are silently ignored.
-
-    Args:
-        config: Server configuration dictionary
-        server_name: Name of the server (for error messages)
-
-    Returns:
-        Validated configuration dictionary (same as input, after validation)
-
-    Raises:
-        ValueError: If configuration is invalid
-
-    Examples:
-        >>> validate_mcp_server_config({"url": "http://localhost:8080"}, "my_server")
-        {\'url\': \'http://localhost:8080\'}
-        >>> validate_mcp_server_config({"command": "python", "args": ["server.py"]}, "my_server")
-        {\'command\': \'python\', \'args\': [\'server.py\']}
-    '''

aip_agents/memory/__init__.pyi

@@ -1,5 +0,0 @@
-from aip_agents.memory.base import BaseMemory as BaseMemory
-from aip_agents.memory.constants import MemoryMethod as MemoryMethod
-from aip_agents.memory.factory import MemoryFactory as MemoryFactory
-
-__all__ = ['BaseMemory', 'MemoryMethod', 'MemoryFactory']

aip_agents/memory/adapters/__init__.pyi

@@ -1,4 +0,0 @@
-from aip_agents.memory.adapters.base_adapter import BaseMemoryAdapter as BaseMemoryAdapter
-from aip_agents.memory.adapters.mem0 import Mem0Memory as Mem0Memory
-
-__all__ = ['Mem0Memory', 'BaseMemoryAdapter']

aip_agents/memory/adapters/base_adapter.pyi

@@ -1,150 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.memory.base import BaseMemory as BaseMemory
-from aip_agents.memory.constants import MemoryDefaults as MemoryDefaults
-from aip_agents.types import ChatMessage as ChatMessage
-from aip_agents.utils.datetime import format_created_updated_label as format_created_updated_label
-from aip_agents.utils.logger import get_logger as get_logger
-from concurrent.futures import Future
-from dataclasses import dataclass
-from gllm_memory import MemoryManager
-from gllm_memory.enums import MemoryScope
-from typing import Any, ClassVar
-
-MemoryManager = Any
-MemoryScope = Any
-logger: Incomplete
-DEFAULT_SCOPE: ClassVar[set[MemoryScope]]
-
-@dataclass(frozen=True)
-class _RetrieveOptions:
-    user_id: str
-    top_k: int
-    metadata: dict[str, str] | None
-    keywords: Any
-    page: int
-    categories: list[str] | None
-
-class _AsyncRunner:
-    """Runs async coroutines on a dedicated background event loop."""
-    def __init__(self) -> None: ...
-    def run(self, awaitable: Any) -> Any:
-        """Execute an awaitable on the background loop and block for the result.
-
-        Args:
-            awaitable: The coroutine to execute.
-
-        Returns:
-            The result of the coroutine execution.
-        """
-    def shutdown(self, timeout: float | None = 5.0) -> None:
-        """Gracefully stop the event loop thread.
-
-        Args:
-            timeout: Maximum time to wait for the thread to stop.
-        """
-    def __del__(self) -> None: ...
-
-class BaseMemoryAdapter(BaseMemory):
-    """Provider-agnostic long-term memory adapter backed by gllm_memory."""
-    agent_id: Incomplete
-    namespace: Incomplete
-    limit: Incomplete
-    max_chars: Incomplete
-    def __init__(self, *, agent_id: str, manager: MemoryManager, namespace: str | None = None, limit: int = ..., max_chars: int = ...) -> None:
-        """Initialize the GLLM memory adapter.
-
-        Args:
-            agent_id: Unique identifier for the agent using this memory.
-            manager: Configured gllm_memory MemoryManager instance.
-            namespace: Optional namespace for organizing memories.
-            limit: Maximum number of memories to retrieve in search operations.
-            max_chars: Maximum character length for text content.
-        """
-    @classmethod
-    def validate_env(cls) -> None:
-        """Base adapter does not enforce environment validation."""
-    def get_messages(self) -> list[ChatMessage]:
-        """Retrieve all stored chat messages.
-
-        Returns:
-            An empty list as GLLM adapter doesn't support message retrieval.
-        """
-    def add_message(self, message: ChatMessage) -> None:
-        """Best-effort single-message persistence for API parity.
-
-        Args:
-            message: The chat message to add to memory.
-        """
-    def clear(self) -> None:
-        """Clear all stored memories.
-
-        Raises:
-            NotImplementedError: This method is not implemented for GLLM adapter.
-        """
-    def search(self, query: str, *, user_id: str, limit: int | None = None, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
-        """Search for memories using a text query.
-
-        Args:
-            query: The search query string.
-            user_id: User identifier for the search scope.
-            limit: Maximum number of results to return.
-            filters: Optional filters to apply to the search.
-
-        Returns:
-            List of memory hits matching the search criteria.
-        """
-    def retrieve(self, *, query: str | None, user_id: str, limit: int | None = None, filters: dict[str, Any] | None = None, page: int | None = None) -> list[dict[str, Any]]:
-        """Retrieve memories with optional search query and filters.
-
-        Args:
-            query: Optional search query string. If None, retrieves all memories.
-            user_id: User identifier for the retrieval scope.
-            limit: Maximum number of results to return.
-            filters: Optional filters to apply to the retrieval.
-            page: Page number for pagination.
-
-        Returns:
-            List of memory hits matching the criteria.
-        """
-    def save_interaction(self, *, user_text: str, ai_text: str, user_id: str) -> None:
-        """Save a user-AI interaction as memories.
-
-        Args:
-            user_text: The user's input text.
-            ai_text: The AI's response text.
-            user_id: User identifier for the memory storage.
-        """
-    def save_interaction_async(self, *, user_text: str, ai_text: str, user_id: str) -> Future[Any]:
-        """Schedule save_interaction without blocking the caller.
-
-        Args:
-            user_text: The user's input text to save.
-            ai_text: The AI's response text to save.
-            user_id: User identifier for the memory storage.
-        """
-    def format_hits(self, hits: list[dict[str, Any]], max_items: int = ..., with_tag: bool = True) -> str:
-        """Format memory hits into a readable string.
-
-        Args:
-            hits: List of memory hit dictionaries to format.
-            max_items: Maximum number of hits to include in the output.
-            with_tag: Whether to wrap the output with memory tags.
-
-        Returns:
-            Formatted string representation of the memory hits.
-        """
-    def flush_pending_writes(self, timeout: float | None = None) -> None:
-        """Block until current async writes complete.
-
-        Args:
-            timeout: Maximum time to wait for pending writes to complete.
-        """
-    def close(self, *, wait: bool = True, timeout: float | None = None) -> None:
-        """Release background resources and optionally wait for pending saves.
-
-        Args:
-            wait: Whether to wait for pending async operations to complete.
-            timeout: Maximum time to wait when wait=True.
-        """
-    def __del__(self) -> None:
-        """Clean up resources when the adapter is garbage collected."""

aip_agents/memory/adapters/mem0.pyi

@@ -1,22 +0,0 @@
-from aip_agents.memory.adapters.base_adapter import BaseMemoryAdapter as BaseMemoryAdapter
-from aip_agents.memory.constants import MemoryDefaults as MemoryDefaults
-from typing import Any
-
-MemoryManager = Any
-
-class Mem0Memory(BaseMemoryAdapter):
-    """Mem0-backed long-term memory adapter using the gllm_memory SDK."""
-    def __init__(self, *, agent_id: str, namespace: str | None = None, limit: int = ..., max_chars: int = ..., host: str | None = None, instruction: str | None = None) -> None:
-        """Initialize the Mem0 memory adapter.
-
-        Args:
-            agent_id: Unique identifier for the agent using this memory.
-            namespace: Optional namespace for organizing memories.
-            limit: Maximum number of memories to retrieve in search operations.
-            max_chars: Maximum character length for text content.
-            host: Optional host URL for the Mem0 service.
-            instruction: Optional instruction text for memory operations.
-        """
-    @classmethod
-    def validate_env(cls) -> None:
-        """Ensure the Mem0 API key is available."""