glaip-sdk 0.6.15b2__py3-none-any.whl → 0.6.15b3__py3-none-any.whl

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",
+]

glaip_sdk/utils/rendering/layout/progress.py

@@ -0,0 +1,202 @@
+"""Progress and timing utilities for the renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from time import monotonic
+from typing import Any
+
+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:
+    """Return the current animated spinner character for visual feedback."""
+    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,
+    streaming_started_at: float | None,
+) -> float | None:
+    """Return the elapsed seconds using server data when available."""
+    if server_elapsed_time is not None and streaming_started_at is not None:
+        return server_elapsed_time
+    if started_at is None:
+        return None
+    try:
+        return monotonic() - started_at
+    except Exception:
+        return None
+
+
+def _format_elapsed_suffix(elapsed: float) -> str:
+    """Return formatting suffix for elapsed timing."""
+    if elapsed >= 1:
+        return f"{elapsed:.2f}s"
+    elapsed_ms = int(elapsed * 1000)
+    return f"{elapsed_ms}ms" if elapsed_ms > 0 else "<1ms"
+
+
+def format_working_indicator(
+    started_at: float | None,
+    server_elapsed_time: float | None = None,
+    streaming_started_at: float | None = None,
+) -> str:
+    """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):
+        return base_message
+
+    spinner_chip = f"{get_spinner_char()} {base_message}"
+    elapsed = _resolve_elapsed_time(started_at, server_elapsed_time, streaming_started_at)
+    if elapsed is None:
+        return spinner_chip
+
+    suffix = _format_elapsed_suffix(elapsed)
+    return f"{spinner_chip} ({suffix})"
+
+
+def format_elapsed_time(elapsed_seconds: float) -> str:
+    """Format elapsed time in a human-readable format.
+
+    Args:
+        elapsed_seconds: Time in seconds
+
+    Returns:
+        Formatted time string
+    """
+    if elapsed_seconds >= 60:
+        minutes = int(elapsed_seconds // 60)
+        seconds = elapsed_seconds % 60
+        return f"{minutes}m {seconds:.1f}s"
+    elif elapsed_seconds >= 1:
+        return f"{elapsed_seconds:.2f}s"
+    else:
+        ms = int(elapsed_seconds * 1000)
+        return f"{ms}ms" if ms > 0 else "<1ms"
+
+
+def is_delegation_tool(tool_name: str) -> bool:
+    """Check if a tool name indicates delegation functionality.
+
+    Args:
+        tool_name: The name of the tool to check
+
+    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()
+
+
+def _delegation_tool_title(tool_name: str) -> str | None:
+    """Return delegation-aware title or ``None`` when not applicable."""
+    if tool_name.startswith("delegate_to_"):
+        sub_agent_name = tool_name.replace("delegate_to_", "", 1)
+        return f"Sub-Agent: {sub_agent_name}"
+    if tool_name.startswith("delegate_"):
+        sub_agent_name = tool_name.replace("delegate_", "", 1)
+        return f"Sub-Agent: {sub_agent_name}"
+    return None
+
+
+def _strip_path_and_extension(tool_name: str) -> str:
+    """Return tool name without path segments or extensions."""
+    filename = tool_name.rsplit("/", 1)[-1]
+    base_name = filename.split(".", 1)[0]
+    return base_name
+
+
+def format_tool_title(tool_name: str) -> str:
+    """Format tool name for panel title display.
+
+    Args:
+        tool_name: The full tool name (may include file paths)
+
+    Returns:
+        Formatted title string suitable for panel display
+    """
+    # Check if this is a delegation tool
+    if is_delegation_tool(tool_name):
+        delegation_title = _delegation_tool_title(tool_name)
+        if delegation_title:
+            return delegation_title
+
+    # For regular tools, clean up the name
+    # Remove file path prefixes if present
+    clean_name = _strip_path_and_extension(tool_name)
+
+    # 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))