glaip-sdk 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

glaip_sdk/cli/transcript/viewer.py

@@ -25,6 +25,7 @@ except Exception:  # pragma: no cover - optional dependency
     Choice = None  # type: ignore[assignment]
 
 from glaip_sdk.cli.transcript.cache import suggest_filename
+from glaip_sdk.cli.utils import prompt_export_choice_questionary, questionary_safe_ask
 from glaip_sdk.icons import ICON_AGENT, ICON_DELEGATE, ICON_TOOL_STEP
 from glaip_sdk.rich_components import AIPPanel
 from glaip_sdk.utils.rendering.formatting import (
@@ -85,6 +86,7 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
     # Rendering helpers
     # ------------------------------------------------------------------
     def _render(self) -> None:
+        """Render the transcript viewer interface."""
         try:
             if self.console.is_terminal:
                 self.console.clear()
@@ -115,12 +117,22 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
             self._render_transcript_view(query)
 
     def _render_default_view(self, query: str | None) -> None:
+        """Render the default summary view.
+
+        Args:
+            query: Optional user query to display.
+        """
         if query:
             self._render_user_query(query)
         self._render_steps_summary()
         self._render_final_panel()
 
     def _render_transcript_view(self, query: str | None) -> None:
+        """Render the full transcript view with events.
+
+        Args:
+            query: Optional user query to display.
+        """
         if not self.ctx.events:
             self.console.print("[dim]No SSE events were captured for this run.[/dim]")
             return
@@ -148,6 +160,7 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         self.console.print()
 
     def _render_final_panel(self) -> None:
+        """Render the final result panel."""
         content = self.ctx.final_output or self.ctx.default_output or "No response content captured."
         title = "Final Result"
         duration_text = self._extract_final_duration()
@@ -161,6 +174,7 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
     # Interaction loops
     # ------------------------------------------------------------------
     def _fallback_loop(self) -> None:
+        """Fallback interaction loop for non-interactive terminals."""
         while True:
             try:
                 ch = click.getchar()
@@ -181,6 +195,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
                 continue
 
     def _handle_command(self, raw: str) -> bool:
+        """Handle a command input.
+
+        Args:
+            raw: Raw command string.
+
+        Returns:
+            True to continue, False to exit.
+        """
         lowered = raw.lower()
         if lowered in {"exit", "quit", "q"}:
             return True
@@ -238,38 +260,10 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     def _prompt_export_choice(self, default_path: Path, default_display: str) -> tuple[str, Any] | None:
         """Render interactive export menu with numeric shortcuts."""
-        if not self.console.is_terminal or questionary is None or Choice is None:
-            return None
-
-        try:
-            answer = questionary.select(
-                "Export transcript",
-                choices=[
-                    Choice(
-                        title=f"Save to default ({default_display})",
-                        value=("default", default_path),
-                        shortcut_key="1",
-                    ),
-                    Choice(
-                        title="Choose a different path",
-                        value=("custom", None),
-                        shortcut_key="2",
-                    ),
-                    Choice(
-                        title="Cancel",
-                        value=("cancel", None),
-                        shortcut_key="3",
-                    ),
-                ],
-                use_shortcuts=True,
-                instruction="Press 1-3 (or arrows) then Enter.",
-            ).ask()
-        except Exception:
+        if not self.console.is_terminal:
             return None
 
-        if answer is None:
-            return ("cancel", None)
-        return answer
+        return prompt_export_choice_questionary(default_path, default_display)
 
     def _prompt_custom_destination(self) -> Path | None:
         """Prompt for custom export path with filesystem completion."""
@@ -277,11 +271,12 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
             return None
 
         try:
-            response = questionary.path(
+            question = questionary.path(
                 "Destination path (Tab to autocomplete):",
                 default="",
                 only_directories=False,
-            ).ask()
+            )
+            response = questionary_safe_ask(question)
         except Exception:
             return None
 
@@ -339,15 +334,26 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
             self.console.print(f"[red]Failed to export transcript: {exc}[/red]")
 
     def _print_command_hint(self) -> None:
+        """Print command hint for user interaction."""
         self.console.print("[dim]Ctrl+T to toggle transcript · type `e` to export · press Enter to exit[/dim]")
         self.console.print()
 
     def _get_user_query(self) -> str | None:
+        """Extract user query from metadata or manifest.
+
+        Returns:
+            User query string or None.
+        """
         meta = self.ctx.meta or {}
         manifest = self.ctx.manifest_entry or {}
         return meta.get("input_message") or meta.get("query") or meta.get("message") or manifest.get("input_message")
 
     def _render_user_query(self, query: str) -> None:
+        """Render user query in a panel.
+
+        Args:
+            query: User query string to render.
+        """
         panel = AIPPanel(
             Markdown(f"Query: {query}"),
             title="User Request",
@@ -357,6 +363,7 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         self.console.print()
 
     def _render_steps_summary(self) -> None:
+        """Render steps summary panel."""
         stored_lines = self.ctx.meta.get("transcript_step_lines")
         if stored_lines:
             body = Text("\n".join(stored_lines), style="dim")
@@ -373,6 +380,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _format_steps_summary(steps: list[dict[str, Any]]) -> str:
+        """Format steps summary as text.
+
+        Args:
+            steps: List of step dictionaries.
+
+        Returns:
+            Formatted text string.
+        """
         if not steps:
             return "  No steps yet"
 
@@ -388,6 +403,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _extract_event_time(event: dict[str, Any]) -> float | None:
+        """Extract timestamp from event metadata.
+
+        Args:
+            event: Event dictionary.
+
+        Returns:
+            Time value as float or None.
+        """
         metadata = event.get("metadata") or {}
         time_value = metadata.get("time")
         try:
@@ -399,6 +422,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _parse_received_timestamp(event: dict[str, Any]) -> datetime | None:
+        """Parse received timestamp from event.
+
+        Args:
+            event: Event dictionary.
+
+        Returns:
+            Parsed datetime or None.
+        """
         value = event.get("received_at")
         if not value:
             return None
@@ -412,6 +443,11 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         return None
 
     def _extract_final_duration(self) -> str | None:
+        """Extract final duration from events.
+
+        Returns:
+            Duration string or None.
+        """
         for event in self.ctx.events:
             metadata = event.get("metadata") or {}
             if metadata.get("kind") == "final_response":
@@ -424,6 +460,11 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         return None
 
     def _build_step_summary(self) -> list[dict[str, Any]]:
+        """Build step summary from stored steps or events.
+
+        Returns:
+            List of step dictionaries.
+        """
         stored = self.ctx.meta.get("transcript_steps")
         if isinstance(stored, list) and stored:
             return [
@@ -496,6 +537,15 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         is_last: bool,
         lines: list[str],
     ) -> None:
+        """Recursively render a tree branch of steps.
+
+        Args:
+            manager: StepManager instance.
+            step_id: ID of step to render.
+            ancestor_state: Tuple of ancestor branch states.
+            is_last: Whether this is the last child.
+            lines: List to append rendered lines to.
+        """
         step = manager.by_id.get(step_id)
         if not step:
             return
@@ -525,6 +575,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
             )
 
     def _should_hide_step(self, step: Any) -> bool:
+        """Check if a step should be hidden.
+
+        Args:
+            step: Step object.
+
+        Returns:
+            True if step should be hidden.
+        """
         if getattr(step, "parent_id", None) is None:
             return False
         name = getattr(step, "name", "") or ""
@@ -536,6 +594,13 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         root_id: str,
         lines: list[str],
     ) -> None:
+        """Decorate root step presentation with friendly label.
+
+        Args:
+            manager: StepManager instance.
+            root_id: Root step ID.
+            lines: Lines list to modify.
+        """
         if not lines:
             return
 
@@ -554,6 +619,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
             lines.insert(1, f"     {query}")
 
     def _coerce_step_event(self, event: dict[str, Any]) -> dict[str, Any] | None:
+        """Coerce event to step event format.
+
+        Args:
+            event: Event dictionary.
+
+        Returns:
+            Step event dictionary or None.
+        """
         metadata = event.get("metadata")
         if not isinstance(metadata, dict):
             return None
@@ -569,6 +642,15 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         }
 
     def _format_tree_line(self, step: Any, branch_state: tuple[bool, ...]) -> str:
+        """Format a tree line for a step.
+
+        Args:
+            step: Step object.
+            branch_state: Branch state tuple.
+
+        Returns:
+            Formatted line string.
+        """
         prefix = build_connector_prefix(branch_state)
         raw_label = normalise_display_label(getattr(step, "display_label", None))
         title, summary = self._split_label(raw_label)
@@ -594,6 +676,15 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         return line
 
     def _friendly_root_label(self, step: Any, fallback: str | None) -> str:
+        """Generate friendly label for root step.
+
+        Args:
+            step: Step object.
+            fallback: Fallback label string.
+
+        Returns:
+            Friendly label string.
+        """
         agent_name = self.ctx.manifest_entry.get("agent_name") or (self.ctx.meta or {}).get("agent_name")
         agent_id = self.ctx.manifest_entry.get("agent_id") or getattr(step, "name", "")
 
@@ -607,6 +698,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _format_duration_badge(step: Any) -> str | None:
+        """Format duration badge for a step.
+
+        Args:
+            step: Step object.
+
+        Returns:
+            Duration badge string or None.
+        """
         duration_ms = getattr(step, "duration_ms", None)
         if duration_ms is None:
             return None
@@ -626,6 +725,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _split_label(label: str) -> tuple[str, str | None]:
+        """Split label into title and summary.
+
+        Args:
+            label: Label string.
+
+        Returns:
+            Tuple of (title, summary).
+        """
         if " — " in label:
             title, summary = label.split(" — ", 1)
             return title.strip(), summary.strip()
@@ -633,6 +740,15 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _truncate_summary(summary: str, limit: int = 48) -> str:
+        """Truncate summary to specified length.
+
+        Args:
+            summary: Summary string.
+            limit: Maximum length.
+
+        Returns:
+            Truncated summary string.
+        """
         summary = summary.strip()
         if len(summary) <= limit:
             return summary
@@ -640,6 +756,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _looks_like_uuid(value: str) -> bool:
+        """Check if string looks like a UUID.
+
+        Args:
+            value: String to check.
+
+        Returns:
+            True if value looks like UUID.
+        """
         stripped = value.replace("-", "").replace(" ", "")
         if len(stripped) not in {32, 36}:
             return False
@@ -647,6 +771,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _format_duration_from_ms(value: Any) -> str | None:
+        """Format duration from milliseconds.
+
+        Args:
+            value: Duration value in milliseconds.
+
+        Returns:
+            Formatted duration string or None.
+        """
         try:
             if value is None:
                 return None
@@ -662,12 +794,29 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _is_step_event(metadata: dict[str, Any]) -> bool:
+        """Check if metadata represents a step event.
+
+        Args:
+            metadata: Event metadata dictionary.
+
+        Returns:
+            True if metadata represents a step event.
+        """
         kind = metadata.get("kind")
         return kind in {"agent_step", "agent_thinking_step"}
 
     def _iter_step_candidates(
         self, event: dict[str, Any], metadata: dict[str, Any]
     ) -> Iterable[tuple[str, dict[str, Any]]]:
+        """Iterate step candidates from event.
+
+        Args:
+            event: Event dictionary.
+            metadata: Event metadata dictionary.
+
+        Yields:
+            Tuples of (step_name, step_info).
+        """
         tool_info = metadata.get("tool_info") or {}
 
         yielded = False
@@ -691,6 +840,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
     def _iter_tool_call_candidates(
         tool_info: dict[str, Any],
     ) -> Iterable[tuple[str, dict[str, Any]]]:
+        """Iterate tool call candidates from tool_info.
+
+        Args:
+            tool_info: Tool info dictionary.
+
+        Yields:
+            Tuples of (tool_name, tool_call_info).
+        """
         tool_calls = tool_info.get("tool_calls")
         if isinstance(tool_calls, list):
             for call in tool_calls:
@@ -702,6 +859,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
     def _extract_direct_tool(
         tool_info: dict[str, Any],
     ) -> tuple[str, dict[str, Any]] | None:
+        """Extract direct tool from tool_info.
+
+        Args:
+            tool_info: Tool info dictionary.
+
+        Returns:
+            Tuple of (tool_name, tool_info) or None.
+        """
         if isinstance(tool_info, dict):
             name = tool_info.get("name")
             if name:
@@ -710,6 +875,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _extract_completed_name(event: dict[str, Any]) -> str | None:
+        """Extract completed tool name from event content.
+
+        Args:
+            event: Event dictionary.
+
+        Returns:
+            Tool name or None.
+        """
         content = event.get("content") or ""
         if isinstance(content, str) and content.startswith("Completed "):
             name = content.replace("Completed ", "").strip()
@@ -723,6 +896,16 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         order: list[str],
         name: str,
     ) -> dict[str, Any]:
+        """Ensure step entry exists, creating if needed.
+
+        Args:
+            steps: Steps dictionary.
+            order: Order list.
+            name: Step name.
+
+        Returns:
+            Step dictionary.
+        """
         if name not in steps:
             steps[name] = {
                 "name": name,
@@ -742,6 +925,14 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
         info: dict[str, Any],
         event: dict[str, Any],
     ) -> None:
+        """Apply update to step from event metadata.
+
+        Args:
+            step: Step dictionary to update.
+            metadata: Event metadata.
+            info: Step info dictionary.
+            event: Event dictionary.
+        """
         status = metadata.get("status")
         event_time = metadata.get("time")
 
@@ -760,6 +951,15 @@ class PostRunViewer:  # pragma: no cover - interactive flows are not unit tested
 
     @staticmethod
     def _is_step_finished(metadata: dict[str, Any], event: dict[str, Any]) -> bool:
+        """Check if step is finished.
+
+        Args:
+            metadata: Event metadata.
+            event: Event dictionary.
+
+        Returns:
+            True if step is finished.
+        """
         status = metadata.get("status")
         return status == "finished" or bool(event.get("final"))
 

glaip_sdk/cli/update_notifier.py

@@ -8,7 +8,6 @@ from __future__ import annotations
 
 import importlib
 import logging
-import os
 from collections.abc import Callable, Iterable, Iterator
 from contextlib import contextmanager
 from typing import Any, Literal
@@ -26,6 +25,7 @@ from glaip_sdk.branding import (
     WARNING_STYLE,
 )
 from glaip_sdk.cli.commands.update import update_command
+from glaip_sdk.cli.constants import UPDATE_CHECK_ENABLED
 from glaip_sdk.cli.utils import command_hint, format_command_hint
 from glaip_sdk.rich_components import AIPPanel
 
@@ -72,7 +72,7 @@ def _fetch_latest_version(package_name: str) -> str | None:
 
 def _should_check_for_updates() -> bool:
     """Return False when update checks are explicitly disabled."""
-    return os.getenv("AIP_NO_UPDATE_CHECK") is None
+    return UPDATE_CHECK_ENABLED
 
 
 def _build_update_panel(