glaip-sdk 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

glaip_sdk/utils/rendering/renderer/config.py

@@ -0,0 +1,33 @@
+"""Configuration types for the renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class RendererConfig:
+    """Configuration for the RichStreamRenderer."""
+
+    # Style and layout
+    theme: str = "dark"  # dark|light
+    style: str = "pretty"  # pretty|debug|minimal
+
+    # Performance
+    think_threshold: float = 0.7
+    refresh_debounce: float = 0.25
+    render_thinking: bool = True
+    live: bool = True
+    persist_live: bool = True
+
+    # Debug visibility toggles
+    show_delegate_tool_panels: bool = False
+
+    # Scrollback/append options
+    append_finished_snapshots: bool = False
+    snapshot_max_chars: int = 4000
+    snapshot_max_lines: int = 60

glaip_sdk/utils/rendering/renderer/console.py

@@ -0,0 +1,54 @@
+"""Console handling utilities for the renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import io
+
+from rich.console import Console as RichConsole
+
+
+class CapturingConsole:
+    """Console wrapper that captures all output for saving."""
+
+    def __init__(self, original_console, capture=False):
+        """Initialize the capturing console.
+
+        Args:
+            original_console: The original Rich console instance
+            capture: Whether to capture output in addition to displaying it
+        """
+        self.original_console = original_console
+        self.capture = capture
+        self.captured_output = []
+
+    def print(self, *args, **kwargs):
+        """Print to both original console and capture buffer if capturing."""
+        # Always print to original console
+        self.original_console.print(*args, **kwargs)
+
+        if self.capture:
+            # Capture the output as text
+            # Create a temporary console to capture output
+            temp_output = io.StringIO()
+            temp_console = RichConsole(
+                file=temp_output,
+                width=self.original_console.size.width,
+                legacy_windows=False,
+                force_terminal=False,
+            )
+            temp_console.print(*args, **kwargs)
+            self.captured_output.append(temp_output.getvalue())
+
+    def get_captured_output(self):
+        """Get the captured output as plain text."""
+        if self.capture:
+            return "".join(self.captured_output)
+        return ""
+
+    def __getattr__(self, name):
+        """Delegate all other attributes to the original console."""
+        return getattr(self.original_console, name)

glaip_sdk/utils/rendering/renderer/debug.py

@@ -0,0 +1,82 @@
+"""Debug rendering utilities for verbose SSE event display.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import json
+from datetime import datetime
+from time import monotonic
+from typing import Any
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+
+def render_debug_event(
+    event: dict[str, Any], console: Console, started_ts: float | None = None
+) -> None:
+    """Render a debug panel for an SSE event.
+
+    Args:
+        event: The SSE event data
+        console: Rich console to print to
+        started_ts: Monotonic timestamp when streaming started
+    """
+    try:
+        # Add relative time since first meaningful event and wall-clock stamp
+        now_mono = monotonic()
+        rel = 0.0
+        if started_ts is not None:
+            rel = max(0.0, now_mono - started_ts)
+        ts_full = datetime.now().strftime("%H:%M:%S.%f")
+        ts_ms = ts_full[:-3]  # trim to milliseconds
+
+        # Compose a descriptive title with kind/status
+        sse_kind = (event.get("metadata") or {}).get("kind") or "event"
+        status_str = event.get("status") or (event.get("metadata") or {}).get("status")
+        title = (
+            f"SSE: {sse_kind} — {status_str} @ {ts_ms} (+{rel:.2f}s)"
+            if status_str
+            else f"SSE: {sse_kind} @ {ts_ms} (+{rel:.2f}s)"
+        )
+
+        # Deep-pretty the event by parsing nested JSON strings
+        def _dejson(obj):
+            if isinstance(obj, dict):
+                return {k: _dejson(v) for k, v in obj.items()}
+            if isinstance(obj, list):
+                return [_dejson(x) for x in obj]
+            if isinstance(obj, str):
+                s = obj.strip()
+                if (s.startswith("{") and s.endswith("}")) or (
+                    s.startswith("[") and s.endswith("]")
+                ):
+                    try:
+                        return _dejson(json.loads(s))
+                    except Exception:
+                        return obj
+                return obj
+            return obj
+
+        try:
+            event_json = json.dumps(_dejson(event), indent=2, ensure_ascii=False)
+        except Exception:
+            event_json = str(event)
+
+        # Choose border color by kind for readability
+        border = {
+            "agent_step": "blue",
+            "content": "green",
+            "final_response": "green",
+            "status": "yellow",
+            "artifact": "grey42",
+        }.get(sse_kind, "grey42")
+
+        # Render using Markdown with JSON code block (consistent with tool panels)
+        md = Markdown(f"```json\n{event_json}\n```", code_theme="monokai")
+        console.print(Panel(md, title=title, border_style=border))
+    except Exception as e:
+        # Debug helpers must not break streaming
+        print(f"Debug error: {e}")  # Fallback debug output

glaip_sdk/utils/rendering/renderer/panels.py

@@ -0,0 +1,123 @@
+"""Panel rendering utilities for the renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.text import Text
+
+
+def create_main_panel(content: str, title: str, theme: str = "dark") -> Panel:
+    """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 Panel(
+            Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
+            title=title,
+            border_style="green",
+        )
+    else:
+        # Placeholder panel
+        placeholder = Text("Processing...", style="dim")
+        return Panel(
+            placeholder,
+            title=title,
+            border_style="green",
+        )
+
+
+def create_tool_panel(
+    title: str,
+    content: str,
+    status: str = "running",
+    theme: str = "dark",
+    is_delegation: bool = False,
+) -> Panel:
+    """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
+
+    Returns:
+        Rich Panel instance
+    """
+    mark = "✓" if status == "finished" else "⟳"
+    border_style = "magenta" if is_delegation else "blue"
+
+    return Panel(
+        Markdown(
+            content or "Processing...",
+            code_theme=("monokai" if theme == "dark" else "github"),
+        ),
+        title=f"{title}  {mark}",
+        border_style=border_style,
+    )
+
+
+def create_context_panel(
+    title: str,
+    content: str,
+    status: str = "running",
+    theme: str = "dark",
+    is_delegation: bool = False,
+) -> Panel:
+    """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 = "magenta" if is_delegation else "cyan"
+
+    return Panel(
+        Markdown(
+            content,
+            code_theme=("monokai" if theme == "dark" else "github"),
+        ),
+        title=f"{title}  {mark}",
+        border_style=border_style,
+    )
+
+
+def create_final_panel(
+    content: str, title: str = "Final Result", theme: str = "dark"
+) -> Panel:
+    """Create a final result panel.
+
+    Args:
+        content: Final result content
+        title: Panel title
+        theme: Color theme
+
+    Returns:
+        Rich Panel instance
+    """
+    return Panel(
+        Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
+        title=title,
+        border_style="green",
+        padding=(0, 1),
+    )

glaip_sdk/utils/rendering/renderer/progress.py

@@ -0,0 +1,118 @@
+"""Progress and timing utilities for the renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from time import monotonic
+
+from glaip_sdk.utils.rendering.formatting import get_spinner_char
+
+
+def get_spinner() -> str:
+    """Return the current animated spinner character for visual feedback."""
+    return get_spinner_char()
+
+
+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.
+
+    Args:
+        started_at: Timestamp when work started, or None
+        server_elapsed_time: Server-reported elapsed time if available
+        streaming_started_at: When streaming started
+
+    Returns:
+        Formatted working indicator string with elapsed time
+    """
+    chip = "Working..."
+
+    # Use server timing if available (more accurate)
+    if server_elapsed_time is not None and streaming_started_at is not None:
+        elapsed = server_elapsed_time
+    elif started_at:
+        try:
+            elapsed = monotonic() - started_at
+        except Exception:
+            return chip
+    else:
+        return chip
+
+    if elapsed >= 1:
+        chip = f"Working... ({elapsed:.2f}s)"
+    else:
+        elapsed_ms = int(elapsed * 1000)
+        chip = f"Working... ({elapsed_ms}ms)" if elapsed_ms > 0 else "Working... (<1ms)"
+    return chip
+
+
+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 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):
+        # Extract the sub-agent name from delegation tool names
+        if tool_name.startswith("delegate_to_"):
+            sub_agent_name = tool_name.replace("delegate_to_", "")
+            return f"Sub-Agent: {sub_agent_name}"
+        elif tool_name.startswith("delegate_"):
+            sub_agent_name = tool_name.replace("delegate_", "")
+            return f"Sub-Agent: {sub_agent_name}"
+
+    # For regular tools, clean up the name
+    # Remove file path prefixes if present
+    if "/" in tool_name:
+        tool_name = tool_name.split("/")[-1]
+    if "." in tool_name:
+        tool_name = tool_name.split(".")[0]
+
+    # Convert snake_case to Title Case
+    return tool_name.replace("_", " ").title()

glaip_sdk/utils/rendering/renderer/stream.py

@@ -0,0 +1,198 @@
+"""Event routing and parsing utilities for the renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from time import monotonic
+from typing import Any
+
+
+class StreamProcessor:
+    """Handles event routing and parsing for streaming agent execution."""
+
+    def __init__(self):
+        """Initialize the stream processor."""
+        self.streaming_started_at: float | None = None
+        self.server_elapsed_time: float | None = None
+        self.current_event_tools: set[str] = set()
+        self.current_event_sub_agents: set[str] = set()
+        self.current_event_finished_panels: set[str] = set()
+        self.last_event_time_by_ctx: dict[str, float] = {}
+
+    def reset_event_tracking(self):
+        """Reset tracking for the current event."""
+        self.current_event_tools.clear()
+        self.current_event_sub_agents.clear()
+        self.current_event_finished_panels.clear()
+
+    def extract_event_metadata(self, event: dict[str, Any]) -> dict[str, Any]:
+        """Extract metadata from an event.
+
+        Args:
+            event: Event dictionary
+
+        Returns:
+            Dictionary with extracted metadata
+        """
+        metadata = event.get("metadata", {})
+        # Update server elapsed timing if backend provides it
+        try:
+            t = metadata.get("time")
+            if isinstance(t, int | float):
+                self.server_elapsed_time = float(t)
+        except Exception:
+            pass
+
+        return {
+            "kind": metadata.get("kind") if metadata else None,
+            "task_id": event.get("task_id"),
+            "context_id": event.get("context_id"),
+            "content": event.get("content", ""),
+            "status": metadata.get("status") if metadata else event.get("status"),
+            "metadata": metadata,
+        }
+
+    def parse_tool_calls(
+        self, event: dict[str, Any]
+    ) -> tuple[str | None, Any, Any, list]:
+        """Parse tool call information from an event.
+
+        Args:
+            event: Event dictionary
+
+        Returns:
+            Tuple of (tool_name, tool_args, tool_output, tool_calls_info)
+        """
+        tool_name = None
+        tool_args = {}
+        tool_out = None
+        tool_calls_info = []
+
+        # Extract tool information from metadata
+        metadata = event.get("metadata", {})
+        tool_calls = metadata.get("tool_calls", [])
+
+        if tool_calls:
+            # Take the first tool call if multiple exist
+            first_call = tool_calls[0] if isinstance(tool_calls, list) else tool_calls
+            tool_name = first_call.get("name")
+            tool_args = first_call.get("arguments", {})
+            tool_out = first_call.get("output")
+
+            # Collect info for all tool calls
+            for call in tool_calls if isinstance(tool_calls, list) else [tool_calls]:
+                if isinstance(call, dict) and "name" in call:
+                    tool_calls_info.append(
+                        (
+                            call.get("name", ""),
+                            call.get("arguments", {}),
+                            call.get("output"),
+                        )
+                    )
+
+        # Fallback to nested metadata.tool_info (newer schema)
+        if not tool_calls_info:
+            tool_info = metadata.get("tool_info", {}) or {}
+            # Case 1: tool_info.tool_calls
+            ti_calls = tool_info.get("tool_calls")
+            if isinstance(ti_calls, list) and ti_calls:
+                for call in ti_calls:
+                    if isinstance(call, dict) and call.get("name"):
+                        tool_calls_info.append(
+                            (call.get("name"), call.get("args", {}), call.get("output"))
+                        )
+                if tool_calls_info and not tool_name:
+                    tool_name, tool_args, tool_out = tool_calls_info[0]
+            # Case 2: single tool_info name/args/output
+            if tool_info.get("name") and not tool_name:
+                tool_name = tool_info.get("name")
+                tool_args = tool_info.get("args", {})
+                tool_out = tool_info.get("output")
+                tool_calls_info.append((tool_name, tool_args, tool_out))
+
+        return tool_name, tool_args, tool_out, tool_calls_info
+
+    def update_timing(self, context_id: str | None):
+        """Update timing information for the given context.
+
+        Args:
+            context_id: Context identifier
+        """
+        if context_id:
+            self.last_event_time_by_ctx[context_id] = monotonic()
+
+    def should_insert_thinking_gap(
+        self, task_id: str | None, context_id: str | None, think_threshold: float
+    ) -> bool:
+        """Determine if a thinking gap should be inserted.
+
+        Args:
+            task_id: Task identifier
+            context_id: Context identifier
+            think_threshold: Threshold for thinking gap
+
+        Returns:
+            True if thinking gap should be inserted
+        """
+        if not task_id or not context_id:
+            return False
+
+        last_time = self.last_event_time_by_ctx.get(context_id)
+        if last_time is None:
+            return True
+
+        elapsed = monotonic() - last_time
+        return elapsed >= think_threshold
+
+    def track_tools_and_agents(
+        self, tool_name: str | None, tool_calls_info: list, is_delegation_tool_func
+    ):
+        """Track tools and sub-agents mentioned in the current event.
+
+        Args:
+            tool_name: Primary tool name
+            tool_calls_info: List of tool call information
+            is_delegation_tool_func: Function to check if tool is delegation
+        """
+        # Track all tools mentioned in this event
+        if tool_name:
+            self.current_event_tools.add(tool_name)
+            # If it's a delegation tool, add the sub-agent name
+            if is_delegation_tool_func(tool_name):
+                sub_agent_name = self._extract_sub_agent_name(tool_name)
+                self.current_event_sub_agents.add(sub_agent_name)
+
+        if tool_calls_info:
+            for tool_call_name, _, _ in tool_calls_info:
+                self.current_event_tools.add(tool_call_name)
+                # If it's a delegation tool, add the sub-agent name
+                if is_delegation_tool_func(tool_call_name):
+                    sub_agent_name = self._extract_sub_agent_name(tool_call_name)
+                    self.current_event_sub_agents.add(sub_agent_name)
+
+    def _extract_sub_agent_name(self, tool_name: str) -> str:
+        """Extract sub-agent name from delegation tool name.
+
+        Args:
+            tool_name: Delegation tool name
+
+        Returns:
+            Sub-agent name
+        """
+        if tool_name.startswith("delegate_to_"):
+            return tool_name.replace("delegate_to_", "")
+        elif tool_name.startswith("delegate_"):
+            return tool_name.replace("delegate_", "")
+        else:
+            return tool_name
+
+    def get_current_event_tools(self) -> set[str]:
+        """Get the set of tools mentioned in the current event."""
+        return self.current_event_tools.copy()
+
+    def get_current_event_sub_agents(self) -> set[str]:
+        """Get the set of sub-agents mentioned in the current event."""
+        return self.current_event_sub_agents.copy()