glaip-sdk 0.0.20__py3-none-any.whl → 0.7.7__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,11 +8,17 @@ from __future__ import annotations
 
 import json
 import re
-import time
 from collections.abc import Callable
 from typing import Any
 
-from glaip_sdk.icons import ICON_AGENT_STEP, ICON_DELEGATE, ICON_TOOL_STEP
+from glaip_sdk.icons import (
+    ICON_AGENT_STEP,
+    ICON_DELEGATE,
+    ICON_STATUS_FAILED,
+    ICON_STATUS_SUCCESS,
+    ICON_STATUS_WARNING,
+    ICON_TOOL_STEP,
+)
 
 # Constants for argument formatting
 DEFAULT_ARGS_MAX_LEN = 100
@@ -37,9 +43,15 @@ SECRET_VALUE_PATTERNS = [
     re.compile(r"eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+"),  # JWT tokens
 ]
 SENSITIVE_PATTERNS = re.compile(
-    r"password\s*[:=]\s*[^\s,}]+|secret\s*[:=]\s*[^\s,}]+|token\s*[:=]\s*[^\s,}]+|key\s*[:=]\s*[^\s,}]+|api_key\s*[:=]\s*[^\s,}]+|^password$|^secret$|^token$|^key$|^api_key$",
+    r"(?:password|secret|token|key|api_key)(?:\s*[:=]\s*[^\s,}]+)?",
     re.IGNORECASE,
 )
+SECRET_MASK = "••••••"
+STATUS_GLYPHS = {
+    "success": ICON_STATUS_SUCCESS,
+    "failed": ICON_STATUS_FAILED,
+    "warning": ICON_STATUS_WARNING,
+}
 
 
 def _truncate_string(s: str, max_len: int) -> str:
@@ -53,7 +65,7 @@ def mask_secrets_in_string(text: str) -> str:
     """Mask sensitive information in a string."""
     result = text
     for pattern in SECRET_VALUE_PATTERNS:
-        result = re.sub(pattern, "••••••", result)
+        result = re.sub(pattern, SECRET_MASK, result)
     return result
 
 
@@ -74,7 +86,7 @@ def _redact_dict_values(text: dict) -> dict:
     result = {}
     for key, value in text.items():
         if _is_sensitive_key(key):
-            result[key] = "••••••"
+            result[key] = SECRET_MASK
         elif _should_recurse_redaction(value):
             result[key] = redact_sensitive(value)
         else:
@@ -92,11 +104,11 @@ def _redact_string_content(text: str) -> str:
     result = text
     # First mask secrets
     for pattern in SECRET_VALUE_PATTERNS:
-        result = re.sub(pattern, "••••••", result)
+        result = re.sub(pattern, SECRET_MASK, result)
     # Then redact sensitive patterns
     result = re.sub(
         SENSITIVE_PATTERNS,
-        lambda m: m.group(0).split("=")[0] + "=••••••",
+        lambda m: m.group(0).split("=")[0] + "=" + SECRET_MASK,
         result,
     )
     return result
@@ -105,15 +117,28 @@ def _redact_string_content(text: str) -> str:
 def _is_sensitive_key(key: str) -> bool:
     """Check if a key contains sensitive information."""
     key_lower = key.lower()
-    return any(
-        sensitive in key_lower
-        for sensitive in ["password", "secret", "token", "key", "api_key"]
-    )
+    return any(sensitive in key_lower for sensitive in ["password", "secret", "token", "key", "api_key"])
 
 
 def _should_recurse_redaction(value: Any) -> bool:
     """Check if a value should be recursively processed."""
-    return isinstance(value, dict | list) or isinstance(value, str)
+    return isinstance(value, (dict, list)) or isinstance(value, str)
+
+
+def glyph_for_status(icon_key: str | None) -> str | None:
+    """Return glyph representing a step status icon key."""
+    if not icon_key:
+        return None
+    return STATUS_GLYPHS.get(icon_key)
+
+
+def normalise_display_label(label: str | None) -> str:
+    """Return a user facing label or the Unknown fallback."""
+    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:
@@ -132,7 +157,7 @@ def pretty_args(args: dict | None, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
     try:
         args_str = json.dumps(masked_args, ensure_ascii=False, separators=(",", ":"))
         return _truncate_string(args_str, max_len)
-    except (TypeError, ValueError, Exception):
+    except Exception:
         # Fallback to string representation if JSON serialization fails
         args_str = str(masked_args)
         return _truncate_string(args_str, max_len)
@@ -162,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
@@ -128,9 +129,7 @@ def create_context_panel(
     )
 
 
-def create_final_panel(
-    content: str, title: str = "Final Result", theme: str = "dark"
-) -> AIPPanel:
+def create_final_panel(content: str, title: str = "Final Result", theme: str = "dark") -> AIPPanel:
     """Create a final result panel.
 
     Args:
@@ -147,3 +146,11 @@ def create_final_panel(
         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,
@@ -48,15 +89,11 @@ def format_working_indicator(
     """Format a working indicator with elapsed time."""
     base_message = "Working..."
 
-    if started_at is None and (
-        server_elapsed_time is None or streaming_started_at is None
-    ):
+    if started_at is None and (server_elapsed_time is None or streaming_started_at is None):
         return base_message
 
     spinner_chip = f"{get_spinner_char()} {base_message}"
-    elapsed = _resolve_elapsed_time(
-        started_at, server_elapsed_time, streaming_started_at
-    )
+    elapsed = _resolve_elapsed_time(started_at, server_elapsed_time, streaming_started_at)
     if elapsed is None:
         return spinner_chip
 
@@ -93,11 +130,7 @@ def is_delegation_tool(tool_name: str) -> bool:
     Returns:
         True if this is a delegation tool
     """
-    return (
-        tool_name.startswith("delegate_to_")
-        or tool_name.startswith("delegate_")
-        or "sub_agent" in tool_name.lower()
-    )
+    return tool_name.startswith("delegate_to_") or tool_name.startswith("delegate_") or "sub_agent" in tool_name.lower()
 
 
 def _delegation_tool_title(tool_name: str) -> str | None:
@@ -139,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