glaip-sdk 0.1.2__py3-none-any.whl → 0.7.17__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

@@ -29,6 +29,28 @@ def is_uuid(value: str) -> bool:
         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.
 
@@ -49,19 +71,9 @@ def extract_ids(items: list[str | Any] | None) -> list[str]:
     if not items:
         return []
 
-    ids = []
-    for item in items:
-        if isinstance(item, str):
-            ids.append(item)
-        elif hasattr(item, "id"):
-            ids.append(str(item.id))
-        elif isinstance(item, dict) and "id" in item:
-            ids.append(str(item["id"]))
-        else:
-            # Fallback: convert to string
-            ids.append(str(item))
-
-    return ids
+    # 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]:

glaip_sdk/utils/runtime_config.py

@@ -0,0 +1,426 @@
+"""Runtime configuration helpers for agent execution.
+
+Provides utilities for normalizing runtime_config keys from various input types
+(SDK objects, UUIDs, names) to stable platform IDs.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from collections.abc import Mapping
+
+from glaip_sdk.utils.resource_refs import is_uuid
+from gllm_core.utils import LoggerManager
+
+if TYPE_CHECKING:
+    from glaip_sdk.agents import Agent
+    from glaip_sdk.mcps import MCP
+    from glaip_sdk.registry import AgentRegistry, MCPRegistry, ToolRegistry
+    from glaip_sdk.tools import Tool
+
+    # Type alias for config key inputs (only used in type hints)
+    ConfigKeyInput = str | Agent | Tool | MCP | type[Agent] | type[Tool] | type[MCP]
+
+    # Type alias for registry types
+    Registry = ToolRegistry | MCPRegistry | AgentRegistry
+
+    # Type alias for runtime config dict shape after normalization
+    # Top-level keys include:
+    # - "tool_configs", "mcp_configs", "agent_config"
+    # - Agent IDs for agent-specific overrides
+    # Values are nested dictionaries whose contents depend on the section.
+    RuntimeConfigDict = dict[str, dict[str, object]]
+
+logger = LoggerManager().get_logger(__name__)
+
+# Config fields that need key normalization (maps field name to registry type)
+_NORMALIZABLE_FIELDS = {
+    "tool_configs": "tool",
+    "mcp_configs": "mcp",
+}
+
+# Config fields that are preserved as-is (no normalization needed)
+_PASSTHROUGH_FIELDS = {"agent_config"}
+
+
+def _extract_id_from_key(key: ConfigKeyInput) -> str | None:
+    """Extract ID directly from key if available.
+
+    Args:
+        key: The config key to extract ID from.
+
+    Returns:
+        The ID string if available, None otherwise.
+    """
+    if isinstance(key, str) and is_uuid(key):
+        return key
+    if hasattr(key, "id") and key.id is not None:
+        return key.id
+    return None
+
+
+def _resolve_via_registry(key: ConfigKeyInput, registry: Registry | None) -> str | None:
+    """Attempt to resolve key via registry.
+
+    Args:
+        key: The config key to resolve.
+        registry: Registry to use for resolution.
+
+    Returns:
+        The resolved ID string if successful, None otherwise.
+    """
+    if registry is None:
+        return None
+
+    try:
+        return registry.resolve(key).id
+    except (KeyError, ValueError, AttributeError) as exc:
+        logger.debug("Failed to resolve key via registry: %r", key, exc_info=exc)
+        return None
+    except Exception as exc:  # pragma: no cover - unexpected failures
+        logger.warning(
+            "Unexpected error resolving key via registry for %r: %s",
+            key,
+            exc,
+            exc_info=True,
+        )
+        return None
+
+
+def _resolve_config_key(
+    key: ConfigKeyInput,
+    registry: Registry | None,
+    *,
+    missing_registry_message: str,
+    unresolved_message: str,
+) -> str:
+    """Resolve a config key using a registry when needed.
+
+    For non-ID keys this always requires a registry; callers customize the
+    error messages for missing registries vs unresolved keys.
+    """
+    # Allow direct UUID / object.id without needing a registry
+    if (extracted_id := _extract_id_from_key(key)) is not None:
+        return extracted_id
+
+    # For non-ID keys we always require a registry
+    if registry is None:
+        raise ValueError(missing_registry_message.format(key=key))
+
+    if (resolved_id := _resolve_via_registry(key, registry)) is not None:
+        return resolved_id
+
+    raise ValueError(unresolved_message.format(key=key))
+
+
+def _normalize_section_keys(
+    config_section: dict[ConfigKeyInput, dict[str, object]],
+    registry: Registry | None,
+) -> dict[str, dict[str, object]]:
+    """Normalize keys in a single config section (e.g. tool_configs).
+
+    Converts ConfigKeyInput keys (SDK objects, names, classes) to stable IDs
+    using the provided registry.
+
+    Example:
+        Input:  {ToolClass: {"param": "value"}, "tool-name": {"x": 1}}
+        Output: {"uuid-1": {"param": "value"}, "uuid-2": {"x": 1}}
+
+    Args:
+        config_section: The config section dict to normalize.
+        registry: Registry to use for resolving keys.
+
+    Returns:
+        Normalized config section with all keys converted to IDs.
+    """
+    normalized: dict[str, dict[str, object]] = {}
+    for key, value in config_section.items():
+        resolved_id = _resolve_config_key(
+            key,
+            registry,
+            missing_registry_message="Unable to resolve runtime_config key via registry: {key!r}",
+            unresolved_message="Unable to resolve runtime_config key via registry: {key!r}",
+        )
+        normalized[resolved_id] = value
+    return normalized
+
+
+def _is_agent_specific_key(key: object) -> bool:
+    """Check if a key represents an agent-specific override.
+
+    Agent-specific keys are:
+    - Agent instances (from glaip_sdk.agents.Agent)
+    - UUID strings (agent IDs)
+    - Non-reserved string names (resolved via agent_registry)
+
+    NOT agent-specific:
+    - Known config field names (tool_configs, mcp_configs, agent_config)
+    - Tool or MCP objects (these are only valid inside *_configs sections)
+
+    Args:
+        key: The key to check.
+
+    Returns:
+        True if the key could be an agent-specific override.
+    """
+    from glaip_sdk.agents import Agent  # noqa: PLC0415
+
+    # Agent instance
+    if isinstance(key, Agent):
+        return True
+
+    # Non-string keys that are not Agent instances are not agent-specific
+    if not isinstance(key, str):
+        return False
+
+    # Known config field names are not agent-specific
+    if key in _NORMALIZABLE_FIELDS or key in _PASSTHROUGH_FIELDS:
+        return False
+
+    # Any other string key is treated as an agent reference (ID or name)
+    return True
+
+
+def _normalize_standard_config(
+    config: dict[str, object],
+    tool_registry: ToolRegistry | None,
+    mcp_registry: MCPRegistry | None,
+    context: str = "",
+) -> dict[str, object]:
+    """Normalize a standard config dict with tool_configs, mcp_configs, agent_config sections.
+
+    Used for both global runtime_config and agent-specific nested configs.
+    Delegates key normalization to _normalize_section_keys for each section.
+
+    Example:
+        Input:  {"tool_configs": {ToolClass: {...}}, "agent_config": {...}}
+        Output: {"tool_configs": {"tool-uuid": {...}}, "agent_config": {...}}
+
+    Args:
+        config: The config dict to normalize.
+        tool_registry: Registry for resolving tool keys.
+        mcp_registry: Registry for resolving MCP keys.
+        context: Context string for warning messages.
+
+    Returns:
+        Normalized config dict.
+    """
+    registries: dict[str, Registry | None] = {
+        "tool": tool_registry,
+        "mcp": mcp_registry,
+    }
+
+    result: dict[str, object] = {}
+
+    for field, value in config.items():
+        if field in _NORMALIZABLE_FIELDS and isinstance(value, dict):
+            registry_type = _NORMALIZABLE_FIELDS[field]
+            result[field] = _normalize_section_keys(value, registries.get(registry_type))
+        elif field in _PASSTHROUGH_FIELDS:
+            result[field] = value
+        else:
+            logger.warning("Unknown field '%s' in %s, ignoring", field, context or "config")
+
+    return result
+
+
+def normalize_runtime_config_keys(
+    runtime_config: RuntimeConfigDict | None,
+    tool_registry: ToolRegistry | None,
+    mcp_registry: MCPRegistry | None,
+    agent_registry: AgentRegistry | None,
+) -> RuntimeConfigDict | None:
+    """Normalize runtime_config keys from various input types to stable IDs.
+
+    Handles both global configs and agent-specific overrides:
+    - Global: tool_configs, mcp_configs, agent_config
+    - Agent-specific: keyed by Agent object, agent UUID, or agent name string
+
+    Example:
+        Input:
+        {
+            "tool_configs": {ToolClass: {"param": "val"}},
+            "agent_config": {"planning": True},
+            AgentClass: {"mcp_configs": {MCPClass: {...}}}
+        }
+        Output:
+        {
+            "tool_configs": {"tool-uuid": {"param": "val"}},
+            "agent_config": {"planning": True},
+            "agent-uuid": {"mcp_configs": {"mcp-uuid": {...}}}
+        }
+
+    Converts keys from:
+    - SDK objects → their .id attribute
+    - UUID strings → passed through
+    - Names → resolved via appropriate registry
+
+    Args:
+        runtime_config: The runtime configuration dict to normalize.
+        tool_registry: Registry for resolving tool keys.
+        mcp_registry: Registry for resolving MCP keys.
+        agent_registry: Registry for resolving agent keys.
+
+    Returns:
+        Normalized runtime_config with all keys converted to IDs, or None if input is None.
+    """
+    if runtime_config is None:
+        return None
+
+    if not runtime_config:
+        return {}
+
+    registries: dict[str, Registry | None] = {
+        "tool": tool_registry,
+        "mcp": mcp_registry,
+    }
+
+    result: dict[str, object] = {}
+
+    for field, value in runtime_config.items():
+        if field in _NORMALIZABLE_FIELDS and isinstance(value, dict):
+            registry_type = _NORMALIZABLE_FIELDS[field]
+            result[field] = _normalize_section_keys(value, registries.get(registry_type))
+        elif field in _PASSTHROUGH_FIELDS:
+            result[field] = value
+        elif _is_agent_specific_key(field) and isinstance(value, dict):
+            agent_id = _resolve_config_key(
+                field,
+                agent_registry,
+                missing_registry_message=(
+                    "Agent-specific runtime_config provided but no agent_registry is available to resolve key: {key!r}"
+                ),
+                unresolved_message="Unable to resolve agent-specific runtime_config key: {key!r}",
+            )
+            result[agent_id] = _normalize_standard_config(
+                value,
+                tool_registry,
+                mcp_registry,
+                context=f"agent '{agent_id}'",
+            )
+        else:
+            logger.warning("Unknown field '%s' in runtime_config, ignoring", field)
+
+    return result
+
+
+# =============================================================================
+# LOCAL MODE UTILITIES
+# =============================================================================
+# The functions below are for local execution mode where resources are NOT
+# deployed and have no UUIDs. They resolve keys to names (not IDs).
+# =============================================================================
+
+
+def _get_name_from_class(cls: type) -> str:
+    """Extract name from a class, handling Pydantic models and @property descriptors.
+
+    Args:
+        cls: The class to extract name from.
+
+    Returns:
+        The resolved name string.
+    """
+    # Try class-level name attribute first, but guard against @property descriptors
+    # When a class has @property name, getattr returns the property object, not a string
+    class_name = getattr(cls, "name", None)
+    if isinstance(class_name, str) and class_name:
+        return class_name
+
+    # For Pydantic models, check model_fields for default value
+    model_fields = getattr(cls, "model_fields", None)
+    if model_fields and "name" in model_fields:
+        field_info = model_fields["name"]
+        default = getattr(field_info, "default", None)
+        if default and isinstance(default, str):
+            return default
+
+    # Fallback to class __name__
+    return cls.__name__
+
+
+def get_name_from_key(key: object) -> str | None:
+    """Resolve config key to name for local mode (no registry needed).
+
+    Supports instances, classes, and string names. UUID strings are not
+    supported in local mode and return None with a warning.
+
+    Args:
+        key: Tool, MCP, or Agent instance/class/string.
+
+    Returns:
+        The resolved name string, or None if UUID (not applicable locally).
+
+    Raises:
+        ValueError: If the key cannot be resolved to a valid name.
+    """
+    # Class type (not instance) - must check BEFORE hasattr("name")
+    # because classes with @property name will have hasattr return True
+    # but getattr returns the property descriptor, not a string
+    if isinstance(key, type):
+        return _get_name_from_class(key)
+
+    # String key - check early to avoid attribute access
+    if isinstance(key, str):
+        if is_uuid(key):
+            logger.warning("UUID '%s' not supported in local mode, skipping", key)
+            return None
+        return key
+
+    # Instance with name attribute
+    if hasattr(key, "name"):
+        name = getattr(key, "name", None)
+        # Guard against @property that returns non-string (e.g., descriptor)
+        if isinstance(name, str) and name:
+            return name
+
+    raise ValueError(f"Unable to resolve config key: {key!r}")
+
+
+def normalize_local_config_keys(config: Mapping[object, object]) -> dict[str, object]:
+    """Normalize all keys in a config dict to names for local mode.
+
+    Converts instance/class/string keys to string names without using
+    registry. UUID keys are skipped with a warning.
+
+    Args:
+        config: Dict/Mapping with instance/class/string keys and any values.
+
+    Returns:
+        Dict with string name keys only. UUID keys are omitted.
+    """
+    if not config:
+        return {}
+
+    result: dict[str, object] = {}
+    for key, value in config.items():
+        name = get_name_from_key(key)
+        if name is not None:
+            result[name] = value
+    return result
+
+
+def merge_configs(*configs: dict | None) -> dict:
+    """Merge multiple config dicts with priority ordering.
+
+    Later configs override earlier ones for the same key. None configs
+    are skipped gracefully.
+
+    Args:
+        *configs: Config dicts in priority order (lowest priority first).
+
+    Returns:
+        Merged config dict with later values overriding earlier ones.
+
+    Example:
+        >>> merge_configs({"a": 1}, {"a": 2, "b": 3})
+        {"a": 2, "b": 3}
+    """
+    result: dict = {}
+    for config in configs:
+        if config:
+            result.update(config)
+    return result

glaip_sdk/utils/serialization.py

@@ -88,9 +88,20 @@ def write_yaml(file_path: Path, data: dict[str, Any]) -> None:
 
     # Custom YAML dumper for user-friendly instruction formatting
     class LiteralString(str):
+        """String subclass for YAML literal block scalar formatting."""
+
         pass
 
     def literal_string_representer(dumper: yaml.Dumper, data: "LiteralString") -> yaml.nodes.Node:
+        """YAML representer for LiteralString to use literal block scalar style.
+
+        Args:
+            dumper: YAML dumper instance.
+            data: LiteralString instance to represent.
+
+        Returns:
+            YAML node with literal block scalar style for multiline strings.
+        """
         # Use literal block scalar (|) for multiline strings to preserve formatting
         if "\n" in data:
             return dumper.represent_scalar("tag:yaml.org,2002:str", data, style="|")
@@ -239,6 +250,11 @@ def _iter_public_attribute_names(resource: Any) -> Iterable[str]:
     names: list[str] = []
 
     def _collect(candidates: Iterable[str] | None) -> None:
+        """Collect unique candidate attribute names.
+
+        Args:
+            candidates: Iterable of candidate attribute names.
+        """
         for candidate in candidates or ():
             if candidate not in seen:
                 seen.add(candidate)
@@ -287,6 +303,7 @@ def _collect_from_dir(resource: Any, collect_func: Callable[[Iterable[str]], Non
 
 
 def _safe_getattr(resource: Any, name: str) -> Any:
+    """Return getattr(resource, name) but swallow any exception and return None."""
     try:
         return getattr(resource, name)
     except Exception:
@@ -294,6 +311,7 @@ def _safe_getattr(resource: Any, name: str) -> Any:
 
 
 def _should_include_attribute(key: str, value: Any) -> bool:
+    """Return True when an attribute should be serialized."""
     if key in _EXCLUDED_ATTRS or key in _EXCLUDED_NAMES:
         return False
     if key.startswith("_"):