glaip-sdk 0.1.2__py3-none-any.whl → 0.7.17__py3-none-any.whl

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":

glaip_sdk/utils/rendering/layout/__init__.py

@@ -0,0 +1,64 @@
+"""Layout utilities exposed for renderer/viewer consumers.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from glaip_sdk.utils.rendering.layout.panels import (
+    create_context_panel,
+    create_final_panel,
+    create_main_panel,
+    create_tool_panel,
+)
+from glaip_sdk.utils.rendering.layout.progress import (
+    TrailingSpinnerLine,
+    build_progress_footer,
+    format_elapsed_time,
+    format_tool_title,
+    format_working_indicator,
+    get_spinner,
+    get_spinner_char,
+    is_delegation_tool,
+)
+from glaip_sdk.utils.rendering.layout.transcript import (
+    DEFAULT_TRANSCRIPT_THEME,
+    TranscriptGlyphs,
+    TranscriptRow,
+    TranscriptSnapshot,
+    build_final_panel,
+    build_transcript_snapshot,
+    build_transcript_view,
+    extract_query_from_meta,
+    format_final_panel_title,
+    render_final_panel,
+)
+from glaip_sdk.utils.rendering.layout.summary import render_summary_panels
+
+__all__ = [
+    # Panels
+    "create_context_panel",
+    "create_final_panel",
+    "create_main_panel",
+    "create_tool_panel",
+    "render_summary_panels",
+    # Progress
+    "TrailingSpinnerLine",
+    "build_progress_footer",
+    "format_elapsed_time",
+    "format_tool_title",
+    "format_working_indicator",
+    "get_spinner",
+    "get_spinner_char",
+    "is_delegation_tool",
+    # Transcript
+    "DEFAULT_TRANSCRIPT_THEME",
+    "TranscriptGlyphs",
+    "TranscriptRow",
+    "TranscriptSnapshot",
+    "build_final_panel",
+    "build_transcript_snapshot",
+    "build_transcript_view",
+    "extract_query_from_meta",
+    "format_final_panel_title",
+    "render_final_panel",
+]

glaip_sdk/utils/rendering/{renderer → layout}/panels.py

@@ -6,6 +6,7 @@ Authors:
 
 from __future__ import annotations
 
+
 from rich.align import Align
 from rich.markdown import Markdown
 from rich.spinner import Spinner
@@ -145,3 +146,11 @@ def create_final_panel(content: str, title: str = "Final Result", theme: str = "
         border_style=SUCCESS,
         padding=(0, 1),
     )
+
+
+__all__ = [
+    "create_main_panel",
+    "create_tool_panel",
+    "create_context_panel",
+    "create_final_panel",
+]

glaip_sdk/utils/rendering/{renderer → layout}/progress.py

@@ -7,8 +7,22 @@ Authors:
 from __future__ import annotations
 
 from time import monotonic
+from typing import Any
 
-from glaip_sdk.utils.rendering.formatting import get_spinner_char
+from rich.console import Console as RichConsole
+from rich.console import Group
+from rich.measure import Measurement
+from rich.spinner import Spinner
+from rich.text import Text
+
+from glaip_sdk.utils.rendering.steps.manager import StepManager
+
+_SPINNER_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+
+def _spinner_time() -> float:
+    """Return the monotonic time used for spinner animation."""
+    return monotonic()
 
 
 def get_spinner() -> str:
@@ -16,6 +30,33 @@ def get_spinner() -> str:
     return get_spinner_char()
 
 
+def get_spinner_char() -> str:
+    """Return the spinner frame based on elapsed time."""
+    frame_index = int(_spinner_time() * 10) % len(_SPINNER_FRAMES)
+    return _SPINNER_FRAMES[frame_index]
+
+
+class TrailingSpinnerLine:
+    """Render a text line with a trailing animated Rich spinner."""
+
+    def __init__(self, base_text: Text, spinner: Spinner) -> None:
+        """Initialize spinner line with base text and spinner component."""
+        self._base_text = base_text
+        self._spinner = spinner
+
+    def __rich_console__(self, console: RichConsole, options: Any) -> Any:  # type: ignore[override]
+        """Render the text with trailing animated spinner."""
+        spinner_render = self._spinner.render(console.get_time())
+        combined = Text.assemble(self._base_text.copy(), " ", spinner_render)
+        yield combined
+
+    def __rich_measure__(self, console: RichConsole, options: Any) -> Measurement:  # type: ignore[override]
+        """Measure the combined text and spinner dimensions."""
+        snapshot = self._spinner.render(0)
+        combined = Text.assemble(self._base_text.copy(), " ", snapshot)
+        return Measurement.get(console, options, combined)
+
+
 def _resolve_elapsed_time(
     started_at: float | None,
     server_elapsed_time: float | None,
@@ -131,3 +172,31 @@ def format_tool_title(tool_name: str) -> str:
 
     # Convert snake_case to Title Case
     return clean_name.replace("_", " ").title()
+
+
+def _has_running_steps(steps: StepManager) -> bool:
+    for step in steps.by_id.values():
+        if getattr(step, "status", None) not in {"finished", "failed", "stopped"}:
+            return True
+    return False
+
+
+def build_progress_footer(
+    *,
+    state: Any,
+    steps: StepManager,
+    started_at: float | None,
+    server_elapsed_time: float | None,
+) -> Group | None:
+    """Return a trailing progress indicator when work is ongoing."""
+    if not _has_running_steps(steps):
+        return None
+
+    indicator = format_working_indicator(
+        started_at,
+        server_elapsed_time,
+        getattr(state, "streaming_started_at", None),
+    )
+    text = Text(indicator, style="dim")
+    spinner = Spinner("dots", style="dim")
+    return Group(TrailingSpinnerLine(text, spinner))

glaip_sdk/utils/rendering/layout/summary.py

@@ -0,0 +1,74 @@
+"""Summary panel helpers shared between renderer and viewer.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from glaip_sdk.utils.rendering.layout.transcript import (
+    DEFAULT_TRANSCRIPT_THEME,
+    build_transcript_snapshot,
+    build_transcript_view,
+    normalise_meta_payload,
+)
+from glaip_sdk.utils.rendering.state import RendererState
+from glaip_sdk.utils.rendering.steps import StepManager
+
+
+def render_summary_panels(
+    state: RendererState,
+    steps: StepManager,
+    *,
+    theme: str | None = None,
+    summary_window: int | None = None,
+    include_query_panel: bool = True,
+    include_final_panel: bool = True,
+    step_status_overrides: dict[str, str] | None = None,
+) -> list[Any]:
+    """Return shared summary panels for renderer and offline viewer."""
+    resolved_theme = theme or DEFAULT_TRANSCRIPT_THEME
+    snapshot_source = state.to_snapshot() if hasattr(state, "to_snapshot") else state
+    if isinstance(snapshot_source, Mapping):
+        raw_meta = snapshot_source.get("meta")
+    else:
+        raw_meta = getattr(state, "meta", None)
+    snapshot_meta = normalise_meta_payload(raw_meta)
+    snapshot = build_transcript_snapshot(
+        snapshot_source,
+        steps,
+        meta=snapshot_meta,
+        summary_window=summary_window,
+        theme=resolved_theme,
+        step_status_overrides=step_status_overrides,
+    )
+    _header, body = build_transcript_view(snapshot, theme=resolved_theme)
+
+    return [
+        renderable
+        for renderable in body
+        if _should_include_summary_panel(
+            renderable,
+            include_query_panel=include_query_panel,
+            include_final_panel=include_final_panel,
+        )
+    ]
+
+
+def _should_include_summary_panel(
+    renderable: Any,
+    *,
+    include_query_panel: bool,
+    include_final_panel: bool,
+) -> bool:
+    """Return True when the panel should be included in the summary list."""
+    title = getattr(renderable, "title", "")
+    normalised = title.lower() if isinstance(title, str) else ""
+    if not include_query_panel and normalised == "user request":
+        return False
+    if not include_final_panel and normalised.startswith("final result"):
+        return False
+    return True