glaip-sdk 0.0.7__py3-none-any.whl → 0.6.5b6__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

@@ -6,11 +6,20 @@ Authors:
 
 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_STATUS_FAILED,
+    ICON_STATUS_SUCCESS,
+    ICON_STATUS_WARNING,
+    ICON_TOOL_STEP,
+)
+
 # Constants for argument formatting
 DEFAULT_ARGS_MAX_LEN = 100
 IMPORTANT_PARAMETER_KEYS = [
@@ -34,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:
@@ -50,48 +65,82 @@ 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
 
 
 def redact_sensitive(text: str | dict | list) -> str | dict | list:
     """Redact sensitive information in a string, dict, or list."""
     if isinstance(text, dict):
-        # Recursively process dictionary values
-        result = {}
-        for key, value in text.items():
-            # Check if the key itself is sensitive
-            key_lower = key.lower()
-            if any(
-                sensitive in key_lower
-                for sensitive in ["password", "secret", "token", "key", "api_key"]
-            ):
-                result[key] = "••••••"
-            elif isinstance(value, dict | list) or isinstance(value, str):
-                result[key] = redact_sensitive(value)
-            else:
-                result[key] = value
-        return result
+        return _redact_dict_values(text)
     elif isinstance(text, list):
-        # Recursively process list items
-        return [redact_sensitive(item) for item in text]
+        return _redact_list_items(text)
     elif isinstance(text, str):
-        # Process string - first mask secrets, then redact sensitive patterns
-        result = text
-        # First mask secrets
-        for pattern in SECRET_VALUE_PATTERNS:
-            result = re.sub(pattern, "••••••", result)
-        # Then redact sensitive patterns
-        result = re.sub(
-            SENSITIVE_PATTERNS,
-            lambda m: m.group(0).split("=")[0] + "=••••••",
-            result,
-        )
-        return result
+        return _redact_string_content(text)
     else:
         return text
 
 
+def _redact_dict_values(text: dict) -> dict:
+    """Recursively process dictionary values and redact sensitive keys."""
+    result = {}
+    for key, value in text.items():
+        if _is_sensitive_key(key):
+            result[key] = SECRET_MASK
+        elif _should_recurse_redaction(value):
+            result[key] = redact_sensitive(value)
+        else:
+            result[key] = value
+    return result
+
+
+def _redact_list_items(text: list) -> list:
+    """Recursively process list items."""
+    return [redact_sensitive(item) for item in text]
+
+
+def _redact_string_content(text: str) -> str:
+    """Process string - first mask secrets, then redact sensitive patterns."""
+    result = text
+    # First mask secrets
+    for pattern in SECRET_VALUE_PATTERNS:
+        result = re.sub(pattern, SECRET_MASK, result)
+    # Then redact sensitive patterns
+    result = re.sub(
+        SENSITIVE_PATTERNS,
+        lambda m: m.group(0).split("=")[0] + "=" + SECRET_MASK,
+        result,
+    )
+    return result
+
+
+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"])
+
+
+def _should_recurse_redaction(value: Any) -> bool:
+    """Check if a value should be recursively processed."""
+    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:
     """Format arguments in a pretty way."""
     if not args:
@@ -106,11 +155,9 @@ def pretty_args(args: dict | None, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
 
     # Convert to JSON string and truncate if needed
     try:
-        import json
-
         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)
@@ -140,19 +187,14 @@ 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:
-    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":
-        return "⚙️"  # Gear emoji for tool
+        return ICON_TOOL_STEP
     if step_kind == "delegate":
-        return "🤝"  # Handshake for delegate
+        return ICON_DELEGATE
     if step_kind == "agent":
-        return "🧠"  # Brain emoji for agent
+        return ICON_AGENT_STEP
     return ""
 
 

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,12 +6,26 @@ Authors:
 
 from __future__ import annotations
 
+
+from rich.align import Align
 from rich.markdown import Markdown
+from rich.spinner import Spinner
 from rich.text import Text
 
+from glaip_sdk.branding import INFO, PRIMARY, SUCCESS, WARNING
 from glaip_sdk.rich_components import AIPPanel
 
 
+def _spinner_renderable(message: str = "Processing...") -> Align:
+    """Build a Rich spinner renderable for loading placeholders."""
+    spinner = Spinner(
+        "dots",
+        text=Text(f" {message}", style="dim"),
+        style=INFO,
+    )
+    return Align.left(spinner)
+
+
 def create_main_panel(content: str, title: str, theme: str = "dark") -> AIPPanel:
     """Create a main content panel.
 
@@ -27,15 +41,13 @@ def create_main_panel(content: str, title: str, theme: str = "dark") -> AIPPanel
         return AIPPanel(
             Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
             title=title,
-            border_style="green",
+            border_style=SUCCESS,
         )
     else:
-        # Placeholder panel
-        placeholder = Text("Processing...", style="dim")
         return AIPPanel(
-            placeholder,
+            _spinner_renderable(),
             title=title,
-            border_style="green",
+            border_style=SUCCESS,
         )
 
 
@@ -45,6 +57,8 @@ def create_tool_panel(
     status: str = "running",
     theme: str = "dark",
     is_delegation: bool = False,
+    *,
+    spinner_message: str | None = None,
 ) -> AIPPanel:
     """Create a tool execution panel.
 
@@ -54,19 +68,29 @@ def create_tool_panel(
         status: Tool execution status
         theme: Color theme
         is_delegation: Whether this is a delegation tool
+        spinner_message: Optional custom message to show alongside the spinner
 
     Returns:
         Rich Panel instance
     """
-    mark = "✓" if status == "finished" else "⟳"
-    border_style = "magenta" if is_delegation else "blue"
+    mark = "✓" if status == "finished" else ""
+    border_style = WARNING if is_delegation else PRIMARY
 
-    return AIPPanel(
-        Markdown(
-            content or "Processing...",
+    if content:
+        body_renderable = Markdown(
+            content,
             code_theme=("monokai" if theme == "dark" else "github"),
-        ),
-        title=f"{title}  {mark}",
+        )
+    elif status == "running":
+        body_renderable = _spinner_renderable(spinner_message or f"{title} running...")
+    else:
+        body_renderable = Text("No output yet.", style="dim")
+
+    title_text = f"{title}  {mark}".rstrip()
+
+    return AIPPanel(
+        body_renderable,
+        title=title_text,
         border_style=border_style,
     )
 
@@ -90,22 +114,22 @@ def create_context_panel(
     Returns:
         Rich Panel instance
     """
-    mark = "✓" if status == "finished" else "⟳"
-    border_style = "magenta" if is_delegation else "cyan"
+    mark = "✓" if status == "finished" else ""
+    border_style = WARNING if is_delegation else INFO
+
+    title_text = f"{title}  {mark}".rstrip()
 
     return AIPPanel(
         Markdown(
             content,
             code_theme=("monokai" if theme == "dark" else "github"),
         ),
-        title=f"{title}  {mark}",
+        title=title_text,
         border_style=border_style,
     )
 
 
-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:
@@ -119,6 +143,14 @@ def create_final_panel(
     return AIPPanel(
         Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
         title=title,
-        border_style="green",
+        border_style=SUCCESS,
         padding=(0, 1),
     )
+
+
+__all__ = [
+    "create_main_panel",
+    "create_tool_panel",
+    "create_context_panel",
+    "create_final_panel",
+]