glaip-sdk 0.6.15b2__py3-none-any.whl → 0.6.15b3__py3-none-any.whl

glaip_sdk/utils/rendering/viewer/presenter.py

@@ -0,0 +1,184 @@
+"""Shared presenter utilities for CLI/offline transcript viewing.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from rich.console import Console
+
+from glaip_sdk.utils.rendering.layout.transcript import (
+    DEFAULT_TRANSCRIPT_THEME,
+    TranscriptGlyphs,
+    TranscriptSnapshot,
+    build_transcript_snapshot,
+    build_transcript_view,
+)
+from glaip_sdk.utils.rendering.renderer.debug import render_debug_event_stream
+from glaip_sdk.utils.rendering.state import RendererState, coerce_received_at
+from glaip_sdk.utils.rendering.steps import StepManager
+
+
+@dataclass(slots=True)
+class ViewerContext:
+    """Runtime context passed to transcript presenters."""
+
+    manifest_entry: dict[str, Any]
+    events: list[dict[str, Any]]
+    default_output: str
+    final_output: str
+    stream_started_at: float | None
+    meta: dict[str, Any]
+
+
+def render_post_run_view(
+    console: Console,
+    ctx: ViewerContext,
+    *,
+    glyphs: TranscriptGlyphs | None = None,
+    theme: str = DEFAULT_TRANSCRIPT_THEME,
+) -> TranscriptSnapshot:
+    """Render the default summary view and return the snapshot used."""
+    snapshot, _state = prepare_viewer_snapshot(
+        ctx,
+        glyphs=glyphs,
+        theme=theme,
+    )
+    render_transcript_view(console, snapshot, theme=theme)
+    return snapshot
+
+
+def render_transcript_view(
+    console: Console,
+    snapshot: TranscriptSnapshot,
+    *,
+    theme: str = DEFAULT_TRANSCRIPT_THEME,
+) -> None:
+    """Render the transcript summary using a prepared snapshot."""
+    header, body = build_transcript_view(snapshot, theme=theme)
+    _print_renderables(console, header + body)
+
+
+def render_transcript_events(console: Console, events: list[dict[str, Any]]) -> None:
+    """Pretty-print transcript events using shared debug presenter."""
+    if not events:
+        console.print("[dim]No SSE events were captured for this run.[/dim]")
+        console.print()
+        return
+
+    console.print("[bold]Transcript Events[/bold]")
+    console.print("[dim]────────────────────────────────────────────────────────[/dim]")
+
+    render_debug_event_stream(
+        events,
+        console,
+        resolve_timestamp=lambda event: coerce_received_at(event.get("received_at")),
+    )
+    console.print()
+
+
+def prepare_viewer_snapshot(
+    ctx: ViewerContext,
+    *,
+    glyphs: TranscriptGlyphs | None,
+    theme: str,
+) -> tuple[TranscriptSnapshot, RendererState]:
+    """Build a transcript snapshot plus renderer state for reusable viewing."""
+    state = _build_renderer_state(ctx)
+    manager = _build_steps_from_events(ctx.events)
+    query = _extract_query_from_manifest(ctx)
+    merged_meta = _merge_meta(ctx)
+    snapshot = build_transcript_snapshot(
+        state,
+        manager,
+        glyphs=glyphs,
+        query_text=query,
+        meta=merged_meta,
+        theme=theme,
+    )
+    return snapshot, state
+
+
+def _build_renderer_state(ctx: ViewerContext) -> RendererState:
+    state = RendererState()
+    state.meta = dict(ctx.meta or {})
+
+    final_text = (ctx.final_output or "").strip()
+    default_text = (ctx.default_output or "").strip()
+    if final_text:
+        state.final_text = final_text
+    elif default_text:
+        state.final_text = default_text
+        state.buffer.append(default_text)
+
+    duration = _extract_final_duration(ctx.events)
+    if duration:
+        state.final_duration_text = duration  # pragma: no cover - exercised indirectly via end-to-end tests
+    state.events = list(ctx.events or [])
+    return state
+
+
+def _build_steps_from_events(events: list[dict[str, Any]]) -> StepManager:
+    manager = StepManager()
+    for event in events or []:
+        payload = _coerce_step_event(event)
+        if not payload:
+            continue
+        try:
+            manager.apply_event(payload)
+        except ValueError:
+            continue
+    return manager
+
+
+def _coerce_step_event(event: dict[str, Any]) -> dict[str, Any] | None:
+    metadata = event.get("metadata")
+    if not isinstance(metadata, dict):
+        return None
+    if not isinstance(metadata.get("step_id"), str):
+        return None
+    return {
+        "metadata": metadata,
+        "status": event.get("status"),
+        "task_state": event.get("task_state"),
+        "content": event.get("content"),
+        "task_id": event.get("task_id"),
+        "context_id": event.get("context_id"),
+    }
+
+
+def _extract_final_duration(events: list[dict[str, Any]]) -> str | None:
+    for event in events or []:
+        metadata = event.get("metadata") or {}
+        if metadata.get("kind") != "final_response":
+            continue
+        time_value = metadata.get("time")
+        if isinstance(time_value, (int, float)):
+            return f"{float(time_value):.2f}s"
+    return None
+
+
+def _extract_query_from_manifest(ctx: ViewerContext) -> str | None:
+    query = ctx.manifest_entry.get("input_message") or ctx.meta.get("input_message") or ctx.meta.get("query")
+    if isinstance(query, str) and query.strip():
+        return query.strip()
+    return None
+
+
+def _merge_meta(ctx: ViewerContext) -> dict[str, Any]:
+    merged = dict(ctx.meta or {})
+    manifest = ctx.manifest_entry or {}
+    for key in ("agent_name", "agent_id", "model", "run_id", "input_message"):
+        if key in manifest and manifest[key] and key not in merged:
+            merged[key] = manifest[key]
+    return merged
+
+
+def _print_renderables(console: Console, renderables: list[Any]) -> None:
+    for renderable in renderables:
+        console.print(renderable)
+        console.print()

glaip_sdk/utils/resource_refs.py

@@ -0,0 +1,195 @@
+"""Resource reference utilities for ID/name extraction and UUID detection.
+
+This module provides normalized helpers for working with resource references
+across the SDK, consolidating logic that was previously duplicated between
+CLI and SDK layers.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import re
+from typing import Any
+from uuid import UUID
+
+
+def is_uuid(value: str) -> bool:
+    """Check if a string is a valid UUID.
+
+    Args:
+        value: String to check
+
+    Returns:
+        True if value is a valid UUID, False otherwise
+    """
+    try:
+        UUID(value)
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
+def _extract_id_from_item(item: Any, *, skip_missing: bool = False) -> str | None:
+    """Extract ID from a single item.
+
+    Args:
+        item: Item that may be a string, object with .id, or dict with "id" key.
+        skip_missing: If True, return None for items without IDs. If False, convert to string.
+
+    Returns:
+        Extracted ID as string, or None if skip_missing=True and no ID found.
+    """
+    if isinstance(item, str):
+        return item
+    if hasattr(item, "id"):
+        return str(item.id)
+    if isinstance(item, dict) and "id" in item:
+        return str(item["id"])
+    if skip_missing:
+        return None
+    # Fallback: convert to string
+    return str(item)
+
+
+def extract_ids(items: list[str | Any] | None) -> list[str]:
+    """Extract IDs from a list of objects or strings.
+
+    This function unifies the behavior between CLI and SDK layers, always
+    returning a list (empty list for None/empty input) rather than None.
+
+    Args:
+        items: List of items that may be strings, objects with .id, or other types
+
+    Returns:
+        List of extracted IDs (empty list if items is None/empty)
+
+    Examples:
+        extract_ids([{"id": "123"}, "456"]) -> ["123", "456"]
+        extract_ids(None) -> []
+        extract_ids([]) -> []
+    """
+    if not items:
+        return []
+
+    # Extract IDs from all items, converting non-ID items to strings
+    extracted_ids = [_extract_id_from_item(item, skip_missing=False) for item in items]
+    return [id_val for id_val in extracted_ids if id_val is not None]
+
+
+def extract_names(items: list[str | Any] | None) -> list[str]:
+    """Extract names from a list of objects or strings.
+
+    Args:
+        items: List of items that may be strings, objects with .name, or other types
+
+    Returns:
+        List of extracted names (empty list if items is None/empty)
+
+    Examples:
+        extract_names([{"name": "tool1"}, "tool2"]) -> ["tool1", "tool2"]
+        extract_names(None) -> []
+    """
+    if not items:
+        return []
+
+    names = []
+    for item in items:
+        if isinstance(item, str):
+            names.append(item)
+        elif hasattr(item, "name"):
+            names.append(str(item.name))
+        elif isinstance(item, dict) and "name" in item:
+            names.append(str(item["name"]))
+        else:
+            # Fallback: convert to string
+            names.append(str(item))
+
+    return names
+
+
+def find_by_name(items: list[Any], name: str, case_sensitive: bool = False) -> list[Any]:
+    """Filter items by name with optional case sensitivity.
+
+    This is a common pattern used across different clients for client-side
+    filtering when the backend doesn't support name query parameters.
+
+    Args:
+        items: List of items to filter
+        name: Name to search for
+        case_sensitive: Whether the search should be case sensitive
+
+    Returns:
+        Filtered list of items matching the name
+    """
+    if not name:
+        return items
+
+    if case_sensitive:
+        return [item for item in items if name in item.name]
+    else:
+        return [item for item in items if name.lower() in item.name.lower()]
+
+
+def sanitize_name(name: str) -> str:
+    """Sanitize a name for resource creation.
+
+    Args:
+        name: Raw name input
+
+    Returns:
+        Sanitized name suitable for resource creation
+    """
+    # Remove special characters and normalize
+    sanitized = re.sub(r"[^a-zA-Z0-9\-_]", "-", name.strip())
+    sanitized = re.sub(r"-+", "-", sanitized)  # Collapse multiple dashes
+    return sanitized.lower().strip("-")
+
+
+def validate_name_format(name: str, resource_type: str = "resource") -> str:
+    """Validate resource name format and return cleaned version.
+
+    Args:
+        name: Name to validate
+        resource_type: Type of resource (for error messages)
+
+    Returns:
+        Cleaned name
+
+    Raises:
+        ValueError: If name format is invalid
+    """
+    # Map resource types to proper display names
+    type_display = {"agent": "Agent", "tool": "Tool", "mcp": "MCP"}
+    display_type = type_display.get(resource_type.lower(), resource_type.title())
+
+    if not name or not name.strip():
+        raise ValueError(f"{display_type} name cannot be empty")
+
+    cleaned_name = name.strip()
+
+    if len(cleaned_name) < 1:
+        raise ValueError(f"{display_type} name cannot be empty")
+
+    if len(cleaned_name) > 100:
+        raise ValueError(f"{display_type} name cannot be longer than 100 characters")
+
+    # Check for valid characters (alphanumeric, hyphens, underscores)
+    if not re.match(r"^[a-zA-Z0-9_-]+$", cleaned_name):
+        raise ValueError(f"{display_type} name can only contain letters, numbers, hyphens, and underscores")
+
+    return cleaned_name
+
+
+def validate_name_uniqueness(name: str, existing_names: list[str], resource_type: str = "resource") -> None:
+    """Validate that a resource name is unique.
+
+    Args:
+        name: Name to validate
+        existing_names: List of existing names to check against
+        resource_type: Type of resource (for error messages)
+
+    Raises:
+        ValueError: If name is not unique
+    """
+    if name.lower() in [existing.lower() for existing in existing_names]:
+        raise ValueError(f"A {resource_type.lower()} named '{name}' already exists. Please choose a unique name.")

glaip_sdk/utils/run_renderer.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Modern run renderer for agent execution with clean streaming output.
+
+This module provides a modern CLI experience similar to Claude Code and Gemini CLI,
+with compact headers, streaming markdown, collapsible tool steps, and clean output.
+
+This is a compatibility shim that re-exports components from the new modular renderer package.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+# Configure logger
+import logging
+
+from glaip_sdk.utils.rendering.models import RunStats
+
+# Re-export main components from the new modular renderer package
+from glaip_sdk.utils.rendering.renderer.base import RichStreamRenderer
+from glaip_sdk.utils.rendering.renderer.config import RendererConfig
+from glaip_sdk.utils.rendering.renderer.console import CapturingConsole
+
+# Legacy imports for backward compatibility
+from glaip_sdk.utils.rendering.renderer.debug import render_debug_event
+from glaip_sdk.utils.rendering.steps import StepManager
+
+logger = logging.getLogger("glaip_sdk.run_renderer")
+
+
+# The full implementation has been moved to glaip_sdk.utils.rendering.renderer.base
+# This file now serves as a compatibility shim for existing imports.
+__all__ = [
+    "CapturingConsole",
+    "RendererConfig",
+    "RichStreamRenderer",
+    "RunStats",
+    "StepManager",
+    "render_debug_event",
+]