glaip-sdk 0.0.19__py3-none-any.whl → 0.0.20__py3-none-any.whl

glaip_sdk/utils/display.py

@@ -4,9 +4,51 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from glaip_sdk.utils.rich_utils import RICH_AVAILABLE
+from glaip_sdk.branding import SUCCESS, SUCCESS_STYLE
+from glaip_sdk.icons import ICON_AGENT
+
+if TYPE_CHECKING:  # pragma: no cover - import-time typing helpers
+    from rich.console import Console
+    from rich.text import Text
+
+    from glaip_sdk.rich_components import AIPPanel
+
+
+def _check_rich_available() -> bool:
+    """Check if Rich and our custom components can be imported."""
+    try:
+        __import__("rich.console")
+        __import__("rich.text")
+        __import__("glaip_sdk.rich_components")
+        return True
+    except Exception:
+        return False
+
+
+RICH_AVAILABLE = _check_rich_available()
+
+
+def _create_console() -> "Console":
+    """Return a Console instance with lazy import to ease mocking."""
+    from rich.console import Console  # Local import for test friendliness
+
+    return Console()
+
+
+def _create_text(*args: Any, **kwargs: Any) -> "Text":
+    """Return a Text instance with lazy import to ease mocking."""
+    from rich.text import Text  # Local import for test friendliness
+
+    return Text(*args, **kwargs)
+
+
+def _create_panel(*args: Any, **kwargs: Any) -> "AIPPanel":
+    """Return an AIPPanel instance with lazy import to ease mocking."""
+    from glaip_sdk.rich_components import AIPPanel  # Local import for test friendliness
+
+    return AIPPanel(*args, **kwargs)
 
 
 def print_agent_output(output: str, title: str = "Agent Output") -> None:
@@ -17,17 +59,11 @@ def print_agent_output(output: str, title: str = "Agent Output") -> None:
         title: Title for the output panel
     """
     if RICH_AVAILABLE:
-        # Lazy import Rich components
-        from rich.console import Console
-        from rich.text import Text
-
-        from glaip_sdk.rich_components import AIPPanel
-
-        console = Console()
-        panel = AIPPanel(
-            Text(output, style="green"),
+        console = _create_console()
+        panel = _create_panel(
+            _create_text(output, style=SUCCESS),
             title=title,
-            border_style="green",
+            border_style=SUCCESS,
         )
         console.print(panel)
     else:
@@ -36,7 +72,7 @@ def print_agent_output(output: str, title: str = "Agent Output") -> None:
         print("=" * (len(title) + 8))
 
 
-def print_agent_created(agent: Any, title: str = "🤖 Agent Created") -> None:
+def print_agent_created(agent: Any, title: str = f"{ICON_AGENT} Agent Created") -> None:
     """Print agent creation success with rich formatting.
 
     Args:
@@ -44,21 +80,16 @@ def print_agent_created(agent: Any, title: str = "🤖 Agent Created") -> None:
         title: Title for the output panel
     """
     if RICH_AVAILABLE:
-        # Lazy import Rich components
-        from rich.console import Console
-
-        from glaip_sdk.rich_components import AIPPanel
-
-        console = Console()
-        panel = AIPPanel(
-            f"[green]✅ Agent '{agent.name}' created successfully![/green]\n\n"
+        console = _create_console()
+        panel = _create_panel(
+            f"[{SUCCESS_STYLE}]✅ Agent '{agent.name}' created successfully![/]\n\n"
             f"ID: {agent.id}\n"
             f"Model: {getattr(agent, 'model', 'N/A')}\n"
             f"Type: {getattr(agent, 'type', 'config')}\n"
             f"Framework: {getattr(agent, 'framework', 'langchain')}\n"
             f"Version: {getattr(agent, 'version', '1.0')}",
             title=title,
-            border_style="green",
+            border_style=SUCCESS,
         )
         console.print(panel)
     else:
@@ -77,11 +108,10 @@ def print_agent_updated(agent: Any) -> None:
         agent: The updated agent object
     """
     if RICH_AVAILABLE:
-        # Lazy import Rich components
-        from rich.console import Console
-
-        console = Console()
-        console.print(f"[green]✅ Agent '{agent.name}' updated successfully[/green]")
+        console = _create_console()
+        console.print(
+            f"[{SUCCESS_STYLE}]✅ Agent '{agent.name}' updated successfully[/]"
+        )
     else:
         print(f"✅ Agent '{agent.name}' updated successfully")
 
@@ -93,10 +123,9 @@ def print_agent_deleted(agent_id: str) -> None:
         agent_id: The deleted agent's ID
     """
     if RICH_AVAILABLE:
-        # Lazy import Rich components
-        from rich.console import Console
-
-        console = Console()
-        console.print(f"[green]✅ Agent deleted successfully (ID: {agent_id})[/green]")
+        console = _create_console()
+        console.print(
+            f"[{SUCCESS_STYLE}]✅ Agent deleted successfully (ID: {agent_id})[/]"
+        )
     else:
         print(f"✅ Agent deleted successfully (ID: {agent_id})")

glaip_sdk/utils/rendering/formatting.py

@@ -6,11 +6,14 @@ Authors:
 
 from __future__ import annotations
 
+import json
 import re
 import time
 from collections.abc import Callable
 from typing import Any
 
+from glaip_sdk.icons import ICON_AGENT_STEP, ICON_DELEGATE, ICON_TOOL_STEP
+
 # Constants for argument formatting
 DEFAULT_ARGS_MAX_LEN = 100
 IMPORTANT_PARAMETER_KEYS = [
@@ -127,8 +130,6 @@ def pretty_args(args: dict | None, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
 
     # Convert to JSON string and truncate if needed
     try:
-        import json
-
         args_str = json.dumps(masked_args, ensure_ascii=False, separators=(",", ":"))
         return _truncate_string(args_str, max_len)
     except (TypeError, ValueError, Exception):
@@ -174,11 +175,11 @@ def get_spinner_char() -> str:
 def get_step_icon(step_kind: str) -> str:
     """Get the appropriate icon for a step kind."""
     if step_kind == "tool":
-        return "⚙️"  # Gear emoji for tool
+        return ICON_TOOL_STEP
     if step_kind == "delegate":
-        return "🤝"  # Handshake for delegate
+        return ICON_DELEGATE
     if step_kind == "agent":
-        return "🧠"  # Brain emoji for agent
+        return ICON_AGENT_STEP
     return ""
 
 

glaip_sdk/utils/rendering/renderer/base.py

@@ -8,16 +8,20 @@ from __future__ import annotations
 
 import json
 import logging
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from time import monotonic
 from typing import Any
 
+from rich.align import Align
 from rich.console import Console as RichConsole
 from rich.console import Group
 from rich.live import Live
 from rich.markdown import Markdown
+from rich.spinner import Spinner
 from rich.text import Text
 
+from glaip_sdk.icons import ICON_AGENT, ICON_AGENT_STEP, ICON_DELEGATE, ICON_TOOL_STEP
 from glaip_sdk.rich_components import AIPPanel
 from glaip_sdk.utils.rendering.formatting import (
     format_main_title,
@@ -49,6 +53,25 @@ logger = logging.getLogger("glaip_sdk.run_renderer")
 LESS_THAN_1MS = "[<1ms]"
 
 
+def _coerce_received_at(value: Any) -> datetime | None:
+    """Coerce a received_at value to an aware datetime if possible."""
+    if value is None:
+        return None
+
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+
+    if isinstance(value, str):
+        try:
+            normalised = value.replace("Z", "+00:00")
+            dt = datetime.fromisoformat(normalised)
+        except ValueError:
+            return None
+        return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+    return None
+
+
 @dataclass
 class RendererState:
     """Internal state for the renderer."""
@@ -56,10 +79,13 @@ class RendererState:
     buffer: list[str] | None = None
     final_text: str = ""
     streaming_started_at: float | None = None
-    printed_final_panel: bool = False
+    printed_final_output: bool = False
     finalizing_ui: bool = False
     final_duration_seconds: float | None = None
     final_duration_text: str | None = None
+    events: list[dict[str, Any]] = field(default_factory=list)
+    meta: dict[str, Any] = field(default_factory=dict)
+    streaming_started_event_ts: datetime | None = None
 
     def __post_init__(self) -> None:
         """Initialize renderer state after dataclass creation.
@@ -127,7 +153,10 @@ class RichStreamRenderer:
 
         # Set up initial state
         self._started_at = monotonic()
-        self.stream_processor.streaming_started_at = self._started_at
+        try:
+            self.state.meta = json.loads(json.dumps(meta))
+        except Exception:
+            self.state.meta = dict(meta)
 
         # Print compact header and user request (parity with old renderer)
         self._render_header(meta)
@@ -147,7 +176,7 @@ class RichStreamRenderer:
 
     def _build_header_parts(self, meta: dict[str, Any]) -> list[str]:
         """Build header text parts from metadata."""
-        parts: list[str] = ["🤖"]
+        parts: list[str] = [ICON_AGENT]
         agent_name = meta.get("agent_name", "agent")
         if agent_name:
             parts.append(agent_name)
@@ -193,29 +222,71 @@ class RichStreamRenderer:
             )
         )
 
+    def _ensure_streaming_started_baseline(self, timestamp: float) -> None:
+        """Synchronize streaming start state across renderer components."""
+        self.state.streaming_started_at = timestamp
+        self.stream_processor.streaming_started_at = timestamp
+        self._started_at = timestamp
+
     def on_event(self, ev: dict[str, Any]) -> None:
         """Handle streaming events from the backend."""
-        # Reset event tracking
+        received_at = self._resolve_received_timestamp(ev)
+        self._capture_event(ev, received_at)
         self.stream_processor.reset_event_tracking()
 
-        # Track streaming start time
-        if self.state.streaming_started_at is None:
-            self.state.streaming_started_at = monotonic()
+        self._sync_stream_start(ev, received_at)
 
-        # Extract event metadata
         metadata = self.stream_processor.extract_event_metadata(ev)
-        kind = metadata["kind"]
-        context_id = metadata["context_id"]
-        content = metadata["content"]
+        self.stream_processor.update_timing(metadata["context_id"])
 
-        # Render debug event panel if verbose mode is enabled
-        if self.verbose:
-            render_debug_event(ev, self.console, self.state.streaming_started_at)
+        self._maybe_render_debug(ev, received_at)
+        self._dispatch_event(ev, metadata)
+
+    def _resolve_received_timestamp(self, ev: dict[str, Any]) -> datetime:
+        """Return the timestamp an event was received, normalising inputs."""
+        received_at = _coerce_received_at(ev.get("received_at"))
+        if received_at is None:
+            received_at = datetime.now(timezone.utc)
+
+        if self.state.streaming_started_event_ts is None:
+            self.state.streaming_started_event_ts = received_at
+
+        return received_at
 
-        # Update timing
-        self.stream_processor.update_timing(context_id)
+    def _sync_stream_start(
+        self, ev: dict[str, Any], received_at: datetime | None
+    ) -> None:
+        """Ensure renderer and stream processor share a streaming baseline."""
+        baseline = self.state.streaming_started_at
+        if baseline is None:
+            baseline = monotonic()
+            self._ensure_streaming_started_baseline(baseline)
+        elif getattr(self.stream_processor, "streaming_started_at", None) is None:
+            self._ensure_streaming_started_baseline(baseline)
+
+        if ev.get("status") == "streaming_started":
+            self.state.streaming_started_event_ts = received_at
+            self._ensure_streaming_started_baseline(monotonic())
+
+    def _maybe_render_debug(
+        self, ev: dict[str, Any], received_at: datetime
+    ) -> None:  # pragma: no cover - guard rails for verbose mode
+        """Render debug view when verbose mode is enabled."""
+        if not self.verbose:
+            return
+
+        render_debug_event(
+            ev,
+            self.console,
+            received_ts=received_at,
+            baseline_ts=self.state.streaming_started_event_ts,
+        )
+
+    def _dispatch_event(self, ev: dict[str, Any], metadata: dict[str, Any]) -> None:
+        """Route events to the appropriate renderer handlers."""
+        kind = metadata["kind"]
+        content = metadata["content"]
 
-        # Handle different event types
         if kind == "status":
             self._handle_status_event(ev)
         elif kind == "content":
@@ -225,14 +296,13 @@ class RichStreamRenderer:
         elif kind in {"agent_step", "agent_thinking_step"}:
             self._handle_agent_step_event(ev)
         else:
-            # Update live display for unhandled events
             self._ensure_live()
 
     def _handle_status_event(self, ev: dict[str, Any]) -> None:
         """Handle status events."""
         status = ev.get("status")
         if status == "streaming_started":
-            self.state.streaming_started_at = monotonic()
+            return
 
     def _handle_content_event(self, content: str) -> None:
         """Handle content streaming events."""
@@ -252,16 +322,7 @@ class RichStreamRenderer:
             self._update_final_duration(meta_payload.get("time"))
 
             self._ensure_live()
-
-            # In verbose mode, show the final result in a panel
-            if self.verbose and content.strip():
-                final_panel = create_final_panel(
-                    content,
-                    title=self._final_panel_title(),
-                    theme=self.cfg.theme,
-                )
-                self.console.print(final_panel)
-                self.state.printed_final_panel = True
+            self._print_final_panel_if_needed()
 
     def _handle_agent_step_event(self, ev: dict[str, Any]) -> None:
         """Handle agent step events."""
@@ -307,17 +368,22 @@ class RichStreamRenderer:
         self._shutdown_live()
 
     def _print_final_panel_if_needed(self) -> None:
-        """Print final result panel if verbose mode and content available."""
-        if self.verbose and not self.state.printed_final_panel:
-            body = ("".join(self.state.buffer) or "").strip()
-            if body:
-                final_panel = create_final_panel(
-                    body,
-                    title=self._final_panel_title(),
-                    theme=self.cfg.theme,
-                )
-                self.console.print(final_panel)
-                self.state.printed_final_panel = True
+        """Print final result when configuration requires it."""
+        if self.state.printed_final_output:
+            return
+
+        body = (self.state.final_text or "".join(self.state.buffer) or "").strip()
+        if not body:
+            return
+
+        if self.verbose:
+            final_panel = create_final_panel(
+                body,
+                title=self._final_panel_title(),
+                theme=self.cfg.theme,
+            )
+            self.console.print(final_panel)
+            self.state.printed_final_output = True
 
     def on_complete(self, stats: RunStats) -> None:
         """Handle completion event."""
@@ -348,7 +414,7 @@ class RichStreamRenderer:
         # Stop live display
         self._stop_live_display()
 
-        # Print final panel if needed
+        # Render final output based on configuration
         self._print_final_panel_if_needed()
 
     def _ensure_live(self) -> None:
@@ -469,6 +535,37 @@ class RichStreamRenderer:
         if self.cfg.live:
             self._ensure_live()
 
+    # ------------------------------------------------------------------
+    # Transcript helpers
+    # ------------------------------------------------------------------
+    def _capture_event(
+        self, ev: dict[str, Any], received_at: datetime | None = None
+    ) -> None:
+        """Capture a deep copy of SSE events for transcript replay."""
+        try:
+            captured = json.loads(json.dumps(ev))
+        except Exception:
+            captured = ev
+
+        if received_at is not None:
+            try:
+                captured["received_at"] = received_at.isoformat()
+            except Exception:
+                try:
+                    captured["received_at"] = str(received_at)
+                except Exception:
+                    captured["received_at"] = repr(received_at)
+
+        self.state.events.append(captured)
+
+    def get_aggregated_output(self) -> str:
+        """Return the concatenated assistant output collected so far."""
+        return ("".join(self.state.buffer or [])).strip()
+
+    def get_transcript_events(self) -> list[dict[str, Any]]:
+        """Return captured SSE events."""
+        return list(self.state.events)
+
     def _maybe_insert_thinking_gap(
         self, task_id: str | None, context_id: str | None
     ) -> None:
@@ -993,11 +1090,11 @@ class RichStreamRenderer:
     def _get_step_icon(self, step_kind: str) -> str:
         """Get icon for step kind."""
         if step_kind == "tool":
-            return "⚙️"
+            return ICON_TOOL_STEP
         elif step_kind == "delegate":
-            return "🤝"
+            return ICON_DELEGATE
         elif step_kind == "agent":
-            return "🧠"
+            return ICON_AGENT_STEP
         return ""
 
     def _format_step_status(self, step: Step) -> str:
@@ -1049,30 +1146,64 @@ class RichStreamRenderer:
                 running_by_ctx.setdefault(key, []).append(st)
         return running_by_ctx
 
-    def _render_steps_text(self) -> Text:
+    def _is_parallel_tool(
+        self,
+        step: Step,
+        running_by_ctx: dict[tuple[str | None, str | None], list],
+    ) -> bool:
+        """Return True if multiple tools are running in the same context."""
+        key = (step.task_id, step.context_id)
+        return len(running_by_ctx.get(key, [])) > 1
+
+    def _compose_step_renderable(
+        self,
+        step: Step,
+        running_by_ctx: dict[tuple[str | None, str | None], list],
+    ) -> Any:
+        """Compose a single renderable for the steps panel."""
+        finished = is_step_finished(step)
+        status_br = self._format_step_status(step)
+        display_name = self._get_step_display_name(step)
+
+        if (
+            not finished
+            and step.kind == "tool"
+            and self._is_parallel_tool(step, running_by_ctx)
+        ):
+            status_br = status_br.replace("]", " 🔄]")
+
+        icon = self._get_step_icon(step.kind)
+        text_line = Text(style="dim")
+        text_line.append(icon)
+        text_line.append(" ")
+        text_line.append(display_name)
+        if status_br:
+            text_line.append(" ")
+            text_line.append(status_br)
+        if finished:
+            text_line.append(" ✓")
+
+        if finished:
+            return text_line
+
+        spinner = Spinner("dots", text=text_line, style="dim")
+        return Align.left(spinner)
+
+    def _render_steps_text(self) -> Any:
         """Render the steps panel content."""
         if not (self.steps.order or self.steps.children):
             return Text("No steps yet", style="dim")
 
         running_by_ctx = self._check_parallel_tools()
-        lines: list[str] = []
-
+        renderables: list[Any] = []
         for sid in self.steps.order:
-            st = self.steps.by_id[sid]
-            status_br = self._format_step_status(st)
-            display_name = self._get_step_display_name(st)
-            tail = " ✓" if is_step_finished(st) else ""
-
-            # Add parallel indicator for running tools
-            if st.kind == "tool" and not is_step_finished(st):
-                key = (st.task_id, st.context_id)
-                if len(running_by_ctx.get(key, [])) > 1:
-                    status_br = status_br.replace("]", " 🔄]")
+            line = self._compose_step_renderable(self.steps.by_id[sid], running_by_ctx)
+            renderables.append(line)
 
-            icon = self._get_step_icon(st.kind)
-            lines.append(f"{icon} {display_name} {status_br}{tail}")
+        if not renderables:
+            return Text("No steps yet", style="dim")
 
-        return Text("\n".join(lines), style="dim")
+        return Group(*renderables)
 
     def _should_skip_finished_panel(self, sid: str, status: str) -> bool:
         """Check if a finished panel should be skipped."""
@@ -1154,18 +1285,27 @@ class RichStreamRenderer:
         return self._format_elapsed_time(dur) if isinstance(dur, int | float) else None
 
     def _process_running_tool_panel(
-        self, title: str, meta: dict[str, Any], body: str
-    ) -> tuple[str, str]:
+        self,
+        title: str,
+        meta: dict[str, Any],
+        body: str,
+        *,
+        include_spinner: bool = False,
+    ) -> tuple[str, str] | tuple[str, str, str | None]:
         """Process a running tool panel."""
         elapsed_str = self._calculate_elapsed_time(meta)
         adjusted_title = f"{title}  · {elapsed_str}"
         chip = f"⏱ {elapsed_str}"
+        spinner_message: str | None = None
 
-        if not body:
-            body = chip
+        if not body.strip():
+            body = ""
+            spinner_message = f"{title} running... {elapsed_str}"
         else:
             body = f"{body}\n\n{chip}"
 
+        if include_spinner:
+            return adjusted_title, body, spinner_message
         return adjusted_title, body
 
     def _process_finished_tool_panel(self, title: str, meta: dict[str, Any]) -> str:
@@ -1188,8 +1328,12 @@ class RichStreamRenderer:
         body = "".join(chunks)
         adjusted_title = title
 
+        spinner_message: str | None = None
+
         if status == "running":
-            adjusted_title, body = self._process_running_tool_panel(title, meta, body)
+            adjusted_title, body, spinner_message = self._process_running_tool_panel(
+                title, meta, body, include_spinner=True
+            )
         elif status == "finished":
             adjusted_title = self._process_finished_tool_panel(title, meta)
 
@@ -1199,10 +1343,13 @@ class RichStreamRenderer:
             status=status,
             theme=self.cfg.theme,
             is_delegation=is_delegation,
+            spinner_message=spinner_message,
         )
 
     def _render_tool_panels(self) -> list[AIPPanel]:
         """Render tool execution output panels."""
+        if not getattr(self.cfg, "show_delegate_tool_panels", False):
+            return []
         panels: list[AIPPanel] = []
         for sid in self.tool_order:
             meta = self.tool_panels.get(sid) or {}