glaip-sdk 0.6.23__py3-none-any.whl → 0.6.25__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/registry/tool.py

@@ -66,9 +66,16 @@ class ToolRegistry(BaseRegistry["Tool"]):
         Raises:
             ValueError: If name cannot be extracted from the reference.
         """
+        # Lazy import to avoid circular dependency
+        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 ""
@@ -101,17 +108,61 @@ class ToolRegistry(BaseRegistry["Tool"]):
             ValueError: If the tool cannot be resolved.
         """
         # Lazy imports to avoid circular dependency
+        from glaip_sdk.tools.base import Tool as ToolClass  # noqa: PLC0415
+        from glaip_sdk.tools.base import ToolType  # noqa: PLC0415
         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
+        # Tool instance from Tool.from_native() or Tool.from_langchain()
+        # Use try/except to handle mocked Tool class in tests
+        try:
+            is_tool_instance = isinstance(ref, ToolClass)
+        except TypeError:
+            is_tool_instance = False
+
+        if is_tool_instance:
+            # 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[name] = ref
+                # Also cache by id for consistency with other resolution branches
+                self._cache[ref.id] = ref
+                return ref
+
+            # Tool.from_native() - look up on platform
+            if ref.tool_type == ToolType.NATIVE:
+                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}")
+
+            # Tool.from_langchain() - upload the tool_class
+            if ref.tool_class is not None:
+                logger.info("Uploading custom tool: %s", name)
+                tool = update_or_create_tool(ref.tool_class)
+                self._cache[name] = tool
+                if tool.id:
+                    self._cache[tool.id] = tool
+                return tool
+
+            # 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()."
+            )
+
+        # Already deployed tool (not a ToolClass, but has id/name) - just cache and return
+        # This handles API response objects and backward compatibility
         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
+            # Tool without ID (backward compatibility) - look up on platform
             logger.info("Looking up native tool: %s", name)
             tool = find_tool(name)
             if tool:
@@ -132,9 +183,7 @@ class ToolRegistry(BaseRegistry["Tool"]):
         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", ""))
+                tool = ToolClass(id=tool_id, name=ref.get("name", ""))
                 self._cache[name] = tool
                 return tool
             raise ValueError(f"Tool dict missing 'id': {ref}")

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-0.6.23.dist-info → glaip_sdk-0.6.25.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glaip-sdk
-Version: 0.6.23
+Version: 0.6.25
 Summary: Python SDK and CLI for GL AIP (GDP Labs AI Agent Package) - Build, run, and manage AI agents
 Author-email: Raymond Christopher <raymond.christopher@gdplabs.id>
 License: MIT