glaip-sdk 0.6.10__py3-none-any.whl → 0.7.27__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/mcp_config_builder.py

@@ -60,19 +60,42 @@ class MCPConfigBuilder:
     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")
+        if isinstance(headers, dict):
+            cleaned_headers = MCPConfigBuilder._clean_headers(headers)
+            if cleaned_headers:
+                return cleaned_headers
+
+        logger.warning("custom-header auth requires 'headers' dict with at least one non-null key/value")
         return None
 
+    @staticmethod
+    def _clean_headers(headers: dict[str, Any]) -> dict[str, str] | None:
+        """Clean header dict by filtering None keys/values and stringifying values.
+
+        Args:
+            headers: Raw headers dict potentially containing None or non-string values.
+
+        Returns:
+            Cleaned headers dict with string keys/values, or None if empty after cleaning.
+        """
+        cleaned: dict[str, str] = {}
+        for key, value in headers.items():
+            if key is None:
+                logger.warning("Dropping header with null key")
+                continue
+            if value is None:
+                logger.warning("Dropping header '%s' with null value", key)
+                continue
+            cleaned[str(key)] = str(value)
+
+        return cleaned if cleaned else 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
+            return MCPConfigBuilder._clean_headers(headers)
         token = authentication.get("token")
         if token:
             return {"Authorization": f"Bearer {token}"}
@@ -82,11 +105,9 @@ class MCPConfigBuilder:
     @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
+            return MCPConfigBuilder._clean_headers(headers)
         key = authentication.get("key")
         value = authentication.get("value")
         if key and value:

glaip_sdk/runner/ptc_adapter.py

@@ -0,0 +1,98 @@
+"""PTC adapter for local runner integration.
+
+This module provides validation and normalization of PTC configuration
+for use in the local LangGraph runner. It ensures PTC is configured
+correctly and rejects unsupported configuration sources.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from glaip_sdk.exceptions import ValidationError
+
+if TYPE_CHECKING:
+    from glaip_sdk.ptc import PTC
+
+
+def validate_ptc_for_local_run(
+    agent_ptc: PTC | None,
+    agent_config_ptc: Any | None,
+    runtime_config_ptc: Any | None,
+) -> PTC | None:
+    """Validate PTC configuration for local runs.
+
+    Args:
+        agent_ptc: PTC object from Agent.ptc parameter.
+        agent_config_ptc: PTC from agent_config (should be None for local).
+        runtime_config_ptc: PTC from runtime_config (should be None for v1).
+
+    Returns:
+        Validated PTC object if enabled, None otherwise.
+
+    Raises:
+        ValidationError: If agent_config.ptc or runtime_config.ptc are provided,
+            or if agent_ptc is not a PTC instance when provided.
+    """
+    if agent_config_ptc is not None:
+        msg = (
+            "PTC configuration via agent_config.ptc is not supported for local runs. "
+            "Please configure PTC using the Agent.ptc parameter instead: "
+            "Agent(name='...', ptc=PTC(enabled=True), ...)"
+        )
+        raise ValidationError(msg)
+
+    if runtime_config_ptc is not None:
+        msg = (
+            "PTC configuration via runtime_config.ptc is not supported in v1. "
+            "PTC configuration must be set at Agent initialization time using "
+            "the Agent.ptc parameter and cannot be overridden at runtime. "
+            "This preserves local/remote parity and prevents ambiguous precedence."
+        )
+        raise ValidationError(msg)
+
+    if agent_ptc is None:
+        return None
+
+    from glaip_sdk.ptc import PTC  # noqa: PLC0415
+
+    if not isinstance(agent_ptc, PTC):
+        msg = (
+            f"Agent.ptc must be a PTC instance, got {type(agent_ptc).__name__}. "
+            "Example: Agent(name='...', ptc=PTC(enabled=True), ...)"
+        )
+        raise ValidationError(msg)
+
+    if not agent_ptc.enabled:
+        return None
+
+    return agent_ptc
+
+
+def normalize_ptc_for_aip_agents(ptc: PTC | None) -> Any:
+    """Normalize PTC config for aip-agents LangGraphReactAgent.
+
+    Args:
+        ptc: Validated PTC object or None.
+
+    Returns:
+        PTCSandboxConfig for aip-agents or None if PTC disabled.
+    """
+    if ptc is None or not ptc.enabled:
+        return None
+
+    from aip_agents.ptc import PromptConfig, PTCSandboxConfig  # noqa: PLC0415
+
+    # Build PromptConfig if prompt dict is provided.
+    prompt_config = None
+    if ptc.prompt is not None:
+        prompt_config = PromptConfig(**ptc.prompt)
+
+    return PTCSandboxConfig(
+        enabled=ptc.enabled,
+        sandbox_timeout=ptc.sandbox_timeout,
+        prompt=prompt_config,
+    )

glaip_sdk/runner/tool_adapter/langchain_tool_adapter.py

@@ -9,9 +9,10 @@ Authors:
 
 from typing import Any
 
-from glaip_sdk.runner.tool_adapter.base_tool_adapter import BaseToolAdapter
 from gllm_core.utils import LoggerManager
 
+from glaip_sdk.runner.tool_adapter.base_tool_adapter import BaseToolAdapter
+
 logger = LoggerManager().get_logger(__name__)
 
 # Constant for unknown tool name placeholder
@@ -73,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

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]