glaip-sdk 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

glaip_sdk/cli/transcript/viewer.py

@@ -85,6 +85,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 +116,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 +159,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 +173,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 +194,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
@@ -339,15 +360,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 +389,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 +406,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 +429,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 +448,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 +469,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 +486,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 +563,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 +601,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 +620,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 +645,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 +668,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 +702,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 +724,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 +751,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 +766,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 +782,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 +797,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 +820,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 +866,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 +885,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 +901,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 +922,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 +951,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 +977,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(
@@ -244,6 +244,7 @@ def _suppress_library_logging(
 def _refresh_installed_version(console: Console, ctx: Any) -> None:
     """Reload runtime metadata after an in-process upgrade."""
     new_version: str | None = None
+    branding_module: Any | None = None
 
     try:
         version_module = importlib.reload(importlib.import_module("glaip_sdk._version"))
@@ -252,16 +253,18 @@ def _refresh_installed_version(console: Console, ctx: Any) -> None:
         _LOGGER.debug("Failed to reload glaip_sdk._version: %s", exc, exc_info=True)
 
     try:
-        branding_module = importlib.import_module("glaip_sdk.branding")
+        branding_module = importlib.reload(importlib.import_module("glaip_sdk.branding"))
         if new_version:
             branding_module.SDK_VERSION = new_version
     except Exception as exc:  # pragma: no cover - defensive guard
         _LOGGER.debug("Failed to update branding metadata: %s", exc, exc_info=True)
+        branding_module = None
 
     session = _get_slash_session(ctx)
     if session and hasattr(session, "refresh_branding"):
         try:
-            session.refresh_branding(new_version)
+            branding_cls = getattr(branding_module, "AIPBranding", None) if branding_module else None
+            session.refresh_branding(new_version, branding_cls=branding_cls)
             return
         except Exception as exc:  # pragma: no cover - defensive guard
             _LOGGER.debug("Failed to refresh active slash session: %s", exc, exc_info=True)

glaip_sdk/cli/utils.py

@@ -18,9 +18,10 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 
 import click
+import yaml
 from rich.console import Console, Group
 from rich.markdown import Markdown
-from rich.pretty import Pretty
+from rich.syntax import Syntax
 
 from glaip_sdk import _version as _version_module
 from glaip_sdk.branding import (
@@ -30,9 +31,40 @@ from glaip_sdk.branding import (
     SUCCESS_STYLE,
     WARNING_STYLE,
 )
+from glaip_sdk.cli import masking, pager
+from glaip_sdk.cli.constants import LITERAL_STRING_THRESHOLD, TABLE_SORT_ENABLED
+from glaip_sdk.cli.config import load_config
+from glaip_sdk.cli.context import (
+    _get_view,
+    detect_export_format as _detect_export_format,
+    get_ctx_value,
+)
 from glaip_sdk.cli.rich_helpers import markup_text
 from glaip_sdk.icons import ICON_AGENT
-from glaip_sdk.rich_components import AIPPanel
+from glaip_sdk.rich_components import AIPPanel, AIPTable
+from glaip_sdk.utils import is_uuid
+from glaip_sdk.utils.rendering.renderer import (
+    CapturingConsole,
+    RendererConfig,
+    RichStreamRenderer,
+)
+
+
+class _LiteralYamlDumper(yaml.SafeDumper):
+    """YAML dumper that emits literal scalars for multiline strings."""
+
+
+def _literal_str_representer(dumper: yaml.Dumper, data: str) -> yaml.nodes.ScalarNode:
+    """Represent strings in YAML, using literal blocks for verbose values."""
+    needs_literal = "\n" in data or "\r" in data
+    if not needs_literal and LITERAL_STRING_THRESHOLD and len(data) >= LITERAL_STRING_THRESHOLD:  # pragma: no cover
+        needs_literal = True
+
+    style = "|" if needs_literal else None
+    return dumper.represent_scalar("tag:yaml.org,2002:str", data, style=style)
+
+
+_LiteralYamlDumper.add_representer(str, _literal_str_representer)
 
 # Optional interactive deps (fuzzy palette)
 try:
@@ -56,22 +88,6 @@ except Exception:  # pragma: no cover - optional dependency
 
 if TYPE_CHECKING:  # pragma: no cover - import-only during type checking
     from glaip_sdk import Client
-from glaip_sdk.cli import masking, pager
-from glaip_sdk.cli.config import load_config
-from glaip_sdk.cli.context import (
-    _get_view,
-    get_ctx_value,
-)
-from glaip_sdk.cli.context import (
-    detect_export_format as _detect_export_format,
-)
-from glaip_sdk.rich_components import AIPTable
-from glaip_sdk.utils import is_uuid
-from glaip_sdk.utils.rendering.renderer import (
-    CapturingConsole,
-    RendererConfig,
-    RichStreamRenderer,
-)
 
 console = Console()
 pager.console = console
@@ -602,6 +618,7 @@ def _prompt_with_auto_select(
     valid_choices = set(choices)
 
     def _auto_select(_: Buffer) -> None:
+        """Auto-select text when a valid choice is entered."""
         text = buffer.text
         if not text or text not in valid_choices:
             return
@@ -635,9 +652,23 @@ class _FuzzyCompleter:
     """Fuzzy completer for prompt_toolkit."""
 
     def __init__(self, words: list[str]) -> None:
+        """Initialize fuzzy completer with word list.
+
+        Args:
+            words: List of words to complete from.
+        """
         self.words = words
 
     def get_completions(self, document: Any, _complete_event: Any) -> Any:  # pragma: no cover
+        """Get fuzzy completions for the current word.
+
+        Args:
+            document: Document object from prompt_toolkit.
+            _complete_event: Completion event (unused).
+
+        Yields:
+            Completion objects matching the current word.
+        """
         word = document.get_word_before_cursor()
         if not word:
             return
@@ -769,7 +800,7 @@ def _fuzzy_score(search: str, target: str) -> int:
     return score
 
 
-# ----------------------------- Pretty outputs ---------------------------- #
+# ----------------------- Structured renderer helpers -------------------- #
 
 
 def _coerce_result_payload(result: Any) -> Any:
@@ -811,6 +842,37 @@ def _render_markdown_output(data: Any) -> None:
         click.echo(str(data))
 
 
+def _format_yaml_text(data: Any) -> str:
+    """Convert structured payloads to YAML for readability."""
+    try:
+        yaml_text = yaml.dump(
+            data,
+            sort_keys=False,
+            default_flow_style=False,
+            allow_unicode=True,
+            Dumper=_LiteralYamlDumper,
+        )
+    except Exception:  # pragma: no cover - defensive YAML fallback
+        try:
+            return str(data)
+        except Exception:  # pragma: no cover - defensive str fallback
+            return repr(data)
+
+    yaml_text = yaml_text.rstrip()
+    if yaml_text.endswith("..."):  # pragma: no cover - defensive YAML cleanup
+        yaml_text = yaml_text[:-3].rstrip()
+    return yaml_text
+
+
+def _build_yaml_renderable(data: Any) -> Any:
+    """Return a syntax-highlighted YAML renderable when possible."""
+    yaml_text = _format_yaml_text(data) or "# No data"
+    try:
+        return Syntax(yaml_text, "yaml", word_wrap=False)
+    except Exception:  # pragma: no cover - defensive syntax highlighting fallback
+        return yaml_text
+
+
 def output_result(
     ctx: Any,
     result: Any,
@@ -843,7 +905,7 @@ def output_result(
         _render_markdown_output(data)
         return
 
-    renderable = Pretty(data)
+    renderable = _build_yaml_renderable(data)
     if panel_title:
         console.print(AIPPanel(renderable, title=panel_title))
     else:
@@ -854,7 +916,7 @@ def output_result(
 # ----------------------------- List rendering ---------------------------- #
 
 # Threshold no longer used - fuzzy palette is always default for TTY
-# _PICK_THRESHOLD = int(os.getenv("AIP_PICK_THRESHOLD", "5") or "5")
+# _PICK_THRESHOLD = 5
 
 
 def _normalise_rows(items: list[Any], transform_func: Callable[[Any], dict[str, Any]] | None) -> list[dict[str, Any]]:
@@ -902,12 +964,7 @@ def _render_markdown_list(rows: list[dict[str, Any]], title: str, columns: list[
 
 def _should_sort_rows(rows: list[dict[str, Any]]) -> bool:
     """Return True when rows should be name-sorted prior to rendering."""
-    return (
-        os.getenv("AIP_TABLE_NO_SORT", "0") not in ("1", "true", "on")
-        and rows
-        and isinstance(rows[0], dict)
-        and "name" in rows[0]
-    )
+    return TABLE_SORT_ENABLED and rows and isinstance(rows[0], dict) and "name" in rows[0]
 
 
 def _create_table(columns: list[tuple[str, str, str, int | None]], title: str) -> Any: