glaip-sdk 0.1.2__py3-none-any.whl → 0.7.17__py3-none-any.whl

glaip_sdk/runner/tool_adapter/langchain_tool_adapter.py

@@ -0,0 +1,242 @@
+"""LangChain tool adapter for local agent runtime.
+
+This module handles adaptation of glaip-sdk tool references to LangChain
+BaseTool instances for local execution with aip-agents (LangGraph backend).
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from typing import Any
+
+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
+_UNKNOWN_TOOL_NAME = "<unknown>"
+
+
+class LangChainToolAdapter(BaseToolAdapter):
+    """Adapts glaip-sdk tools to LangChain BaseTool format for aip-agents.
+
+    Handles:
+    - LangChain BaseTool classes → instantiate
+    - LangChain BaseTool instances → return as-is
+    - Tool.from_langchain() → extract underlying tool
+    - @tool_plugin decorator → ignore (just metadata)
+
+    Rejects:
+    - Tool.from_native() → platform-specific
+    - String tool names → platform-specific
+    """
+
+    def adapt_tools(self, tool_refs: list[Any]) -> list[Any]:
+        """Adapt tool references to LangChain BaseTool instances.
+
+        Args:
+            tool_refs: List of tool references from Agent definition.
+
+        Returns:
+            List of LangChain BaseTool instances.
+
+        Raises:
+            ValueError: If tool is not supported in local mode.
+        """
+        langchain_tools = []
+
+        for tool_ref in tool_refs:
+            langchain_tool = self._adapt_single_tool(tool_ref)
+            langchain_tools.append(langchain_tool)
+
+        logger.debug("Adapted %d tools to LangChain format", len(langchain_tools))
+        return langchain_tools
+
+    def _adapt_single_tool(self, tool_ref: Any) -> Any:
+        """Adapt a single tool reference.
+
+        Args:
+            tool_ref: Single tool reference to adapt.
+
+        Returns:
+            LangChain BaseTool instance.
+
+        Raises:
+            ValueError: If tool is not supported.
+        """
+        # 1. Tool.from_langchain() wrapper
+        if self._is_tool_wrapper(tool_ref):
+            return self._extract_from_wrapper(tool_ref)
+
+        # 2. Direct LangChain BaseTool
+        if self._is_langchain_tool(tool_ref):
+            return self._instantiate_langchain_tool(tool_ref)
+
+        # 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
+        raise ValueError(
+            f"Unsupported tool type for local mode: {type(tool_ref)}. "
+            "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.
+
+        Args:
+            ref: Object to check.
+
+        Returns:
+            True if ref is a Tool.from_langchain() wrapper.
+        """
+        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().
+
+        Args:
+            wrapper: Tool.from_langchain() wrapper object.
+
+        Returns:
+            LangChain BaseTool instance.
+
+        Raises:
+            ValueError: If the wrapper's underlying tool is not a valid 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):
+            langchain_tool = langchain_tool()
+
+        logger.debug(
+            "Extracted LangChain tool from wrapper: %s",
+            getattr(langchain_tool, "name", _UNKNOWN_TOOL_NAME),
+        )
+        return langchain_tool
+
+    def _is_langchain_tool(self, ref: Any) -> bool:
+        """Check if ref is a LangChain BaseTool class or instance.
+
+        Args:
+            ref: Object to check.
+
+        Returns:
+            True if ref is a LangChain BaseTool.
+        """
+        from glaip_sdk.utils.tool_detection import is_langchain_tool  # noqa: PLC0415
+
+        return is_langchain_tool(ref)
+
+    def _instantiate_langchain_tool(self, ref: Any) -> Any:
+        """Instantiate LangChain tool if class, return as-is if instance.
+
+        Args:
+            ref: LangChain BaseTool class or instance.
+
+        Returns:
+            LangChain BaseTool instance.
+        """
+        if isinstance(ref, type):
+            # It's a class, instantiate it
+            # Note: @tool_plugin decorator doesn't affect instantiation
+            return ref()
+        return ref
+
+    def _is_platform_tool(self, ref: Any) -> bool:
+        """Check if ref is platform-specific (not supported locally).
+
+        Args:
+            ref: Object to check.
+
+        Returns:
+            True if ref is a platform-specific tool.
+        """
+        # String tool names
+        if isinstance(ref, str):
+            return True
+
+        # Tool.from_native() instances
+        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
+
+    def _get_platform_tool_error(self, ref: Any) -> str:
+        """Get error message for platform tools.
+
+        Args:
+            ref: Platform tool reference.
+
+        Returns:
+            Error message string.
+        """
+        from glaip_sdk.runner.deps import (  # noqa: PLC0415
+            get_local_mode_not_supported_for_tool_message,
+        )
+
+        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]

glaip_sdk/tools/__init__.py

@@ -0,0 +1,22 @@
+"""Tool package for GL AIP platform.
+
+This package provides the Tool class, ToolType enum, and ToolRegistry
+for managing tools on the GL AIP platform.
+
+Example:
+    >>> from glaip_sdk.tools import Tool, ToolType, get_tool_registry
+    >>> native_tool = Tool.from_native("web_search")
+    >>> custom_tool = Tool.from_langchain(MyCustomTool)
+"""
+
+from __future__ import annotations
+
+from glaip_sdk.registry.tool import ToolRegistry, get_tool_registry
+from glaip_sdk.tools.base import Tool, ToolType
+
+__all__ = [
+    "Tool",
+    "ToolType",
+    "ToolRegistry",
+    "get_tool_registry",
+]