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

glaip_sdk/models/agent_runs.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Agent run models for AIP SDK.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from datetime import datetime, timedelta
+from typing import Any, Literal
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+# Type alias for SSE event dictionaries
+RunOutputChunk = dict[str, Any]
+
+
+class RunSummary(BaseModel):
+    """Represents a single agent run in list/table views with metadata only."""
+
+    id: UUID
+    agent_id: UUID
+    run_type: Literal["manual", "schedule"]
+    schedule_id: UUID | None = None
+    status: Literal["started", "success", "failed", "cancelled", "aborted", "unavailable"]
+    started_at: datetime
+    completed_at: datetime | None = None
+    input: str | None = None
+    config: dict[str, Any] | None = None
+    created_at: datetime
+    updated_at: datetime
+
+    @field_validator("completed_at")
+    @classmethod
+    def validate_completed_after_started(cls, v: datetime | None, info) -> datetime | None:
+        """Validate that completed_at is after started_at if present."""
+        if v is not None and "started_at" in info.data:
+            started_at = info.data["started_at"]
+            if v < started_at:
+                raise ValueError("completed_at must be after started_at")
+        return v
+
+    def duration(self) -> timedelta | None:
+        """Calculate duration from started_at to completed_at.
+
+        Returns:
+            Duration as timedelta if completed_at exists, None otherwise
+        """
+        if self.completed_at is not None:
+            return self.completed_at - self.started_at
+        return None
+
+    def duration_formatted(self) -> str:
+        """Format duration as HH:MM:SS string.
+
+        Returns:
+            Formatted duration string or "—" if not completed
+        """
+        duration = self.duration()
+        if duration is None:
+            return "—"
+        total_seconds = int(duration.total_seconds())
+        hours = total_seconds // 3600
+        minutes = (total_seconds % 3600) // 60
+        seconds = total_seconds % 60
+        return f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+
+    def input_preview(self, max_length: int = 120) -> str:
+        """Generate truncated input preview for table display.
+
+        Args:
+            max_length: Maximum length of preview string
+
+        Returns:
+            Truncated input string or "—" if input is None or empty
+        """
+        if not self.input:
+            return "—"
+        # Strip newlines and collapse whitespace
+        preview = " ".join(self.input.split())
+        if len(preview) > max_length:
+            return preview[:max_length] + "…"
+        return preview
+
+
+class RunsPage(BaseModel):
+    """Represents a paginated collection of run summaries from the list endpoint."""
+
+    data: list[RunSummary]
+    total: int = Field(ge=0)
+    page: int = Field(ge=1)
+    limit: int = Field(ge=1, le=100)
+    has_next: bool
+    has_prev: bool
+
+    @model_validator(mode="after")
+    def validate_pagination_consistency(self) -> "RunsPage":
+        """Validate pagination consistency."""
+        # If has_next is True, then page * limit < total
+        if self.has_next and self.page * self.limit >= self.total:
+            raise ValueError("has_next inconsistency: page * limit must be < total when has_next is True")
+        return self
+
+
+class RunWithOutput(RunSummary):
+    """Extends RunSummary with the complete SSE event stream for detailed viewing."""
+
+    output: list[RunOutputChunk] = Field(default_factory=list)
+
+    @field_validator("output", mode="before")
+    @classmethod
+    def normalize_output(cls, v: Any) -> list[RunOutputChunk]:
+        """Normalize output field to empty list when null."""
+        if v is None:
+            return []
+        return v

glaip_sdk/models.py

@@ -23,21 +23,22 @@ class Agent(BaseModel):
     id: str
     name: str
     instruction: str | None = None
-    description: str | None = None  # Add missing description field
+    description: str | None = None
     type: str | None = None
     framework: str | None = None
     version: str | None = None
-    tools: list[dict[str, Any]] | None = None  # Backend returns ToolReference objects
-    agents: list[dict[str, Any]] | None = None  # Backend returns AgentReference objects
-    mcps: list[dict[str, Any]] | None = None  # Backend returns MCPReference objects
-    tool_configs: dict[str, Any] | None = None  # Backend returns tool configurations keyed by tool UUID
+    tools: list[dict[str, Any]] | None = None
+    agents: list[dict[str, Any]] | None = None
+    mcps: list[dict[str, Any]] | None = None
+    tool_configs: dict[str, Any] | None = None
+    mcp_configs: dict[str, Any] | None = None
     agent_config: dict[str, Any] | None = None
     timeout: int = DEFAULT_AGENT_RUN_TIMEOUT
     metadata: dict[str, Any] | None = None
     language_model_id: str | None = None
     a2a_profile: dict[str, Any] | None = None
-    created_at: datetime | None = None  # Backend returns creation timestamp
-    updated_at: datetime | None = None  # Backend returns last update timestamp
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
     _client: Any = None
 
     def _set_client(self, client: Any) -> "Agent":

glaip_sdk/rich_components.py

@@ -1,10 +1,15 @@
-"""Custom Rich components with copy-friendly defaults."""
+"""Custom Rich components with copy-friendly defaults.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
 
 from __future__ import annotations
 
 from rich import box
 from rich.panel import Panel
 from rich.table import Table
+from rich.text import Text
 
 
 class AIPPanel(Panel):
@@ -66,4 +71,55 @@ class AIPGrid(Table):
         )
 
 
-__all__ = ["AIPPanel", "AIPTable", "AIPGrid"]
+class RemoteRunsTable(AIPTable):
+    """Rich Table for displaying remote agent runs with pagination support."""
+
+    def __init__(self, *args, **kwargs):
+        """Initialize RemoteRunsTable with columns for run display.
+
+        Args:
+            *args: Positional arguments passed to AIPTable
+            **kwargs: Keyword arguments passed to AIPTable
+        """
+        kwargs.setdefault("row_styles", ("dim", "none"))
+        kwargs.setdefault("show_header", True)
+        super().__init__(*args, **kwargs)
+        # Add columns for run display
+        self.add_column("", width=2, no_wrap=True)  # Selection gutter
+        self.add_column("Run UUID", style="cyan", width=36, no_wrap=True)
+        self.add_column("Type", style="yellow", width=8, no_wrap=True)
+        self.add_column("Status", style="magenta", width=12, no_wrap=True)
+        self.add_column("Started (UTC)", style="dim", width=20, no_wrap=True)
+        self.add_column("Completed (UTC)", style="dim", width=20, no_wrap=True)
+        self.add_column("Duration", style="green", width=10, no_wrap=True)
+        self.add_column("Input Preview", style="white", width=40, overflow="ellipsis")
+
+    def add_run_row(
+        self,
+        run_uuid: str,
+        run_type: str,
+        status: str,
+        started: str,
+        completed: str,
+        duration: str,
+        preview: str,
+        *,
+        selected: bool = False,
+    ) -> None:
+        """Append a run row with optional selection styling."""
+        gutter = Text("› ", style="bold bright_cyan") if selected else Text("  ")
+        row_style = "reverse" if selected else None
+        self.add_row(
+            gutter,
+            run_uuid,
+            run_type,
+            status,
+            started,
+            completed,
+            duration,
+            preview,
+            style=row_style,
+        )
+
+
+__all__ = ["AIPPanel", "AIPTable", "AIPGrid", "RemoteRunsTable"]

glaip_sdk/utils/client_utils.py

@@ -426,6 +426,19 @@ def _prepare_stream_entry(
     )
 
 
+def add_kwargs_to_payload(payload: dict[str, Any], kwargs: dict[str, Any], excluded_keys: set[str]) -> None:
+    """Add kwargs to payload excluding specified keys.
+
+    Args:
+        payload: Payload dictionary to update.
+        kwargs: Keyword arguments to add.
+        excluded_keys: Keys to exclude from kwargs.
+    """
+    for key, value in kwargs.items():
+        if key not in excluded_keys:
+            payload[key] = value
+
+
 def prepare_multipart_data(message: str, files: list[str | BinaryIO]) -> MultipartData:
     """Prepare multipart form data for file uploads.
 

glaip_sdk/utils/display.py

@@ -4,6 +4,9 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+from __future__ import annotations
+
+from importlib import import_module
 from typing import TYPE_CHECKING, Any
 
 from glaip_sdk.branding import SUCCESS, SUCCESS_STYLE
@@ -13,42 +16,47 @@ if TYPE_CHECKING:  # pragma: no cover - import-time typing helpers
     from rich.console import Console
     from rich.text import Text
 
-    from glaip_sdk.rich_components import AIPPanel
+    from glaip_sdk.rich_components import AIPanel
+else:  # pragma: no cover - runtime fallback for type checking
+    AIPanel = Any  # type: ignore[assignment]
 
 
 def _check_rich_available() -> bool:
-    """Check if Rich and our custom components can be imported."""
+    """Return True when core Rich display dependencies are importable."""
     try:
         __import__("rich.console")
         __import__("rich.text")
         __import__("glaip_sdk.rich_components")
-        return True
     except Exception:
         return False
+    return True
 
 
 RICH_AVAILABLE = _check_rich_available()
 
 
-def _create_console() -> "Console":
+def _create_console() -> Console:
     """Return a Console instance with lazy import to ease mocking."""
-    from rich.console import Console  # Local import for test friendliness
-
-    return Console()
+    if not RICH_AVAILABLE:  # pragma: no cover - defensive guard
+        raise RuntimeError("Rich Console is not available")
+    console_module = import_module("rich.console")
+    return console_module.Console()
 
 
-def _create_text(*args: Any, **kwargs: Any) -> "Text":
+def _create_text(*args: Any, **kwargs: Any) -> Text:
     """Return a Text instance with lazy import to ease mocking."""
-    from rich.text import Text  # Local import for test friendliness
+    if not RICH_AVAILABLE:  # pragma: no cover - defensive guard
+        raise RuntimeError("Rich Text is not available")
+    text_module = import_module("rich.text")
+    return text_module.Text(*args, **kwargs)
 
-    return Text(*args, **kwargs)
 
-
-def _create_panel(*args: Any, **kwargs: Any) -> "AIPPanel":
+def _create_panel(*args: Any, **kwargs: Any) -> AIPanel:
     """Return an AIPPanel instance with lazy import to ease mocking."""
-    from glaip_sdk.rich_components import AIPPanel  # Local import for test friendliness
-
-    return AIPPanel(*args, **kwargs)
+    if not RICH_AVAILABLE:  # pragma: no cover - defensive guard
+        raise RuntimeError("AIPPanel is not available")
+    components = import_module("glaip_sdk.rich_components")
+    return components.AIPPanel(*args, **kwargs)
 
 
 def print_agent_output(output: str, title: str = "Agent Output") -> None:

glaip_sdk/utils/export.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Export utilities for remote agent run transcripts.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from glaip_sdk.models.agent_runs import RunWithOutput, RunOutputChunk
+
+
+def export_remote_transcript_jsonl(
+    run: RunWithOutput,
+    destination: Path,
+    *,
+    overwrite: bool = False,
+    agent_name: str | None = None,
+    model: str | None = None,
+) -> Path:
+    """Export a remote run transcript to JSONL format compatible with local transcript viewers.
+
+    Args:
+        run: RunWithOutput instance to export
+        destination: Target file path for JSONL export
+        overwrite: Whether to overwrite existing file
+        agent_name: Optional agent name for metadata
+        model: Optional model name for metadata (extracted from run.config if not provided)
+
+    Returns:
+        Path to the exported file
+
+    Raises:
+        FileExistsError: If destination exists and overwrite is False
+        OSError: If file cannot be written
+    """
+    if destination.exists() and not overwrite:
+        raise FileExistsError(f"File already exists: {destination}")
+
+    # Ensure parent directory exists
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    model_name = model or _extract_model(run)
+    final_output_text = _extract_final_output(run.output) or ""
+
+    meta_payload = _build_meta_payload(run, agent_name, model_name)
+    meta_record = _build_meta_record(run, agent_name, model_name, final_output_text, meta_payload)
+
+    _write_jsonl_file(destination, meta_record, run.output)
+
+    return destination
+
+
+def _build_meta_payload(run: RunWithOutput, agent_name: str | None, model_name: str | None) -> dict[str, Any]:
+    """Build the meta payload dictionary."""
+    return {
+        "agent_name": agent_name,
+        "model": model_name,
+        "input_message": run.input,
+        "status": run.status,
+        "run_type": run.run_type,
+        "schedule_id": str(run.schedule_id) if run.schedule_id else None,
+        "config": run.config or {},
+        "created_at": run.created_at.isoformat() if run.created_at else None,
+        "updated_at": run.updated_at.isoformat() if run.updated_at else None,
+        "event_count": len(run.output),
+    }
+
+
+def _build_meta_record(
+    run: RunWithOutput,
+    agent_name: str | None,
+    model_name: str | None,
+    final_output_text: str,
+    meta_payload: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the meta record dictionary."""
+    return {
+        "type": "meta",
+        "run_id": str(run.id),
+        "agent_id": str(run.agent_id),
+        "agent_name": agent_name,
+        "model": model_name,
+        "created_at": run.created_at.isoformat() if run.created_at else None,
+        "default_output": final_output_text,
+        "final_output": final_output_text,
+        "server_run_id": str(run.id),
+        "started_at": run.started_at.isoformat() if run.started_at else None,
+        "finished_at": run.completed_at.isoformat() if run.completed_at else None,
+        "meta": meta_payload,
+        "source": "remote_history",
+        # Back-compat fields used by older tooling
+        "run_type": run.run_type,
+        "schedule_id": str(run.schedule_id) if run.schedule_id else None,
+        "status": run.status,
+        "input": run.input,
+        "config": run.config or {},
+        "updated_at": run.updated_at.isoformat() if run.updated_at else None,
+    }
+
+
+def _write_jsonl_file(destination: Path, meta_record: dict[str, Any], events: list[RunOutputChunk]) -> None:
+    """Write the JSONL file with meta and event records."""
+    records: list[dict[str, Any]] = [meta_record]
+    records.extend({"type": "event", "event": event} for event in events)
+
+    with destination.open("w", encoding="utf-8") as fh:
+        for idx, record in enumerate(records):
+            json.dump(record, fh, ensure_ascii=False, indent=2, default=_json_default)
+            fh.write("\n")
+            if idx != len(records) - 1:
+                fh.write("\n")
+
+
+def _extract_model(run: RunWithOutput) -> str | None:
+    """Best-effort extraction of the model name from run metadata."""
+    config = run.config or {}
+    if isinstance(config, dict):
+        model = config.get("model") or config.get("llm", {}).get("model")
+        if isinstance(model, str):
+            return model
+    return None
+
+
+def _extract_final_output(events: list[RunOutputChunk]) -> str | None:
+    """Return the final response content from the event stream."""
+    for chunk in reversed(events):
+        content = chunk.get("content")
+        if not content:
+            continue
+        if chunk.get("event_type") == "final_response" or chunk.get("final"):
+            return str(content)
+    return None
+
+
+def _json_default(obj: Any) -> Any:
+    """JSON serializer for datetime objects."""
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    raise TypeError(f"Type {type(obj)} not serializable")

glaip_sdk/utils/import_export.py

@@ -9,8 +9,10 @@ Authors:
 
 from typing import Any
 
+from glaip_sdk.utils.resource_refs import _extract_id_from_item
 
-def extract_ids_from_export(items: list[Any]) -> list[str]:  # pylint: disable=duplicate-code
+
+def extract_ids_from_export(items: list[Any]) -> list[str]:
     """Extract IDs from export format (list of dicts with id/name fields).
 
     This function is similar to `extract_ids` in `resource_refs.py` but differs in behavior:
@@ -36,14 +38,9 @@ def extract_ids_from_export(items: list[Any]) -> list[str]:  # pylint: disable=d
 
     ids = []
     for item in items:
-        if isinstance(item, str):
-            ids.append(item)
-        elif hasattr(item, "id"):
-            ids.append(str(item.id))
-        elif isinstance(item, dict) and "id" in item:
-            ids.append(str(item["id"]))
-        # Skip items without ID (don't convert to string)
-        # Note: This differs from extract_ids() in resource_refs.py which converts all items to strings
+        extracted = _extract_id_from_item(item, skip_missing=True)
+        if extracted is not None:
+            ids.append(extracted)
 
     return ids
 

glaip_sdk/utils/rendering/__init__.py

@@ -1 +1,115 @@
-"""Rendering utilities package (formatting, models, steps, debug)."""
+"""Rendering utilities package (formatting, models, steps, debug).
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from datetime import datetime
+from typing import Any
+
+from rich.console import Console
+
+from glaip_sdk.models.agent_runs import RunWithOutput
+from glaip_sdk.utils.rendering.renderer.debug import render_debug_event, render_debug_event_stream
+
+
+def _parse_event_received_timestamp(event: dict[str, Any]) -> datetime | None:
+    """Parse received_at timestamp from SSE event.
+
+    Args:
+        event: SSE event dictionary
+
+    Returns:
+        Parsed datetime or None if not available
+    """
+    received_at = event.get("received_at")
+    if not received_at:
+        return None
+
+    if isinstance(received_at, datetime):
+        return received_at
+
+    if isinstance(received_at, str):
+        try:
+            # Try ISO format first
+            return datetime.fromisoformat(received_at.replace("Z", "+00:00"))
+        except ValueError:
+            try:
+                # Try common formats
+                return datetime.strptime(received_at, "%Y-%m-%dT%H:%M:%S.%fZ")
+            except ValueError:
+                return None
+
+    return None
+
+
+def render_remote_sse_transcript(
+    run: RunWithOutput,
+    console: Console,
+    *,
+    show_metadata: bool = True,
+) -> None:
+    """Render remote SSE transcript events for a RunWithOutput.
+
+    Args:
+        run: RunWithOutput instance containing events
+        console: Rich console to render to
+        show_metadata: Whether to show run metadata summary
+    """
+    if show_metadata:
+        # Render metadata summary
+        console.print(f"[bold]Run: {run.id}[/bold]")
+        console.print(f"[dim]Agent: {run.agent_id}[/dim]")
+        console.print(f"[dim]Status: {run.status}[/dim]")
+        console.print(f"[dim]Type: {run.run_type}[/dim]")
+        if run.schedule_id:
+            console.print(f"[dim]Schedule ID: {run.schedule_id}[/dim]")
+        else:
+            console.print("[dim]Schedule: —[/dim]")
+        console.print(f"[dim]Started: {run.started_at.isoformat()}[/dim]")
+        if run.completed_at:
+            console.print(f"[dim]Completed: {run.completed_at.isoformat()}[/dim]")
+            console.print(f"[dim]Duration: {run.duration_formatted()}[/dim]")
+        console.print()
+
+    # Render events
+    if not run.output:
+        console.print("[dim]No SSE events available for this run.[/dim]")
+        return
+
+    console.print("[bold]SSE Events[/bold]")
+    console.print("[dim]────────────────────────────────────────────────────────[/dim]")
+
+    render_debug_event_stream(
+        run.output,
+        console,
+        resolve_timestamp=_parse_event_received_timestamp,
+    )
+    console.print()
+
+
+class RemoteSSETranscriptRenderer:
+    """Renderer for remote SSE transcripts from RunWithOutput."""
+
+    def __init__(self, console: Console | None = None):
+        """Initialize the renderer.
+
+        Args:
+            console: Rich console instance (creates default if None)
+        """
+        self.console = console or Console()
+
+    def render(self, run: RunWithOutput, *, show_metadata: bool = True) -> None:
+        """Render a remote run transcript.
+
+        Args:
+            run: RunWithOutput instance to render
+            show_metadata: Whether to show run metadata summary
+        """
+        render_remote_sse_transcript(run, self.console, show_metadata=show_metadata)
+
+
+__all__ = [
+    "render_remote_sse_transcript",
+    "RemoteSSETranscriptRenderer",
+]

glaip_sdk/utils/rendering/formatting.py

@@ -8,7 +8,6 @@ from __future__ import annotations
 
 import json
 import re
-import time
 from collections.abc import Callable
 from typing import Any
 
@@ -47,11 +46,6 @@ SENSITIVE_PATTERNS = re.compile(
     r"(?:password|secret|token|key|api_key)(?:\s*[:=]\s*[^\s,}]+)?",
     re.IGNORECASE,
 )
-CONNECTOR_VERTICAL = "│   "
-CONNECTOR_EMPTY = "    "
-CONNECTOR_BRANCH = "├─ "
-CONNECTOR_LAST = "└─ "
-ROOT_MARKER = ""
 SECRET_MASK = "••••••"
 STATUS_GLYPHS = {
     "success": ICON_STATUS_SUCCESS,
@@ -140,20 +134,11 @@ def glyph_for_status(icon_key: str | None) -> str | None:
 
 def normalise_display_label(label: str | None) -> str:
     """Return a user facing label or the Unknown fallback."""
-    label = (label or "").strip()
-    return label or "Unknown step detail"
-
-
-def build_connector_prefix(branch_state: tuple[bool, ...]) -> str:
-    """Build connector prefix for a tree line based on ancestry state."""
-    if not branch_state:
-        return ROOT_MARKER
-
-    parts: list[str] = []
-    for ancestor_is_last in branch_state[:-1]:
-        parts.append(CONNECTOR_EMPTY if ancestor_is_last else CONNECTOR_VERTICAL)
-    parts.append(CONNECTOR_LAST if branch_state[-1] else CONNECTOR_BRANCH)
-    return "".join(parts)
+    if not isinstance(label, str):
+        text = ""
+    else:
+        text = label.strip()
+    return text or "Unknown step detail"
 
 
 def pretty_args(args: dict | None, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
@@ -202,16 +187,6 @@ def pretty_out(output: any, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
     return _truncate_string(output_str, max_len)
 
 
-def get_spinner_char() -> str:
-    """Get the next character for a spinner animation.
-
-    Returns:
-        A single character from the spinner frames based on current time
-    """
-    frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
-    return frames[int(time.time() * 10) % len(frames)]
-
-
 def get_step_icon(step_kind: str) -> str:
     """Get the appropriate icon for a step kind."""
     if step_kind == "tool":