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

glaip_sdk/utils/rendering/steps/format.py

@@ -0,0 +1,176 @@
+"""Presentation helpers for rendering steps.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from glaip_sdk.icons import ICON_AGENT_STEP, ICON_DELEGATE, ICON_TOOL_STEP
+from glaip_sdk.utils.rendering.formatting import glyph_for_status, normalise_display_label, pretty_args
+from glaip_sdk.utils.rendering.models import Step
+
+if TYPE_CHECKING:  # pragma: no cover - typing helpers only
+    from glaip_sdk.utils.rendering.layout.transcript import TranscriptGlyphs
+
+UNKNOWN_STEP_DETAIL = "Unknown step detail"
+STATUS_ICON_STYLES = {
+    "success": "green",
+    "failed": "red",
+    "warning": "yellow",
+}
+CONNECTOR_VERTICAL = "│   "
+CONNECTOR_EMPTY = "    "
+CONNECTOR_BRANCH = "├─ "
+CONNECTOR_LAST = "└─ "
+ROOT_MARKER = ""
+
+
+@dataclass(slots=True)
+class StepPresentation:
+    """Lightweight view model for formatted steps."""
+
+    step_id: str
+    title: str
+    glyph: str | None
+    status_style: str | None
+    args_text: str | None = None
+    failure_reason: str | None = None
+    duration_ms: int | None = None
+    status_text: str | None = None
+
+
+def humanize_tool_name(raw_name: str | None) -> str:
+    """Return a user-facing name for a tool or agent identifier."""
+    if not raw_name:
+        return UNKNOWN_STEP_DETAIL
+    name = raw_name
+    if name.startswith("delegate_to_"):
+        name = name.removeprefix("delegate_to_")
+    elif name.startswith("delegate_"):
+        name = name.removeprefix("delegate_")
+    cleaned = name.replace("_", " ").replace("-", " ").strip()
+    if not cleaned:
+        return UNKNOWN_STEP_DETAIL
+    lowered = cleaned.lower()
+    return lowered[0].upper() + lowered[1:] if lowered else UNKNOWN_STEP_DETAIL
+
+
+def step_icon_for_kind(step_kind: str) -> str:
+    """Return the icon prefix for a step kind."""
+    if step_kind == "agent":
+        return ICON_AGENT_STEP
+    if step_kind == "delegate":
+        return ICON_DELEGATE
+    if step_kind == "thinking":
+        return "💭"
+    return ICON_TOOL_STEP
+
+
+def resolve_label_body(step_kind: str, tool_name: str | None, metadata: dict[str, Any]) -> str:
+    """Resolve the textual body for a step label."""
+    if step_kind == "thinking":
+        thinking_text = metadata.get("thinking_and_activity_info")
+        if isinstance(thinking_text, str) and thinking_text.strip():
+            return thinking_text.strip()
+        return "Thinking…"
+
+    if step_kind == "delegate":
+        return humanize_tool_name(tool_name)
+
+    if step_kind == "agent":
+        agent_name = metadata.get("agent_name")
+        if isinstance(agent_name, str) and agent_name.strip():
+            return agent_name.strip()
+
+    return humanize_tool_name(tool_name)
+
+
+def compose_display_label(
+    step_kind: str,
+    tool_name: str | None,
+    args: dict[str, Any],
+    metadata: dict[str, Any],
+) -> str:
+    """Compose the display label for a step using tool metadata."""
+    icon = step_icon_for_kind(step_kind)
+    body = resolve_label_body(step_kind, tool_name, metadata)
+    label = f"{icon} {body}".strip()
+    if isinstance(args, dict) and args:
+        label = f"{label} —"
+    return label or UNKNOWN_STEP_DETAIL
+
+
+def status_icon_for_step(step: Step) -> str:
+    """Return the canonical status icon key for a step."""
+    if step.status == "failed":
+        return "failed"
+    if step.branch_failed:
+        return "warning"
+    if step.status == "finished":
+        return "success"
+    if step.status == "stopped":
+        return "warning"
+    return "spinner"
+
+
+def format_step_label(step: Step) -> str:
+    """Return the normalized display label for a step."""
+    label = normalise_display_label(getattr(step, "display_label", None))
+    if label and label != UNKNOWN_STEP_DETAIL:
+        return label
+    metadata = getattr(step, "metadata", {}) or {}
+    computed = compose_display_label(step.kind, getattr(step, "name", None), getattr(step, "args", {}), metadata)
+    return normalise_display_label(computed)
+
+
+def format_tool_args(step: Step, max_len: int = 160) -> str | None:
+    """Return a pretty-printed args summary for a step."""
+    if not step.args:
+        return None
+    try:
+        return pretty_args(step.args, max_len=max_len)
+    except Exception:
+        return None
+
+
+def format_step(
+    step: Step,
+    *,
+    glyphs: TranscriptGlyphs | None = None,
+    label: str | None = None,
+) -> StepPresentation:
+    """Return a StepPresentation for downstream transcript rendering."""
+    del glyphs  # Reserved for future glyph customisation hooks
+    if label:
+        resolved_label = normalise_display_label(label)
+    else:
+        resolved_label = format_step_label(step)
+    glyph_key = status_icon_for_step(step)
+    glyph = glyph_for_status(glyph_key)
+    style = STATUS_ICON_STYLES.get(glyph_key)
+    failure_reason = (step.failure_reason or "").strip() or None
+    return StepPresentation(
+        step_id=step.step_id,
+        title=resolved_label,
+        glyph=glyph,
+        status_style=style,
+        args_text=format_tool_args(step),
+        failure_reason=failure_reason,
+        duration_ms=getattr(step, "duration_ms", None),
+    )
+
+
+def build_connector_prefix(branch_state: tuple[bool, ...]) -> str:
+    """Build connector prefix for a tree line based on ancestry state."""
+    if not branch_state:
+        return ROOT_MARKER
+
+    parts: list[str] = []
+    for ancestor_is_last in branch_state[:-1]:
+        parts.append(CONNECTOR_EMPTY if ancestor_is_last else CONNECTOR_VERTICAL)
+    parts.append(CONNECTOR_LAST if branch_state[-1] else CONNECTOR_BRANCH)
+    return "".join(parts)

glaip_sdk/utils/rendering/{steps.py → steps/manager.py}

@@ -9,9 +9,15 @@ from __future__ import annotations
 from collections.abc import Iterator
 
 from glaip_sdk.utils.rendering.models import Step
+from glaip_sdk.utils.rendering.step_tree_state import StepTreeState
+from glaip_sdk.utils.rendering.steps.event_processor import StepEventMixin
 
 
-class StepManager:
+class StepManagerError(Exception):
+    """Raised when invalid operations are attempted on the step tree."""
+
+
+class StepManager(StepEventMixin):
     """Manages the lifecycle and organization of execution steps.
 
     Tracks step creation, parent-child relationships, and execution state
@@ -24,13 +30,22 @@ class StepManager:
         Args:
             max_steps: Maximum number of steps to retain before pruning
         """
-        self.by_id: dict[str, Step] = {}
-        self.order: list[str] = []
-        self.children: dict[str, list[str]] = {}
+        normalised_max = int(max_steps) if isinstance(max_steps, (int, float)) else 0
+        self.state = StepTreeState(max_steps=normalised_max)
+        self.by_id: dict[str, Step] = self.state.step_index
         self.key_index: dict[tuple, str] = {}
         self.slot_counter: dict[tuple, int] = {}
-        self.max_steps = max_steps
+        self.max_steps = normalised_max
         self._last_running: dict[tuple, str] = {}
+        self._step_aliases: dict[str, str] = {}
+        self.root_agent_id: str | None = None
+        self._scope_anchors: dict[str, list[str]] = {}
+        self._step_scope_map: dict[str, str] = {}
+
+    def set_root_agent(self, agent_id: str | None) -> None:
+        """Record the root agent identifier for scope-aware parenting."""
+        if isinstance(agent_id, str) and agent_id.strip():
+            self.root_agent_id = agent_id.strip()
 
     def _alloc_slot(
         self,
@@ -86,9 +101,7 @@ class StepManager:
         Returns:
             The Step instance (new or existing)
         """
-        existing = self.find_running(
-            task_id=task_id, context_id=context_id, kind=kind, name=name
-        )
+        existing = self.find_running(task_id=task_id, context_id=context_id, kind=kind, name=name)
         if existing:
             if args and existing.args != args:
                 existing.args = args
@@ -111,6 +124,7 @@ class StepManager:
         else:
             self.order.append(step_id)
         self.key_index[key] = step_id
+        self.state.retained_ids.add(step_id)
         self._prune_steps()
         self._last_running[(task_id, context_id, kind, name)] = step_id
         return st
@@ -131,26 +145,46 @@ class StepManager:
 
     def _remove_subtree(self, root_id: str) -> None:
         """Remove a complete subtree from all data structures."""
+        for step_id in self._collect_subtree_ids(root_id):
+            self._purge_step_references(step_id)
+
+    def _collect_subtree_ids(self, root_id: str) -> list[str]:
+        """Return a flat list of step ids contained within a subtree."""
         stack = [root_id]
-        to_remove = []
+        collected: list[str] = []
         while stack:
             sid = stack.pop()
-            to_remove.append(sid)
+            collected.append(sid)
             stack.extend(self.children.pop(sid, []))
+        return collected
 
-        for sid in to_remove:
-            st = self.by_id.pop(sid, None)
-            if st:
-                key = (st.task_id, st.context_id, st.kind, st.name)
-                self._last_running.pop(key, None)
-            for _parent, kids in list(self.children.items()):
-                if sid in kids:
-                    kids.remove(sid)
-            if sid in self.order:
-                self.order.remove(sid)
+    def _purge_step_references(self, step_id: str) -> None:
+        """Remove a single step id from all indexes and helper structures."""
+        st = self.by_id.pop(step_id, None)
+        if st:
+            key = (st.task_id, st.context_id, st.kind, st.name)
+            self._last_running.pop(key, None)
+            self.state.retained_ids.discard(step_id)
+            self.state.discard_running(step_id)
+        self._remove_parent_links(step_id)
+        if step_id in self.order:
+            self.order.remove(step_id)
+        self.state.buffered_children.pop(step_id, None)
+        self.state.pending_branch_failures.discard(step_id)
+
+    def _remove_parent_links(self, child_id: str) -> None:
+        """Detach a child id from any parent lists."""
+        for parent, kids in self.children.copy().items():
+            if child_id not in kids:
+                continue
+            kids.remove(child_id)
+            if not kids:
+                self.children.pop(parent, None)
 
     def _should_prune_steps(self, total: int) -> bool:
         """Check if steps should be pruned."""
+        if self.max_steps <= 0:
+            return False
         return total > self.max_steps
 
     def _get_oldest_step_id(self) -> str | None:
@@ -172,6 +206,32 @@ class StepManager:
             self._remove_subtree(sid)
             total -= subtree_size
 
+    def remove_step(self, step_id: str) -> None:
+        """Remove a single step from the tree and cached indexes."""
+        step = self.by_id.pop(step_id, None)
+        if not step:
+            return
+
+        if step.parent_id:
+            self.state.unlink_child(step.parent_id, step_id)
+        else:
+            self.state.unlink_root(step_id)
+
+        self.children.pop(step_id, None)
+        self.state.buffered_children.pop(step_id, None)
+        self.state.retained_ids.discard(step_id)
+        self.state.pending_branch_failures.discard(step_id)
+        self.state.discard_running(step_id)
+
+        self.key_index = {key: sid for key, sid in self.key_index.items() if sid != step_id}
+        for key, last_sid in self._last_running.copy().items():
+            if last_sid == step_id:
+                self._last_running.pop(key, None)
+
+        aliases = [alias for alias, target in self._step_aliases.items() if alias == step_id or target == step_id]
+        for alias in aliases:
+            self._step_aliases.pop(alias, None)
+
     def get_child_count(self, step_id: str) -> int:
         """Get the number of child steps for a given step.
 
@@ -224,6 +284,24 @@ class StepManager:
                 return st
         return None
 
+    def list_ordered(self) -> list[Step]:
+        """Return a depth-first list of steps currently tracked."""
+        ordered: list[Step] = []
+        for step_id, _branch_state in self.iter_tree():
+            step = self.by_id.get(step_id)
+            if step:
+                ordered.append(step)
+        return ordered
+
+    def prune_for_summary(self, limit: int) -> list[tuple[str, tuple[bool, ...]]]:
+        """Return the most recent ``limit`` nodes for compact summaries."""
+        if limit < 0:
+            raise StepManagerError("limit must be non-negative")
+        nodes = list(self.iter_tree())
+        if limit == 0 or len(nodes) <= limit:
+            return nodes
+        return nodes[-limit:]
+
     def finish(
         self,
         *,
@@ -250,9 +328,7 @@ class StepManager:
         Raises:
             RuntimeError: If no matching step is found
         """
-        st = self.find_running(
-            task_id=task_id, context_id=context_id, kind=kind, name=name
-        )
+        st = self.find_running(task_id=task_id, context_id=context_id, kind=kind, name=name)
         if not st:
             # Try to find any existing step with matching parameters, even if not running
             for sid in reversed(list(self._iter_all_steps())):
@@ -269,9 +345,7 @@ class StepManager:
 
             # If still no step found, create a new one
             if not st:
-                st = self.start_or_get(
-                    task_id=task_id, context_id=context_id, kind=kind, name=name
-                )
+                st = self.start_or_get(task_id=task_id, context_id=context_id, kind=kind, name=name)
 
         if output:
             st.output = output
@@ -289,3 +363,25 @@ class StepManager:
                 sid = stack.pop()
                 yield sid
                 stack.extend(self.children.get(sid, []))
+
+    def iter_tree(self) -> Iterator[tuple[str, tuple[bool, ...]]]:
+        """Expose depth-first traversal info for rendering."""
+        yield from self.state.iter_visible_tree()
+
+    @property
+    def order(self) -> list[str]:
+        """Root step ordering accessor backed by StepTreeState."""
+        return self.state.root_order
+
+    @order.setter
+    def order(self, value: list[str]) -> None:
+        self.state.root_order = list(value)
+
+    @property
+    def children(self) -> dict[str, list[str]]:
+        """Child mapping accessor backed by StepTreeState."""
+        return self.state.child_map
+
+    @children.setter
+    def children(self, value: dict[str, list[str]]) -> None:
+        self.state.child_map = value

glaip_sdk/utils/rendering/timing.py

@@ -0,0 +1,36 @@
+"""Shared timing helpers for renderer components.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def coerce_server_time(value: Any) -> float | None:
+    """Convert a raw SSE/server time payload into a float."""
+    if isinstance(value, (int, float)):
+        return float(value)
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def calculate_timeline_duration(
+    start_server: float | None,
+    end_server: float | None,
+    start_monotonic: float | None,
+    end_monotonic: float | None,
+) -> float | None:
+    """Return best-effort elapsed time using server or monotonic clocks."""
+    if start_server is not None and end_server is not None:
+        return max(0.0, float(end_server) - float(start_server))
+    if start_monotonic is not None and end_monotonic is not None:
+        try:
+            return max(0.0, float(end_monotonic) - float(start_monotonic))
+        except Exception:
+            return None
+    return None

glaip_sdk/utils/rendering/viewer/__init__.py

@@ -0,0 +1,21 @@
+"""Shared transcript viewer exports.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from glaip_sdk.utils.rendering.viewer.presenter import (
+    ViewerContext,
+    prepare_viewer_snapshot,
+    render_post_run_view,
+    render_transcript_events,
+    render_transcript_view,
+)
+
+__all__ = [
+    "ViewerContext",
+    "prepare_viewer_snapshot",
+    "render_post_run_view",
+    "render_transcript_events",
+    "render_transcript_view",
+]

glaip_sdk/utils/rendering/viewer/presenter.py

@@ -0,0 +1,184 @@
+"""Shared presenter utilities for CLI/offline transcript viewing.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from rich.console import Console
+
+from glaip_sdk.utils.rendering.layout.transcript import (
+    DEFAULT_TRANSCRIPT_THEME,
+    TranscriptGlyphs,
+    TranscriptSnapshot,
+    build_transcript_snapshot,
+    build_transcript_view,
+)
+from glaip_sdk.utils.rendering.renderer.debug import render_debug_event_stream
+from glaip_sdk.utils.rendering.state import RendererState, coerce_received_at
+from glaip_sdk.utils.rendering.steps import StepManager
+
+
+@dataclass(slots=True)
+class ViewerContext:
+    """Runtime context passed to transcript presenters."""
+
+    manifest_entry: dict[str, Any]
+    events: list[dict[str, Any]]
+    default_output: str
+    final_output: str
+    stream_started_at: float | None
+    meta: dict[str, Any]
+
+
+def render_post_run_view(
+    console: Console,
+    ctx: ViewerContext,
+    *,
+    glyphs: TranscriptGlyphs | None = None,
+    theme: str = DEFAULT_TRANSCRIPT_THEME,
+) -> TranscriptSnapshot:
+    """Render the default summary view and return the snapshot used."""
+    snapshot, _state = prepare_viewer_snapshot(
+        ctx,
+        glyphs=glyphs,
+        theme=theme,
+    )
+    render_transcript_view(console, snapshot, theme=theme)
+    return snapshot
+
+
+def render_transcript_view(
+    console: Console,
+    snapshot: TranscriptSnapshot,
+    *,
+    theme: str = DEFAULT_TRANSCRIPT_THEME,
+) -> None:
+    """Render the transcript summary using a prepared snapshot."""
+    header, body = build_transcript_view(snapshot, theme=theme)
+    _print_renderables(console, header + body)
+
+
+def render_transcript_events(console: Console, events: list[dict[str, Any]]) -> None:
+    """Pretty-print transcript events using shared debug presenter."""
+    if not events:
+        console.print("[dim]No SSE events were captured for this run.[/dim]")
+        console.print()
+        return
+
+    console.print("[bold]Transcript Events[/bold]")
+    console.print("[dim]────────────────────────────────────────────────────────[/dim]")
+
+    render_debug_event_stream(
+        events,
+        console,
+        resolve_timestamp=lambda event: coerce_received_at(event.get("received_at")),
+    )
+    console.print()
+
+
+def prepare_viewer_snapshot(
+    ctx: ViewerContext,
+    *,
+    glyphs: TranscriptGlyphs | None,
+    theme: str,
+) -> tuple[TranscriptSnapshot, RendererState]:
+    """Build a transcript snapshot plus renderer state for reusable viewing."""
+    state = _build_renderer_state(ctx)
+    manager = _build_steps_from_events(ctx.events)
+    query = _extract_query_from_manifest(ctx)
+    merged_meta = _merge_meta(ctx)
+    snapshot = build_transcript_snapshot(
+        state,
+        manager,
+        glyphs=glyphs,
+        query_text=query,
+        meta=merged_meta,
+        theme=theme,
+    )
+    return snapshot, state
+
+
+def _build_renderer_state(ctx: ViewerContext) -> RendererState:
+    state = RendererState()
+    state.meta = dict(ctx.meta or {})
+
+    final_text = (ctx.final_output or "").strip()
+    default_text = (ctx.default_output or "").strip()
+    if final_text:
+        state.final_text = final_text
+    elif default_text:
+        state.final_text = default_text
+        state.buffer.append(default_text)
+
+    duration = _extract_final_duration(ctx.events)
+    if duration:
+        state.final_duration_text = duration  # pragma: no cover - exercised indirectly via end-to-end tests
+    state.events = list(ctx.events or [])
+    return state
+
+
+def _build_steps_from_events(events: list[dict[str, Any]]) -> StepManager:
+    manager = StepManager()
+    for event in events or []:
+        payload = _coerce_step_event(event)
+        if not payload:
+            continue
+        try:
+            manager.apply_event(payload)
+        except ValueError:
+            continue
+    return manager
+
+
+def _coerce_step_event(event: dict[str, Any]) -> dict[str, Any] | None:
+    metadata = event.get("metadata")
+    if not isinstance(metadata, dict):
+        return None
+    if not isinstance(metadata.get("step_id"), str):
+        return None
+    return {
+        "metadata": metadata,
+        "status": event.get("status"),
+        "task_state": event.get("task_state"),
+        "content": event.get("content"),
+        "task_id": event.get("task_id"),
+        "context_id": event.get("context_id"),
+    }
+
+
+def _extract_final_duration(events: list[dict[str, Any]]) -> str | None:
+    for event in events or []:
+        metadata = event.get("metadata") or {}
+        if metadata.get("kind") != "final_response":
+            continue
+        time_value = metadata.get("time")
+        if isinstance(time_value, (int, float)):
+            return f"{float(time_value):.2f}s"
+    return None
+
+
+def _extract_query_from_manifest(ctx: ViewerContext) -> str | None:
+    query = ctx.manifest_entry.get("input_message") or ctx.meta.get("input_message") or ctx.meta.get("query")
+    if isinstance(query, str) and query.strip():
+        return query.strip()
+    return None
+
+
+def _merge_meta(ctx: ViewerContext) -> dict[str, Any]:
+    merged = dict(ctx.meta or {})
+    manifest = ctx.manifest_entry or {}
+    for key in ("agent_name", "agent_id", "model", "run_id", "input_message"):
+        if key in manifest and manifest[key] and key not in merged:
+            merged[key] = manifest[key]
+    return merged
+
+
+def _print_renderables(console: Console, renderables: list[Any]) -> None:
+    for renderable in renderables:
+        console.print(renderable)
+        console.print()