glaip-sdk 0.6.5b3__py3-none-any.whl → 0.7.17__py3-none-any.whl

glaip_sdk/payload_schemas/guardrails.py

@@ -0,0 +1,34 @@
+"""Guardrail payload schemas for API communication.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class GuardrailEnginePayload(BaseModel):
+    """Payload schema for a single guardrail engine configuration.
+
+    This model defines the structure for individual safety engines (e.g., phrase_matcher, nemo)
+    when communicating with the GL AIP backend.
+    """
+
+    type: str = Field(..., description="The type of guardrail engine (e.g., 'phrase_matcher', 'nemo')")
+    config: Mapping[str, Any] = Field(..., description="Engine-specific configuration parameters")
+
+
+class GuardrailPayload(BaseModel):
+    """Payload schema for global guardrail settings.
+
+    This model acts as the container for all guardrail configurations within the agent_config.
+    """
+
+    enabled: bool = Field(default=True, description="Global toggle to enable or disable all guardrails")
+    engines: Sequence[GuardrailEnginePayload] = Field(
+        default_factory=list,
+        description="List of configured guardrail engines",
+    )

glaip_sdk/registry/tool.py

@@ -1,6 +1,6 @@
 """Tool registry for glaip_sdk.
 
-This module provides the ToolRegistry that caches deployed tools
+This module provides a ToolRegistry that caches deployed tools
 to avoid redundant API calls when deploying agents with tools.
 
 Authors:
@@ -54,6 +54,32 @@ class ToolRegistry(BaseRegistry["Tool"]):
         value = getattr(obj, attr, None)
         return value if isinstance(value, str) else None
 
+    def _extract_name_from_instance(self, ref: Any) -> str | None:
+        """Extract name from a non-type instance.
+
+        Args:
+            ref: The instance to extract name from.
+
+        Returns:
+            The extracted name, or None if not found.
+        """
+        if isinstance(ref, type):
+            return None
+        return self._get_string_attr(ref, "name")
+
+    def _extract_name_from_class(self, ref: Any) -> str | None:
+        """Extract name from a class.
+
+        Args:
+            ref: The class to extract name from.
+
+        Returns:
+            The extracted name, or None if not found.
+        """
+        if not isinstance(ref, type):
+            return None
+        return self._get_string_attr(ref, "name") or self._get_name_from_model_fields(ref)
+
     def _extract_name(self, ref: Any) -> str:
         """Extract tool name from a reference.
 
@@ -66,90 +92,269 @@ class ToolRegistry(BaseRegistry["Tool"]):
         Raises:
             ValueError: If name cannot be extracted from the reference.
         """
+        # Lazy import to avoid circular dependency: Tool -> ToolRegistry -> Tool
+        from glaip_sdk.tools.base import Tool  # noqa: PLC0415
+
         if isinstance(ref, str):
             return ref
 
+        # Tool instance (from Tool.from_langchain() or Tool.from_native())
+        if isinstance(ref, Tool):
+            return ref.get_name()
+
         # 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
+        name = self._extract_name_from_instance(ref)
+        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
+        name = self._extract_name_from_class(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.
+    def _cache_tool(self, tool: Tool, name: str) -> None:
+        """Cache a tool by name and ID if available.
 
         Args:
-            ref: The tool reference to resolve.
-            name: The extracted tool name.
+            tool: The tool to cache.
+            name: The tool name.
+        """
+        self._cache[name] = tool
+        if hasattr(tool, "id") and tool.id:
+            self._cache[tool.id] = tool
+
+    def _resolve_native_platform_tool(self, name: str, tool_class: type | None = None) -> Tool:
+        """Find a native tool on the platform and cache it.
+
+        Args:
+            name: The tool name to look up.
+            tool_class: Optional local implementation to preserve.
 
         Returns:
-            The resolved glaip_sdk.models.Tool object.
+            The resolved Tool object.
 
         Raises:
-            ValueError: If the tool cannot be resolved.
+            ValueError: If the tool is not found on the platform.
         """
-        # Lazy imports to avoid circular dependency
         from glaip_sdk.utils.discovery import find_tool  # noqa: PLC0415
+
+        logger.info("Looking up native tool: %s", name)
+        tool = find_tool(name)
+        if tool:
+            # Preserve local implementation if provided
+            if tool_class:
+                tool.tool_class = tool_class
+            self._cache_tool(tool, name)
+            return tool
+
+        raise ValueError(
+            f"Native tool '{name}' not found on platform. Ensure the tool is deployed or check for name mismatches."
+        )
+
+    def _resolve_tool_instance(self, ref: Any, name: str) -> Tool | None:
+        """Resolve a ToolClass instance.
+
+        Args:
+            ref: The ToolClass instance to resolve.
+            name: The extracted tool name.
+
+        Returns:
+            The resolved tool, or None if not a ToolClass instance.
+        """
+        # Lazy imports to avoid circular dependency: Tool -> ToolRegistry -> Tool
+        from glaip_sdk.tools.base import Tool as ToolClass  # noqa: PLC0415
+        from glaip_sdk.tools.base import ToolType  # noqa: PLC0415
+
+        # Use try/except to handle mocked Tool class in tests
+        try:
+            is_tool_instance = isinstance(ref, ToolClass)
+        except TypeError:
+            return None
+
+        if not is_tool_instance:
+            return None
+
+        # If Tool has an ID, it's already deployed - return as-is
+        if ref.id is not None:
+            logger.debug("Caching already deployed tool: %s", name)
+            self._cache_tool(ref, name)
+            return ref
+
+        # Tool.from_native() - look up on platform
+        if ref.tool_type == ToolType.NATIVE:
+            return self._resolve_native_platform_tool(name, tool_class=getattr(ref, "tool_class", None))
+
+        # Tool.from_langchain() - resolve the inner tool_class (promoted or uploaded)
+        if ref.tool_class is not None:
+            return self._resolve_custom_tool(ref.tool_class, name)
+
+        # Unresolvable Tool instance - neither native nor has tool_class
+        raise ValueError(
+            f"Cannot resolve Tool instance: {ref}. "
+            f"Tool has no id, is not NATIVE type, and has no tool_class. "
+            f"Ensure Tool is created via Tool.from_native() or Tool.from_langchain()."
+        )
+
+    def _resolve_deployed_tool(self, ref: Any, name: str) -> Tool | None:
+        """Resolve an already deployed tool (has id/name attributes).
+
+        Args:
+            ref: The tool reference to resolve.
+            name: The extracted tool name.
+
+        Returns:
+            The resolved tool, or None if not a deployed tool.
+        """
+        # Already deployed tool (not a ToolClass, but has id/name)
+        # This handles API response objects and backward compatibility
+        if not (hasattr(ref, "id") and hasattr(ref, "name") and not isinstance(ref, type)):
+            return None
+
+        if ref.id is not None:
+            logger.debug("Caching already deployed tool: %s", name)
+            # Use _cache_tool to cache by both name and ID for consistency
+            self._cache_tool(ref, name)
+            return ref
+
+        # Tool without ID (backward compatibility) - look up on platform
+        return self._resolve_native_platform_tool(name)
+
+    def _resolve_custom_tool(self, ref: Any, name: str) -> Tool | None:
+        """Resolve a custom tool class, promoting aip_agents.tools classes to NATIVE.
+
+        This method handles two main paths:
+        1. **Promotion**: If the tool class is from `aip_agents.tools`, it is automatically
+           promoted to a `NATIVE` tool type. It then performs a platform lookup to link it
+           with the deployed native tool while preserving the local `tool_class` for local execution.
+        2. **Upload**: If it is a standard LangChain tool, it is uploaded to the platform
+           as a custom tool.
+
+        Args:
+            ref: The tool reference (usually a class) to resolve.
+            name: The extracted tool name.
+
+        Returns:
+            The resolved tool, or None if not a custom tool.
+        """
+        # aip_agents tools are automatically promoted to NATIVE
+        if self._is_aip_agents_tool(ref):
+            from glaip_sdk.utils.tool_detection import get_tool_name  # noqa: PLC0415
+
+            # Get name from class attribute or field
+            tool_name = get_tool_name(ref)
+            if tool_name is None:
+                raise ValueError(f"Tool class {ref.__name__} has no 'name' attribute")
+
+            return self._resolve_native_platform_tool(tool_name, tool_class=ref)
+
+        if not self._is_custom_tool(ref):
+            return None
+
+        # Regular custom tools - upload to platform
         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
+        logger.info("Uploading custom tool: %s", name)
+        tool = update_or_create_tool(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
+        # Cache the resolved tool
+        self._cache_tool(tool, name)
+        if hasattr(tool, "id") and tool.id:
+            self._cache[tool.id] = tool
+
+        return tool
+
+    def _resolve_dict_tool(self, ref: Any, name: str) -> Tool | None:
+        """Resolve a tool from a dict (API response).
+
+        Args:
+            ref: The dict to resolve.
+            name: The extracted tool name.
+
+        Returns:
+            The resolved tool, or None if not a dict.
+        """
+        # Lazy imports to avoid circular dependency
+        from glaip_sdk.tools.base import Tool as ToolClass  # noqa: PLC0415
+
+        if not isinstance(ref, dict):
+            return None
+
+        tool_id = ref.get("id")
+        if tool_id:
+            tool = ToolClass(id=tool_id, name=ref.get("name", ""))
+            # Use _cache_tool to cache by both name and ID for consistency
+            self._cache_tool(tool, name)
             return tool
+        raise ValueError(f"Tool dict missing 'id': {ref}")
 
-        # 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
+    def _resolve_string_tool(self, ref: Any, name: str) -> Tool | None:
+        """Resolve a tool from a string name.
+
+        Args:
+            ref: The string to resolve.
+            name: The extracted tool name.
+
+        Returns:
+            The resolved tool, or None if not a string.
+        """
+        if not isinstance(ref, str):
+            return None
 
-                tool = Tool(id=tool_id, name=ref.get("name", ""))
-                self._cache[name] = tool
-                return tool
-            raise ValueError(f"Tool dict missing 'id': {ref}")
+        return self._resolve_native_platform_tool(name)
 
-        # 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}")
+    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 tool cannot be resolved.
+        """
+        # Try each resolution strategy in order
+        resolvers = [
+            self._resolve_tool_instance,
+            self._resolve_deployed_tool,
+            self._resolve_custom_tool,
+            self._resolve_dict_tool,
+            self._resolve_string_tool,
+        ]
+
+        for resolver in resolvers:
+            result = resolver(ref, name)
+            if result is not None:
+                return result
 
         raise ValueError(f"Could not resolve tool reference: {ref}")
 
+    def _is_aip_agents_tool(self, ref: Any) -> bool:
+        """Check if reference is an aip-agents tool.
+
+        Args:
+            ref: The reference to check.
+
+        Returns:
+            True if ref is from aip_agents.tools package.
+        """
+        try:
+            from glaip_sdk.utils.tool_detection import (  # noqa: PLC0415
+                is_aip_agents_tool,
+            )
+        except ImportError:
+            return False
+
+        return is_aip_agents_tool(ref)
+
     def _is_custom_tool(self, ref: Any) -> bool:
         """Check if reference is a custom tool class/instance.
 
@@ -160,19 +365,21 @@ class ToolRegistry(BaseRegistry["Tool"]):
             True if ref is a custom tool that needs uploading.
         """
         try:
-            from langchain_core.tools import BaseTool  # noqa: PLC0415
+            from glaip_sdk.utils.tool_detection import (  # noqa: PLC0415
+                is_langchain_tool,
+            )
 
-            # LangChain BaseTool class
-            if isinstance(ref, type) and issubclass(ref, BaseTool):
-                return True
-
-            # LangChain BaseTool instance
-            if isinstance(ref, BaseTool):
-                return True
+            is_tool = is_langchain_tool(ref)
         except ImportError:
-            pass
+            is_tool = hasattr(ref, "args_schema") or hasattr(ref, "_run")
+            if is_tool:
+                logger.warning("tool_detection module missing; identifying tool via fallback attributes.")
+
+        # aip_agents tools are NOT custom - they're native
+        if is_tool and self._is_aip_agents_tool(ref):
+            return False
 
-        return False
+        return is_tool
 
     def resolve(self, ref: Any) -> Tool:
         """Resolve a tool reference to a platform Tool object.
@@ -191,9 +398,9 @@ class ToolRegistry(BaseRegistry["Tool"]):
             if ref.id is not None:
                 name = self._extract_name(ref)
                 if name not in self._cache:
-                    self._cache[name] = ref
+                    # Use _cache_tool to cache by both name and ID for consistency
+                    self._cache_tool(ref, name)
                 return ref
-
             # Tool without ID (e.g., from Tool.from_native()) - needs platform lookup
             # Fall through to normal resolution
 

glaip_sdk/runner/__init__.py

@@ -0,0 +1,76 @@
+"""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 typing import TYPE_CHECKING, Any
+
+from glaip_sdk.runner.deps import (
+    LOCAL_RUNTIME_AVAILABLE,
+    check_local_runtime_available,
+    get_local_runtime_missing_message,
+)
+
+# Default runner instance
+_default_runner: Any | None = None
+
+
+def get_default_runner() -> Any:
+    """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:
+        # Lazy import to avoid requiring aip-agents when runner is not used
+        from glaip_sdk.runner.langgraph import LangGraphRunner  # noqa: PLC0415
+
+        _default_runner = LangGraphRunner()
+
+    return _default_runner
+
+
+if TYPE_CHECKING:
+    from glaip_sdk.runner.langgraph import LangGraphRunner
+
+__all__ = [
+    "LOCAL_RUNTIME_AVAILABLE",
+    "LangGraphRunner",
+    "check_local_runtime_available",
+    "get_default_runner",
+    "get_local_runtime_missing_message",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import for LangGraphRunner to avoid requiring aip-agents when not used."""
+    if name == "LangGraphRunner":
+        from glaip_sdk.runner.langgraph import LangGraphRunner  # noqa: PLC0415
+
+        globals()["LangGraphRunner"] = LangGraphRunner
+        return LangGraphRunner
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

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.
+        """
+        ...