glaip-sdk 0.6.5b6__py3-none-any.whl → 0.7.12__py3-none-any.whl

glaip_sdk/models/schedule.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""Schedule DTO models for AIP SDK.
+
+These models represent API payloads and responses. They are intentionally DTO-only
+and do not contain runtime behavior.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from glaip_sdk.models.agent_runs import RunStatus
+
+
+class ScheduleConfig(BaseModel):
+    """Cron-like schedule configuration matching backend ScheduleConfig.
+
+    All fields accept cron-style values:
+    - Specific values: "0", "9", "1"
+    - Wildcards: "*"
+    - Intervals: "*/5", "*/2"
+    - Ranges: "1-5", "9-17"
+    - Lists: "1,3,5"
+
+    Note: day_of_week uses 0-6 where 0=Monday.
+    """
+
+    minute: str = "*"
+    hour: str = "*"
+    day_of_month: str = "*"
+    month: str = "*"
+    day_of_week: str = "*"
+
+    model_config = ConfigDict(from_attributes=True)
+
+    def to_cron_string(self) -> str:
+        """Convert to standard cron string format.
+
+        Returns:
+            Cron string in format "minute hour day_of_month month day_of_week"
+        """
+        return f"{self.minute} {self.hour} {self.day_of_month} {self.month} {self.day_of_week}"
+
+    @classmethod
+    def from_cron_string(cls, cron: str) -> "ScheduleConfig":
+        """Parse a cron string into ScheduleConfig.
+
+        Args:
+            cron: Cron string in format "minute hour day_of_month month day_of_week"
+
+        Returns:
+            ScheduleConfig instance
+
+        Raises:
+            ValueError: If cron string doesn't have exactly 5 fields
+        """
+        parts = cron.split()
+        if len(parts) != 5:
+            raise ValueError(f"Invalid cron string: expected 5 fields, got {len(parts)}")
+        return cls(
+            minute=parts[0],
+            hour=parts[1],
+            day_of_month=parts[2],
+            month=parts[3],
+            day_of_week=parts[4],
+        )
+
+
+class ScheduleMetadata(BaseModel):
+    """Metadata embedded in schedule responses.
+
+    Contains the agent association, input text, and cron configuration.
+    """
+
+    agent_id: str
+    input: str
+    schedule: ScheduleConfig
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class ScheduleResponse(BaseModel):
+    """Schedule response DTO.
+
+    Attributes:
+        id: Schedule ID.
+        next_run_time: Next run time as returned by the API.
+        time_until_next_run: Human-readable duration until next run.
+        metadata: Schedule metadata.
+        created_at: Creation timestamp.
+        updated_at: Update timestamp.
+        agent_id: Agent ID derived from metadata.
+        input: Input text derived from metadata.
+        schedule_config: ScheduleConfig derived from metadata.
+    """
+
+    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
+
+    model_config = ConfigDict(from_attributes=True)
+
+    @property
+    def agent_id(self) -> str | None:
+        """Get the agent ID from metadata."""
+        return self.metadata.agent_id if self.metadata else None
+
+    @property
+    def input(self) -> str | None:
+        """Get the scheduled input text from metadata."""
+        return self.metadata.input if self.metadata else None
+
+    @property
+    def schedule_config(self) -> ScheduleConfig | None:
+        """Get the schedule configuration from metadata."""
+        return self.metadata.schedule if self.metadata else None
+
+    def __repr__(self) -> str:
+        """Return a readable representation of the schedule."""
+        parts = [f"ScheduleResponse(id={self.id!r}"]
+        if self.next_run_time:
+            parts.append(f"next_run_time={self.next_run_time!r}")
+        if self.time_until_next_run:
+            parts.append(f"time_until_next_run={self.time_until_next_run!r}")
+        if self.agent_id:
+            parts.append(f"agent_id={self.agent_id!r}")
+        if self.created_at:
+            parts.append(f"created_at={self.created_at!r}")
+        return ", ".join(parts) + ")"
+
+    def __str__(self) -> str:
+        """Return a readable string representation."""
+        return self.__repr__()
+
+
+# Type alias for SSE event dictionaries
+ScheduleRunOutputChunk = dict[str, Any]
+
+
+class ScheduleRunResponse(BaseModel):
+    """Schedule run response DTO."""
+
+    id: str
+    agent_id: str
+    schedule_id: str | None = None  # May be None for non-scheduled runs
+    status: RunStatus  # Backend uses lowercase.
+    run_type: str | None = None  # "schedule" for scheduled runs
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+    input: str | None = None  # Input used for the execution.
+    config: ScheduleConfig | dict[str, str] | None = None  # Schedule config used.
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    model_config = ConfigDict(from_attributes=True, extra="ignore")
+
+    @property
+    def duration(self) -> str | None:
+        """Calculate the duration of the run.
+
+        Returns:
+            Formatted duration string (HH:MM:SS) or None if incomplete
+        """
+        if self.started_at and self.completed_at:
+            delta = self.completed_at - self.started_at
+            total_seconds = int(delta.total_seconds())
+            hours, remainder = divmod(total_seconds, 3600)
+            minutes, seconds = divmod(remainder, 60)
+            return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+        return None
+
+    def __repr__(self) -> str:
+        """Return a readable representation of the run."""
+        parts = [f"ScheduleRunResponse(id={self.id!r}"]
+        parts.append(f"status={self.status!r}")
+        if self.started_at:
+            parts.append(f"started_at={self.started_at.isoformat()!r}")
+        if self.duration:
+            parts.append(f"duration={self.duration!r}")
+        return ", ".join(parts) + ")"
+
+    def __str__(self) -> str:
+        """Return a readable string representation."""
+        return self.__repr__()
+
+
+class ScheduleRunResult(BaseModel):
+    """Full output payload for a schedule run.
+
+    Maps to the backend's AgentRunWithOutputResponse which includes
+    run metadata plus the output stream.
+    """
+
+    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  # Input used for the execution.
+    config: ScheduleConfig | dict[str, str] | None = None  # Schedule config used.
+    output: list[ScheduleRunOutputChunk] | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    model_config = ConfigDict(from_attributes=True, extra="ignore")
+
+    def __repr__(self) -> str:
+        """Return a readable representation of the result."""
+        output_count = len(self.output) if self.output else 0
+        return f"ScheduleRunResult(id={self.id!r}, status={self.status!r}, output_chunks={output_count})"
+
+    def __str__(self) -> str:
+        """Return a readable string representation."""
+        return self.__repr__()

glaip_sdk/payload_schemas/agent.py

@@ -57,6 +57,7 @@ AGENT_FIELD_RULES: Mapping[str, FieldRule] = {
     "timeout": FieldRule(cli_managed_create=True, cli_managed_update=True),
     # Fields requiring sanitisation before sending to the API
     "agent_config": FieldRule(requires_sanitization=True),
+    "guardrail": FieldRule(requires_sanitization=True),
 }
 
 

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)
+
+        # Cache the resolved tool
+        self._cache_tool(tool, name)
+        if hasattr(tool, "id") and tool.id:
+            self._cache[tool.id] = 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
+        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.
 
-                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.
 
@@ -160,13 +365,22 @@ class ToolRegistry(BaseRegistry["Tool"]):
             True if ref is a custom tool that needs uploading.
         """
         try:
-            from glaip_sdk.utils.tool_detection import is_langchain_tool  # noqa: PLC0415
+            from glaip_sdk.utils.tool_detection import (  # noqa: PLC0415
+                is_langchain_tool,
+            )
 
-            return is_langchain_tool(ref)
+            is_tool = is_langchain_tool(ref)
         except ImportError:
-            # Handle case where langchain_core is not available or tool_detection import fails
+            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_tool
+
     def resolve(self, ref: Any) -> Tool:
         """Resolve a tool reference to a platform Tool object.
 
@@ -184,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