glaip-sdk 0.6.5b6__py3-none-any.whl → 0.7.12__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/langchain_mcp_adapter.py

@@ -9,10 +9,9 @@ Authors:
 
 from typing import Any
 
-from gllm_core.utils import LoggerManager
-
 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__)
 
@@ -115,17 +114,117 @@ class LangChainMCPAdapter(BaseMCPAdapter):
         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:
-            headers = MCPConfigBuilder.build_headers_from_auth(mcp.authentication)
-            if headers:
-                config["headers"] = headers
+            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

glaip_sdk/runner/tool_adapter/langchain_tool_adapter.py

@@ -15,6 +15,9 @@ from glaip_sdk.runner.tool_adapter.base_tool_adapter import BaseToolAdapter
 
 logger = LoggerManager().get_logger(__name__)
 
+# Constant for unknown tool name placeholder
+_UNKNOWN_TOOL_NAME = "<unknown>"
+
 
 class LangChainToolAdapter(BaseToolAdapter):
     """Adapts glaip-sdk tools to LangChain BaseTool format for aip-agents.
@@ -71,8 +74,30 @@ class LangChainToolAdapter(BaseToolAdapter):
         if self._is_langchain_tool(tool_ref):
             return self._instantiate_langchain_tool(tool_ref)
 
-        # 3. Platform tools (not supported)
+        # 3. Native tools with discovered class
         if self._is_platform_tool(tool_ref):
+            # Try to discover local implementation for native tool
+            from glaip_sdk.utils.tool_detection import (  # noqa: PLC0415
+                find_aip_agents_tool_class,
+                get_tool_name,
+            )
+
+            # Get tool name from reference
+            tool_name = get_tool_name(tool_ref) if not isinstance(tool_ref, str) else tool_ref
+
+            if tool_name:
+                discovered_class = find_aip_agents_tool_class(tool_name)
+                if discovered_class:
+                    logger.info("Instantiating native tool locally: %s", tool_name)
+                    try:
+                        return discovered_class()
+                    except TypeError as exc:
+                        raise ValueError(
+                            f"Could not instantiate native tool '{tool_name}'. "
+                            "Ensure it has a zero-argument constructor or adjust the instantiation logic."
+                        ) from exc
+
+            # If no local class found, raise platform tool error
             raise ValueError(self._get_platform_tool_error(tool_ref))
 
         # 4. Unknown type
@@ -81,6 +106,15 @@ class LangChainToolAdapter(BaseToolAdapter):
             "Local mode only supports LangChain BaseTool classes/instances."
         )
 
+    def _has_explicit_attr(self, ref: Any, attr: str) -> bool:
+        """Check if attribute is explicitly set on the object.
+
+        This avoids false positives from objects like MagicMock, where hasattr()
+        can return True even if the attribute was never set.
+        """
+        ref_dict = getattr(ref, "__dict__", None)
+        return isinstance(ref_dict, dict) and attr in ref_dict
+
     def _is_tool_wrapper(self, ref: Any) -> bool:
         """Check if ref is a Tool.from_langchain() wrapper.
 
@@ -90,7 +124,13 @@ class LangChainToolAdapter(BaseToolAdapter):
         Returns:
             True if ref is a Tool.from_langchain() wrapper.
         """
-        return hasattr(ref, "langchain_tool") and hasattr(ref, "id") and hasattr(ref, "name")
+        if self._has_explicit_attr(ref, "langchain_tool") and hasattr(ref, "id") and hasattr(ref, "name"):
+            return True
+
+        if self._has_explicit_attr(ref, "tool_class"):
+            return getattr(ref, "tool_class", None) is not None
+
+        return False
 
     def _extract_from_wrapper(self, wrapper: Any) -> Any:
         """Extract underlying LangChain tool from Tool.from_langchain().
@@ -100,8 +140,29 @@ class LangChainToolAdapter(BaseToolAdapter):
 
         Returns:
             LangChain BaseTool instance.
+
+        Raises:
+            ValueError: If the wrapper's underlying tool is not a valid LangChain tool.
         """
-        langchain_tool = wrapper.langchain_tool
+        langchain_tool = getattr(wrapper, "langchain_tool", None)
+        if langchain_tool is None:
+            langchain_tool = getattr(wrapper, "tool_class", None)
+
+        # Validate the extracted object is a valid LangChain tool
+        if langchain_tool is None:
+            wrapper_name = getattr(wrapper, "name", _UNKNOWN_TOOL_NAME)
+            raise ValueError(
+                f"Tool wrapper '{wrapper_name}' does not contain a valid LangChain tool. "
+                "Ensure Tool.from_langchain() was called with a LangChain BaseTool class or instance."
+            )
+
+        # Validate it's actually a LangChain tool (class or instance)
+        if not self._is_langchain_tool(langchain_tool):
+            wrapper_name = getattr(wrapper, "name", _UNKNOWN_TOOL_NAME)
+            raise ValueError(
+                f"Tool wrapper '{wrapper_name}' contains an invalid tool type: {type(langchain_tool)}. "
+                "Expected a LangChain BaseTool class or instance."
+            )
 
         # If it's a class, instantiate it
         if isinstance(langchain_tool, type):
@@ -109,7 +170,7 @@ class LangChainToolAdapter(BaseToolAdapter):
 
         logger.debug(
             "Extracted LangChain tool from wrapper: %s",
-            getattr(langchain_tool, "name", "<unknown>"),
+            getattr(langchain_tool, "name", _UNKNOWN_TOOL_NAME),
         )
         return langchain_tool
 
@@ -155,8 +216,10 @@ class LangChainToolAdapter(BaseToolAdapter):
             return True
 
         # Tool.from_native() instances
-        if hasattr(ref, "id") and hasattr(ref, "name") and not hasattr(ref, "langchain_tool"):
-            return True
+        if hasattr(ref, "id") and hasattr(ref, "name") and not self._has_explicit_attr(ref, "langchain_tool"):
+            tool_class = getattr(ref, "tool_class", None) if self._has_explicit_attr(ref, "tool_class") else None
+            if tool_class is None:
+                return True
 
         return False
 
@@ -173,5 +236,7 @@ class LangChainToolAdapter(BaseToolAdapter):
             get_local_mode_not_supported_for_tool_message,
         )
 
-        tool_name = ref if isinstance(ref, str) else getattr(ref, "name", "<unknown>")
+        tool_name = ref if isinstance(ref, str) else getattr(ref, "name", None)
+        if tool_name is None:
+            tool_name = getattr(getattr(ref, "tool_class", None), "__name__", _UNKNOWN_TOOL_NAME)
         return get_local_mode_not_supported_for_tool_message(tool_name)

glaip_sdk/schedules/__init__.py

@@ -0,0 +1,22 @@
+"""Schedules runtime package.
+
+This package contains runtime schedule resource objects (class-based) that
+encapsulate behavior and API interactions via attached clients.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from glaip_sdk.schedules.base import (
+    Schedule,
+    ScheduleListResult,
+    ScheduleRun,
+    ScheduleRunListResult,
+)
+
+__all__ = [
+    "Schedule",
+    "ScheduleListResult",
+    "ScheduleRun",
+    "ScheduleRunListResult",
+]

glaip_sdk/schedules/base.py

@@ -0,0 +1,291 @@
+"""Schedule runtime resources.
+
+This module contains class-based runtime resources for schedules.
+
+The runtime resources:
+- Are not Pydantic models.
+- Are returned from public client APIs.
+- Delegate API operations to a bound ScheduleClient.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from glaip_sdk.models.agent_runs import RunStatus
+from glaip_sdk.models.schedule import (
+    ScheduleConfig,
+    ScheduleMetadata,
+    ScheduleResponse,
+    ScheduleRunResponse,
+    ScheduleRunResult,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+    from glaip_sdk.client.schedules import ScheduleClient
+
+_SCHEDULE_CLIENT_REQUIRED_MSG = "No client available. Use client.schedules.get() to get a client-connected schedule."
+_SCHEDULE_RUN_CLIENT_REQUIRED_MSG = (
+    "No client available. Use client.schedules.list_runs() to get a client-connected schedule run."
+)
+
+
+class Schedule:
+    """Runtime schedule resource.
+
+    Attributes:
+        id (str): The schedule ID.
+        next_run_time (str | None): Next run time as returned by the API.
+        time_until_next_run (str | None): Human readable duration until next run.
+        metadata (ScheduleMetadata | None): Schedule metadata.
+        created_at (datetime | None): Creation timestamp.
+        updated_at (datetime | None): Update timestamp.
+    """
+
+    def __init__(
+        self,
+        *,
+        id: str,
+        next_run_time: str | None = None,
+        time_until_next_run: str | None = None,
+        metadata: ScheduleMetadata | None = None,
+        created_at: datetime | None = None,
+        updated_at: datetime | None = None,
+        _client: ScheduleClient | None = None,
+    ) -> None:
+        """Initialize a runtime Schedule."""
+        self.id = id
+        self.next_run_time = next_run_time
+        self.time_until_next_run = time_until_next_run
+        self.metadata = metadata
+        self.created_at = created_at
+        self.updated_at = updated_at
+        self._client = _client
+
+    @classmethod
+    def from_response(cls, response: ScheduleResponse, *, client: ScheduleClient) -> Schedule:
+        """Build a runtime Schedule from a DTO response.
+
+        Args:
+            response: Parsed schedule response DTO.
+            client: ScheduleClient to bind.
+
+        Returns:
+            Runtime Schedule.
+        """
+        return cls(
+            id=response.id,
+            next_run_time=response.next_run_time,
+            time_until_next_run=response.time_until_next_run,
+            metadata=response.metadata,
+            created_at=response.created_at,
+            updated_at=response.updated_at,
+            _client=client,
+        )
+
+    @property
+    def agent_id(self) -> str | None:
+        """Agent ID derived from metadata."""
+        return self.metadata.agent_id if self.metadata else None
+
+    @property
+    def input(self) -> str | None:
+        """Input text derived from metadata."""
+        return self.metadata.input if self.metadata else None
+
+    @property
+    def schedule_config(self) -> ScheduleConfig | None:
+        """Schedule configuration derived from metadata."""
+        return self.metadata.schedule if self.metadata else None
+
+    def update(
+        self,
+        *,
+        input: str | None = None,
+        schedule: ScheduleConfig | dict[str, str] | str | None = None,
+    ) -> Schedule:
+        """Update this schedule."""
+        if self._client is None:
+            raise RuntimeError(_SCHEDULE_CLIENT_REQUIRED_MSG)
+        return self._client.update(self.id, input=input, schedule=schedule)
+
+    def delete(self) -> None:
+        """Delete this schedule."""
+        if self._client is None:
+            raise RuntimeError(_SCHEDULE_CLIENT_REQUIRED_MSG)
+        self._client.delete(self.id)
+
+    def list_runs(
+        self,
+        *,
+        status: RunStatus | None = None,
+        limit: int | None = None,
+        page: int | None = None,
+    ) -> ScheduleRunListResult:
+        """List runs for this schedule."""
+        if self._client is None:
+            raise RuntimeError(_SCHEDULE_CLIENT_REQUIRED_MSG)
+        if self.agent_id is None:
+            raise ValueError("Schedule has no agent_id")
+        return self._client.list_runs(
+            self.agent_id,
+            schedule_id=self.id,
+            status=status,
+            limit=limit,
+            page=page,
+        )
+
+    def __repr__(self) -> str:
+        """Return a developer-friendly representation."""
+        parts: list[str] = [f"id={self.id!r}"]
+        if self.agent_id is not None:
+            parts.append(f"agent_id={self.agent_id!r}")
+        if self.next_run_time is not None:
+            parts.append(f"next_run_time={self.next_run_time!r}")
+        if self.time_until_next_run is not None:
+            parts.append(f"time_until_next_run={self.time_until_next_run!r}")
+        if self.created_at is not None:
+            parts.append(f"created_at={self.created_at!r}")
+        return f"Schedule({', '.join(parts)})"
+
+    def __str__(self) -> str:
+        """Return a readable string representation."""
+        return self.__repr__()
+
+
+class ScheduleRun:
+    """Runtime schedule run resource."""
+
+    def __init__(
+        self,
+        *,
+        id: str,
+        agent_id: str,
+        schedule_id: str | None = None,
+        status: RunStatus,
+        run_type: str | None = None,
+        started_at: datetime | None = None,
+        completed_at: datetime | None = None,
+        input: str | None = None,
+        config: ScheduleConfig | dict[str, str] | None = None,
+        created_at: datetime | None = None,
+        updated_at: datetime | None = None,
+        _client: ScheduleClient | None = None,
+    ) -> None:
+        """Initialize a runtime ScheduleRun."""
+        self.id = id
+        self.agent_id = agent_id
+        self.schedule_id = schedule_id
+        self.status = status
+        self.run_type = run_type
+        self.started_at = started_at
+        self.completed_at = completed_at
+        self.input = input
+        self.config = config
+        self.created_at = created_at
+        self.updated_at = updated_at
+        self._client = _client
+
+    @classmethod
+    def from_response(cls, response: ScheduleRunResponse, *, client: ScheduleClient) -> ScheduleRun:
+        """Build a runtime ScheduleRun from a DTO response."""
+        return cls(
+            id=response.id,
+            agent_id=response.agent_id,
+            schedule_id=response.schedule_id,
+            status=response.status,
+            run_type=response.run_type,
+            started_at=response.started_at,
+            completed_at=response.completed_at,
+            input=response.input,
+            config=response.config,
+            created_at=response.created_at,
+            updated_at=response.updated_at,
+            _client=client,
+        )
+
+    def get_result(self) -> ScheduleRunResult:
+        """Retrieve the full output payload for this run."""
+        if self._client is None:
+            raise RuntimeError(_SCHEDULE_RUN_CLIENT_REQUIRED_MSG)
+        if self.agent_id is None:
+            raise ValueError("Schedule run has no agent_id")
+        return self._client.get_run_result(self.agent_id, self.id)
+
+    @property
+    def duration(self) -> str | None:
+        """Formatted duration (HH:MM:SS) when both timestamps are available."""
+        if not self.started_at or not self.completed_at:
+            return None
+
+        total_seconds = int((self.completed_at - self.started_at).total_seconds())
+        minutes, seconds = divmod(total_seconds, 60)
+        hours, minutes = divmod(minutes, 60)
+        return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+
+    def __repr__(self) -> str:
+        """Return a developer-friendly representation."""
+        parts: list[str] = [f"id={self.id!r}", f"status={self.status!r}"]
+        if self.started_at is not None:
+            parts.append(f"started_at={self.started_at.isoformat()!r}")
+        duration = self.duration
+        if duration is not None:
+            parts.append(f"duration={duration!r}")
+        return f"ScheduleRun({', '.join(parts)})"
+
+    def __str__(self) -> str:
+        """Return a readable string representation."""
+        return self.__repr__()
+
+
+@dataclass
+class ScheduleListResult:
+    """Paginated list wrapper for runtime schedules."""
+
+    items: list[Schedule]
+    total: int | None = field(default=None)
+    page: int | None = field(default=None)
+    limit: int | None = field(default=None)
+    has_next: bool | None = field(default=None)
+    has_prev: bool | None = field(default=None)
+
+    def __iter__(self):
+        """Iterate over schedules."""
+        yield from self.items
+
+    def __len__(self) -> int:
+        """Return the number of schedules in this page."""
+        return self.items.__len__()
+
+    def __getitem__(self, index: int) -> Schedule:
+        """Return the schedule at the given index."""
+        return self.items[index]
+
+
+@dataclass
+class ScheduleRunListResult:
+    """Paginated list wrapper for runtime schedule runs."""
+
+    items: list[ScheduleRun]
+    total: int | None = field(default=None)
+    page: int | None = field(default=None)
+    limit: int | None = field(default=None)
+    has_next: bool | None = field(default=None)
+    has_prev: bool | None = field(default=None)
+
+    def __iter__(self):
+        """Iterate over schedule runs."""
+        yield from self.items
+
+    def __len__(self) -> int:
+        """Return the number of runs in this page."""
+        return self.items.__len__()
+
+    def __getitem__(self, index: int) -> ScheduleRun:
+        """Return the run at the given index."""
+        return self.items[index]