glaip-sdk 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

glaip_sdk/cli/utils.py

@@ -12,8 +12,9 @@ import json
 import logging
 import os
 import sys
+import asyncio
 from collections.abc import Callable, Iterable
-from contextlib import AbstractContextManager, nullcontext
+from contextlib import AbstractContextManager, contextmanager, nullcontext
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 
@@ -39,10 +40,11 @@ from glaip_sdk.cli.context import (
     detect_export_format as _detect_export_format,
     get_ctx_value,
 )
-from glaip_sdk.cli.rich_helpers import markup_text
+from glaip_sdk.cli.io import export_resource_to_file_with_validation
+from glaip_sdk.cli.rich_helpers import markup_text, print_markup
 from glaip_sdk.icons import ICON_AGENT
 from glaip_sdk.rich_components import AIPPanel, AIPTable
-from glaip_sdk.utils import is_uuid
+from glaip_sdk.utils import format_datetime, is_uuid
 from glaip_sdk.utils.rendering.renderer import (
     CapturingConsole,
     RendererConfig,
@@ -50,6 +52,160 @@ from glaip_sdk.utils.rendering.renderer import (
 )
 
 
+@contextmanager
+def bind_slash_session_context(ctx: Any, session: Any) -> Any:
+    """Temporarily attach a slash session to the Click context.
+
+    Args:
+        ctx: Click context object.
+        session: SlashSession instance to bind.
+
+    Yields:
+        None - context manager for use in with statement.
+    """
+    ctx_obj = getattr(ctx, "obj", None)
+    has_context = isinstance(ctx_obj, dict)
+    previous_session = ctx_obj.get("_slash_session") if has_context else None
+    if has_context:
+        ctx_obj["_slash_session"] = session
+    try:
+        yield
+    finally:
+        if has_context:
+            if previous_session is None:
+                ctx_obj.pop("_slash_session", None)
+            else:
+                ctx_obj["_slash_session"] = previous_session
+
+
+def restore_slash_session_context(ctx_obj: dict[str, Any], previous_session: Any | None) -> None:
+    """Restore slash session context after operation.
+
+    Args:
+        ctx_obj: Click context obj dictionary.
+        previous_session: Previous session to restore, or None to remove.
+    """
+    if previous_session is None:
+        ctx_obj.pop("_slash_session", None)
+    else:
+        ctx_obj["_slash_session"] = previous_session
+
+
+def handle_best_effort_check(
+    check_func: Callable[[], None],
+) -> None:
+    """Handle best-effort duplicate/existence checks with proper exception handling.
+
+    Args:
+        check_func: Function that performs the check and raises ClickException if duplicate found.
+    """
+    try:
+        check_func()
+    except click.ClickException:
+        raise
+    except Exception:
+        # Non-fatal: best-effort duplicate check
+        pass
+
+
+def prompt_export_choice_questionary(
+    default_path: Path,
+    default_display: str,
+) -> tuple[str, Path | None] | None:
+    """Prompt user for export destination using questionary with numeric shortcuts.
+
+    Args:
+        default_path: Default export path.
+        default_display: Formatted display string for default path.
+
+    Returns:
+        Tuple of (choice, path) or None if cancelled/unavailable.
+        Choice can be "default", "custom", or "cancel".
+    """
+    # Import here for optional dependency (questionary may not be installed)
+    try:  # pragma: no cover - optional dependency
+        import questionary
+        from questionary import Choice
+    except Exception:  # pragma: no cover - optional dependency
+        return None
+
+    if questionary is None or Choice is None:
+        return None
+
+    try:
+        question = questionary.select(
+            "Export transcript",
+            choices=[
+                Choice(
+                    title=f"Save to default ({default_display})",
+                    value=("default", default_path),
+                    shortcut_key="1",
+                ),
+                Choice(
+                    title="Choose a different path",
+                    value=("custom", None),
+                    shortcut_key="2",
+                ),
+                Choice(
+                    title="Cancel",
+                    value=("cancel", None),
+                    shortcut_key="3",
+                ),
+            ],
+            use_shortcuts=True,
+            instruction="Press 1-3 (or arrows) then Enter.",
+        )
+        answer = questionary_safe_ask(question)
+    except Exception:
+        return None
+
+    if answer is None:
+        return ("cancel", None)
+    return answer
+
+
+def questionary_safe_ask(question: Any, *, patch_stdout: bool = False) -> Any:
+    """Run `questionary.Question` safely even when an asyncio loop is active."""
+    ask_fn = getattr(question, "unsafe_ask", None)
+    if not callable(ask_fn):
+        raise RuntimeError("Questionary prompt is missing unsafe_ask()")
+
+    if not _asyncio_loop_running():
+        return ask_fn(patch_stdout=patch_stdout)
+
+    return _run_questionary_in_thread(question, patch_stdout=patch_stdout)
+
+
+def _asyncio_loop_running() -> bool:
+    """Return True when an asyncio event loop is already running."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return False
+    return True
+
+
+def _run_questionary_in_thread(question: Any, *, patch_stdout: bool = False) -> Any:
+    """Execute a questionary prompt in a background thread."""
+    if getattr(question, "should_skip_question", False):
+        return getattr(question, "default", None)
+
+    application = getattr(question, "application", None)
+    run_callable = getattr(application, "run", None) if application is not None else None
+    if callable(run_callable):
+        try:
+            if patch_stdout:
+                from prompt_toolkit.patch_stdout import patch_stdout as pt_patch_stdout
+
+                with pt_patch_stdout():
+                    return run_callable(in_thread=True)
+            return run_callable(in_thread=True)
+        except TypeError:
+            pass
+
+    return question.unsafe_ask(patch_stdout=patch_stdout)
+
+
 class _LiteralYamlDumper(yaml.SafeDumper):
     """YAML dumper that emits literal scalars for multiline strings."""
 
@@ -160,8 +316,6 @@ def format_datetime_fields(
     Returns:
         New dictionary with formatted datetime fields
     """
-    from glaip_sdk.utils import format_datetime
-
     formatted = data.copy()
     for field in fields:
         if field in formatted:
@@ -224,10 +378,6 @@ def handle_resource_export(
         get_by_id_func: Function to fetch resource by ID
         console_override: Optional console override
     """
-    from glaip_sdk.cli.display import handle_rich_output
-    from glaip_sdk.cli.io import export_resource_to_file_with_validation
-    from glaip_sdk.cli.rich_helpers import print_markup
-
     active_console = console_override or console
 
     # Auto-detect format from file extension
@@ -251,6 +401,8 @@ def handle_resource_export(
         ):
             export_resource_to_file_with_validation(full_resource, export_path, detected_format)
     except Exception:
+        from glaip_sdk.cli.display import handle_rich_output  # noqa: E402 - avoid circular import
+
         handle_rich_output(
             ctx,
             markup_text(f"[{WARNING_STYLE}]⚠️  Failed to fetch full details, using available data[/]"),
@@ -345,6 +497,28 @@ def sdk_version() -> str:
     return "0.0.0"
 
 
+@contextmanager
+def with_client_and_spinner(
+    ctx: Any,
+    spinner_message: str,
+    *,
+    console_override: Console | None = None,
+) -> Any:
+    """Context manager for commands that need client and spinner.
+
+    Args:
+        ctx: Click context.
+        spinner_message: Message to display in spinner.
+        console_override: Optional console override.
+
+    Yields:
+        Client instance.
+    """
+    client = get_client(ctx)
+    with spinner_context(ctx, spinner_message, console_override=console_override):
+        yield client
+
+
 def spinner_context(
     ctx: Any | None,
     message: str,

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,
@@ -226,14 +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."
             )
-    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_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)

glaip_sdk/client/agents.py

@@ -5,9 +5,11 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+import asyncio
 import json
 import logging
 from collections.abc import AsyncGenerator, Callable, Iterator, Mapping
+from contextlib import asynccontextmanager
 from os import PathLike
 from pathlib import Path
 from typing import Any, BinaryIO
@@ -20,6 +22,7 @@ from glaip_sdk.client._agent_payloads import (
     AgentListResult,
     AgentUpdateRequest,
 )
+from glaip_sdk.client.agent_runs import AgentRunsClient
 from glaip_sdk.client.base import BaseClient
 from glaip_sdk.client.mcps import MCPClient
 from glaip_sdk.client.run_rendering import (
@@ -28,6 +31,7 @@ from glaip_sdk.client.run_rendering import (
 )
 from glaip_sdk.client.tools import ToolClient
 from glaip_sdk.config.constants import (
+    AGENT_CONFIG_FIELDS,
     DEFAULT_AGENT_FRAMEWORK,
     DEFAULT_AGENT_RUN_TIMEOUT,
     DEFAULT_AGENT_TYPE,
@@ -67,6 +71,19 @@ _MERGED_SEQUENCE_FIELDS = ("tools", "agents", "mcps")
 _DEFAULT_METADATA_TYPE = "custom"
 
 
+@asynccontextmanager
+async def _async_timeout_guard(timeout_seconds: float | None) -> AsyncGenerator[None, None]:
+    """Apply an asyncio timeout when a custom timeout is provided."""
+    if timeout_seconds is None:
+        yield
+        return
+    try:
+        async with asyncio.timeout(timeout_seconds):
+            yield
+    except asyncio.TimeoutError as exc:
+        raise httpx.TimeoutException(f"Request timed out after {timeout_seconds}s") from exc
+
+
 def _normalise_sequence(value: Any) -> list[Any] | None:
     """Normalise optional sequence inputs to plain lists."""
     if value is None:
@@ -193,19 +210,7 @@ def _extract_original_refs(raw_definition: dict) -> dict[str, list]:
 
 def _build_cli_args(overrides_dict: dict) -> dict[str, Any]:
     """Build CLI args from overrides, filtering out None values."""
-    cli_args = {
-        key: overrides_dict.get(key)
-        for key in (
-            "name",
-            "instruction",
-            "model",
-            "tools",
-            "agents",
-            "mcps",
-            "timeout",
-        )
-        if overrides_dict.get(key) is not None
-    }
+    cli_args = {key: overrides_dict.get(key) for key in AGENT_CONFIG_FIELDS if overrides_dict.get(key) is not None}
 
     # Normalize sequence fields
     for field in _MERGED_SEQUENCE_FIELDS:
@@ -254,6 +259,7 @@ class AgentClient(BaseClient):
         self._renderer_manager = AgentRunRenderingManager(logger)
         self._tool_client: ToolClient | None = None
         self._mcp_client: MCPClient | None = None
+        self._runs_client: "AgentRunsClient | None" = None
 
     def list_agents(
         self,
@@ -1172,7 +1178,7 @@ class AgentClient(BaseClient):
         message: str,
         files: list[str | BinaryIO] | None = None,
         *,
-        timeout: float | None = None,
+        request_timeout: float | None = None,
         **kwargs,
     ) -> AsyncGenerator[dict, None]:
         """Async run an agent with a message, yielding streaming JSON chunks.
@@ -1181,7 +1187,7 @@ class AgentClient(BaseClient):
             agent_id: ID of the agent to run
             message: Message to send to the agent
             files: Optional list of files to include
-            timeout: Request timeout in seconds
+            request_timeout: Optional request timeout in seconds (defaults to client timeout)
             **kwargs: Additional arguments (chat_history, pii_mapping, etc.)
 
         Yields:
@@ -1192,18 +1198,22 @@ class AgentClient(BaseClient):
             httpx.TimeoutException: When general timeout occurs
             Exception: For other unexpected errors
         """
+        # Derive timeout values for request/control flow
+        legacy_timeout = kwargs.get("timeout")
+        http_timeout_override = request_timeout if request_timeout is not None else legacy_timeout
+        http_timeout = http_timeout_override or self.timeout
+
         # Prepare request data
         payload, data_payload, files_payload, headers = self._prepare_request_data(message, files, **kwargs)
 
         # Create async client configuration
-        async_client_config = self._create_async_client_config(timeout, headers)
+        async_client_config = self._create_async_client_config(http_timeout_override, headers)
 
         # Get execution timeout for streaming control
         timeout_seconds = kwargs.get("timeout", DEFAULT_AGENT_RUN_TIMEOUT)
         agent_name = kwargs.get("agent_name")
 
-        try:
-            # Create async client and stream response
+        async def _chunk_stream() -> AsyncGenerator[dict, None]:
             async with httpx.AsyncClient(**async_client_config) as async_client:
                 async for chunk in self._stream_agent_response(
                     async_client,
@@ -1217,7 +1227,17 @@ class AgentClient(BaseClient):
                 ):
                     yield chunk
 
-        finally:
-            # Ensure cleanup - this is handled by the calling context
-            # but we keep this for safety in case of future changes
-            pass
+        async with _async_timeout_guard(http_timeout):
+            async for chunk in _chunk_stream():
+                yield chunk
+
+    @property
+    def runs(self) -> "AgentRunsClient":
+        """Get the agent runs client."""
+        if self._runs_client is None:
+            # Import here to avoid circular dependency with client.main
+            from glaip_sdk.client.main import _build_shared_config
+
+            shared_config = _build_shared_config(self)
+            self._runs_client = AgentRunsClient(**shared_config)
+        return self._runs_client

glaip_sdk/client/main.py

@@ -14,6 +14,23 @@ from glaip_sdk.client.tools import ToolClient
 from glaip_sdk.models import MCP, Agent, Tool
 
 
+def _build_shared_config(client: BaseClient) -> dict[str, Any]:
+    """Build shared configuration dictionary for sub-clients.
+
+    Args:
+        client: Base client instance.
+
+    Returns:
+        Dictionary with shared configuration.
+    """
+    return {
+        "parent_client": client,
+        "api_url": client.api_url,
+        "api_key": client.api_key,
+        "timeout": client._timeout,
+    }
+
+
 class Client(BaseClient):
     """Main client that composes all specialized clients and shares one HTTP session."""
 
@@ -25,12 +42,7 @@ class Client(BaseClient):
         """
         super().__init__(**kwargs)
         # Share the single httpx.Client + config with sub-clients
-        shared_config = {
-            "parent_client": self,
-            "api_url": self.api_url,
-            "api_key": self.api_key,
-            "timeout": self._timeout,
-        }
+        shared_config = _build_shared_config(self)
         self.agents = AgentClient(**shared_config)
         self.tools = ToolClient(**shared_config)
         self.mcps = MCPClient(**shared_config)

glaip_sdk/client/mcps.py

@@ -14,7 +14,7 @@ from glaip_sdk.config.constants import (
     DEFAULT_MCP_TYPE,
 )
 from glaip_sdk.models import MCP
-from glaip_sdk.utils.client_utils import create_model_instances, find_by_name
+from glaip_sdk.utils.client_utils import add_kwargs_to_payload, create_model_instances, find_by_name
 
 # API endpoints
 MCPS_ENDPOINT = "/mcps/"
@@ -147,9 +147,7 @@ class MCPClient(BaseClient):
 
         # Add any other kwargs (excluding already handled ones)
         excluded_keys = {"type"}  # type is handled above
-        for key, value in kwargs.items():
-            if key not in excluded_keys:
-                payload[key] = value
+        add_kwargs_to_payload(payload, kwargs, excluded_keys)
 
         return payload
 

glaip_sdk/client/tools.py

@@ -18,6 +18,7 @@ from glaip_sdk.config.constants import (
 )
 from glaip_sdk.models import Tool
 from glaip_sdk.utils.client_utils import (
+    add_kwargs_to_payload,
     create_model_instances,
     find_by_name,
 )
@@ -200,9 +201,7 @@ class ToolClient(BaseClient):
 
         # Add any other kwargs (excluding already handled ones)
         excluded_keys = {"tags", "version"}
-        for key, value in kwargs.items():
-            if key not in excluded_keys:
-                payload[key] = value
+        add_kwargs_to_payload(payload, kwargs, excluded_keys)
 
         return payload
 

glaip_sdk/config/constants.py

@@ -39,3 +39,14 @@ DEFAULT_MCP_TRANSPORT = "stdio"
 
 # Default error messages
 DEFAULT_ERROR_MESSAGE = "Unknown error"
+
+# Agent configuration fields used for CLI args and payload building
+AGENT_CONFIG_FIELDS = (
+    "name",
+    "instruction",
+    "model",
+    "tools",
+    "agents",
+    "mcps",
+    "timeout",
+)