glaip-sdk 0.1.3__py3-none-any.whl → 0.6.19__py3-none-any.whl

glaip_sdk/registry/tool.py

@@ -0,0 +1,232 @@
+"""Tool registry for glaip_sdk.
+
+This module provides the ToolRegistry that caches deployed tools
+to avoid redundant API calls when deploying agents with tools.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from glaip_sdk.registry.base import BaseRegistry
+
+if TYPE_CHECKING:
+    from glaip_sdk.tools import Tool
+
+logger = logging.getLogger(__name__)
+
+
+class ToolRegistry(BaseRegistry["Tool"]):
+    """Registry for tools.
+
+    Resolves tool references to glaip_sdk.models.Tool objects.
+    Caches results to avoid redundant API calls and duplicate uploads.
+
+    Handles:
+        - Tool classes (LangChain BaseTool subclasses) → upload, cache, return Tool
+        - glaip_sdk.models.Tool → return as-is (uses tool.id)
+        - String names → lookup on platform, cache, return Tool
+
+    Attributes:
+        _cache: Internal cache mapping names to Tool objects.
+
+    Example:
+        >>> registry = get_tool_registry()
+        >>> tool = registry.resolve(WebSearchTool)
+        >>> print(tool.id)
+    """
+
+    def _get_name_from_model_fields(self, ref: type) -> str | None:
+        """Extract name from Pydantic model_fields if available."""
+        model_fields = getattr(ref, "model_fields", {})
+        if "name" not in model_fields:
+            return None
+        field_info = model_fields["name"]
+        default = getattr(field_info, "default", None)
+        return default if isinstance(default, str) else None
+
+    def _get_string_attr(self, obj: Any, attr: str) -> str | None:
+        """Get attribute if it's a string, otherwise None."""
+        value = getattr(obj, attr, None)
+        return value if isinstance(value, str) else None
+
+    def _extract_name(self, ref: Any) -> str:
+        """Extract tool name from a reference.
+
+        Args:
+            ref: A tool class, instance, dict, or string name.
+
+        Returns:
+            The extracted tool name.
+
+        Raises:
+            ValueError: If name cannot be extracted from the reference.
+        """
+        if isinstance(ref, str):
+            return ref
+
+        # Dict from API response - extract name or id
+        if isinstance(ref, dict):
+            return ref.get("name") or ref.get("id") or ""
+
+        # Tool instance (not a class) with name attribute
+        if not isinstance(ref, type):
+            name = self._get_string_attr(ref, "name")
+            if name:
+                return name
+
+        # Tool class - try direct attribute first, then model_fields
+        if isinstance(ref, type):
+            name = self._get_string_attr(ref, "name") or self._get_name_from_model_fields(ref)
+            if name:
+                return name
+
+        raise ValueError(f"Cannot extract name from: {ref}")
+
+    def _resolve_and_cache(self, ref: Any, name: str) -> Tool:
+        """Resolve tool reference - upload if class, find if string/native.
+
+        Args:
+            ref: The tool reference to resolve.
+            name: The extracted tool name.
+
+        Returns:
+            The resolved glaip_sdk.models.Tool object.
+
+        Raises:
+            ValueError: If the tool cannot be resolved.
+        """
+        # Lazy imports to avoid circular dependency
+        from glaip_sdk.utils.discovery import find_tool  # noqa: PLC0415
+        from glaip_sdk.utils.sync import update_or_create_tool  # noqa: PLC0415
+
+        # Already deployed tool (glaip_sdk.models.Tool with ID) - just cache and return
+        if hasattr(ref, "id") and hasattr(ref, "name") and not isinstance(ref, type):
+            if ref.id is not None:
+                logger.debug("Caching already deployed tool: %s", name)
+                self._cache[name] = ref
+                return ref
+
+            # Tool without ID (e.g., Tool.from_native()) - look up on platform
+            logger.info("Looking up native tool: %s", name)
+            tool = find_tool(name)
+            if tool:
+                self._cache[name] = tool
+                return tool
+            raise ValueError(f"Native tool not found on platform: {name}")
+
+        # Custom tool class - upload it
+        if self._is_custom_tool(ref):
+            logger.info("Uploading custom tool: %s", name)
+            tool = update_or_create_tool(ref)
+            self._cache[name] = tool
+            if tool.id:
+                self._cache[tool.id] = tool
+            return tool
+
+        # Dict from API response - use ID directly if available
+        if isinstance(ref, dict):
+            tool_id = ref.get("id")
+            if tool_id:
+                from glaip_sdk.tools.base import Tool  # noqa: PLC0415
+
+                tool = Tool(id=tool_id, name=ref.get("name", ""))
+                self._cache[name] = tool
+                return tool
+            raise ValueError(f"Tool dict missing 'id': {ref}")
+
+        # String name - look up on platform (could be native or existing tool)
+        if isinstance(ref, str):
+            logger.info("Looking up tool by name: %s", name)
+            tool = find_tool(name)
+            if tool:
+                self._cache[name] = tool
+                return tool
+            raise ValueError(f"Tool not found on platform: {name}")
+
+        raise ValueError(f"Could not resolve tool reference: {ref}")
+
+    def _is_custom_tool(self, ref: Any) -> bool:
+        """Check if reference is a custom tool class/instance.
+
+        Args:
+            ref: The reference to check.
+
+        Returns:
+            True if ref is a custom tool that needs uploading.
+        """
+        try:
+            from glaip_sdk.utils.tool_detection import (  # noqa: PLC0415
+                is_langchain_tool,
+            )
+        except ImportError:
+            return False
+
+        return is_langchain_tool(ref)
+
+    def resolve(self, ref: Any) -> Tool:
+        """Resolve a tool reference to a platform Tool object.
+
+        Overrides base resolve to handle SDK tools differently.
+
+        Args:
+            ref: The tool reference to resolve.
+
+        Returns:
+            The resolved glaip_sdk.models.Tool object.
+        """
+        # Check if it's a Tool instance (not a class)
+        if hasattr(ref, "id") and hasattr(ref, "name") and not isinstance(ref, type):
+            # If Tool has an ID, it's already deployed - return as-is
+            if ref.id is not None:
+                name = self._extract_name(ref)
+                if name not in self._cache:
+                    self._cache[name] = ref
+                return ref
+
+            # Tool without ID (e.g., from Tool.from_native()) - needs platform lookup
+            # Fall through to normal resolution
+
+        return super().resolve(ref)
+
+
+class _ToolRegistrySingleton:
+    """Singleton holder for ToolRegistry to avoid global statement."""
+
+    _instance: ToolRegistry | None = None
+
+    @classmethod
+    def get_instance(cls) -> ToolRegistry:
+        """Get or create the singleton instance.
+
+        Returns:
+            The global ToolRegistry instance.
+        """
+        if cls._instance is None:
+            cls._instance = ToolRegistry()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance (for testing)."""
+        cls._instance = None
+
+
+def get_tool_registry() -> ToolRegistry:
+    """Get the singleton ToolRegistry instance.
+
+    Returns a global ToolRegistry that caches tools across the session.
+
+    Returns:
+        The global ToolRegistry instance.
+
+    Example:
+        >>> from glaip_sdk.registry import get_tool_registry
+        >>> registry = get_tool_registry()
+        >>> tool = registry.resolve("web_search")
+    """
+    return _ToolRegistrySingleton.get_instance()

glaip_sdk/rich_components.py

@@ -1,10 +1,15 @@
-"""Custom Rich components with copy-friendly defaults."""
+"""Custom Rich components with copy-friendly defaults.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
 
 from __future__ import annotations
 
 from rich import box
 from rich.panel import Panel
 from rich.table import Table
+from rich.text import Text
 
 
 class AIPPanel(Panel):
@@ -66,4 +71,55 @@ class AIPGrid(Table):
         )
 
 
-__all__ = ["AIPPanel", "AIPTable", "AIPGrid"]
+class RemoteRunsTable(AIPTable):
+    """Rich Table for displaying remote agent runs with pagination support."""
+
+    def __init__(self, *args, **kwargs):
+        """Initialize RemoteRunsTable with columns for run display.
+
+        Args:
+            *args: Positional arguments passed to AIPTable
+            **kwargs: Keyword arguments passed to AIPTable
+        """
+        kwargs.setdefault("row_styles", ("dim", "none"))
+        kwargs.setdefault("show_header", True)
+        super().__init__(*args, **kwargs)
+        # Add columns for run display
+        self.add_column("", width=2, no_wrap=True)  # Selection gutter
+        self.add_column("Run UUID", style="cyan", width=36, no_wrap=True)
+        self.add_column("Type", style="yellow", width=8, no_wrap=True)
+        self.add_column("Status", style="magenta", width=12, no_wrap=True)
+        self.add_column("Started (UTC)", style="dim", width=20, no_wrap=True)
+        self.add_column("Completed (UTC)", style="dim", width=20, no_wrap=True)
+        self.add_column("Duration", style="green", width=10, no_wrap=True)
+        self.add_column("Input Preview", style="white", width=40, overflow="ellipsis")
+
+    def add_run_row(
+        self,
+        run_uuid: str,
+        run_type: str,
+        status: str,
+        started: str,
+        completed: str,
+        duration: str,
+        preview: str,
+        *,
+        selected: bool = False,
+    ) -> None:
+        """Append a run row with optional selection styling."""
+        gutter = Text("› ", style="bold bright_cyan") if selected else Text("  ")
+        row_style = "reverse" if selected else None
+        self.add_row(
+            gutter,
+            run_uuid,
+            run_type,
+            status,
+            started,
+            completed,
+            duration,
+            preview,
+            style=row_style,
+        )
+
+
+__all__ = ["AIPPanel", "AIPTable", "AIPGrid", "RemoteRunsTable"]

glaip_sdk/runner/__init__.py

@@ -0,0 +1,59 @@
+"""Local agent execution runners.
+
+This module provides runners for executing glaip-sdk agents locally
+without requiring the AIP backend server. The primary runner is
+LangGraphRunner which uses the aip-agents library.
+
+To use local execution, install with the [local] extra:
+    pip install "glaip-sdk[local]"
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+Example:
+    >>> from glaip_sdk.runner import get_default_runner
+    >>> from glaip_sdk.agents import Agent
+    >>>
+    >>> agent = Agent(name="my-agent", instruction="You are helpful.")
+    >>> runner = get_default_runner()
+    >>> result = runner.run(agent, "Hello!")
+"""
+
+from glaip_sdk.runner.deps import (
+    LOCAL_RUNTIME_AVAILABLE,
+    check_local_runtime_available,
+    get_local_runtime_missing_message,
+)
+from glaip_sdk.runner.langgraph import LangGraphRunner
+
+# Default runner instance
+_default_runner: LangGraphRunner | None = None
+
+
+def get_default_runner() -> LangGraphRunner:
+    """Get the default runner instance for local agent execution.
+
+    Returns:
+        The default LangGraphRunner instance.
+
+    Raises:
+        RuntimeError: If local runtime dependencies are not available.
+    """
+    global _default_runner
+
+    if not check_local_runtime_available():
+        raise RuntimeError(get_local_runtime_missing_message())
+
+    if _default_runner is None:
+        _default_runner = LangGraphRunner()
+
+    return _default_runner
+
+
+__all__ = [
+    "LOCAL_RUNTIME_AVAILABLE",
+    "LangGraphRunner",
+    "check_local_runtime_available",
+    "get_default_runner",
+    "get_local_runtime_missing_message",
+]

glaip_sdk/runner/base.py

@@ -0,0 +1,84 @@
+"""Abstract base class for agent execution runners.
+
+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 TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from glaip_sdk.agents.base import Agent
+
+
+class BaseRunner(ABC):
+    """Abstract base class for agent execution runners.
+
+    Runners are responsible for executing glaip-sdk Agent instances
+    and returning results. Different runner implementations may use
+    different execution backends (LangGraph, Google ADK, etc.).
+    """
+
+    @abstractmethod
+    def run(
+        self,
+        agent: Agent,
+        message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,
+        chat_history: list[dict[str, str]] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute agent synchronously and return final response text.
+
+        Args:
+            agent: The glaip_sdk Agent to execute.
+            message: The user message to send to the agent.
+            verbose: If True, emit debug trace output during execution.
+                Defaults to False.
+            runtime_config: Optional runtime configuration for tools, MCPs, etc.
+                Defaults to None.
+            chat_history: Optional list of prior conversation messages.
+                Defaults to None.
+            **kwargs: Additional keyword arguments passed to the backend.
+
+        Returns:
+            The final response text from the agent.
+
+        Raises:
+            RuntimeError: If execution fails.
+        """
+        ...
+
+    @abstractmethod
+    async def arun(
+        self,
+        agent: Agent,
+        message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,
+        chat_history: list[dict[str, str]] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute agent asynchronously and return final response text.
+
+        Args:
+            agent: The glaip_sdk Agent to execute.
+            message: The user message to send to the agent.
+            verbose: If True, emit debug trace output during execution.
+                Defaults to False.
+            runtime_config: Optional runtime configuration for tools, MCPs, etc.
+                Defaults to None.
+            chat_history: Optional list of prior conversation messages.
+                Defaults to None.
+            **kwargs: Additional keyword arguments passed to the backend.
+
+        Returns:
+            The final response text from the agent.
+
+        Raises:
+            RuntimeError: If execution fails.
+        """
+        ...

glaip_sdk/runner/deps.py

@@ -0,0 +1,112 @@
+"""Dependency detection utilities for the runner module.
+
+This module provides helpers to detect whether the local runtime dependencies
+(aip-agents) are installed and to generate actionable error messages when they
+are not available.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+Example:
+    >>> from glaip_sdk.runner.deps import check_local_runtime_available
+    >>> if not check_local_runtime_available():
+    ...     print(get_local_runtime_missing_message())
+"""
+
+from __future__ import annotations
+
+import importlib.util
+
+from gllm_core.utils import LoggerManager
+
+logger = LoggerManager().get_logger(__name__)
+
+# Module-level cache for import availability check
+_local_runtime_available: bool | None = None
+
+
+def _probe_aip_agents_import() -> bool:
+    """Check if aip_agents is available without importing it.
+
+    Returns:
+        True if aip_agents appears importable, False otherwise.
+    """
+    return importlib.util.find_spec("aip_agents") is not None
+
+
+def check_local_runtime_available() -> bool:
+    """Check if the local runtime dependencies are installed and importable.
+
+    This function probes for the aip_agents module which provides the
+    LangGraphReactAgent for local execution. Results are cached for efficiency.
+
+    Returns:
+        True if local runtime is available, False otherwise.
+    """
+    global _local_runtime_available
+
+    if _local_runtime_available is None:
+        _local_runtime_available = _probe_aip_agents_import()
+        if _local_runtime_available:
+            logger.debug("Local runtime dependencies (aip-agents) detected")
+        else:
+            logger.debug("Local runtime dependencies (aip-agents) not available")
+
+    return _local_runtime_available
+
+
+# Cached availability flag for use in conditions without function call overhead
+LOCAL_RUNTIME_AVAILABLE: bool = check_local_runtime_available()
+
+
+def get_local_runtime_missing_message() -> str:
+    """Generate an actionable error message when local runtime is not available.
+
+    Returns:
+        A user-friendly message explaining how to install local runtime dependencies
+        or how to use server-backed execution as an alternative.
+    """
+    return (
+        "Local runtime dependencies are not installed. "
+        "To run agents locally without an AIP server, install with:\n\n"
+        '    pip install "glaip-sdk[local]"\n\n'
+        "Alternatively, call deploy() to run this agent on the AIP server."
+    )
+
+
+def get_local_mode_not_supported_for_tool_message(tool_ref: str) -> str:
+    """Generate an error message for tools that cannot be used in local mode.
+
+    Args:
+        tool_ref: A string identifier for the tool (name, ID, or type description).
+
+    Returns:
+        Error message explaining that the tool type is not supported locally.
+    """
+    return (
+        f"Tool '{tool_ref}' cannot be used in local mode. "
+        "Local runtime only supports LangChain-compatible tool classes/instances "
+        "and Tool.from_langchain(...) references. "
+        "Native platform tools (Tool.from_native()) require server-backed execution "
+        "via deploy()."
+    )
+
+
+def get_uuid_not_supported_message(key_type: str, uuid_value: str) -> str:
+    """Generate an error message when a UUID is used in local mode.
+
+    In local mode, runtime_config keys must be tool/agent/MCP objects or names,
+    not UUIDs which require platform registry resolution.
+
+    Args:
+        key_type: The type of key (e.g., "tool", "agent", "mcp").
+        uuid_value: The UUID that was incorrectly provided.
+
+    Returns:
+        Error message explaining that UUIDs are not supported in local mode.
+    """
+    return (
+        f"UUID-like {key_type} key '{uuid_value}' is not supported in local mode. "
+        f"Local runtime cannot resolve {key_type} IDs - pass the {key_type} "
+        f"class/instance or name instead."
+    )