glaip-sdk 0.1.0__py3-none-any.whl → 0.6.10__py3-none-any.whl

glaip_sdk/cli/validators.py

@@ -13,6 +13,7 @@ from typing import Any
 
 import click
 
+from glaip_sdk.cli.utils import handle_best_effort_check
 from glaip_sdk.utils.validation import (
     coerce_timeout,
     validate_agent_instruction,
@@ -42,7 +43,7 @@ def validate_agent_name_cli(name: str) -> str:
     try:
         return validate_agent_name(name)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def validate_agent_instruction_cli(instruction: str) -> str:
@@ -60,7 +61,7 @@ def validate_agent_instruction_cli(instruction: str) -> str:
     try:
         return validate_agent_instruction(instruction)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def validate_timeout_cli(timeout: int) -> int:
@@ -78,7 +79,7 @@ def validate_timeout_cli(timeout: int) -> int:
     try:
         return validate_timeout(timeout)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def validate_tool_name_cli(name: str) -> str:
@@ -96,7 +97,7 @@ def validate_tool_name_cli(name: str) -> str:
     try:
         return validate_tool_name(name)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def validate_mcp_name_cli(name: str) -> str:
@@ -114,7 +115,7 @@ def validate_mcp_name_cli(name: str) -> str:
     try:
         return validate_mcp_name(name)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def validate_file_path_cli(file_path: str | Path, must_exist: bool = True) -> Path:
@@ -133,7 +134,7 @@ def validate_file_path_cli(file_path: str | Path, must_exist: bool = True) -> Pa
     try:
         return validate_file_path(file_path, must_exist)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def validate_directory_path_cli(dir_path: str | Path, must_exist: bool = True) -> Path:
@@ -152,7 +153,7 @@ def validate_directory_path_cli(dir_path: str | Path, must_exist: bool = True) -
     try:
         return validate_directory_path(dir_path, must_exist)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def validate_url_cli(url: str) -> str:
@@ -170,7 +171,7 @@ def validate_url_cli(url: str) -> str:
     try:
         return validate_url(url)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def validate_api_key_cli(api_key: str) -> str:
@@ -188,7 +189,7 @@ def validate_api_key_cli(api_key: str) -> str:
     try:
         return validate_api_key(api_key)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def coerce_timeout_cli(value: int | float | str) -> int:
@@ -206,7 +207,7 @@ def coerce_timeout_cli(value: int | float | str) -> int:
     try:
         return coerce_timeout(value)
     except ValueError as e:
-        raise click.ClickException(str(e))
+        raise click.ClickException(str(e)) from e
 
 
 def validate_name_uniqueness_cli(
@@ -226,15 +227,12 @@ def validate_name_uniqueness_cli(
     Raises:
         click.ClickException: If name is not unique
     """
-    try:
+
+    def _check_duplicate() -> None:
         existing = finder_func(name=name)
         if existing:
             raise click.ClickException(
-                f"A {resource_type.lower()} named '{name}' already exists. "
-                "Please choose a unique name."
+                f"A {resource_type.lower()} named '{name}' already exists. Please choose a unique name."
             )
-    except click.ClickException:
-        raise
-    except Exception:
-        # Non-fatal: best-effort duplicate check
-        pass
+
+    handle_best_effort_check(_check_duplicate)

glaip_sdk/client/__init__.py

@@ -5,6 +5,7 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+from glaip_sdk.client.agent_runs import AgentRunsClient
 from glaip_sdk.client.main import Client
 
-__all__ = ["Client"]
+__all__ = ["AgentRunsClient", "Client"]

glaip_sdk/client/_agent_payloads.py

@@ -15,10 +15,7 @@ from glaip_sdk.config.constants import (
     DEFAULT_AGENT_VERSION,
     DEFAULT_MODEL,
 )
-from glaip_sdk.payload_schemas.agent import (
-    AgentImportOperation,
-    get_import_field_plan,
-)
+from glaip_sdk.payload_schemas.agent import AgentImportOperation, get_import_field_plan
 from glaip_sdk.utils.client_utils import extract_ids
 
 _LM_CONFLICT_KEYS = {
@@ -209,6 +206,11 @@ class AgentListParams:
         return params
 
     def _base_filter_params(self) -> dict[str, Any]:
+        """Build base filter parameters from non-None fields.
+
+        Returns:
+            Dictionary of filter parameters with non-None values.
+        """
         return {
             key: value
             for key, value in (
@@ -221,6 +223,11 @@ class AgentListParams:
         }
 
     def _apply_pagination_params(self, params: dict[str, Any]) -> None:
+        """Apply pagination parameters to the params dictionary.
+
+        Args:
+            params: Dictionary to update with pagination parameters.
+        """
         if self.limit is not None:
             if not 1 <= self.limit <= 100:
                 raise ValueError("limit must be between 1 and 100 inclusive")
@@ -238,6 +245,11 @@ class AgentListParams:
             params["sync_langflow_agents"] = str(self.sync_langflow_agents).lower()
 
     def _apply_timestamp_filters(self, params: dict[str, Any]) -> None:
+        """Apply timestamp filter parameters to the params dictionary.
+
+        Args:
+            params: Dictionary to update with timestamp filter parameters.
+        """
         timestamp_filters = {
             "created_at_start": self.created_at_start,
             "created_at_end": self.created_at_end,
@@ -249,6 +261,11 @@ class AgentListParams:
                 params[key] = value
 
     def _apply_metadata_filters(self, params: dict[str, Any]) -> None:
+        """Apply metadata filter parameters to the params dictionary.
+
+        Args:
+            params: Dictionary to update with metadata filter parameters.
+        """
         if not self.metadata:
             return
         for key, value in self.metadata.items():
@@ -269,12 +286,22 @@ class AgentListResult:
     message: str | None = None
 
     def __len__(self) -> int:  # pragma: no cover - simple delegation
+        """Return the number of items in the result list."""
         return len(self.items)
 
     def __iter__(self):  # pragma: no cover - simple delegation
+        """Return an iterator over the items in the result list."""
         return iter(self.items)
 
     def __getitem__(self, index: int) -> Any:  # pragma: no cover - simple delegation
+        """Get an item from the result list by index.
+
+        Args:
+            index: Index of the item to retrieve.
+
+        Returns:
+            The item at the specified index.
+        """
         return self.items[index]
 
 
@@ -348,9 +375,7 @@ class AgentCreateRequest:
             payload["tool_configs"] = _copy_structure(self.tool_configs)
 
         effective_agent_config = _sanitize_agent_config(self.agent_config)
-        effective_agent_config = _merge_execution_timeout(
-            effective_agent_config, self.timeout
-        )
+        effective_agent_config = _merge_execution_timeout(effective_agent_config, self.timeout)
         if effective_agent_config:
             payload["agent_config"] = effective_agent_config
 
@@ -407,31 +432,25 @@ __all__ = [
 ]
 
 
-def _build_base_update_payload(
-    request: AgentUpdateRequest, current_agent: Any
-) -> dict[str, Any]:
+def _build_base_update_payload(request: AgentUpdateRequest, current_agent: Any) -> dict[str, Any]:
+    """Populate immutable agent update fields using request data or existing agent defaults."""
+    # Support both "agent_type" (runtime class) and "type" (API response) attributes
+    current_type = getattr(current_agent, "agent_type", None) or getattr(current_agent, "type", None)
     return {
-        "name": request.name.strip()
-        if request.name is not None
-        else getattr(current_agent, "name", None),
-        "instruction": request.instruction.strip()
-        if request.instruction is not None
-        else getattr(current_agent, "instruction", None),
-        "type": request.agent_type
-        or getattr(current_agent, "type", None)
-        or DEFAULT_AGENT_TYPE,
-        "framework": request.framework
-        or getattr(current_agent, "framework", None)
-        or DEFAULT_AGENT_FRAMEWORK,
-        "version": request.version
-        or getattr(current_agent, "version", None)
-        or DEFAULT_AGENT_VERSION,
+        "name": (request.name.strip() if request.name is not None else getattr(current_agent, "name", None)),
+        "instruction": (
+            request.instruction.strip()
+            if request.instruction is not None
+            else getattr(current_agent, "instruction", None)
+        ),
+        "type": request.agent_type or current_type or DEFAULT_AGENT_TYPE,
+        "framework": request.framework or getattr(current_agent, "framework", None) or DEFAULT_AGENT_FRAMEWORK,
+        "version": request.version or getattr(current_agent, "version", None) or DEFAULT_AGENT_VERSION,
     }
 
 
-def _resolve_update_language_model_fields(
-    request: AgentUpdateRequest, current_agent: Any
-) -> dict[str, Any]:
+def _resolve_update_language_model_fields(request: AgentUpdateRequest, current_agent: Any) -> dict[str, Any]:
+    """Resolve the language-model portion of an update request with sensible fallbacks."""
     fields = resolve_language_model_fields(
         model=request.model,
         language_model_id=request.language_model_id,
@@ -443,9 +462,8 @@ def _resolve_update_language_model_fields(
     return fields
 
 
-def _collect_optional_update_fields(
-    request: AgentUpdateRequest, current_agent: Any
-) -> dict[str, Any]:
+def _collect_optional_update_fields(request: AgentUpdateRequest, current_agent: Any) -> dict[str, Any]:
+    """Collect optional agent fields, preserving current values when updates are absent."""
     result: dict[str, Any] = {}
 
     for field_name, value in (
@@ -483,9 +501,8 @@ def _collect_optional_update_fields(
     return result
 
 
-def _collect_relationship_fields(
-    request: AgentUpdateRequest, current_agent: Any
-) -> dict[str, Any]:
+def _collect_relationship_fields(request: AgentUpdateRequest, current_agent: Any) -> dict[str, Any]:
+    """Return relationship identifiers (tools/agents/mcps) for an update request."""
     return {
         "tools": _resolve_relation_ids(request.tools, current_agent, "tools"),
         "agents": _resolve_relation_ids(request.agents, current_agent, "agents"),
@@ -493,9 +510,8 @@ def _collect_relationship_fields(
     }
 
 
-def _resolve_agent_config_update(
-    request: AgentUpdateRequest, current_agent: Any
-) -> dict[str, Any] | None:
+def _resolve_agent_config_update(request: AgentUpdateRequest, current_agent: Any) -> dict[str, Any] | None:
+    """Determine the agent_config payload to send, if any."""
     effective_agent_config = _sanitize_agent_config(request.agent_config)
     if effective_agent_config is not None:
         return effective_agent_config

glaip_sdk/client/agent_runs.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Agent runs client for AIP SDK.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from typing import Any
+
+import httpx
+
+from glaip_sdk.client.base import BaseClient
+from glaip_sdk.exceptions import TimeoutError, ValidationError
+from glaip_sdk.models.agent_runs import RunSummary, RunsPage, RunWithOutput
+
+
+class AgentRunsClient(BaseClient):
+    """Client for agent run operations."""
+
+    def list_runs(
+        self,
+        agent_id: str,
+        *,
+        limit: int = 20,
+        page: int = 1,
+    ) -> RunsPage:
+        """List agent runs with pagination.
+
+        Args:
+            agent_id: UUID of the agent
+            limit: Number of runs per page (1-100, default 20)
+            page: Page number (1-based, default 1)
+
+        Returns:
+            RunsPage containing paginated run summaries
+
+        Raises:
+            ValidationError: If pagination parameters are invalid
+            NotFoundError: If agent is not found
+            AuthenticationError: If authentication fails
+            TimeoutError: If request times out (30s default)
+        """
+        self._validate_pagination_params(limit, page)
+        envelope = self._fetch_runs_envelope(agent_id, limit, page)
+        normalized_data = self._normalize_runs_payload(envelope.get("data"))
+        runs = [RunSummary(**item) for item in normalized_data]
+        return self._build_runs_page(envelope, runs, limit, page)
+
+    def _fetch_runs_envelope(self, agent_id: str, limit: int, page: int) -> dict[str, Any]:
+        params = {"limit": limit, "page": page}
+        try:
+            envelope = self._request_with_envelope(
+                "GET",
+                f"/agents/{agent_id}/runs",
+                params=params,
+            )
+        except httpx.TimeoutException as e:
+            raise TimeoutError(f"Request timed out after {self._timeout}s while fetching agent runs") from e
+
+        if isinstance(envelope, dict):
+            return envelope
+        return {"data": envelope}
+
+    @staticmethod
+    def _validate_pagination_params(limit: int, page: int) -> None:
+        if limit < 1 or limit > 100:
+            raise ValidationError("limit must be between 1 and 100")
+        if page < 1:
+            raise ValidationError("page must be >= 1")
+
+    @staticmethod
+    def _normalize_runs_payload(data_payload: Any) -> list[Any]:
+        if not data_payload:
+            return []
+        normalized_data: list[Any] = []
+        for item in data_payload:
+            normalized_data.append(AgentRunsClient._normalize_run_item(item))
+        return normalized_data
+
+    @staticmethod
+    def _normalize_run_item(item: Any) -> Any:
+        if isinstance(item, dict):
+            if item.get("config") is None:
+                item["config"] = {}
+            schedule_id = item.get("schedule_id")
+            if schedule_id == "None" or schedule_id == "":
+                item["schedule_id"] = None
+        return item
+
+    @staticmethod
+    def _build_runs_page(
+        envelope: dict[str, Any],
+        runs: list[RunSummary],
+        limit: int,
+        page: int,
+    ) -> RunsPage:
+        return RunsPage(
+            data=runs,
+            total=envelope.get("total", 0),
+            page=envelope.get("page", page),
+            limit=envelope.get("limit", limit),
+            has_next=envelope.get("has_next", False),
+            has_prev=envelope.get("has_prev", False),
+        )
+
+    def get_run(
+        self,
+        agent_id: str,
+        run_id: str,
+    ) -> RunWithOutput:
+        """Get detailed run information including SSE event stream.
+
+        Args:
+            agent_id: UUID of the agent
+            run_id: UUID of the run
+
+        Returns:
+            RunWithOutput containing complete run details and event stream
+
+        Raises:
+            NotFoundError: If run or agent is not found
+            AuthenticationError: If authentication fails
+            TimeoutError: If request times out (30s default)
+        """
+        try:
+            envelope = self._request_with_envelope(
+                "GET",
+                f"/agents/{agent_id}/runs/{run_id}",
+            )
+        except httpx.TimeoutException as e:
+            raise TimeoutError(f"Request timed out after {self._timeout}s while fetching run detail") from e
+
+        if not isinstance(envelope, dict):
+            envelope = {"data": envelope}
+
+        data = envelope.get("data") or {}
+        # Normalize config, output, and schedule_id fields
+        if data.get("config") is None:
+            data["config"] = {}
+        if data.get("output") is None:
+            data["output"] = []
+        # Normalize schedule_id: convert string "None" to None
+        schedule_id = data.get("schedule_id")
+        if schedule_id == "None" or schedule_id == "":
+            data["schedule_id"] = None
+
+        return RunWithOutput(**data)