glaip-sdk 0.0.7__py3-none-any.whl → 0.6.5b6__py3-none-any.whl

glaip_sdk/utils/rendering/renderer/config.py

@@ -13,21 +13,15 @@ from dataclasses import 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
+    summary_display_window: int = 20
 
     # Scrollback/append options
+    summary_max_steps: int = 0
     append_finished_snapshots: bool = False
-    snapshot_max_chars: int = 4000
-    snapshot_max_lines: int = 60
+    snapshot_max_chars: int = 0
+    snapshot_max_lines: int = 0

glaip_sdk/utils/rendering/renderer/debug.py

@@ -5,25 +5,53 @@ Authors:
 """
 
 import json
-from datetime import datetime
-from time import monotonic
+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 _calculate_relative_time(started_ts: float | None) -> tuple[float, str]:
-    """Calculate relative time since start."""
-    now_mono = monotonic()
+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
-    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
+    # 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
 
@@ -35,9 +63,7 @@ def _get_event_metadata(event: dict[str, Any]) -> tuple[str, str | None]:
     return sse_kind, status_str
 
 
-def _build_debug_title(
-    sse_kind: str, status_str: str | None, ts_ms: str, rel: float
-) -> 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)"
@@ -53,9 +79,7 @@ def _dejson_value(obj: Any) -> Any:
         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("]")
-        ):
+        if (s.startswith("{") and s.endswith("}")) or (s.startswith("[") and s.endswith("]")):
             try:
                 return _dejson_value(json.loads(s))
             except Exception:
@@ -75,10 +99,10 @@ def _format_event_json(event: dict[str, Any]) -> str:
 def _get_border_color(sse_kind: str) -> str:
     """Get border color for event type."""
     border_map = {
-        "agent_step": "blue",
-        "content": "green",
-        "final_response": "green",
-        "status": "yellow",
+        "agent_step": PRIMARY,
+        "content": SUCCESS,
+        "final_response": SUCCESS,
+        "status": WARNING,
         "artifact": "grey42",
     }
     return border_map.get(sse_kind, "grey42")
@@ -91,18 +115,24 @@ def _create_debug_panel(title: str, event_json: str, border: str) -> AIPPanel:
 
 
 def render_debug_event(
-    event: dict[str, Any], console: Console, started_ts: float | None = None
+    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
-        started_ts: Monotonic timestamp when streaming started
+        received_ts: Client-side receipt timestamp, if available
+        baseline_ts: Baseline event timestamp for elapsed timing
     """
     try:
         # Calculate timing information
-        rel, ts_ms = _calculate_relative_time(started_ts)
+        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)
@@ -123,3 +153,26 @@ def render_debug_event(
     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

@@ -38,27 +38,25 @@ class StreamProcessor:
         Returns:
             Dictionary with extracted metadata
         """
-        metadata = event.get("metadata", {})
+        metadata = event.get("metadata") or {}
         # Update server elapsed timing if backend provides it
         try:
             t = metadata.get("time")
-            if isinstance(t, int | float):
+            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": event.get("task_id"),
-            "context_id": event.get("context_id"),
+            "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]:
+    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:
@@ -84,9 +82,7 @@ class StreamProcessor:
 
         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]:
+    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
@@ -98,9 +94,7 @@ class StreamProcessor:
         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"))
-                    )
+                    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
@@ -114,9 +108,7 @@ class StreamProcessor:
 
         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]:
+    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 {}
 
@@ -125,9 +117,7 @@ class StreamProcessor:
 
         return None, {}, None, []
 
-    def parse_tool_calls(
-        self, event: dict[str, Any]
-    ) -> tuple[str | None, Any, Any, list[tuple[str, Any, Any]]]:
+    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:
@@ -139,21 +129,13 @@ class StreamProcessor:
         metadata = event.get("metadata", {})
 
         # Try primary extraction method
-        (
-            tool_name,
-            tool_args,
-            tool_out,
-            tool_calls_info,
-        ) = self._extract_metadata_tool_calls(metadata)
+        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:
-            (
-                tool_name,
-                tool_args,
-                tool_out,
-                tool_calls_info,
-            ) = self._extract_tool_calls_from_metadata(metadata)
+            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
 
@@ -166,29 +148,6 @@ class StreamProcessor:
         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,

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