glaip-sdk 0.0.20__py3-none-any.whl → 0.7.7__py3-none-any.whl

glaip_sdk/runner/logging_config.py

@@ -0,0 +1,77 @@
+"""Logging configuration for CLI to suppress noisy dependency warnings.
+
+This module provides centralized logging suppression for optional dependencies
+that emit noisy warnings during CLI usage. Warnings are suppressed by default
+but can be shown using GLAIP_LOG_LEVEL=DEBUG.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import logging
+import os
+import warnings
+
+NOISY_LOGGERS = ["transformers", "gllm_privacy", "google.cloud.aiplatform"]
+
+
+class NameFilter(logging.Filter):
+    """Filter logs by logger name prefix."""
+
+    def __init__(self, prefixes: list[str]) -> None:
+        """Initialize filter with logger name prefixes to suppress.
+
+        Args:
+            prefixes: List of logger name prefixes to filter out.
+        """
+        super().__init__()
+        self.prefixes = prefixes
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Filter log records by name prefix.
+
+        Args:
+            record: Log record to filter.
+
+        Returns:
+            False if record should be suppressed, True otherwise.
+        """
+        return not any(record.name.startswith(p) for p in self.prefixes)
+
+
+def setup_cli_logging() -> None:
+    """Suppress INFO from noisy third-party libraries.
+
+    Use GLAIP_LOG_LEVEL=DEBUG to see all warnings.
+    This function is idempotent - calling it multiple times is safe.
+    """
+    # Check env level FIRST before any suppression
+    env_level = os.getenv("GLAIP_LOG_LEVEL", "").upper()
+    is_debug = env_level == "DEBUG"
+
+    if is_debug:
+        # Debug mode: show everything, no suppression
+        if env_level and hasattr(logging, env_level):
+            logging.basicConfig(level=getattr(logging, env_level))
+        return
+
+    # Default mode: suppress noisy warnings
+    if env_level and hasattr(logging, env_level):
+        logging.basicConfig(level=getattr(logging, env_level))
+
+    # Add handler filter to suppress by name prefix (handles child loggers)
+    # Check if filter already exists to ensure idempotency
+    root_logger = logging.getLogger()
+    has_name_filter = any(isinstance(f, NameFilter) for h in root_logger.handlers for f in h.filters)
+
+    if not has_name_filter:
+        handler = logging.StreamHandler()
+        handler.addFilter(NameFilter(NOISY_LOGGERS))
+        root_logger.addHandler(handler)
+
+    # Suppress FutureWarning for GCS (idempotent - multiple calls are safe)
+    warnings.filterwarnings(
+        "ignore",
+        category=FutureWarning,
+        message=r".*google-cloud-storage.*",
+    )

glaip_sdk/runner/mcp_adapter/__init__.py

@@ -0,0 +1,13 @@
+"""MCP adapter module for local agent runtime.
+
+This module provides MCP adapters for converting glaip-sdk MCP references
+to backend-specific MCP configuration formats.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from glaip_sdk.runner.mcp_adapter.base_mcp_adapter import BaseMCPAdapter
+from glaip_sdk.runner.mcp_adapter.langchain_mcp_adapter import LangChainMCPAdapter
+
+__all__ = ["BaseMCPAdapter", "LangChainMCPAdapter"]

glaip_sdk/runner/mcp_adapter/base_mcp_adapter.py

@@ -0,0 +1,43 @@
+"""Base MCP adapter for local agent runtime.
+
+This module defines the abstract base class for MCP adapters.
+Different backends (LangGraph, Google ADK) implement their own adapters.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseMCPAdapter(ABC):
+    """Abstract base class for MCP adapters.
+
+    One Interface, Multiple Implementations:
+    - LangChainMCPAdapter: Adapts to aip-agents mcp_config format
+    - GoogleADKMCPAdapter: Adapts to Google ADK format (future)
+
+    Each backend implements this interface to adapt glaip-sdk MCPs
+    to their specific MCP configuration format.
+    """
+
+    @abstractmethod
+    def adapt_mcps(self, mcp_refs: list[Any]) -> dict[str, Any]:
+        """Adapt glaip-sdk MCP references to backend-specific format.
+
+        Args:
+            mcp_refs: List of MCP references from Agent definition.
+                Can be: MCP class instances, MCP.from_native() refs, etc.
+
+        Returns:
+            Backend-specific MCP configuration.
+            For LangChain/aip-agents: dict[str, dict[str, Any]] mapping server names to config.
+            For Google ADK: dict in Google ADK MCP format.
+
+        Raises:
+            ValueError: If MCP is not supported by this backend.
+        """
+        ...

glaip_sdk/runner/mcp_adapter/langchain_mcp_adapter.py

@@ -0,0 +1,257 @@
+"""LangChain MCP adapter for local agent runtime.
+
+This module handles adaptation of glaip-sdk MCP references to aip-agents
+MCP configuration format for local execution.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from typing import Any
+
+from glaip_sdk.runner.mcp_adapter.base_mcp_adapter import BaseMCPAdapter
+from glaip_sdk.runner.mcp_adapter.mcp_config_builder import MCPConfigBuilder
+from gllm_core.utils import LoggerManager
+
+logger = LoggerManager().get_logger(__name__)
+
+
+class LangChainMCPAdapter(BaseMCPAdapter):
+    """Adapts glaip-sdk MCPs to aip-agents mcp_config dict format.
+
+    Handles:
+    - MCP class with http transport → convert to mcp_config
+    - MCP class with sse transport → convert to mcp_config
+    - MCP class with stdio transport → convert to mcp_config
+
+    Rejects:
+    - MCP.from_native() → platform-specific
+    - String MCP references → platform-specific
+    """
+
+    def adapt_mcps(self, mcp_refs: list[Any]) -> dict[str, Any]:
+        """Adapt MCP references to aip-agents mcp_config format.
+
+        Args:
+            mcp_refs: List of MCP references from Agent definition.
+
+        Returns:
+            Dictionary mapping server names to configuration dicts.
+            Format: {server_name: {transport: ..., url: ..., ...}}
+
+        Raises:
+            ValueError: If MCP is not supported in local mode.
+        """
+        mcp_configs = {}
+
+        for mcp_ref in mcp_refs:
+            server_name, config = self._adapt_single_mcp(mcp_ref)
+            mcp_configs[server_name] = config
+
+        logger.debug("Adapted %d MCPs to aip-agents format", len(mcp_configs))
+        return mcp_configs
+
+    def _adapt_single_mcp(self, mcp_ref: Any) -> tuple[str, dict[str, Any]]:
+        """Adapt a single MCP reference.
+
+        Args:
+            mcp_ref: Single MCP reference to adapt.
+
+        Returns:
+            Tuple of (server_name, config_dict).
+
+        Raises:
+            ValueError: If MCP is not supported.
+        """
+        # 1. String references (not supported)
+        if isinstance(mcp_ref, str):
+            raise ValueError(self._get_platform_mcp_error(mcp_ref))
+
+        # 2. MCP instance - check if it's local or platform
+        if self._is_local_mcp(mcp_ref):
+            config = self._convert_mcp_config(mcp_ref)
+            return mcp_ref.name, config
+
+        # 3. Platform MCP (from_native, from_id)
+        if self._is_platform_mcp(mcp_ref):
+            raise ValueError(self._get_platform_mcp_error(mcp_ref))
+
+        # 4. Unknown type
+        raise ValueError(
+            f"Unsupported MCP type for local mode: {type(mcp_ref)}. "
+            "Local mode only supports MCP class instances with http/sse/stdio transport."
+        )
+
+    def _is_local_mcp(self, ref: Any) -> bool:
+        """Check if ref is a local MCP (has transport config)."""
+        return (
+            hasattr(ref, "transport")
+            and hasattr(ref, "name")
+            and getattr(ref, "transport", None) in ("http", "sse", "stdio")
+            and not self._is_lookup_only(ref)
+        )
+
+    def _is_lookup_only(self, ref: Any) -> bool:
+        """Check if MCP is lookup-only (platform reference)."""
+        return hasattr(ref, "_lookup_only") and getattr(ref, "_lookup_only", False)
+
+    def _convert_mcp_config(self, mcp: Any) -> dict[str, Any]:
+        """Convert glaip-sdk MCP to aip-agents mcp_config format.
+
+        Args:
+            mcp: glaip-sdk MCP instance.
+
+        Returns:
+            aip-agents compatible MCP config dict.
+        """
+        # Start with user-provided config
+        config = mcp.config.copy() if mcp.config else {}
+
+        # Ensure transport is set
+        config["transport"] = mcp.transport
+
+        # Map server_url to url if needed (aip-agents uses 'url')
+        if "server_url" in config and "url" not in config:
+            config["url"] = config.pop("server_url")
+
+        self._validate_converted_config(
+            mcp_name=mcp.name,
+            transport=mcp.transport,
+            config=config,
+        )
+
+        # Convert authentication to headers using MCPConfigBuilder
+        # Merge with existing headers (auth headers take precedence for conflicts)
+        if hasattr(mcp, "authentication") and mcp.authentication:
+            auth_headers = MCPConfigBuilder.build_headers_from_auth(mcp.authentication)
+            if auth_headers:
+                existing_headers = config.get("headers", {})
+                config["headers"] = {**existing_headers, **auth_headers}
+            else:
+                logger.warning("Failed to build headers from authentication for MCP '%s'", mcp.name)
+
+        logger.debug("Converted MCP '%s' with transport '%s'", mcp.name, mcp.transport)
+        return config
+
+    def _validate_converted_config(self, mcp_name: str, transport: str, config: dict[str, Any]) -> None:
+        """Validate converted MCP config matches aip-agents schema expectations.
+
+        This method performs transport-specific validation after the glaip-sdk MCP
+        has been converted into the `aip-agents` `mcp_config` dictionary.
+
+        Args:
+            mcp_name: The MCP server name.
+            transport: The MCP transport type.
+            config: The converted MCP configuration dictionary.
+
+        Raises:
+            ValueError: If the configuration is invalid for the chosen transport.
+        """
+        self._validate_transport_config(mcp_name, transport)
+        if transport in ("http", "sse"):
+            self._validate_http_sse_config(
+                mcp_name=mcp_name,
+                transport=transport,
+                config=config,
+            )
+            return
+        if transport == "stdio":
+            self._validate_stdio_config(
+                mcp_name=mcp_name,
+                config=config,
+            )
+
+    def _validate_transport_config(self, mcp_name: str, transport: str) -> None:
+        """Validate that the MCP transport is supported by local mode.
+
+        Args:
+            mcp_name: The MCP server name.
+            transport: The MCP transport type.
+
+        Raises:
+            ValueError: If the transport is not one of 'http', 'sse', or 'stdio'.
+        """
+        if transport not in ("http", "sse", "stdio"):
+            raise ValueError(
+                f"Invalid MCP config for '{mcp_name}': transport must be one of "
+                f"'http', 'sse', or 'stdio'. Got: {transport!r}"
+            )
+
+    def _validate_http_sse_config(self, mcp_name: str, transport: str, config: dict[str, Any]) -> None:
+        """Validate http/sse config has a usable URL.
+
+        Args:
+            mcp_name: The MCP server name.
+            transport: The MCP transport type ('http' or 'sse').
+            config: The converted MCP configuration dictionary.
+
+        Raises:
+            ValueError: If url is missing/empty or does not use http(s) scheme.
+        """
+        url = config.get("url")
+        if not isinstance(url, str) or not url:
+            raise ValueError(
+                f"Invalid MCP config for '{mcp_name}': transport='{transport}' "
+                "requires config['url'] as a non-empty string."
+            )
+
+        if not (url.startswith("http://") or url.startswith("https://")):
+            raise ValueError(
+                f"Invalid MCP config for '{mcp_name}': config['url'] must start with "
+                f"'http://' or 'https://'. Got: {url!r}"
+            )
+
+    def _validate_stdio_config(self, mcp_name: str, config: dict[str, Any]) -> None:
+        """Validate stdio config has a usable command and optional args list.
+
+        Args:
+            mcp_name: The MCP server name.
+            config: The converted MCP configuration dictionary.
+
+        Raises:
+            ValueError: If command is missing/empty or args is not a list of strings.
+        """
+        command = config.get("command")
+        if not isinstance(command, str) or not command:
+            raise ValueError(
+                f"Invalid MCP config for '{mcp_name}': transport='stdio' "
+                "requires config['command'] as a non-empty string."
+            )
+
+        args = config.get("args")
+        if args is not None and (not isinstance(args, list) or any(not isinstance(x, str) for x in args)):
+            raise ValueError(
+                f"Invalid MCP config for '{mcp_name}': transport='stdio' expects "
+                "config['args'] to be a list[str] if provided."
+            )
+
+    def _is_platform_mcp(self, ref: Any) -> bool:
+        """Check if ref is platform-specific (not supported locally)."""
+        # MCP.from_native() or MCP.from_id() instances
+        if self._is_lookup_only(ref):
+            return True
+
+        # MCP with ID but no local transport
+        if hasattr(ref, "id") and getattr(ref, "id") and not self._is_local_mcp(ref):
+            return True
+
+        return False
+
+    def _get_platform_mcp_error(self, ref: Any) -> str:
+        """Get error message for platform MCPs."""
+        if isinstance(ref, str):
+            mcp_name = ref
+        else:
+            mcp_name = getattr(ref, "name", "<unknown>")
+
+        return (
+            f"MCP '{mcp_name}' is not supported in local mode.\n\n"
+            "Local mode only supports MCPs with local transport configurations:\n"
+            "  - MCP(name='...', transport='http', config={{'url': '...'}})\n"
+            "  - MCP(name='...', transport='sse', config={{'url': '...'}})\n"
+            "  - MCP(name='...', transport='stdio', config={{'command': '...'}})\n\n"
+            "Alternatives:\n"
+            "  1. Configure MCP with a local server URL\n"
+            "  2. Deploy the agent to use platform MCPs: agent.deploy()\n"
+            "  3. Remove MCP for local testing"
+        )

glaip_sdk/runner/mcp_adapter/mcp_config_builder.py

@@ -0,0 +1,95 @@
+"""MCP configuration builder helper.
+
+This module provides utilities for building MCP configurations,
+particularly for handling authentication conversion to headers.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from typing import Any
+
+from gllm_core.utils import LoggerManager
+
+logger = LoggerManager().get_logger(__name__)
+
+
+class MCPConfigBuilder:
+    """Helper class for building MCP configurations.
+
+    Handles authentication-to-headers conversion and configuration validation.
+    Simplified version focused on local MCP support needs.
+    """
+
+    @staticmethod
+    def build_headers_from_auth(authentication: dict[str, Any]) -> dict[str, str] | None:
+        """Build HTTP headers from authentication configuration.
+
+        Args:
+            authentication: Authentication configuration dict with 'type' and auth-specific fields.
+
+        Returns:
+            dict[str, str] | None: HTTP headers or None if invalid/no-auth.
+        """
+        if not authentication or "type" not in authentication:
+            return None
+
+        auth_type = str(authentication["type"]).lower()
+
+        # Dispatch to type-specific handlers
+        handlers = {
+            "no-auth": MCPConfigBuilder._handle_no_auth,
+            "custom-header": MCPConfigBuilder._handle_custom_header,
+            "bearer-token": MCPConfigBuilder._handle_bearer_token,
+            "api-key": MCPConfigBuilder._handle_api_key,
+        }
+
+        handler = handlers.get(auth_type)
+        if handler:
+            return handler(authentication)
+
+        logger.warning("Unsupported authentication type: %s", auth_type)
+        return None
+
+    @staticmethod
+    def _handle_no_auth(authentication: dict[str, Any]) -> None:  # noqa: ARG004
+        """Handle no-auth type."""
+        return None
+
+    @staticmethod
+    def _handle_custom_header(authentication: dict[str, Any]) -> dict[str, str] | None:
+        """Handle custom-header auth type."""
+        headers = authentication.get("headers")
+        if isinstance(headers, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in headers.items()):
+            return headers
+        logger.warning("custom-header auth requires 'headers' dict with string keys/values")
+        return None
+
+    @staticmethod
+    def _handle_bearer_token(authentication: dict[str, Any]) -> dict[str, str] | None:
+        """Handle bearer-token auth type."""
+        # Check if headers provided directly
+        headers = authentication.get("headers")
+        if isinstance(headers, dict):
+            return headers
+        # Otherwise build from token
+        token = authentication.get("token")
+        if token:
+            return {"Authorization": f"Bearer {token}"}
+        logger.warning("bearer-token auth requires 'token' field or 'headers' dict")
+        return None
+
+    @staticmethod
+    def _handle_api_key(authentication: dict[str, Any]) -> dict[str, str] | None:
+        """Handle api-key auth type."""
+        # Check if headers provided directly
+        headers = authentication.get("headers")
+        if isinstance(headers, dict):
+            return headers
+        # Otherwise build from key/value
+        key = authentication.get("key")
+        value = authentication.get("value")
+        if key and value:
+            return {str(key): str(value)}
+        logger.warning("api-key auth requires 'key' and 'value' fields or 'headers' dict")
+        return None

glaip_sdk/runner/tool_adapter/__init__.py

@@ -0,0 +1,18 @@
+"""Tool adapter for local agent runtime.
+
+This package provides adapters to convert glaip-sdk tool references
+to backend-specific formats for local execution.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from glaip_sdk.runner.tool_adapter.base_tool_adapter import BaseToolAdapter
+from glaip_sdk.runner.tool_adapter.langchain_tool_adapter import (
+    LangChainToolAdapter,
+)
+
+__all__ = [
+    "BaseToolAdapter",
+    "LangChainToolAdapter",
+]

glaip_sdk/runner/tool_adapter/base_tool_adapter.py

@@ -0,0 +1,44 @@
+"""Base tool adapter for local agent runtime.
+
+This module defines the abstract base class for tool adapters.
+Different backends (LangGraph, Google ADK) implement their own adapters.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseToolAdapter(ABC):
+    """Abstract base class for tool adapters.
+
+    One Interface, Multiple Implementations:
+    - LangChainToolAdapter: Adapts to LangChain BaseTool (for aip-agents)
+    - GoogleADKToolAdapter: Adapts to Google ADK format (future)
+
+    Each backend implements this interface to adapt glaip-sdk tools
+    to their specific tool format.
+    """
+
+    @abstractmethod
+    def adapt_tools(self, tool_refs: list[Any]) -> list[Any]:
+        """Adapt glaip-sdk tool references to backend-specific format.
+
+        Args:
+            tool_refs: List of tool references from Agent definition.
+                Can be: LangChain classes/instances, Tool.from_langchain(),
+                Tool.from_native(), string names, etc.
+
+        Returns:
+            List of tools in backend-specific format.
+            For LangChain: list of BaseTool instances.
+            For Google ADK: list of Google ADK tool objects.
+
+        Raises:
+            ValueError: If tool is not supported by this backend.
+        """
+        ...