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

@@ -0,0 +1,145 @@
+"""Programmatic Tool Calling (PTC) configuration for local SDK runs.
+
+This module provides the PTC class for configuring sandboxed code execution
+in local agent runs. PTC enables agents to call execute_ptc_code and use MCP
+tools programmatically in an E2B sandbox.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glaip_sdk.exceptions import ValidationError
+
+
+class PTC:
+    """Configuration for Programmatic Tool Calling in local runs.
+
+    PTC allows agents to execute Python code in a sandboxed E2B environment
+    with access to registered MCP tools. This is only supported for local
+    runs (local=True) and requires the glaip-sdk[local] installation.
+
+    Example:
+        >>> from glaip_sdk.ptc import PTC
+        >>> from glaip_sdk.agents import Agent
+        >>>
+        >>> ptc = PTC(enabled=True)
+        >>> agent = Agent(
+        ...     name="ptc_demo",
+        ...     instruction="Use execute_ptc_code for multi-tool workflows.",
+        ...     mcps=[my_mcp],
+        ...     ptc=ptc,
+        ... )
+        >>> agent.run("Analyze the repo", local=True)
+
+    Custom timeouts and prompts:
+        >>> ptc = PTC(
+        ...     enabled=True,
+        ...     sandbox_timeout=180.0,
+        ...     prompt={"mode": "full", "include_example": False},
+        ... )
+
+    Args:
+        enabled: Whether PTC is enabled. Must be True to activate PTC.
+            When False, all other fields are ignored (toggle-friendly).
+        sandbox_timeout: Maximum execution time in seconds for sandbox code.
+            Defaults to 120.0 seconds.
+        prompt: Prompt configuration for PTC tool description.
+            Can be a dict with "mode" and "include_example" keys.
+            Defaults to None (uses aip-agents default).
+        custom_tools: NOT SUPPORTED in v1. Raises ValidationError if provided
+            when enabled=True.
+        ptc_packages: NOT SUPPORTED in v1. Raises ValidationError if provided
+            when enabled=True.
+
+    Raises:
+        ValidationError: If custom_tools or ptc_packages are provided when
+            enabled=True (v1 only supports MCP tools).
+    """
+
+    def __init__(
+        self,
+        *,
+        enabled: bool = False,
+        sandbox_timeout: float = 120.0,
+        prompt: dict[str, Any] | None = None,
+        custom_tools: list[Any] | None = None,
+        ptc_packages: list[str] | None = None,
+    ):
+        """Initialize PTC configuration.
+
+        Args:
+            enabled: Whether PTC is enabled. Must be True to activate.
+            sandbox_timeout: Sandbox execution timeout in seconds.
+            prompt: Prompt configuration dict.
+            custom_tools: Custom tools (NOT SUPPORTED in v1).
+            ptc_packages: Sandbox packages (NOT SUPPORTED in v1).
+
+        Raises:
+            ValidationError: If unsupported features are used when enabled=True.
+        """
+        self.enabled = enabled
+        self.sandbox_timeout = sandbox_timeout
+        self.prompt = prompt
+        self._custom_tools = custom_tools
+        self._ptc_packages = ptc_packages
+
+        if self.enabled:
+            self._validate_v1_constraints()
+
+    def _validate_v1_constraints(self) -> None:
+        """Validate that v1-unsupported features are not used.
+
+        Raises:
+            ValidationError: If custom_tools or ptc_packages are provided.
+        """
+        if self._custom_tools is not None:
+            msg = (
+                "PTC custom_tools are not supported in v1. "
+                "Only MCP tools are available in the sandbox. "
+                "Please remove the custom_tools parameter or wait for "
+                "custom tool support in a future release."
+            )
+            raise ValidationError(msg)
+
+        if self._ptc_packages is not None:
+            msg = (
+                "PTC ptc_packages are not supported in v1. "
+                "The sandbox uses a fixed template to maintain local/remote parity. "
+                "Please remove the ptc_packages parameter or wait for "
+                "package installation support in a future release."
+            )
+            raise ValidationError(msg)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert PTC config to dictionary format.
+
+        Returns:
+            Dictionary representation of PTC config.
+        """
+        result: dict[str, Any] = {
+            "enabled": self.enabled,
+        }
+
+        if self.enabled:
+            result["sandbox_timeout"] = self.sandbox_timeout
+            if self.prompt is not None:
+                result["prompt"] = self.prompt
+
+        return result
+
+    def __repr__(self) -> str:
+        """Return string representation of PTC config."""
+        if not self.enabled:
+            return "PTC(enabled=False)"
+
+        parts = [f"enabled={self.enabled}"]
+        if abs(self.sandbox_timeout - 120.0) > 1e-9:
+            parts.append(f"sandbox_timeout={self.sandbox_timeout}")
+        if self.prompt is not None:
+            parts.append(f"prompt={self.prompt!r}")
+
+        return f"PTC({', '.join(parts)})"

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)
+
+        # Cache the resolved tool
+        self._cache_tool(tool, name)
+        if hasattr(tool, "id") and tool.id:
+            self._cache[tool.id] = tool
+
+        return tool
 
-            # 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
+    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.
 
-                tool = Tool(id=tool_id, name=ref.get("name", ""))
-                self._cache[name] = tool
-                return tool
-            raise ValueError(f"Tool dict missing 'id': {ref}")
+        Args:
+            ref: The string to resolve.
+            name: The extracted 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}")
+        Returns:
+            The resolved tool, or None if not a string.
+        """
+        if not isinstance(ref, str):
+            return None
+
+        return self._resolve_native_platform_tool(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.
 
@@ -163,10 +368,18 @@ class ToolRegistry(BaseRegistry["Tool"]):
             from glaip_sdk.utils.tool_detection import (  # noqa: PLC0415
                 is_langchain_tool,
             )
+
+            is_tool = is_langchain_tool(ref)
         except ImportError:
+            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 is_langchain_tool(ref)
+        return is_tool
 
     def resolve(self, ref: Any) -> Tool:
         """Resolve a tool reference to a platform Tool object.
@@ -185,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

@@ -19,18 +19,19 @@ Example:
     >>> 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,
 )
-from glaip_sdk.runner.langgraph import LangGraphRunner
 
 # Default runner instance
-_default_runner: LangGraphRunner | None = None
+_default_runner: Any | None = None
 
 
-def get_default_runner() -> LangGraphRunner:
+def get_default_runner() -> Any:
     """Get the default runner instance for local agent execution.
 
     Returns:
@@ -45,11 +46,17 @@ def get_default_runner() -> LangGraphRunner:
         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",
@@ -57,3 +64,13 @@ __all__ = [
     "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/deps.py

@@ -31,7 +31,10 @@ def _probe_aip_agents_import() -> bool:
     Returns:
         True if aip_agents appears importable, False otherwise.
     """
-    return importlib.util.find_spec("aip_agents") is not None
+    try:
+        return importlib.util.find_spec("aip_agents") is not None
+    except (ImportError, ValueError):
+        return False
 
 
 def check_local_runtime_available() -> bool: