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

glaip_sdk/utils/rendering/layout/summary.py

@@ -1,74 +0,0 @@
-"""Summary panel helpers shared between renderer and viewer.
-
-Authors:
-    Raymond Christopher (raymond.christopher@gdplabs.id)
-"""
-
-from __future__ import annotations
-
-from collections.abc import Mapping
-from typing import Any
-
-from glaip_sdk.utils.rendering.layout.transcript import (
-    DEFAULT_TRANSCRIPT_THEME,
-    build_transcript_snapshot,
-    build_transcript_view,
-    normalise_meta_payload,
-)
-from glaip_sdk.utils.rendering.state import RendererState
-from glaip_sdk.utils.rendering.steps import StepManager
-
-
-def render_summary_panels(
-    state: RendererState,
-    steps: StepManager,
-    *,
-    theme: str | None = None,
-    summary_window: int | None = None,
-    include_query_panel: bool = True,
-    include_final_panel: bool = True,
-    step_status_overrides: dict[str, str] | None = None,
-) -> list[Any]:
-    """Return shared summary panels for renderer and offline viewer."""
-    resolved_theme = theme or DEFAULT_TRANSCRIPT_THEME
-    snapshot_source = state.to_snapshot() if hasattr(state, "to_snapshot") else state
-    if isinstance(snapshot_source, Mapping):
-        raw_meta = snapshot_source.get("meta")
-    else:
-        raw_meta = getattr(state, "meta", None)
-    snapshot_meta = normalise_meta_payload(raw_meta)
-    snapshot = build_transcript_snapshot(
-        snapshot_source,
-        steps,
-        meta=snapshot_meta,
-        summary_window=summary_window,
-        theme=resolved_theme,
-        step_status_overrides=step_status_overrides,
-    )
-    _header, body = build_transcript_view(snapshot, theme=resolved_theme)
-
-    return [
-        renderable
-        for renderable in body
-        if _should_include_summary_panel(
-            renderable,
-            include_query_panel=include_query_panel,
-            include_final_panel=include_final_panel,
-        )
-    ]
-
-
-def _should_include_summary_panel(
-    renderable: Any,
-    *,
-    include_query_panel: bool,
-    include_final_panel: bool,
-) -> bool:
-    """Return True when the panel should be included in the summary list."""
-    title = getattr(renderable, "title", "")
-    normalised = title.lower() if isinstance(title, str) else ""
-    if not include_query_panel and normalised == "user request":
-        return False
-    if not include_final_panel and normalised.startswith("final result"):
-        return False
-    return True

glaip_sdk/utils/rendering/layout/transcript.py

@@ -1,606 +0,0 @@
-"""Shared transcript presentation helpers.
-
-Authors:
-    Raymond Christopher (raymond.christopher@gdplabs.id)
-"""
-
-from __future__ import annotations
-
-import json
-from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
-from typing import Any
-
-from rich.console import Group
-from rich.markdown import Markdown
-from rich.text import Text
-
-from glaip_sdk.icons import ICON_AGENT
-from glaip_sdk.rich_components import AIPPanel
-from glaip_sdk.utils.rendering.layout.panels import create_final_panel
-from glaip_sdk.utils.rendering.renderer.summary_window import clamp_step_nodes
-from glaip_sdk.utils.rendering.state import RendererState
-from glaip_sdk.utils.rendering.steps import (
-    StepManager,
-    StepPresentation,
-    build_connector_prefix,
-    format_step,
-    format_step_label,
-    humanize_tool_name,
-)
-
-DEFAULT_TRANSCRIPT_THEME = "dark"
-_NO_STEPS_TEXT = Text("No steps yet", style="dim")
-
-
-@dataclass(slots=True)
-class TranscriptGlyphs:
-    """Glyph overrides for transcript presentation."""
-
-    branch_fill: str = "│   "
-    branch_empty: str = "    "
-    branch_item: str = "├─ "
-    branch_last: str = "└─ "
-    query_prefix: str = "     "
-
-
-@dataclass(slots=True)
-class TranscriptRow:
-    """Renderable row metadata for the transcript/summary tree."""
-
-    prefix: str
-    presentation: StepPresentation
-
-
-@dataclass(slots=True)
-class TranscriptSnapshot:
-    """Snapshot consumed by presenter/viewer components."""
-
-    rows: list[TranscriptRow]
-    final_panel: Any | None
-    events: list[dict[str, Any]]
-    agent_label: str | None = None
-    model_label: str | None = None
-    run_id: str | None = None
-    query_text: str | None = None
-    duration_text: str | None = None
-    window_header: Text | None = None
-    window_footer: Text | None = None
-
-
-def format_final_panel_title(state: RendererState | Mapping[str, Any], base_title: str = "Final Result") -> str:
-    """Return the final panel title including duration if available."""
-    if isinstance(state, RendererState):
-        duration_text = state.final_duration_text
-    else:
-        duration_text = state.get("final_duration_text") if isinstance(state, Mapping) else None
-    if duration_text:
-        return f"{base_title} · {duration_text}"
-    return base_title
-
-
-def build_final_panel(
-    state: RendererState | Mapping[str, Any],
-    *,
-    theme: str = DEFAULT_TRANSCRIPT_THEME,
-    title: str | None = None,
-) -> Any | None:
-    """Create a Rich panel for the renderer/viewer final output."""
-    if isinstance(state, RendererState):
-        body = (state.final_text or state.buffer.render() or "").strip()
-    else:
-        final_text = str(state.get("final_text", "")) if isinstance(state, Mapping) else ""
-        buffer_text = str(state.get("buffer_text", "")) if isinstance(state, Mapping) else ""
-        body = (final_text or buffer_text).strip()
-    if not body:
-        return None
-    panel_title = title or format_final_panel_title(state)
-    return create_final_panel(body, title=panel_title, theme=theme)
-
-
-def build_transcript_snapshot(
-    state: RendererState | Mapping[str, Any],
-    steps: StepManager,
-    *,
-    glyphs: TranscriptGlyphs | None = None,
-    query_text: str | None = None,
-    meta: Mapping[str, Any] | Sequence[tuple[str, Any]] | None = None,
-    summary_window: int | None = None,
-    theme: str = DEFAULT_TRANSCRIPT_THEME,
-    step_status_overrides: dict[str, str] | None = None,
-) -> TranscriptSnapshot:
-    """Compose a snapshot consumable by renderers/viewers alike."""
-    glyphs = glyphs or TranscriptGlyphs()
-    final_text, buffer_text, events, meta_payload, duration_text = _resolve_state_payload(state, meta)
-    query_value = query_text or extract_query_from_meta(meta_payload)
-    rows, window_header, window_footer = _build_rows(
-        steps,
-        glyphs,
-        meta_payload,
-        summary_window,
-        query_text=query_value,
-        step_status_overrides=step_status_overrides,
-    )
-    if not rows:
-        stored = meta_payload.get("transcript_steps")
-        if isinstance(stored, list) and stored:
-            rows, window_header, window_footer = _rows_from_stored_steps(stored)
-    panel_state: RendererState | Mapping[str, Any]
-    if isinstance(state, RendererState):
-        panel_state = state
-    else:
-        panel_state = {
-            "final_text": final_text,
-            "buffer_text": buffer_text,
-            "final_duration_text": duration_text,
-        }
-    final_panel = build_final_panel(panel_state, theme=theme)
-
-    return TranscriptSnapshot(
-        rows=rows,
-        final_panel=final_panel,
-        events=events,
-        agent_label=_friendly_agent_label(meta_payload),
-        model_label=meta_payload.get("model"),
-        run_id=meta_payload.get("run_id"),
-        query_text=query_value,
-        duration_text=duration_text,
-        window_header=window_header,
-        window_footer=window_footer,
-    )
-
-
-def build_transcript_view(
-    snapshot: TranscriptSnapshot,
-    *,
-    theme: str = DEFAULT_TRANSCRIPT_THEME,
-) -> tuple[list[Any], list[Any]]:
-    """Return header + body renderables for a transcript snapshot."""
-    header_renderables: list[Any] = []
-    body_renderables: list[Any] = []
-
-    header_text = _compose_header_text(snapshot)
-    if header_text is not None:
-        if theme != DEFAULT_TRANSCRIPT_THEME:
-            header_text.style = "bold black"
-        header_renderables.append(header_text)
-
-    if snapshot.query_text:
-        body_renderables.append(
-            _build_query_panel(snapshot.query_text),
-        )
-
-    body_renderables.append(
-        _build_steps_panel(
-            snapshot.rows,
-            window_header=snapshot.window_header,
-            window_footer=snapshot.window_footer,
-            theme=theme,
-        )
-    )
-
-    if snapshot.final_panel is not None:
-        body_renderables.append(snapshot.final_panel)
-
-    return header_renderables, body_renderables
-
-
-def render_final_panel(
-    console: Any,
-    state: RendererState | Mapping[str, Any],
-    *,
-    theme: str = DEFAULT_TRANSCRIPT_THEME,
-    title: str | None = None,
-) -> bool:
-    """Print the shared final panel, returning True when rendered."""
-    panel = build_final_panel(state, theme=theme, title=title)
-    if panel is None:
-        return False
-    console.print(panel)
-    console.print()
-    return True
-
-
-__all__ = [
-    "DEFAULT_TRANSCRIPT_THEME",
-    "TranscriptGlyphs",
-    "TranscriptRow",
-    "TranscriptSnapshot",
-    "build_transcript_snapshot",
-    "build_transcript_view",
-    "render_final_panel",
-    "build_final_panel",
-    "format_final_panel_title",
-    "extract_query_from_meta",
-]
-
-
-def _resolve_state_payload(
-    state: RendererState | Mapping[str, Any],
-    meta_override: Mapping[str, Any] | Sequence[tuple[str, Any]] | None,
-) -> tuple[str, str, list[dict[str, Any]], dict[str, Any], str | None]:
-    if isinstance(state, RendererState):
-        final_text = state.final_text
-        buffer_text = state.buffer.render()
-        events = list(state.events)
-        meta_payload = normalise_meta_payload(meta_override or getattr(state, "meta", None))
-        duration_text = state.final_duration_text
-    else:
-        mapping_state = dict(state) if isinstance(state, Mapping) else {}
-        final_text = str(mapping_state.get("final_text") or "")
-        buffer_text = str(mapping_state.get("buffer_text") or "")
-        events = list(mapping_state.get("events") or [])
-        base_meta = mapping_state.get("meta")
-        meta_payload = normalise_meta_payload(meta_override or base_meta)
-        duration_text = mapping_state.get("final_duration_text")
-    return final_text, buffer_text, events, meta_payload, duration_text
-
-
-def _build_rows(
-    steps: StepManager,
-    glyphs: TranscriptGlyphs,
-    meta_payload: dict[str, Any],
-    summary_window: int | None,
-    *,
-    query_text: str | None,
-    step_status_overrides: dict[str, str] | None = None,
-) -> tuple[list[TranscriptRow], Text | None, Text | None]:
-    nodes = list(steps.iter_tree())
-    header_notice: Text | None = None
-    footer_notice: Text | None = None
-    if summary_window is not None and summary_window > 0:
-        nodes, header_notice, footer_notice = _apply_summary_window(steps, nodes, summary_window)
-
-    rows: list[TranscriptRow] = []
-    for index, (step_id, branch_state) in enumerate(nodes):
-        row = _create_step_row(
-            steps,
-            glyphs,
-            meta_payload,
-            step_id,
-            branch_state,
-            step_status_overrides=step_status_overrides,
-        )
-        if row is not None:
-            rows.append(row)
-            if index == 0:
-                query_row = _create_query_hint_row(glyphs, query_text)
-                if query_row is not None:
-                    rows.append(query_row)
-
-    return rows, header_notice, footer_notice
-
-
-def _apply_summary_window(
-    steps: StepManager,
-    nodes: list[tuple[str, tuple[bool, ...]]],
-    summary_window: int,
-) -> tuple[list[tuple[str, tuple[bool, ...]]], Text | None, Text | None]:
-    """Apply summary window clamping to step nodes."""
-
-    def _get_label(step_id: str) -> str:
-        step = steps.by_id.get(step_id)
-        return format_step_label(step) if step else ""
-
-    def _get_parent(step_id: str) -> str | None:
-        step = steps.by_id.get(step_id)
-        return step.parent_id if step else None
-
-    return clamp_step_nodes(
-        nodes,
-        window=summary_window,
-        get_label=_get_label,
-        get_parent=_get_parent,
-    )
-
-
-def _create_step_row(
-    steps: StepManager,
-    glyphs: TranscriptGlyphs,
-    meta_payload: dict[str, Any],
-    step_id: str,
-    branch_state: tuple[bool, ...],
-    *,
-    step_status_overrides: dict[str, str] | None = None,
-) -> TranscriptRow | None:
-    """Create a transcript row from a step."""
-    step = steps.by_id.get(step_id)
-    if not step:
-        return None
-    override = None
-    if not branch_state and _should_override_root_label(meta_payload):
-        override = _friendly_root_label(meta_payload, step, getattr(step, "display_label", None))
-    presentation = format_step(step, glyphs=glyphs, label=override)
-    if step_status_overrides:
-        status_text = step_status_overrides.get(step_id)
-        if status_text:
-            presentation.status_text = status_text
-    prefix = build_connector_prefix(branch_state)
-    return TranscriptRow(prefix=prefix, presentation=presentation)
-
-
-def _create_query_hint_row(glyphs: TranscriptGlyphs, query_text: str | None) -> TranscriptRow | None:
-    """Create a query hint row mirroring the documented transcript output."""
-    if not query_text:
-        return None
-    return TranscriptRow(
-        prefix=glyphs.query_prefix,
-        presentation=StepPresentation(
-            step_id="query",
-            title=query_text,
-            glyph=None,
-            status_style=None,
-            args_text=None,
-            failure_reason=None,
-            duration_ms=None,
-        ),
-    )
-
-
-def _rows_from_stored_steps(entries: list[dict[str, Any]]) -> tuple[list[TranscriptRow], Text | None, Text | None]:
-    rows: list[TranscriptRow] = []
-    for index, entry in enumerate(entries):
-        title = entry.get("display_name") or entry.get("name") or "Step"
-        finished = entry.get("status") == "finished"
-        duration_ms = entry.get("duration_ms")
-        presentation = StepPresentation(
-            step_id=f"stored-{index}",
-            title=str(title),
-            glyph="✓" if finished else None,
-            status_style="green" if finished else None,
-            args_text=None,
-            failure_reason=None,
-            duration_ms=duration_ms,
-        )
-        rows.append(TranscriptRow(prefix="  ", presentation=presentation))
-    return rows, None, None
-
-
-def _compose_header_text(snapshot: TranscriptSnapshot) -> Text | None:
-    parts: list[str] = []
-    if snapshot.agent_label:
-        parts.append(snapshot.agent_label)
-    if snapshot.model_label:
-        parts.append(snapshot.model_label)
-    if snapshot.duration_text:
-        parts.append(snapshot.duration_text)
-    if snapshot.run_id:
-        parts.append(snapshot.run_id)
-    if not parts:
-        return None
-    return Text(" · ".join(parts), style="bold")
-
-
-def _build_query_panel(query_text: str) -> AIPPanel:
-    """Build a query panel."""
-    return AIPPanel(
-        Markdown(f"**Query:** {query_text.strip()}"),
-        title="User Request",
-        border_style="#d97706",
-        padding=(0, 1),
-    )
-
-
-def _build_steps_panel(
-    rows: Sequence[TranscriptRow],
-    *,
-    window_header: Text | None = None,
-    window_footer: Text | None = None,
-    theme: str = DEFAULT_TRANSCRIPT_THEME,
-) -> AIPPanel:
-    if not rows:
-        steps_body: Text | Group = _NO_STEPS_TEXT.copy()
-    else:
-        rendered = [_format_row_text(row) for row in rows]
-        style = "dim" if theme == DEFAULT_TRANSCRIPT_THEME else "default"
-        steps_body = Text("\n".join(rendered), style=style)
-
-    renderables: list[Any] = []
-    if window_header is not None:
-        renderables.append(window_header)
-    renderables.append(steps_body)
-    if window_footer is not None:
-        renderables.append(window_footer)
-
-    if len(renderables) == 1:
-        body: Any = renderables[0]
-    else:
-        body = Group(*renderables)
-
-    return AIPPanel(body, title="Steps", border_style="blue")
-
-
-def _format_row_text(row: TranscriptRow) -> str:
-    prefix = row.prefix
-    title, summary = _split_label(row.presentation.title)
-    line = f"{prefix}{title}".rstrip()
-
-    args_lines = _extract_args_lines(row)
-    has_args = bool(args_lines)
-
-    if summary:
-        line += f" — {_truncate_summary(summary)}"
-    elif has_args:
-        line += " —"
-
-    badge = _format_duration_badge(row.presentation.duration_ms)
-    status_text = row.presentation.status_text
-    if status_text:
-        line += f" {status_text}"
-    elif badge:
-        line += f" {badge}"
-
-    if row.presentation.glyph:
-        line += f" {row.presentation.glyph}"
-
-    if row.presentation.failure_reason:
-        line += f" {row.presentation.failure_reason}"
-
-    if has_args:
-        for args_line in args_lines:
-            line += f"\n{prefix}     {args_line}"
-
-    return line
-
-
-def _format_duration_badge(duration_ms: int | None) -> str | None:
-    if duration_ms is None:
-        return None
-    try:
-        duration_ms = int(duration_ms)
-    except Exception:
-        return None
-    if duration_ms <= 0:
-        value = "<1ms"
-    elif duration_ms < 1000:
-        value = f"{duration_ms}ms"
-    else:
-        seconds = duration_ms / 1000
-        value = f"{seconds:.2f}s"
-    return f"[{value}]"
-
-
-def _extract_args_lines(row: TranscriptRow) -> list[str]:
-    args_text = row.presentation.args_text
-    if _should_skip_args_summary(row, args_text):
-        return []
-
-    parsed = _parse_args_payload(args_text or "")
-    title = row.presentation.title or ""
-
-    if isinstance(parsed, dict) and parsed:
-        if title.startswith(ICON_AGENT) and set(parsed.keys()) == {"query"}:
-            return [str(parsed["query"])]
-        return [f"{key}: {json.dumps(value, ensure_ascii=False)}" for key, value in parsed.items()]
-
-    if isinstance(parsed, list):
-        return [json.dumps(parsed, ensure_ascii=False)]
-
-    return [args_text or ""]
-
-
-def _should_skip_args_summary(row: TranscriptRow, args_text: str | None) -> bool:
-    if not args_text or args_text == "{}":
-        return True
-    title = (row.presentation.title or "").strip()
-    if title.startswith("💭 Thinking…"):
-        return True
-    if not row.prefix.strip():
-        return True
-    if args_text.strip() == '{"reason":"deterministic_timeline"}':
-        return True
-    return False
-
-
-def _parse_args_payload(args_text: str) -> Any | None:
-    stripped = args_text.lstrip()
-    if stripped.startswith("{") or stripped.startswith("["):
-        try:
-            return json.loads(args_text)
-        except Exception:
-            return None
-    return None
-
-
-def _split_label(label: Any) -> tuple[str, str | None]:
-    if not isinstance(label, str):
-        try:
-            label = str(label)
-        except Exception:
-            return "Step", None
-    if "—" not in label:
-        return label, None
-    title, summary = label.split("—", 1)
-    return title.strip(), summary.strip()
-
-
-def _truncate_summary(summary: str, limit: int = 80) -> str:
-    if len(summary) <= limit:
-        return summary
-    return summary[: limit - 1] + "…"
-
-
-def _friendly_agent_label(meta: Mapping[str, Any]) -> str | None:
-    """Return a user-facing agent label for headers."""
-    raw_name = _string_or_none(meta.get("agent_name"))
-    if raw_name:
-        friendly = humanize_tool_name(raw_name)
-        if friendly:
-            return friendly
-    return _string_or_none(meta.get("agent_id"))
-
-
-def _friendly_root_label(meta: dict[str, Any], step: Any, fallback: str | None) -> str:
-    fallback_label = _string_or_none(fallback)
-    raw_agent_name = _string_or_none(meta.get("agent_name"))
-    agent_name = humanize_tool_name(raw_agent_name) if raw_agent_name else None
-    if agent_name:
-        agent_name = agent_name.title()
-    agent_name = agent_name or fallback_label
-    agent_id = _string_or_none(meta.get("agent_id") or getattr(step, "name", ""))
-
-    if not agent_name:
-        return fallback_label or agent_id or ICON_AGENT
-
-    parts = [ICON_AGENT, agent_name]
-    if agent_id and agent_id != agent_name:
-        parts.append(f"({agent_id})")
-    return " ".join(parts)
-
-
-def extract_query_from_meta(meta: Mapping[str, Any] | None) -> str | None:
-    """Return the canonical query string embedded in renderer metadata."""
-    if not meta:
-        return None
-
-    payload = dict(meta)
-    nested_meta = payload.get("meta") or {}
-    candidate = (
-        payload.get("input_message")
-        or payload.get("query")
-        or payload.get("message")
-        or nested_meta.get("input_message")
-    )
-    if isinstance(candidate, str):
-        candidate = candidate.strip()
-    return candidate or None
-
-
-def _should_override_root_label(meta: Mapping[str, Any] | None) -> bool:
-    if not meta:
-        return False
-    if meta.get("agent_name") or meta.get("agent_id"):
-        return True
-    return False
-
-
-def _string_or_none(value: Any) -> str | None:
-    if value is None:
-        return None
-    try:
-        text = str(value).strip()
-    except Exception:
-        return None
-    return text or None
-
-
-def normalise_meta_payload(meta: Any) -> dict[str, Any]:
-    """Return a defensive dictionary for arbitrary metadata payloads."""
-    if not meta:
-        return {}
-    if isinstance(meta, dict):
-        return dict(meta)
-    if isinstance(meta, Mapping):
-        try:
-            return dict(meta)
-        except Exception:
-            return {}
-    if isinstance(meta, Sequence) and not isinstance(meta, (str, bytes)):
-        try:
-            return dict(meta)
-        except Exception:
-            return {}
-    try:
-        return dict(meta)
-    except Exception:
-        return {}