glaip-sdk 0.6.15b2__py3-none-any.whl → 0.6.16__py3-none-any.whl

glaip_sdk/utils/rendering/renderer/config.py

@@ -0,0 +1,27 @@
+"""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."""
+
+    # Performance
+    refresh_debounce: float = 0.25
+    render_thinking: bool = True
+    live: bool = True
+    persist_live: bool = True
+    summary_display_window: int = 20
+
+    # Scrollback/append options
+    summary_max_steps: int = 0
+    append_finished_snapshots: bool = False
+    snapshot_max_chars: int = 0
+    snapshot_max_lines: int = 0

glaip_sdk/utils/rendering/renderer/console.py

@@ -0,0 +1,55 @@
+"""Console handling utilities for the renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Any
+
+from rich.console import Console as RichConsole
+
+
+class CapturingConsole:
+    """Console wrapper that captures all output for saving."""
+
+    def __init__(self, original_console: RichConsole, capture: bool = False) -> None:
+        """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: list[str] = []
+
+    def print(self, *args: Any, **kwargs: Any) -> None:
+        """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) -> str:
+        """Get the captured output as plain text."""
+        if self.capture:
+            return "".join(self.captured_output)
+        return ""
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate all other attributes to the original console."""
+        return getattr(self.original_console, name)

glaip_sdk/utils/rendering/renderer/debug.py

@@ -0,0 +1,178 @@
+"""Debug rendering utilities for verbose SSE event display.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import json
+from datetime import datetime, timezone
+from typing import Any
+from collections.abc import Callable, Iterable
+
+from rich.console import Console
+from rich.markdown import Markdown
+
+from glaip_sdk.branding import PRIMARY, SUCCESS, WARNING
+from glaip_sdk.rich_components import AIPPanel
+from glaip_sdk.utils.datetime_helpers import coerce_datetime
+
+
+def _parse_event_timestamp(event: dict[str, Any], received_ts: datetime | None = None) -> datetime | None:
+    """Resolve the most accurate timestamp available for the event."""
+    if received_ts is not None:
+        return received_ts if received_ts.tzinfo else received_ts.replace(tzinfo=timezone.utc)
+
+    ts_value = event.get("timestamp") or (event.get("metadata") or {}).get("timestamp")
+    return coerce_datetime(ts_value)
+
+
+def _format_timestamp_for_display(dt: datetime) -> str:
+    """Format timestamp for panel title, including timezone offset."""
+    local_dt = dt.astimezone()
+    ts_ms = local_dt.strftime("%H:%M:%S.%f")[:-3]
+    offset = local_dt.strftime("%z")
+    # offset is always non-empty for timezone-aware datetimes
+    offset = f"{offset[:3]}:{offset[3:]}"
+    return f"{ts_ms} {offset}"
+
+
+def _calculate_relative_time(
+    event_ts: datetime | None,
+    baseline_ts: datetime | None,
+) -> tuple[float, str]:
+    """Calculate relative time since start and format event timestamp."""
+    rel = 0.0
+
+    # Determine display timestamp - use event timestamp when present, otherwise current time
+    display_ts: datetime | None = event_ts
+    if display_ts is None:
+        display_ts = datetime.now(timezone.utc)
+
+    if event_ts is not None and baseline_ts is not None:
+        rel = max(0.0, (event_ts - baseline_ts).total_seconds())
+
+    ts_ms = _format_timestamp_for_display(display_ts)
+
+    return rel, ts_ms
+
+
+def _get_event_metadata(event: dict[str, Any]) -> tuple[str, str | None]:
+    """Extract event kind and status."""
+    sse_kind = (event.get("metadata") or {}).get("kind") or "event"
+    status_str = event.get("status") or (event.get("metadata") or {}).get("status")
+    return sse_kind, status_str
+
+
+def _build_debug_title(sse_kind: str, status_str: str | None, ts_ms: str, rel: float) -> str:
+    """Build the debug event title."""
+    if status_str:
+        return f"SSE: {sse_kind} — {status_str} @ {ts_ms} (+{rel:.2f}s)"
+    else:
+        return f"SSE: {sse_kind} @ {ts_ms} (+{rel:.2f}s)"
+
+
+def _dejson_value(obj: Any) -> Any:
+    """Deep-parse JSON strings in nested objects."""
+    if isinstance(obj, dict):
+        return {k: _dejson_value(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_dejson_value(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_value(json.loads(s))
+            except Exception:
+                return obj
+        return obj
+    return obj
+
+
+def _format_event_json(event: dict[str, Any]) -> str:
+    """Format event as JSON with deep parsing."""
+    try:
+        return json.dumps(_dejson_value(event), indent=2, ensure_ascii=False)
+    except Exception:
+        return str(event)
+
+
+def _get_border_color(sse_kind: str) -> str:
+    """Get border color for event type."""
+    border_map = {
+        "agent_step": PRIMARY,
+        "content": SUCCESS,
+        "final_response": SUCCESS,
+        "status": WARNING,
+        "artifact": "grey42",
+    }
+    return border_map.get(sse_kind, "grey42")
+
+
+def _create_debug_panel(title: str, event_json: str, border: str) -> AIPPanel:
+    """Create the debug panel."""
+    md = Markdown(f"```json\n{event_json}\n```", code_theme="monokai")
+    return AIPPanel(md, title=title, border_style=border)
+
+
+def render_debug_event(
+    event: dict[str, Any],
+    console: Console,
+    *,
+    received_ts: datetime | None = None,
+    baseline_ts: datetime | None = None,
+) -> None:
+    """Render a debug panel for an SSE event.
+
+    Args:
+        event: The SSE event data
+        console: Rich console to print to
+        received_ts: Client-side receipt timestamp, if available
+        baseline_ts: Baseline event timestamp for elapsed timing
+    """
+    try:
+        # Calculate timing information
+        event_ts = _parse_event_timestamp(event, received_ts)
+        rel, ts_ms = _calculate_relative_time(event_ts, baseline_ts)
+
+        # Extract event metadata
+        sse_kind, status_str = _get_event_metadata(event)
+
+        # Build title
+        title = _build_debug_title(sse_kind, status_str, ts_ms, rel)
+
+        # Format event JSON
+        event_json = _format_event_json(event)
+
+        # Get border color
+        border = _get_border_color(sse_kind)
+
+        # Create and print panel
+        panel = _create_debug_panel(title, event_json, border)
+        console.print(panel)
+
+    except Exception as e:
+        # Debug helpers must not break streaming
+        print(f"Debug error: {e}")  # Fallback debug output
+
+
+def render_debug_event_stream(
+    events: Iterable[dict[str, Any]],
+    console: Console,
+    *,
+    resolve_timestamp: Callable[[dict[str, Any]], datetime | None],
+) -> None:
+    """Render a sequence of SSE events with baseline-aware timestamps."""
+    baseline: datetime | None = None
+    for event in events:
+        try:
+            received_ts = resolve_timestamp(event)
+            if baseline is None and received_ts is not None:
+                baseline = received_ts
+            render_debug_event(
+                event,
+                console,
+                received_ts=received_ts,
+                baseline_ts=baseline,
+            )
+        except Exception as exc:  # pragma: no cover - debug stream resilience
+            console.print(f"[red]Debug stream error: {exc}[/red]")

glaip_sdk/utils/rendering/renderer/factory.py

@@ -0,0 +1,138 @@
+"""Renderer factory helpers for CLI, SDK, and slash sessions.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass, is_dataclass, replace
+from inspect import signature
+from typing import Any
+from collections.abc import Callable
+
+from rich.console import Console
+
+from glaip_sdk.utils.rendering.renderer.base import RichStreamRenderer
+from glaip_sdk.utils.rendering.renderer.config import RendererConfig
+from glaip_sdk.utils.rendering.state import TranscriptBuffer
+
+
+@dataclass(slots=True)
+class RendererFactoryOptions:
+    """Shared options for renderer factories."""
+
+    console: Console | None = None
+    cfg_overrides: dict[str, Any] | None = None
+    verbose: bool | None = None
+    transcript_buffer: TranscriptBuffer | None = None
+    callbacks: dict[str, Any] | None = None
+
+    def build(self, factory: Callable[..., RichStreamRenderer]) -> RichStreamRenderer:
+        """Instantiate a renderer using the provided factory and stored options."""
+        params = signature(factory).parameters
+        kwargs: dict[str, Any] = {}
+        if self.console is not None and "console" in params:
+            kwargs["console"] = self.console
+        if self.cfg_overrides is not None and "cfg_overrides" in params:
+            kwargs["cfg_overrides"] = self.cfg_overrides
+        if self.verbose is not None and "verbose" in params:
+            kwargs["verbose"] = self.verbose
+        if self.transcript_buffer is not None and "transcript_buffer" in params:
+            kwargs["transcript_buffer"] = self.transcript_buffer
+        if self.callbacks is not None and "callbacks" in params:
+            kwargs["callbacks"] = self.callbacks
+        return factory(**kwargs)
+
+
+def _build_config(base: RendererConfig, overrides: dict[str, Any] | None = None) -> RendererConfig:
+    cfg = replace(base) if is_dataclass(base) else base
+    if overrides:
+        for key, value in overrides.items():
+            if hasattr(cfg, key):
+                setattr(cfg, key, value)
+    return cfg
+
+
+def make_default_renderer(
+    *,
+    console: Console | None = None,
+    cfg_overrides: dict[str, Any] | None = None,
+    verbose: bool = False,
+    transcript_buffer: TranscriptBuffer | None = None,
+    callbacks: dict[str, Any] | None = None,
+) -> RichStreamRenderer:
+    """Create the default renderer used by SDK and CLI flows."""
+    cfg = _build_config(RendererConfig(), cfg_overrides)
+    return RichStreamRenderer(
+        console=console or Console(),
+        cfg=cfg,
+        verbose=verbose,
+        transcript_buffer=transcript_buffer,
+        callbacks=callbacks,
+    )
+
+
+def make_verbose_renderer(
+    *,
+    console: Console | None = None,
+    cfg_overrides: dict[str, Any] | None = None,
+    transcript_buffer: TranscriptBuffer | None = None,
+    callbacks: dict[str, Any] | None = None,
+) -> RichStreamRenderer:
+    """Create a verbose renderer with snapshot appending disabled."""
+    verbose_cfg = RendererConfig(live=True, append_finished_snapshots=False)
+    cfg = _build_config(verbose_cfg, cfg_overrides)
+    return RichStreamRenderer(
+        console=console or Console(),
+        cfg=cfg,
+        verbose=True,
+        transcript_buffer=transcript_buffer,
+        callbacks=callbacks,
+    )
+
+
+def make_minimal_renderer(
+    *,
+    console: Console | None = None,
+    cfg_overrides: dict[str, Any] | None = None,
+    transcript_buffer: TranscriptBuffer | None = None,
+    callbacks: dict[str, Any] | None = None,
+) -> RichStreamRenderer:
+    """Create a renderer that prints only essential output."""
+    minimal_cfg = RendererConfig(live=False, persist_live=False, render_thinking=False)
+    cfg = _build_config(minimal_cfg, cfg_overrides)
+    return RichStreamRenderer(
+        console=console or Console(),
+        cfg=cfg,
+        verbose=False,
+        transcript_buffer=transcript_buffer,
+        callbacks=callbacks,
+    )
+
+
+def make_silent_renderer(
+    *,
+    console: Console | None = None,
+    cfg_overrides: dict[str, Any] | None = None,
+    transcript_buffer: TranscriptBuffer | None = None,
+    callbacks: dict[str, Any] | None = None,
+) -> RichStreamRenderer:
+    """Create a renderer that suppresses terminal output for background flows."""
+    cfg = _build_config(
+        RendererConfig(
+            live=False,
+            persist_live=False,
+            render_thinking=False,
+        ),
+        cfg_overrides,
+    )
+    silent_console = console or Console(file=io.StringIO(), force_terminal=False)
+    return RichStreamRenderer(
+        console=silent_console,
+        cfg=cfg,
+        verbose=False,
+        transcript_buffer=transcript_buffer,
+        callbacks=callbacks,
+    )

glaip_sdk/utils/rendering/renderer/stream.py

@@ -0,0 +1,202 @@
+"""Event routing and parsing utilities for the renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from time import monotonic
+from typing import Any
+
+
+class StreamProcessor:
+    """Handles event routing and parsing for streaming agent execution."""
+
+    def __init__(self) -> None:
+        """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) -> None:
+        """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") or {}
+        # 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 event.get("kind"),
+            "task_id": metadata.get("task_id") or event.get("task_id"),
+            "context_id": metadata.get("context_id") or event.get("context_id"),
+            "content": event.get("content", ""),
+            "status": metadata.get("status") if metadata else event.get("status"),
+            "metadata": metadata,
+        }
+
+    def _extract_metadata_tool_calls(self, metadata: dict[str, Any]) -> tuple[str | None, dict, Any, list]:
+        """Extract tool calls from metadata."""
+        tool_calls = metadata.get("tool_calls", [])
+        if not tool_calls:
+            return None, {}, None, []
+
+        # 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
+        tool_calls_info = []
+        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"),
+                    )
+                )
+
+        return tool_name, tool_args, tool_out, tool_calls_info
+
+    def _extract_tool_info_calls(self, tool_info: dict[str, Any]) -> tuple[str | None, dict, Any, list]:
+        """Extract tool calls from tool_info structure."""
+        tool_calls_info = []
+        tool_name = None
+        tool_args = {}
+        tool_out = None
+
+        # 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:
+                tool_name, tool_args, tool_out = tool_calls_info[0]
+            return tool_name, tool_args, tool_out, tool_calls_info
+
+        # Case 2: single tool_info name/args/output
+        if tool_info.get("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 _extract_tool_calls_from_metadata(self, metadata: dict[str, Any]) -> tuple[str | None, dict, Any, list]:
+        """Extract tool calls from metadata structure."""
+        tool_info = metadata.get("tool_info", {}) or {}
+
+        if tool_info:
+            return self._extract_tool_info_calls(tool_info)
+
+        return None, {}, None, []
+
+    def parse_tool_calls(self, event: dict[str, Any]) -> tuple[str | None, Any, Any, list[tuple[str, Any, Any]]]:
+        """Parse tool call information from an event.
+
+        Args:
+            event: Event dictionary
+
+        Returns:
+            Tuple of (tool_name, tool_args, tool_output, tool_calls_info)
+        """
+        metadata = event.get("metadata", {})
+
+        # Try primary extraction method
+        tool_calls_result = self._extract_metadata_tool_calls(metadata)
+        tool_name, tool_args, tool_out, tool_calls_info = tool_calls_result
+
+        # Fallback to nested metadata.tool_info (newer schema)
+        if not tool_calls_info:
+            fallback_result = self._extract_tool_calls_from_metadata(metadata)
+            tool_name, tool_args, tool_out, tool_calls_info = fallback_result
+
+        return tool_name, tool_args, tool_out, tool_calls_info
+
+    def update_timing(self, context_id: str | None) -> 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 track_tools_and_agents(
+        self,
+        tool_name: str | None,
+        tool_calls_info: list[tuple[str, Any, Any]],
+        is_delegation_tool_func: Callable[[str], bool],
+    ) -> None:
+        """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()

glaip_sdk/utils/rendering/renderer/summary_window.py

@@ -0,0 +1,79 @@
+"""Helpers for clamping the steps summary view to a rolling window.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from rich.text import Text
+
+Node = tuple[str, tuple[bool, ...]]
+LabelFn = Callable[[str], str]
+ParentFn = Callable[[str], str | None]
+
+
+def clamp_step_nodes(
+    nodes: list[Node],
+    *,
+    window: int,
+    get_label: LabelFn,
+    get_parent: ParentFn,
+) -> tuple[list[Node], Text | None, Text | None]:
+    """Return a windowed slice of nodes plus optional header/footer notices."""
+    if window <= 0 or len(nodes) <= window:
+        return nodes, None, None
+
+    start_index = len(nodes) - window
+    first_visible_step_id = nodes[start_index][0]
+    header = _build_header(first_visible_step_id, window, len(nodes), get_label, get_parent)
+    footer = _build_footer(len(nodes) - window)
+    return nodes[start_index:], header, footer
+
+
+def _build_header(
+    step_id: str,
+    window: int,
+    total: int,
+    get_label: LabelFn,
+    get_parent: ParentFn,
+) -> Text:
+    """Construct the leading notice for a truncated window."""
+    parts = [f"… (latest {window} of {total} steps shown"]
+    path = _collect_path_labels(step_id, get_label, get_parent)
+    if path:
+        parts.append("; continuing with ")
+        parts.append(" / ".join(path))
+    parts.append(")")
+    return Text("".join(parts), style="dim")
+
+
+def _build_footer(hidden_count: int) -> Text:
+    """Construct the footer notice indicating hidden steps."""
+    noun = "step" if hidden_count == 1 else "steps"
+    message = f"{hidden_count} earlier {noun} hidden. Press Ctrl+T to inspect the full transcript."
+    return Text(message, style="dim")
+
+
+def _collect_path_labels(
+    step_id: str,
+    get_label: LabelFn,
+    get_parent: ParentFn,
+) -> list[str]:
+    """Collect labels for the ancestry of the provided step."""
+    labels: list[str] = []
+    seen: set[str] = set()
+    current = step_id
+    while current and current not in seen:
+        seen.add(current)
+        label = get_label(current)
+        if label:
+            labels.append(label)
+        parent = get_parent(current)
+        if not parent:
+            break
+        current = parent
+    labels.reverse()
+    return labels