glaip-sdk 0.0.0b99__py3-none-any.whl

glaip_sdk/utils/rendering/__init__.py

@@ -0,0 +1,115 @@
+"""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

@@ -0,0 +1,264 @@
+"""Formatting helpers for renderer.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+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 = [
+    "model",
+    "temperature",
+    "max_tokens",
+    "top_p",
+    "frequency_penalty",
+    "presence_penalty",
+    "query",
+    "url",
+]
+SECRET_VALUE_PATTERNS = [
+    re.compile(r"sk-[a-zA-Z0-9]{20,}"),  # OpenAI API keys (at least 20 chars)
+    re.compile(r"ya29\.[a-zA-Z0-9_-]+"),  # Google OAuth tokens
+    re.compile(r"ghp_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"gho_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"ghu_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"ghs_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"ghr_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+"),  # JWT tokens
+]
+SENSITIVE_PATTERNS = re.compile(
+    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:
+    """Truncate a string to a maximum length."""
+    if len(s) <= max_len:
+        return s
+    return s[: max_len - 3] + "…"
+
+
+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, 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):
+        return _redact_dict_values(text)
+    elif isinstance(text, list):
+        return _redact_list_items(text)
+    elif isinstance(text, str):
+        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:
+        return "{}"
+
+    # Mask secrets first by recursively processing the structure
+    try:
+        masked_args = redact_sensitive(args)
+    except Exception:
+        # Fallback to original args if redact_sensitive fails
+        masked_args = args
+
+    # Convert to JSON string and truncate if needed
+    try:
+        args_str = json.dumps(masked_args, ensure_ascii=False, separators=(",", ":"))
+        return _truncate_string(args_str, max_len)
+    except Exception:
+        # Fallback to string representation if JSON serialization fails
+        args_str = str(masked_args)
+        return _truncate_string(args_str, max_len)
+
+
+def pretty_out(output: any, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
+    """Format output in a pretty way."""
+    if output is None:
+        return "None"
+
+    if isinstance(output, str):
+        # Mask secrets in string output
+        masked_output = mask_secrets_in_string(output)
+
+        # Remove LaTeX commands (common math expressions)
+        masked_output = re.sub(r"\\[a-zA-Z]+\{[^}]*\}", "", masked_output)
+        masked_output = re.sub(r"\\[a-zA-Z]+", "", masked_output)
+
+        # Strip leading/trailing whitespace but preserve internal spacing
+        masked_output = masked_output.strip()
+        # Replace newlines with spaces to preserve formatting
+        masked_output = masked_output.replace("\n", " ")
+        return _truncate_string(masked_output, max_len)
+
+    # For other types, convert to string and truncate
+    output_str = str(output)
+    return _truncate_string(output_str, max_len)
+
+
+def get_step_icon(step_kind: str) -> str:
+    """Get the appropriate icon for a step kind."""
+    if step_kind == "tool":
+        return ICON_TOOL_STEP
+    if step_kind == "delegate":
+        return ICON_DELEGATE
+    if step_kind == "agent":
+        return ICON_AGENT_STEP
+    return ""
+
+
+def is_step_finished(step: Any) -> bool:
+    """Check if a step is finished.
+
+    Args:
+        step: The step object to check
+
+    Returns:
+        True if the step status is "finished", False otherwise
+    """
+    return getattr(step, "status", None) == "finished"
+
+
+def format_main_title(
+    header_text: str,
+    has_running_steps: bool,
+    get_spinner_char: Callable[[], str],
+) -> str:
+    """Generate the main panel title with dynamic status indicators.
+
+    Args:
+        header_text: The header text from the renderer
+        has_running_steps: Whether there are running steps
+        get_spinner_char: Function to get spinner character
+
+    Returns:
+        A formatted title string showing the agent name and status.
+    """
+    # base name
+    name = (header_text or "").strip() or "Assistant"
+    # strip leading rule emojis if present
+    name = name.replace("—", " ").strip()
+    # spinner if still working
+    mark = "✓" if not has_running_steps else get_spinner_char()
+    return f"{name}  {mark}"
+
+
+def print_header_once(
+    console: Any,
+    text: str,
+    last_header: str,
+    rules_enabled: bool,
+    style: str | None = None,
+) -> str:
+    """Print header text only when it changes to avoid duplicate output.
+
+    Args:
+        console: Rich console instance
+        text: The header text to display
+        last_header: The last header text that was printed
+        rules_enabled: Whether header rules are enabled
+        style: Optional Rich style for the header rule
+
+    Returns:
+        The updated last_header value
+    """
+    if not rules_enabled:
+        return text
+    if text and text != last_header:
+        try:
+            console.rule(text, style=style)
+        except Exception:
+            console.print(text)
+        return text
+    return last_header

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/layout/panels.py

@@ -0,0 +1,156 @@
+"""Panel rendering utilities for the renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+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.
+
+    Args:
+        content: The content to display
+        title: Panel title
+        theme: Color theme ("dark" or "light")
+
+    Returns:
+        Rich Panel instance
+    """
+    if content.strip():
+        return AIPPanel(
+            Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
+            title=title,
+            border_style=SUCCESS,
+        )
+    else:
+        return AIPPanel(
+            _spinner_renderable(),
+            title=title,
+            border_style=SUCCESS,
+        )
+
+
+def create_tool_panel(
+    title: str,
+    content: str,
+    status: str = "running",
+    theme: str = "dark",
+    is_delegation: bool = False,
+    *,
+    spinner_message: str | None = None,
+) -> AIPPanel:
+    """Create a tool execution panel.
+
+    Args:
+        title: Tool name/title
+        content: Tool output content
+        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 = WARNING if is_delegation else PRIMARY
+
+    if content:
+        body_renderable = Markdown(
+            content,
+            code_theme=("monokai" if theme == "dark" else "github"),
+        )
+    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,
+    )
+
+
+def create_context_panel(
+    title: str,
+    content: str,
+    status: str = "running",
+    theme: str = "dark",
+    is_delegation: bool = False,
+) -> AIPPanel:
+    """Create a context/sub-agent panel.
+
+    Args:
+        title: Context title
+        content: Context content
+        status: Execution status
+        theme: Color theme
+        is_delegation: Whether this is a delegation context
+
+    Returns:
+        Rich Panel instance
+    """
+    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=title_text,
+        border_style=border_style,
+    )
+
+
+def create_final_panel(content: str, title: str = "Final Result", theme: str = "dark") -> AIPPanel:
+    """Create a final result panel.
+
+    Args:
+        content: Final result content
+        title: Panel title
+        theme: Color theme
+
+    Returns:
+        Rich Panel instance
+    """
+    return AIPPanel(
+        Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
+        title=title,
+        border_style=SUCCESS,
+        padding=(0, 1),
+    )
+
+
+__all__ = [
+    "create_main_panel",
+    "create_tool_panel",
+    "create_context_panel",
+    "create_final_panel",
+]