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

aip_agents/mcp/client/transports.pyi

@@ -0,0 +1,123 @@
+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."""
+    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/__init__.py

@@ -0,0 +1,7 @@
+"""MCP utility modules.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+__all__: list[str] = []

aip_agents/mcp/utils/config_validator.py

@@ -0,0 +1,139 @@
+"""Configuration validation utilities for MCP.
+
+This module provides validation logic for MCP server configurations,
+specifically for the allowed_tools feature.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from typing import Any
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+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
+    """
+    # None or empty list is valid and means no restriction
+    if allowed_tools is None or allowed_tools == []:
+        return None
+
+    # Validate that it's a list
+    if not isinstance(allowed_tools, list):
+        raise ValueError(f"{context}: 'allowed_tools' must be a list of strings, got {type(allowed_tools).__name__}")
+
+    # Validate that all elements are strings
+    for idx, tool_name in enumerate(allowed_tools):
+        if not isinstance(tool_name, str):
+            raise ValueError(f"{context}: 'allowed_tools[{idx}]' must be a string, got {type(tool_name).__name__}")
+        if not tool_name.strip():
+            raise ValueError(f"{context}: 'allowed_tools[{idx}]' must be a non-empty string")
+
+    return allowed_tools
+
+
+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']
+    """
+    if "allowed_tools" not in config:
+        return None
+
+    allowed_tools = config["allowed_tools"]
+
+    # Use common validation logic
+    return validate_allowed_tools_list(allowed_tools, f"Server '{server_name}'")
+
+
+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']}
+    """
+    if not isinstance(config, dict):
+        raise ValueError(f"Server '{server_name}': configuration must be a dictionary")
+
+    if not config:
+        raise ValueError(f"Server '{server_name}': configuration must not be empty")
+
+    # Validate required fields (url OR command)
+    has_url = "url" in config
+    has_command = "command" in config
+
+    if not (has_url or has_command):
+        raise ValueError(f"Server '{server_name}': must have either 'url' or 'command' field")
+
+    # Validate allowed_tools if present (ignore unknown fields like disabled_tools)
+    validate_allowed_tools_config(config, server_name)
+
+    return config

aip_agents/mcp/utils/config_validator.pyi

@@ -0,0 +1,82 @@
+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__.py

@@ -0,0 +1,14 @@
+"""Memory module for the GLLM agents.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+
+References:
+    https://github.com/GDP-ADMIN/gdplabs-exploration/blob/ai-agent-app/backend/aip_agents/memory/__init__.py
+"""
+
+from aip_agents.memory.base import BaseMemory
+from aip_agents.memory.constants import MemoryMethod
+from aip_agents.memory.factory import MemoryFactory
+
+__all__ = ["BaseMemory", "MemoryMethod", "MemoryFactory"]

aip_agents/memory/__init__.pyi

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

@@ -0,0 +1,10 @@
+"""Memory adapter implementations.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from aip_agents.memory.adapters.base_adapter import BaseMemoryAdapter
+from aip_agents.memory.adapters.mem0 import Mem0Memory
+
+__all__ = ["Mem0Memory", "BaseMemoryAdapter"]

aip_agents/memory/adapters/__init__.pyi

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