glaip-sdk 0.6.11__py3-none-any.whl → 0.6.14__py3-none-any.whl

glaip_sdk/utils/rendering/steps/format.py

@@ -1,176 +0,0 @@
-"""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

@@ -1,387 +0,0 @@
-"""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

@@ -1,36 +0,0 @@
-"""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

@@ -1,21 +0,0 @@
-"""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",
-]