glaip-sdk 0.1.3__py3-none-any.whl → 0.6.19__py3-none-any.whl

glaip_sdk/utils/rendering/renderer/debug.py

@@ -7,31 +7,14 @@ Authors:
 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
-
-
-def _coerce_datetime(value: Any) -> datetime | None:
-    """Attempt to coerce an arbitrary value to an aware datetime."""
-    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
+from glaip_sdk.utils.datetime_helpers import coerce_datetime
 
 
 def _parse_event_timestamp(event: dict[str, Any], received_ts: datetime | None = None) -> datetime | None:
@@ -40,7 +23,7 @@ def _parse_event_timestamp(event: dict[str, Any], received_ts: datetime | 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)
+    return coerce_datetime(ts_value)
 
 
 def _format_timestamp_for_display(dt: datetime) -> str:
@@ -170,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

@@ -129,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
 

glaip_sdk/utils/rendering/renderer/thinking.py

@@ -0,0 +1,273 @@
+"""Thinking scope controller used by the renderer.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from time import monotonic
+from typing import Any
+
+from glaip_sdk.utils.rendering.formatting import is_step_finished
+from glaip_sdk.utils.rendering.models import Step
+from glaip_sdk.utils.rendering.state import ThinkingScopeState
+from glaip_sdk.utils.rendering.steps import StepManager
+from glaip_sdk.utils.rendering.timing import calculate_timeline_duration, coerce_server_time
+
+FINISHED_STATUS_HINTS = {
+    "finished",
+    "success",
+    "succeeded",
+    "completed",
+    "failed",
+    "stopped",
+    "error",
+}
+
+
+class ThinkingScopeController:
+    """Encapsulates deterministic thinking bookkeeping for the renderer."""
+
+    def __init__(self, steps: StepManager, *, step_server_start_times: dict[str, float]) -> None:
+        """Initialize the thinking scope controller.
+
+        Args:
+            steps: Step manager instance for tracking steps
+            step_server_start_times: Dictionary mapping step IDs to server start times
+        """
+        self._steps = steps
+        self._step_server_start_times = step_server_start_times
+        self._scopes: dict[str, ThinkingScopeState] = {}
+
+    def update_timeline(self, step: Step | None, payload: dict[str, Any], *, enabled: bool) -> None:
+        """Update thinking spans for a streamed step event."""
+        if not enabled or not step:
+            return
+
+        now_monotonic = monotonic()
+        server_time = coerce_server_time(payload.get("time"))
+        status_hint = (payload.get("status") or "").lower()
+
+        if self._is_scope_anchor(step):
+            self._update_anchor_thinking(
+                step=step,
+                server_time=server_time,
+                status_hint=status_hint,
+                now_monotonic=now_monotonic,
+            )
+            return
+
+        self._update_child_thinking(
+            step=step,
+            server_time=server_time,
+            status_hint=status_hint,
+            now_monotonic=now_monotonic,
+        )
+
+    def close_active_scopes(self, server_time: float | None) -> None:
+        """Finish any in-flight thinking nodes during finalization."""
+        now = monotonic()
+        for scope in self._scopes.values():
+            if not scope.active_thinking_id:
+                continue
+            self._finish_scope_thinking(scope, server_time, now)
+
+    # ------------------------------------------------------------------
+    # Internal helpers mirroring the previous renderer implementation.
+    # ------------------------------------------------------------------
+    def _update_anchor_thinking(
+        self,
+        *,
+        step: Step,
+        server_time: float | None,
+        status_hint: str,
+        now_monotonic: float,
+    ) -> None:
+        scope = self._get_or_create_scope(step)
+        if scope.anchor_started_at is None and server_time is not None:
+            scope.anchor_started_at = server_time
+
+        if not scope.closed and scope.active_thinking_id is None:
+            self._start_scope_thinking(
+                scope,
+                start_server_time=scope.anchor_started_at or server_time,
+                start_monotonic=now_monotonic,
+            )
+
+        is_anchor_finished = status_hint in FINISHED_STATUS_HINTS or (not status_hint and is_step_finished(step))
+        if is_anchor_finished:
+            scope.anchor_finished_at = server_time or scope.anchor_finished_at
+            self._finish_scope_thinking(scope, server_time, now_monotonic)
+            scope.closed = True
+
+        parent_anchor_id = self._resolve_anchor_id(step)
+        if parent_anchor_id:
+            self._cascade_anchor_update(
+                parent_anchor_id=parent_anchor_id,
+                child_step=step,
+                server_time=server_time,
+                now_monotonic=now_monotonic,
+                is_finished=is_anchor_finished,
+            )
+
+    def _cascade_anchor_update(
+        self,
+        *,
+        parent_anchor_id: str,
+        child_step: Step,
+        server_time: float | None,
+        now_monotonic: float,
+        is_finished: bool,
+    ) -> None:
+        parent_scope = self._scopes.get(parent_anchor_id)
+        if not parent_scope or parent_scope.closed:
+            return
+        if is_finished:
+            self._mark_child_finished(parent_scope, child_step.step_id, server_time, now_monotonic)
+        else:
+            self._mark_child_running(parent_scope, child_step, server_time, now_monotonic)
+
+    def _update_child_thinking(
+        self,
+        *,
+        step: Step,
+        server_time: float | None,
+        status_hint: str,
+        now_monotonic: float,
+    ) -> None:
+        anchor_id = self._resolve_anchor_id(step)
+        if not anchor_id:
+            return
+
+        scope = self._scopes.get(anchor_id)
+        if not scope or scope.closed or step.kind == "thinking":
+            return
+
+        is_finish_event = status_hint in FINISHED_STATUS_HINTS or (not status_hint and is_step_finished(step))
+        if is_finish_event:
+            self._mark_child_finished(scope, step.step_id, server_time, now_monotonic)
+        else:
+            self._mark_child_running(scope, step, server_time, now_monotonic)
+
+    def _resolve_anchor_id(self, step: Step) -> str | None:
+        parent_id = step.parent_id
+        while parent_id:
+            parent = self._steps.by_id.get(parent_id)
+            if not parent:
+                return None
+            if self._is_scope_anchor(parent):
+                return parent.step_id
+            parent_id = parent.parent_id
+        return None
+
+    def _get_or_create_scope(self, step: Step) -> ThinkingScopeState:
+        scope = self._scopes.get(step.step_id)
+        if scope:
+            if scope.task_id is None:
+                scope.task_id = step.task_id
+            if scope.context_id is None:
+                scope.context_id = step.context_id
+            return scope
+        scope = ThinkingScopeState(
+            anchor_id=step.step_id,
+            task_id=step.task_id,
+            context_id=step.context_id,
+        )
+        self._scopes[step.step_id] = scope
+        return scope
+
+    def _is_scope_anchor(self, step: Step) -> bool:
+        if step.kind in {"agent", "delegate"}:
+            return True
+        name = (step.name or "").lower()
+        return name.startswith(("delegate_to_", "delegate_", "delegate "))
+
+    def _start_scope_thinking(
+        self,
+        scope: ThinkingScopeState,
+        *,
+        start_server_time: float | None,
+        start_monotonic: float,
+    ) -> None:
+        if scope.closed or scope.active_thinking_id or not scope.anchor_id:
+            return
+        step = self._steps.start_or_get(
+            task_id=scope.task_id,
+            context_id=scope.context_id,
+            kind="thinking",
+            name=f"agent_thinking_step::{scope.anchor_id}",
+            parent_id=scope.anchor_id,
+            args={"reason": "deterministic_timeline"},
+        )
+        step.display_label = "💭 Thinking…"
+        scope.active_thinking_id = step.step_id
+        scope.idle_started_at = start_server_time
+        scope.idle_started_monotonic = start_monotonic
+
+    def _finish_scope_thinking(
+        self,
+        scope: ThinkingScopeState,
+        end_server_time: float | None,
+        end_monotonic: float,
+    ) -> None:
+        if not scope.active_thinking_id:
+            return
+        thinking_step = self._steps.by_id.get(scope.active_thinking_id)
+        if not thinking_step:
+            scope.active_thinking_id = None
+            scope.idle_started_at = None
+            scope.idle_started_monotonic = None
+            return
+
+        duration = calculate_timeline_duration(
+            scope.idle_started_at,
+            end_server_time,
+            scope.idle_started_monotonic,
+            end_monotonic,
+        )
+        thinking_step.display_label = thinking_step.display_label or "💭 Thinking…"
+        if duration is not None:
+            thinking_step.finish(duration, source="timeline")
+        else:
+            thinking_step.finish(None, source="timeline")
+        scope.active_thinking_id = None
+        scope.idle_started_at = None
+        scope.idle_started_monotonic = None
+
+    def _mark_child_running(
+        self,
+        scope: ThinkingScopeState,
+        step: Step,
+        server_time: float | None,
+        now_monotonic: float,
+    ) -> None:
+        if step.step_id in scope.running_children:
+            return
+        scope.running_children.add(step.step_id)
+        if not scope.active_thinking_id:
+            return
+
+        start_server = self._step_server_start_times.get(step.step_id)
+        if start_server is None:
+            start_server = server_time
+        self._finish_scope_thinking(scope, start_server, now_monotonic)
+
+    def _mark_child_finished(
+        self,
+        scope: ThinkingScopeState,
+        step_id: str,
+        server_time: float | None,
+        now_monotonic: float,
+    ) -> None:
+        scope.running_children.discard(step_id)
+        if scope.active_thinking_id or scope.closed or scope.running_children:
+            return
+        self._start_scope_thinking(
+            scope,
+            start_server_time=server_time,
+            start_monotonic=now_monotonic,
+        )
+
+
+__all__ = ["ThinkingScopeController", "FINISHED_STATUS_HINTS"]