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

glaip_sdk/client/run_rendering.py

@@ -7,9 +7,9 @@ Authors:
 
 from __future__ import annotations
 
-import io
 import json
 import logging
+from collections.abc import Callable
 from time import monotonic
 from typing import Any
 
@@ -19,8 +19,17 @@ from rich.console import Console as _Console
 from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
 from glaip_sdk.utils.client_utils import iter_sse_events
 from glaip_sdk.utils.rendering.models import RunStats
-from glaip_sdk.utils.rendering.renderer import RichStreamRenderer
-from glaip_sdk.utils.rendering.renderer.config import RendererConfig
+from glaip_sdk.utils.rendering.renderer import (
+    RendererFactoryOptions,
+    RichStreamRenderer,
+    make_default_renderer,
+    make_minimal_renderer,
+    make_silent_renderer,
+    make_verbose_renderer,
+)
+from glaip_sdk.utils.rendering.state import TranscriptBuffer
+
+NO_AGENT_RESPONSE_FALLBACK = "No agent response received."
 
 
 def _coerce_to_string(value: Any) -> str:
@@ -36,41 +45,6 @@ def _has_visible_text(value: Any) -> bool:
     return isinstance(value, str) and bool(value.strip())
 
 
-def _update_state_transcript(state: Any, text_value: str) -> bool:
-    """Inject transcript text into renderer state if possible."""
-    if state is None:
-        return False
-
-    updated = False
-
-    if hasattr(state, "final_text") and not _has_visible_text(getattr(state, "final_text", "")):
-        try:
-            state.final_text = text_value
-            updated = True
-        except Exception:
-            pass
-
-    buffer = getattr(state, "buffer", None)
-    if isinstance(buffer, list) and not any(_has_visible_text(item) for item in buffer):
-        buffer.append(text_value)
-        updated = True
-
-    return updated
-
-
-def _update_renderer_transcript(renderer: Any, text_value: str) -> None:
-    """Populate the renderer (or its state) with the supplied text."""
-    state = getattr(renderer, "state", None)
-    if _update_state_transcript(state, text_value):
-        return
-
-    if hasattr(renderer, "final_text") and not _has_visible_text(getattr(renderer, "final_text", "")):
-        try:
-            renderer.final_text = text_value
-        except Exception:
-            pass
-
-
 class AgentRunRenderingManager:
     """Coordinate renderer creation and streaming event handling."""
 
@@ -81,6 +55,7 @@ class AgentRunRenderingManager:
             logger: Optional logger instance, creates default if None
         """
         self._logger = logger or logging.getLogger(__name__)
+        self._buffer_factory = TranscriptBuffer
 
     # --------------------------------------------------------------------- #
     # Renderer setup helpers
@@ -92,17 +67,38 @@ class AgentRunRenderingManager:
         verbose: bool = False,
     ) -> RichStreamRenderer:
         """Create an appropriate renderer based on the supplied spec."""
+        transcript_buffer = self._buffer_factory()
+        base_options = RendererFactoryOptions(console=_Console(), transcript_buffer=transcript_buffer)
         if isinstance(renderer_spec, RichStreamRenderer):
             return renderer_spec
 
         if isinstance(renderer_spec, str):
-            if renderer_spec == "silent":
-                return self._create_silent_renderer()
-            if renderer_spec == "minimal":
-                return self._create_minimal_renderer()
-            return self._create_default_renderer(verbose)
+            lowered = renderer_spec.lower()
+            if lowered == "silent":
+                return self._attach_buffer(base_options.build(make_silent_renderer), transcript_buffer)
+            if lowered == "minimal":
+                return self._attach_buffer(base_options.build(make_minimal_renderer), transcript_buffer)
+            if lowered == "verbose":
+                return self._attach_buffer(base_options.build(make_verbose_renderer), transcript_buffer)
+
+        if verbose:
+            return self._attach_buffer(base_options.build(make_verbose_renderer), transcript_buffer)
 
-        return self._create_default_renderer(verbose)
+        default_options = RendererFactoryOptions(
+            console=_Console(),
+            transcript_buffer=transcript_buffer,
+            verbose=verbose,
+        )
+        return self._attach_buffer(default_options.build(make_default_renderer), transcript_buffer)
+
+    @staticmethod
+    def _attach_buffer(renderer: RichStreamRenderer, buffer: TranscriptBuffer) -> RichStreamRenderer:
+        """Attach a captured transcript buffer to a renderer for later inspection."""
+        try:
+            renderer._captured_transcript_buffer = buffer  # type: ignore[attr-defined]
+        except Exception:
+            pass
+        return renderer
 
     def build_initial_metadata(
         self,
@@ -123,70 +119,6 @@ class AgentRunRenderingManager:
         """Notify renderer that streaming is starting."""
         renderer.on_start(meta)
 
-    def _create_silent_renderer(self) -> RichStreamRenderer:
-        """Create a silent renderer that outputs to a string buffer.
-
-        Returns:
-            RichStreamRenderer configured for silent output.
-        """
-        silent_config = RendererConfig(
-            live=False,
-            persist_live=False,
-            render_thinking=False,
-        )
-        return RichStreamRenderer(
-            console=_Console(file=io.StringIO(), force_terminal=False),
-            cfg=silent_config,
-            verbose=False,
-        )
-
-    def _create_minimal_renderer(self) -> RichStreamRenderer:
-        """Create a minimal renderer with reduced output.
-
-        Returns:
-            RichStreamRenderer configured for minimal output.
-        """
-        minimal_config = RendererConfig(
-            live=False,
-            persist_live=False,
-            render_thinking=False,
-        )
-        return RichStreamRenderer(
-            console=_Console(),
-            cfg=minimal_config,
-            verbose=False,
-        )
-
-    def _create_verbose_renderer(self) -> RichStreamRenderer:
-        """Create a verbose renderer with detailed output.
-
-        Returns:
-            RichStreamRenderer configured for verbose output.
-        """
-        verbose_config = RendererConfig(
-            live=False,
-            append_finished_snapshots=False,
-        )
-        return RichStreamRenderer(
-            console=_Console(),
-            cfg=verbose_config,
-            verbose=True,
-        )
-
-    def _create_default_renderer(self, verbose: bool) -> RichStreamRenderer:
-        """Create the default renderer based on verbosity.
-
-        Args:
-            verbose: Whether to create a verbose renderer.
-
-        Returns:
-            RichStreamRenderer instance.
-        """
-        if verbose:
-            return self._create_verbose_renderer()
-        default_config = RendererConfig()
-        return RichStreamRenderer(console=_Console(), cfg=default_config)
-
     # --------------------------------------------------------------------- #
     # Streaming event handling
     # --------------------------------------------------------------------- #
@@ -382,7 +314,52 @@ class AgentRunRenderingManager:
             return
 
         text_value = _coerce_to_string(text)
-        _update_renderer_transcript(renderer, text_value)
+        state = getattr(renderer, "state", None)
+        if state is None:
+            self._ensure_renderer_text(renderer, text_value)
+            return
+
+        self._ensure_state_final_text(state, text_value)
+        self._ensure_state_buffer(state, text_value)
+
+    def _ensure_renderer_text(self, renderer: RichStreamRenderer, text_value: str) -> None:
+        """Best-effort assignment for renderer.final_text."""
+        if not hasattr(renderer, "final_text"):
+            return
+        current_text = getattr(renderer, "final_text", "")
+        if _has_visible_text(current_text):
+            return
+        self._safe_set_attr(renderer, "final_text", text_value)
+
+    def _ensure_state_final_text(self, state: Any, text_value: str) -> None:
+        """Best-effort assignment for renderer.state.final_text."""
+        current_text = getattr(state, "final_text", "")
+        if _has_visible_text(current_text):
+            return
+        self._safe_set_attr(state, "final_text", text_value)
+
+    def _ensure_state_buffer(self, state: Any, text_value: str) -> None:
+        """Append fallback text to the state buffer when available."""
+        buffer = getattr(state, "buffer", None)
+        if not hasattr(buffer, "append"):
+            return
+        self._safe_append(buffer.append, text_value)
+
+    @staticmethod
+    def _safe_set_attr(target: Any, attr: str, value: str) -> None:
+        """Assign attribute while masking renderer-specific failures."""
+        try:
+            setattr(target, attr, value)
+        except Exception:
+            pass
+
+    @staticmethod
+    def _safe_append(appender: Callable[[str], Any], value: str) -> None:
+        """Invoke append-like functions without leaking renderer errors."""
+        try:
+            appender(value)
+        except Exception:
+            pass
 
     # --------------------------------------------------------------------- #
     # Finalisation helpers
@@ -409,7 +386,9 @@ class AgentRunRenderingManager:
         elif hasattr(renderer, "buffer"):
             buffer_values = renderer.buffer
 
-        if buffer_values is not None:
+        if isinstance(buffer_values, TranscriptBuffer):
+            rendered_text = buffer_values.render()
+        elif buffer_values is not None:
             try:
                 rendered_text = "".join(buffer_values)
             except TypeError:
@@ -420,7 +399,7 @@ class AgentRunRenderingManager:
             self._ensure_renderer_final_content(renderer, fallback_text)
 
         renderer.on_complete(st)
-        return final_text or rendered_text or "No response content received."
+        return final_text or rendered_text or NO_AGENT_RESPONSE_FALLBACK
 
 
 def compute_timeout_seconds(kwargs: dict[str, Any]) -> float:

glaip_sdk/client/shared.py

@@ -0,0 +1,21 @@
+"""Shared helpers for client configuration wiring.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from glaip_sdk.client.base import BaseClient
+
+
+def build_shared_config(client: BaseClient) -> dict[str, Any]:
+    """Return the keyword arguments used to initialize sub-clients."""
+    return {
+        "parent_client": client,
+        "api_url": client.api_url,
+        "api_key": client.api_key,
+        "timeout": client._timeout,
+    }

glaip_sdk/models.py

@@ -23,21 +23,22 @@ class Agent(BaseModel):
     id: str
     name: str
     instruction: str | None = None
-    description: str | None = None  # Add missing description field
+    description: str | None = None
     type: str | None = None
     framework: str | None = None
     version: str | None = None
-    tools: list[dict[str, Any]] | None = None  # Backend returns ToolReference objects
-    agents: list[dict[str, Any]] | None = None  # Backend returns AgentReference objects
-    mcps: list[dict[str, Any]] | None = None  # Backend returns MCPReference objects
-    tool_configs: dict[str, Any] | None = None  # Backend returns tool configurations keyed by tool UUID
+    tools: list[dict[str, Any]] | None = None
+    agents: list[dict[str, Any]] | None = None
+    mcps: list[dict[str, Any]] | None = None
+    tool_configs: dict[str, Any] | None = None
+    mcp_configs: dict[str, Any] | None = None
     agent_config: dict[str, Any] | None = None
     timeout: int = DEFAULT_AGENT_RUN_TIMEOUT
     metadata: dict[str, Any] | None = None
     language_model_id: str | None = None
     a2a_profile: dict[str, Any] | None = None
-    created_at: datetime | None = None  # Backend returns creation timestamp
-    updated_at: datetime | None = None  # Backend returns last update timestamp
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
     _client: Any = None
 
     def _set_client(self, client: Any) -> "Agent":

glaip_sdk/utils/display.py

@@ -4,6 +4,9 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+from __future__ import annotations
+
+from importlib import import_module
 from typing import TYPE_CHECKING, Any
 
 from glaip_sdk.branding import SUCCESS, SUCCESS_STYLE
@@ -13,42 +16,47 @@ if TYPE_CHECKING:  # pragma: no cover - import-time typing helpers
     from rich.console import Console
     from rich.text import Text
 
-    from glaip_sdk.rich_components import AIPPanel
+    from glaip_sdk.rich_components import AIPanel
+else:  # pragma: no cover - runtime fallback for type checking
+    AIPanel = Any  # type: ignore[assignment]
 
 
 def _check_rich_available() -> bool:
-    """Check if Rich and our custom components can be imported."""
+    """Return True when core Rich display dependencies are importable."""
     try:
         __import__("rich.console")
         __import__("rich.text")
         __import__("glaip_sdk.rich_components")
-        return True
     except Exception:
         return False
+    return True
 
 
 RICH_AVAILABLE = _check_rich_available()
 
 
-def _create_console() -> "Console":
+def _create_console() -> Console:
     """Return a Console instance with lazy import to ease mocking."""
-    from rich.console import Console  # Local import for test friendliness
-
-    return Console()
+    if not RICH_AVAILABLE:  # pragma: no cover - defensive guard
+        raise RuntimeError("Rich Console is not available")
+    console_module = import_module("rich.console")
+    return console_module.Console()
 
 
-def _create_text(*args: Any, **kwargs: Any) -> "Text":
+def _create_text(*args: Any, **kwargs: Any) -> Text:
     """Return a Text instance with lazy import to ease mocking."""
-    from rich.text import Text  # Local import for test friendliness
+    if not RICH_AVAILABLE:  # pragma: no cover - defensive guard
+        raise RuntimeError("Rich Text is not available")
+    text_module = import_module("rich.text")
+    return text_module.Text(*args, **kwargs)
 
-    return Text(*args, **kwargs)
 
-
-def _create_panel(*args: Any, **kwargs: Any) -> "AIPPanel":
+def _create_panel(*args: Any, **kwargs: Any) -> AIPanel:
     """Return an AIPPanel instance with lazy import to ease mocking."""
-    from glaip_sdk.rich_components import AIPPanel  # Local import for test friendliness
-
-    return AIPPanel(*args, **kwargs)
+    if not RICH_AVAILABLE:  # pragma: no cover - defensive guard
+        raise RuntimeError("AIPPanel is not available")
+    components = import_module("glaip_sdk.rich_components")
+    return components.AIPPanel(*args, **kwargs)
 
 
 def print_agent_output(output: str, title: str = "Agent Output") -> None:

glaip_sdk/utils/rendering/__init__.py

@@ -10,7 +10,7 @@ from typing import Any
 from rich.console import Console
 
 from glaip_sdk.models.agent_runs import RunWithOutput
-from glaip_sdk.utils.rendering.renderer.debug import render_debug_event
+from glaip_sdk.utils.rendering.renderer.debug import render_debug_event, render_debug_event_stream
 
 
 def _parse_event_received_timestamp(event: dict[str, Any]) -> datetime | None:
@@ -80,18 +80,11 @@ def render_remote_sse_transcript(
     console.print("[bold]SSE Events[/bold]")
     console.print("[dim]────────────────────────────────────────────────────────[/dim]")
 
-    baseline: datetime | None = None
-    for event in run.output:
-        received_ts = _parse_event_received_timestamp(event)
-        if baseline is None and received_ts is not None:
-            baseline = received_ts
-        render_debug_event(
-            event,
-            console,
-            received_ts=received_ts,
-            baseline_ts=baseline,
-        )
-
+    render_debug_event_stream(
+        run.output,
+        console,
+        resolve_timestamp=_parse_event_received_timestamp,
+    )
     console.print()
 
 

glaip_sdk/utils/rendering/formatting.py

@@ -8,7 +8,6 @@ from __future__ import annotations
 
 import json
 import re
-import time
 from collections.abc import Callable
 from typing import Any
 
@@ -47,11 +46,6 @@ SENSITIVE_PATTERNS = re.compile(
     r"(?:password|secret|token|key|api_key)(?:\s*[:=]\s*[^\s,}]+)?",
     re.IGNORECASE,
 )
-CONNECTOR_VERTICAL = "│   "
-CONNECTOR_EMPTY = "    "
-CONNECTOR_BRANCH = "├─ "
-CONNECTOR_LAST = "└─ "
-ROOT_MARKER = ""
 SECRET_MASK = "••••••"
 STATUS_GLYPHS = {
     "success": ICON_STATUS_SUCCESS,
@@ -140,20 +134,11 @@ def glyph_for_status(icon_key: str | None) -> str | None:
 
 def normalise_display_label(label: str | None) -> str:
     """Return a user facing label or the Unknown fallback."""
-    label = (label or "").strip()
-    return label or "Unknown step detail"
-
-
-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)
+    if not isinstance(label, str):
+        text = ""
+    else:
+        text = label.strip()
+    return text or "Unknown step detail"
 
 
 def pretty_args(args: dict | None, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
@@ -202,16 +187,6 @@ def pretty_out(output: any, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
     return _truncate_string(output_str, max_len)
 
 
-def get_spinner_char() -> str:
-    """Get the next character for a spinner animation.
-
-    Returns:
-        A single character from the spinner frames based on current time
-    """
-    frames = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
-    return frames[int(time.time() * 10) % len(frames)]
-
-
 def get_step_icon(step_kind: str) -> str:
     """Get the appropriate icon for a step kind."""
     if step_kind == "tool":

glaip_sdk/utils/rendering/layout/__init__.py

@@ -0,0 +1,64 @@
+"""Layout utilities exposed for renderer/viewer consumers.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from glaip_sdk.utils.rendering.layout.panels import (
+    create_context_panel,
+    create_final_panel,
+    create_main_panel,
+    create_tool_panel,
+)
+from glaip_sdk.utils.rendering.layout.progress import (
+    TrailingSpinnerLine,
+    build_progress_footer,
+    format_elapsed_time,
+    format_tool_title,
+    format_working_indicator,
+    get_spinner,
+    get_spinner_char,
+    is_delegation_tool,
+)
+from glaip_sdk.utils.rendering.layout.transcript import (
+    DEFAULT_TRANSCRIPT_THEME,
+    TranscriptGlyphs,
+    TranscriptRow,
+    TranscriptSnapshot,
+    build_final_panel,
+    build_transcript_snapshot,
+    build_transcript_view,
+    extract_query_from_meta,
+    format_final_panel_title,
+    render_final_panel,
+)
+from glaip_sdk.utils.rendering.layout.summary import render_summary_panels
+
+__all__ = [
+    # Panels
+    "create_context_panel",
+    "create_final_panel",
+    "create_main_panel",
+    "create_tool_panel",
+    "render_summary_panels",
+    # Progress
+    "TrailingSpinnerLine",
+    "build_progress_footer",
+    "format_elapsed_time",
+    "format_tool_title",
+    "format_working_indicator",
+    "get_spinner",
+    "get_spinner_char",
+    "is_delegation_tool",
+    # Transcript
+    "DEFAULT_TRANSCRIPT_THEME",
+    "TranscriptGlyphs",
+    "TranscriptRow",
+    "TranscriptSnapshot",
+    "build_final_panel",
+    "build_transcript_snapshot",
+    "build_transcript_view",
+    "extract_query_from_meta",
+    "format_final_panel_title",
+    "render_final_panel",
+]

glaip_sdk/utils/rendering/{renderer → layout}/panels.py

@@ -6,6 +6,7 @@ Authors:
 
 from __future__ import annotations
 
+
 from rich.align import Align
 from rich.markdown import Markdown
 from rich.spinner import Spinner
@@ -145,3 +146,11 @@ def create_final_panel(content: str, title: str = "Final Result", theme: str = "
         border_style=SUCCESS,
         padding=(0, 1),
     )
+
+
+__all__ = [
+    "create_main_panel",
+    "create_tool_panel",
+    "create_context_panel",
+    "create_final_panel",
+]

glaip_sdk/utils/rendering/{renderer → layout}/progress.py

@@ -7,8 +7,22 @@ Authors:
 from __future__ import annotations
 
 from time import monotonic
+from typing import Any
 
-from glaip_sdk.utils.rendering.formatting import get_spinner_char
+from rich.console import Console as RichConsole
+from rich.console import Group
+from rich.measure import Measurement
+from rich.spinner import Spinner
+from rich.text import Text
+
+from glaip_sdk.utils.rendering.steps.manager import StepManager
+
+_SPINNER_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+
+def _spinner_time() -> float:
+    """Return the monotonic time used for spinner animation."""
+    return monotonic()
 
 
 def get_spinner() -> str:
@@ -16,6 +30,33 @@ def get_spinner() -> str:
     return get_spinner_char()
 
 
+def get_spinner_char() -> str:
+    """Return the spinner frame based on elapsed time."""
+    frame_index = int(_spinner_time() * 10) % len(_SPINNER_FRAMES)
+    return _SPINNER_FRAMES[frame_index]
+
+
+class TrailingSpinnerLine:
+    """Render a text line with a trailing animated Rich spinner."""
+
+    def __init__(self, base_text: Text, spinner: Spinner) -> None:
+        """Initialize spinner line with base text and spinner component."""
+        self._base_text = base_text
+        self._spinner = spinner
+
+    def __rich_console__(self, console: RichConsole, options: Any) -> Any:  # type: ignore[override]
+        """Render the text with trailing animated spinner."""
+        spinner_render = self._spinner.render(console.get_time())
+        combined = Text.assemble(self._base_text.copy(), " ", spinner_render)
+        yield combined
+
+    def __rich_measure__(self, console: RichConsole, options: Any) -> Measurement:  # type: ignore[override]
+        """Measure the combined text and spinner dimensions."""
+        snapshot = self._spinner.render(0)
+        combined = Text.assemble(self._base_text.copy(), " ", snapshot)
+        return Measurement.get(console, options, combined)
+
+
 def _resolve_elapsed_time(
     started_at: float | None,
     server_elapsed_time: float | None,
@@ -131,3 +172,31 @@ def format_tool_title(tool_name: str) -> str:
 
     # Convert snake_case to Title Case
     return clean_name.replace("_", " ").title()
+
+
+def _has_running_steps(steps: StepManager) -> bool:
+    for step in steps.by_id.values():
+        if getattr(step, "status", None) not in {"finished", "failed", "stopped"}:
+            return True
+    return False
+
+
+def build_progress_footer(
+    *,
+    state: Any,
+    steps: StepManager,
+    started_at: float | None,
+    server_elapsed_time: float | None,
+) -> Group | None:
+    """Return a trailing progress indicator when work is ongoing."""
+    if not _has_running_steps(steps):
+        return None
+
+    indicator = format_working_indicator(
+        started_at,
+        server_elapsed_time,
+        getattr(state, "streaming_started_at", None),
+    )
+    text = Text(indicator, style="dim")
+    spinner = Spinner("dots", style="dim")
+    return Group(TrailingSpinnerLine(text, spinner))