glaip-sdk 0.1.3__py3-none-any.whl → 0.6.10__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/manager.py

@@ -0,0 +1,387 @@
+"""Rendering utilities.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+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 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
+    with automatic pruning of old steps when limits are reached.
+    """
+
+    def __init__(self, max_steps: int = 200) -> None:
+        """Initialize the step manager.
+
+        Args:
+            max_steps: Maximum number of steps to retain before pruning
+        """
+        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 = 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,
+        task_id: str | None,
+        context_id: str | None,
+        kind: str,
+        name: str,
+    ) -> int:
+        k = (task_id, context_id, kind, name)
+        self.slot_counter[k] = self.slot_counter.get(k, 0) + 1
+        return self.slot_counter[k]
+
+    def _key(
+        self,
+        task_id: str | None,
+        context_id: str | None,
+        kind: str,
+        name: str,
+        slot: int,
+    ) -> tuple[str | None, str | None, str, str, int]:
+        return (task_id, context_id, kind, name, slot)
+
+    def _make_id(
+        self,
+        task_id: str | None,
+        context_id: str | None,
+        kind: str,
+        name: str,
+        slot: int,
+    ) -> str:
+        return f"{task_id or 't'}::{context_id or 'c'}::{kind}::{name}::{slot}"
+
+    def start_or_get(
+        self,
+        *,
+        task_id: str | None,
+        context_id: str | None,
+        kind: str,
+        name: str,
+        parent_id: str | None = None,
+        args: dict[str, object] | None = None,
+    ) -> Step:
+        """Start a new step or return existing running step with same parameters.
+
+        Args:
+            task_id: Task identifier
+            context_id: Context identifier
+            kind: Step kind (tool, delegate, agent)
+            name: Step name
+            parent_id: Parent step ID if this is a child step
+            args: Step arguments
+
+        Returns:
+            The Step instance (new or existing)
+        """
+        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
+            return existing
+        slot = self._alloc_slot(task_id, context_id, kind, name)
+        key = self._key(task_id, context_id, kind, name, slot)
+        step_id = self._make_id(task_id, context_id, kind, name, slot)
+        st = Step(
+            step_id=step_id,
+            kind=kind,
+            name=name,
+            parent_id=parent_id,
+            task_id=task_id,
+            context_id=context_id,
+            args=args or {},
+        )
+        self.by_id[step_id] = st
+        if parent_id:
+            self.children.setdefault(parent_id, []).append(step_id)
+        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
+
+    def _calculate_total_steps(self) -> int:
+        """Calculate total number of steps."""
+        return len(self.order) + sum(len(v) for v in self.children.values())
+
+    def _get_subtree_size(self, root_id: str) -> int:
+        """Get the size of a subtree (including root)."""
+        subtree = [root_id]
+        stack = list(self.children.get(root_id, []))
+        while stack:
+            x = stack.pop()
+            subtree.append(x)
+            stack.extend(self.children.get(x, []))
+        return len(subtree)
+
+    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]
+        collected: list[str] = []
+        while stack:
+            sid = stack.pop()
+            collected.append(sid)
+            stack.extend(self.children.pop(sid, []))
+        return collected
+
+    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:
+        """Get the oldest step ID for pruning."""
+        return self.order[0] if self.order else None
+
+    def _prune_steps(self) -> None:
+        """Prune steps when total exceeds maximum."""
+        total = self._calculate_total_steps()
+        if not self._should_prune_steps(total):
+            return
+
+        while self._should_prune_steps(total) and self.order:
+            sid = self._get_oldest_step_id()
+            if not sid:
+                break
+
+            subtree_size = self._get_subtree_size(sid)
+            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.
+
+        Args:
+            step_id: The parent step ID
+
+        Returns:
+            Number of child steps
+        """
+        return len(self.children.get(step_id, []))
+
+    def find_running(
+        self,
+        *,
+        task_id: str | None,
+        context_id: str | None,
+        kind: str,
+        name: str,
+    ) -> Step | None:
+        """Find a currently running step with the given parameters.
+
+        Args:
+            task_id: Task identifier
+            context_id: Context identifier
+            kind: Step kind (tool, delegate, agent)
+            name: Step name
+
+        Returns:
+            The running Step if found, None otherwise
+        """
+        key = (task_id, context_id, kind, name)
+        step_id = self._last_running.get(key)
+        if step_id:
+            st = self.by_id.get(step_id)
+            if st and st.status != "finished":
+                return st
+        for sid in reversed(list(self._iter_all_steps())):
+            st = self.by_id.get(sid)
+            if (
+                st
+                and (st.task_id, st.context_id, st.kind, st.name)
+                == (
+                    task_id,
+                    context_id,
+                    kind,
+                    name,
+                )
+                and st.status != "finished"
+            ):
+                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,
+        *,
+        task_id: str | None,
+        context_id: str | None,
+        kind: str,
+        name: str,
+        output: object | None = None,
+        duration_raw: float | None = None,
+    ) -> Step:
+        """Finish a step with the given parameters.
+
+        Args:
+            task_id: Task identifier
+            context_id: Context identifier
+            kind: Step kind (tool, delegate, agent)
+            name: Step name
+            output: Step output data
+            duration_raw: Raw duration in seconds
+
+        Returns:
+            The finished Step instance
+
+        Raises:
+            RuntimeError: If no matching step is found
+        """
+        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())):
+                st_check = self.by_id.get(sid)
+                if (
+                    st_check
+                    and st_check.task_id == task_id
+                    and st_check.context_id == context_id
+                    and st_check.kind == kind
+                    and st_check.name == name
+                ):
+                    st = st_check
+                    break
+
+            # 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)
+
+        if output:
+            st.output = output
+        st.finish(duration_raw)
+        key = (task_id, context_id, kind, name)
+        if self._last_running.get(key) == st.step_id:
+            self._last_running.pop(key, None)
+        return st
+
+    def _iter_all_steps(self) -> Iterator[str]:
+        for root in self.order:
+            yield root
+            stack = list(self.children.get(root, []))
+            while stack:
+                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",
+]