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

glaip_sdk/utils/rendering/state.py

@@ -0,0 +1,204 @@
+"""Renderer state utilities and helpers.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+from collections.abc import Iterable
+
+
+def coerce_received_at(value: Any) -> datetime | None:
+    """Coerce arbitrary values into timezone-aware datetimes 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
+
+
+def truncate_display(text: str | None, limit: int = 160) -> str:
+    """Return text capped at the given character limit with ellipsis."""
+    if not text:
+        return ""
+    stripped = str(text).strip()
+    if len(stripped) <= limit:
+        return stripped
+    return stripped[: limit - 1] + "…"
+
+
+@dataclass(slots=True)
+class TranscriptBuffer:
+    """Utility container for streaming transcript text."""
+
+    lines: list[str] = field(default_factory=list)
+
+    def append(self, value: str | None) -> None:
+        """Append a chunk of transcript text."""
+        if not value:
+            return
+        self.lines.append(value)
+
+    def extend(self, chunks: Iterable[str]) -> None:
+        """Append multiple chunks."""
+        for chunk in chunks:
+            self.append(chunk)
+
+    def clear(self) -> None:
+        """Reset the buffer."""
+        self.lines.clear()
+
+    def render(self) -> str:
+        """Return the concatenated transcript text."""
+        return "".join(self.lines)
+
+    def has_visible_text(self) -> bool:
+        """Return True when any chunk contains non-whitespace characters."""
+        return any(chunk and chunk.strip() for chunk in self.lines)
+
+    def __bool__(self) -> bool:
+        """Allow truthiness checks like a regular list."""
+        return bool(self.lines)
+
+    def __len__(self) -> int:
+        """Return buffered chunk count."""
+        return len(self.lines)
+
+    def __iter__(self):
+        """Iterate over buffered chunks."""
+        return iter(self.lines)
+
+    def __getitem__(self, index: int) -> str:
+        """Return the chunk at the requested index."""
+        return self.lines[index]
+
+    def __contains__(self, item: object) -> bool:
+        """Membership test for convenience."""
+        return item in self.lines
+
+
+@dataclass
+class RendererState:
+    """Internal state for the renderer."""
+
+    buffer: TranscriptBuffer = field(default_factory=TranscriptBuffer)
+    final_text: str = ""
+    streaming_started_at: float | None = None
+    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 record_event(self, event: dict[str, Any], *, received_at: datetime | None = None) -> None:
+        """Capture an event snapshot for transcript replay."""
+        try:
+            captured = json.loads(json.dumps(event))
+        except Exception:
+            captured = dict(event)
+
+        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.events.append(captured)
+
+    def set_final_output(self, value: str) -> None:
+        """Record the final assistant output."""
+        self.final_text = value
+
+    def append_transcript_text(self, value: str) -> None:
+        """Append streaming text to the transcript buffer."""
+        self.buffer.append(value)
+
+    def start_stream_timer(self, now: float | None) -> None:
+        """Record start timestamp when streaming begins."""
+        if now is None or self.streaming_started_at is not None:
+            return
+        self.streaming_started_at = now
+
+    def stop_stream_timer(self, now: float | None) -> float | None:
+        """Record the total elapsed duration."""
+        if now is None or self.streaming_started_at is None:
+            return None
+        duration = max(0.0, now - self.streaming_started_at)
+        self.final_duration_seconds = duration
+        return duration
+
+    def mark_final_duration(self, duration: float | None, *, formatted: str | None = None) -> None:
+        """Store the final duration metadata."""
+        if duration is not None:
+            self.final_duration_seconds = duration
+        self.final_duration_text = formatted
+
+    def to_snapshot(self) -> dict[str, Any]:
+        """Return a serialisable snapshot for presenters."""
+        return prepare_transcript_snapshot(self)
+
+
+@dataclass
+class ThinkingScopeState:
+    """Runtime bookkeeping for deterministic thinking spans."""
+
+    anchor_id: str
+    task_id: str | None
+    context_id: str | None
+    anchor_started_at: float | None = None
+    anchor_finished_at: float | None = None
+    idle_started_at: float | None = None
+    idle_started_monotonic: float | None = None
+    active_thinking_id: str | None = None
+    running_children: set[str] = field(default_factory=set)
+    closed: bool = False
+
+
+def accumulate_final_text(*, state: RendererState) -> str:
+    """Return the most relevant final text for summary panels."""
+    if state.final_text.strip():
+        return state.final_text.strip()
+    return state.buffer.render().strip()
+
+
+def prepare_transcript_snapshot(state: RendererState) -> dict[str, Any]:
+    """Return a dictionary capturing renderer transcript state."""
+    return {
+        "final_text": state.final_text,
+        "buffer_text": state.buffer.render(),
+        "events": list(state.events),
+        "meta": dict(state.meta),
+        "final_duration_seconds": state.final_duration_seconds,
+        "final_duration_text": state.final_duration_text,
+    }
+
+
+__all__ = [
+    "RendererState",
+    "ThinkingScopeState",
+    "TranscriptBuffer",
+    "accumulate_final_text",
+    "coerce_received_at",
+    "prepare_transcript_snapshot",
+    "truncate_display",
+]

glaip_sdk/utils/rendering/step_tree_state.py

@@ -0,0 +1,100 @@
+"""State container for hierarchical renderer steps.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+from glaip_sdk.utils.rendering.models import Step
+
+
+@dataclass(slots=True)
+class StepTreeState:
+    """Track hierarchical ordering, buffers, and pruning metadata."""
+
+    max_steps: int = 200
+    root_order: list[str] = field(default_factory=list)
+    child_map: dict[str, list[str]] = field(default_factory=dict)
+    buffered_children: dict[str, list[str]] = field(default_factory=dict)
+    running_by_context: dict[tuple[str | None, str | None], set[str]] = field(default_factory=dict)
+    retained_ids: set[str] = field(default_factory=set)
+    step_index: dict[str, Step] = field(default_factory=dict)
+    pending_branch_failures: set[str] = field(default_factory=set)
+
+    def link_root(self, step_id: str) -> None:
+        """Ensure a step id is present in the root ordering."""
+        if step_id not in self.root_order:
+            self.root_order.append(step_id)
+
+    def unlink_root(self, step_id: str) -> None:
+        """Remove a step id from the root ordering if present."""
+        if step_id in self.root_order:
+            self.root_order.remove(step_id)
+
+    def link_child(self, parent_id: str, child_id: str) -> None:
+        """Attach a child step to a parent."""
+        children = self.child_map.setdefault(parent_id, [])
+        if child_id not in children:
+            children.append(child_id)
+
+    def unlink_child(self, parent_id: str, child_id: str) -> None:
+        """Detach a child from a parent."""
+        children = self.child_map.get(parent_id)
+        if not children:
+            return
+
+        if child_id in children:
+            children.remove(child_id)
+        # Clean up if the list is now empty
+        if len(children) == 0:
+            self.child_map.pop(parent_id, None)
+
+    def buffer_child(self, parent_id: str, child_id: str) -> None:
+        """Track a child that is waiting for its parent to appear."""
+        queue = self.buffered_children.setdefault(parent_id, [])
+        if child_id not in queue:
+            queue.append(child_id)
+
+    def pop_buffered_children(self, parent_id: str) -> list[str]:
+        """Return any buffered children for a parent."""
+        return self.buffered_children.pop(parent_id, [])
+
+    def discard_running(self, step_id: str) -> None:
+        """Remove a step from running context tracking."""
+        for key, running in tuple(self.running_by_context.items()):
+            if step_id in running:
+                running.discard(step_id)
+                if not running:
+                    self.running_by_context.pop(key, None)
+
+    def iter_visible_tree(self) -> Iterator[tuple[str, tuple[bool, ...]]]:
+        """Yield step ids in depth-first order alongside branch metadata.
+
+        Returns:
+            Iterator of (step_id, branch_state) tuples where branch_state
+            captures whether each ancestor was the last child. This data
+            is later used by rendering helpers to draw connectors such as
+            `│`, `├─`, and `└─` consistently.
+        """
+        roots = tuple(self.root_order)
+        total_roots = len(roots)
+        for index, root_id in enumerate(roots):
+            yield root_id, ()
+            ancestor_state = (index == total_roots - 1,)
+            yield from self._walk_children(root_id, ancestor_state)
+
+    def _walk_children(
+        self, parent_id: str, ancestor_state: tuple[bool, ...]
+    ) -> Iterator[tuple[str, tuple[bool, ...]]]:
+        """Depth-first traversal helper yielding children with ancestry info."""
+        children = self.child_map.get(parent_id, [])
+        total_children = len(children)
+        for idx, child_id in enumerate(children):
+            is_last = idx == total_children - 1
+            branch_state = ancestor_state + (is_last,)
+            yield child_id, branch_state
+            yield from self._walk_children(child_id, branch_state)

glaip_sdk/utils/rendering/steps/__init__.py

@@ -0,0 +1,34 @@
+"""Step management and presentation helpers."""
+
+from glaip_sdk.utils.rendering.steps.format import (
+    UNKNOWN_STEP_DETAIL,
+    STATUS_ICON_STYLES,
+    StepPresentation,
+    build_connector_prefix,
+    compose_display_label,
+    format_step,
+    format_step_label,
+    format_tool_args,
+    humanize_tool_name,
+    resolve_label_body,
+    status_icon_for_step,
+    step_icon_for_kind,
+)
+from glaip_sdk.utils.rendering.steps.manager import StepManager, StepManagerError
+
+__all__ = [
+    "StepManager",
+    "StepManagerError",
+    "UNKNOWN_STEP_DETAIL",
+    "STATUS_ICON_STYLES",
+    "StepPresentation",
+    "build_connector_prefix",
+    "compose_display_label",
+    "format_step",
+    "format_step_label",
+    "format_tool_args",
+    "humanize_tool_name",
+    "resolve_label_body",
+    "status_icon_for_step",
+    "step_icon_for_kind",
+]