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

glaip_sdk/cli/utils.py

@@ -12,15 +12,17 @@ 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
 
 import click
+import yaml
 from rich.console import Console, Group
 from rich.markdown import Markdown
-from rich.pretty import Pretty
+from rich.syntax import Syntax
 
 from glaip_sdk import _version as _version_module
 from glaip_sdk.branding import (
@@ -30,9 +32,195 @@ from glaip_sdk.branding import (
     SUCCESS_STYLE,
     WARNING_STYLE,
 )
-from glaip_sdk.cli.rich_helpers import markup_text
+from glaip_sdk.cli import masking, pager
+from glaip_sdk.cli.constants import LITERAL_STRING_THRESHOLD, TABLE_SORT_ENABLED
+from glaip_sdk.cli.config import load_config
+from glaip_sdk.cli.context import (
+    _get_view,
+    detect_export_format as _detect_export_format,
+    get_ctx_value,
+)
+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
+from glaip_sdk.rich_components import AIPPanel, AIPTable
+from glaip_sdk.utils import format_datetime, is_uuid
+from glaip_sdk.utils.rendering.renderer import (
+    CapturingConsole,
+    RendererConfig,
+    RichStreamRenderer,
+)
+
+
+@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."""
+
+
+def _literal_str_representer(dumper: yaml.Dumper, data: str) -> yaml.nodes.ScalarNode:
+    """Represent strings in YAML, using literal blocks for verbose values."""
+    needs_literal = "\n" in data or "\r" in data
+    if not needs_literal and LITERAL_STRING_THRESHOLD and len(data) >= LITERAL_STRING_THRESHOLD:  # pragma: no cover
+        needs_literal = True
+
+    style = "|" if needs_literal else None
+    return dumper.represent_scalar("tag:yaml.org,2002:str", data, style=style)
+
+
+_LiteralYamlDumper.add_representer(str, _literal_str_representer)
 
 # Optional interactive deps (fuzzy palette)
 try:
@@ -56,22 +244,6 @@ except Exception:  # pragma: no cover - optional dependency
 
 if TYPE_CHECKING:  # pragma: no cover - import-only during type checking
     from glaip_sdk import Client
-from glaip_sdk.cli import masking, pager
-from glaip_sdk.cli.config import load_config
-from glaip_sdk.cli.context import (
-    _get_view,
-    get_ctx_value,
-)
-from glaip_sdk.cli.context import (
-    detect_export_format as _detect_export_format,
-)
-from glaip_sdk.rich_components import AIPTable
-from glaip_sdk.utils import is_uuid
-from glaip_sdk.utils.rendering.renderer import (
-    CapturingConsole,
-    RendererConfig,
-    RichStreamRenderer,
-)
 
 console = Console()
 pager.console = console
@@ -144,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:
@@ -208,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
@@ -235,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[/]"),
@@ -329,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,
@@ -602,6 +792,7 @@ def _prompt_with_auto_select(
     valid_choices = set(choices)
 
     def _auto_select(_: Buffer) -> None:
+        """Auto-select text when a valid choice is entered."""
         text = buffer.text
         if not text or text not in valid_choices:
             return
@@ -635,9 +826,23 @@ class _FuzzyCompleter:
     """Fuzzy completer for prompt_toolkit."""
 
     def __init__(self, words: list[str]) -> None:
+        """Initialize fuzzy completer with word list.
+
+        Args:
+            words: List of words to complete from.
+        """
         self.words = words
 
     def get_completions(self, document: Any, _complete_event: Any) -> Any:  # pragma: no cover
+        """Get fuzzy completions for the current word.
+
+        Args:
+            document: Document object from prompt_toolkit.
+            _complete_event: Completion event (unused).
+
+        Yields:
+            Completion objects matching the current word.
+        """
         word = document.get_word_before_cursor()
         if not word:
             return
@@ -769,7 +974,7 @@ def _fuzzy_score(search: str, target: str) -> int:
     return score
 
 
-# ----------------------------- Pretty outputs ---------------------------- #
+# ----------------------- Structured renderer helpers -------------------- #
 
 
 def _coerce_result_payload(result: Any) -> Any:
@@ -811,6 +1016,37 @@ def _render_markdown_output(data: Any) -> None:
         click.echo(str(data))
 
 
+def _format_yaml_text(data: Any) -> str:
+    """Convert structured payloads to YAML for readability."""
+    try:
+        yaml_text = yaml.dump(
+            data,
+            sort_keys=False,
+            default_flow_style=False,
+            allow_unicode=True,
+            Dumper=_LiteralYamlDumper,
+        )
+    except Exception:  # pragma: no cover - defensive YAML fallback
+        try:
+            return str(data)
+        except Exception:  # pragma: no cover - defensive str fallback
+            return repr(data)
+
+    yaml_text = yaml_text.rstrip()
+    if yaml_text.endswith("..."):  # pragma: no cover - defensive YAML cleanup
+        yaml_text = yaml_text[:-3].rstrip()
+    return yaml_text
+
+
+def _build_yaml_renderable(data: Any) -> Any:
+    """Return a syntax-highlighted YAML renderable when possible."""
+    yaml_text = _format_yaml_text(data) or "# No data"
+    try:
+        return Syntax(yaml_text, "yaml", word_wrap=False)
+    except Exception:  # pragma: no cover - defensive syntax highlighting fallback
+        return yaml_text
+
+
 def output_result(
     ctx: Any,
     result: Any,
@@ -843,7 +1079,7 @@ def output_result(
         _render_markdown_output(data)
         return
 
-    renderable = Pretty(data)
+    renderable = _build_yaml_renderable(data)
     if panel_title:
         console.print(AIPPanel(renderable, title=panel_title))
     else:
@@ -854,7 +1090,7 @@ def output_result(
 # ----------------------------- List rendering ---------------------------- #
 
 # Threshold no longer used - fuzzy palette is always default for TTY
-# _PICK_THRESHOLD = int(os.getenv("AIP_PICK_THRESHOLD", "5") or "5")
+# _PICK_THRESHOLD = 5
 
 
 def _normalise_rows(items: list[Any], transform_func: Callable[[Any], dict[str, Any]] | None) -> list[dict[str, Any]]:
@@ -902,12 +1138,7 @@ def _render_markdown_list(rows: list[dict[str, Any]], title: str, columns: list[
 
 def _should_sort_rows(rows: list[dict[str, Any]]) -> bool:
     """Return True when rows should be name-sorted prior to rendering."""
-    return (
-        os.getenv("AIP_TABLE_NO_SORT", "0") not in ("1", "true", "on")
-        and rows
-        and isinstance(rows[0], dict)
-        and "name" in rows[0]
-    )
+    return TABLE_SORT_ENABLED and rows and isinstance(rows[0], dict) and "name" in rows[0]
 
 
 def _create_table(columns: list[tuple[str, str, str, int | None]], title: str) -> Any:

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_payloads.py

@@ -209,6 +209,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 +226,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 +248,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 +264,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 +289,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]
 
 

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)