glaip-sdk 0.0.1b10__py3-none-any.whl → 0.0.3__py3-none-any.whl

glaip_sdk/utils/client_utils.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+"""Utility functions for AIP SDK clients.
+
+This module contains generic utility functions that can be reused across
+different client types (agents, tools, etc.).
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import logging
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Any, BinaryIO
+
+import httpx
+
+from glaip_sdk.exceptions import AgentTimeoutError
+
+# Set up module-level logger
+logger = logging.getLogger("glaip_sdk.client_utils")
+
+
+class MultipartData:
+    """Container for multipart form data with automatic file handle cleanup."""
+
+    def __init__(self, data: dict[str, Any], files: list[tuple[str, Any]]):
+        """Initialize multipart data container.
+
+        Args:
+            data: Form data dictionary
+            files: List of file tuples for multipart form
+        """
+        self.data = data
+        self.files = files
+        self._exit_stack = ExitStack()
+
+    def close(self):
+        """Close all opened file handles."""
+        self._exit_stack.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+
+def extract_ids(items: list[str | Any] | None) -> list[str] | None:
+    """Extract IDs from a list of objects or strings.
+
+    Args:
+        items: List of items that may be strings, objects with .id, or other types
+
+    Returns:
+        List of extracted IDs, or None if items is empty/None
+    """
+    if not items:
+        return None
+
+    ids = []
+    for item in items:
+        if isinstance(item, str):
+            ids.append(item)
+        elif hasattr(item, "id"):
+            ids.append(item.id)
+        else:
+            # Fallback: convert to string
+            ids.append(str(item))
+
+    return ids
+
+
+def create_model_instances(
+    data: list[dict] | None, model_class: type, client: Any
+) -> list[Any]:
+    """Create model instances from API data with client association.
+
+    This is a common pattern used across different clients (agents, tools, mcps)
+    to create model instances and associate them with the client.
+
+    Args:
+        data: List of dictionaries from API response
+        model_class: The model class to instantiate
+        client: The client instance to associate with models
+
+    Returns:
+        List of model instances with client association
+    """
+    if not data:
+        return []
+
+    return [model_class(**item_data)._set_client(client) for item_data in data]
+
+
+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 iter_sse_events(
+    response: httpx.Response, timeout_seconds: float = None, agent_name: str = None
+):
+    """Iterate over Server-Sent Events with proper parsing.
+
+    Args:
+        response: HTTP response object with streaming content
+        timeout_seconds: Timeout duration in seconds (for error messages)
+        agent_name: Agent name (for error messages)
+
+    Yields:
+        Dictionary with event data, type, and ID
+
+    Raises:
+        AgentTimeoutError: When agent execution times out
+        httpx.TimeoutException: When general timeout occurs
+        Exception: For other unexpected errors
+    """
+    buf = []
+    event_type = None
+    event_id = None
+
+    try:
+        for raw in response.iter_lines():
+            line = raw.decode("utf-8") if isinstance(raw, bytes) else raw
+            if line is None:
+                continue
+
+            # Normalize CRLF and treat whitespace-only as blank
+            line = line.rstrip("\r")
+
+            if not line.strip():  # instead of: if line == ""
+                if buf:
+                    data = "\n".join(buf)
+                    yield {
+                        "event": event_type or "message",
+                        "id": event_id,
+                        "data": data,
+                    }
+                    buf, event_type, event_id = [], None, None
+                continue
+
+            if line.startswith(":"):  # comment
+                continue
+            if line.startswith("data:"):
+                data_line = line[5:].lstrip()
+
+                # Optional: handle sentinel end markers gracefully
+                if data_line.strip() == "[DONE]":
+                    if buf:
+                        data = "\n".join(buf)
+                        yield {
+                            "event": event_type or "message",
+                            "id": event_id,
+                            "data": data,
+                        }
+                    return
+
+                buf.append(data_line)
+            elif line.startswith("event:"):
+                event_type = line[6:].strip() or None
+            elif line.startswith("id:"):
+                event_id = line[3:].strip() or None
+
+        # Flush any remaining data
+        if buf:
+            yield {
+                "event": event_type or "message",
+                "id": event_id,
+                "data": "\n".join(buf),
+            }
+    except httpx.ReadTimeout as e:
+        logger.error(f"Read timeout during streaming: {e}")
+        logger.error("This usually indicates the backend is taking too long to respond")
+        logger.error(
+            "Consider increasing the timeout value or checking backend performance"
+        )
+        # Raise a more user-friendly timeout error
+        raise AgentTimeoutError(
+            timeout_seconds or 30.0,  # Default to 30s if not provided
+            agent_name,
+        )
+    except httpx.TimeoutException as e:
+        logger.error(f"General timeout during streaming: {e}")
+        # Also convert general timeout to agent timeout for consistency
+        raise AgentTimeoutError(timeout_seconds or 30.0, agent_name)
+    except httpx.StreamClosed as e:
+        logger.error(f"Stream closed unexpectedly during streaming: {e}")
+        logger.error("This may indicate a backend issue or network problem")
+        logger.error("The response stream was closed before all data could be read")
+        raise
+    except httpx.ConnectError as e:
+        logger.error(f"Connection error during streaming: {e}")
+        logger.error("Check your network connection and backend availability")
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error during streaming: {e}")
+        logger.error(f"Error type: {type(e).__name__}")
+        # Log additional context if available
+        if hasattr(e, "__cause__") and e.__cause__:
+            logger.error(f"Caused by: {e.__cause__}")
+        raise
+
+
+def prepare_multipart_data(message: str, files: list[str | BinaryIO]) -> MultipartData:
+    """Prepare multipart form data for file uploads.
+
+    Args:
+        message: Text message to include with the upload
+        files: List of file paths or file-like objects
+
+    Returns:
+        MultipartData object with automatic file handle cleanup
+
+    Raises:
+        FileNotFoundError: When a file path doesn't exist
+        ValueError: When a file object is invalid
+    """
+    # Backend expects 'input' for the main prompt. Keep 'message' for
+    # backward-compatibility with any legacy handlers.
+    form_data = {"input": message, "message": message, "stream": True}
+    file_list = []
+
+    with ExitStack() as stack:
+        multipart_data = MultipartData(form_data, [])
+        multipart_data._exit_stack = stack
+
+        for file_item in files:
+            if isinstance(file_item, str):
+                # File path - let httpx stream the file handle
+                file_path = Path(file_item)
+                if not file_path.exists():
+                    raise FileNotFoundError(f"File not found: {file_item}")
+
+                # Open file and register for cleanup
+                fh = stack.enter_context(open(file_path, "rb"))
+                file_list.append(
+                    (
+                        "files",
+                        (
+                            file_path.name,
+                            fh,
+                            "application/octet-stream",
+                        ),
+                    )
+                )
+            else:
+                # File-like object
+                if hasattr(file_item, "name"):
+                    filename = getattr(file_item, "name", "file")
+                else:
+                    filename = "file"
+
+                if hasattr(file_item, "read"):
+                    # For file-like objects, we need to read them since httpx expects bytes
+                    file_content = file_item.read()
+                    file_list.append(
+                        ("files", (filename, file_content, "application/octet-stream"))
+                    )
+                else:
+                    raise ValueError(f"Invalid file object: {file_item}")
+
+        multipart_data.files = file_list
+        return multipart_data

glaip_sdk/utils/rendering/__init__.py

@@ -0,0 +1 @@
+"""Rendering utilities package (formatting, models, steps, debug)."""

glaip_sdk/utils/rendering/formatting.py

@@ -0,0 +1,211 @@
+"""Formatting helpers for renderer.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+# Constants for argument formatting
+DEFAULT_ARGS_MAX_LEN = 100
+IMPORTANT_PARAMETER_KEYS = [
+    "model",
+    "temperature",
+    "max_tokens",
+    "top_p",
+    "frequency_penalty",
+    "presence_penalty",
+    "query",
+    "url",
+]
+SECRET_VALUE_PATTERNS = [
+    re.compile(r"sk-[a-zA-Z0-9]{20,}"),  # OpenAI API keys (at least 20 chars)
+    re.compile(r"ya29\.[a-zA-Z0-9_-]+"),  # Google OAuth tokens
+    re.compile(r"ghp_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"gho_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"ghu_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"ghs_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"ghr_[a-zA-Z0-9]{20,}"),  # GitHub tokens (at least 20 chars)
+    re.compile(r"eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+"),  # JWT tokens
+]
+SENSITIVE_PATTERNS = re.compile(
+    r"password\s*[:=]\s*[^\s,}]+|secret\s*[:=]\s*[^\s,}]+|token\s*[:=]\s*[^\s,}]+|key\s*[:=]\s*[^\s,}]+|api_key\s*[:=]\s*[^\s,}]+|^password$|^secret$|^token$|^key$|^api_key$",
+    re.IGNORECASE,
+)
+
+
+def _truncate_string(s: str, max_len: int) -> str:
+    """Truncate a string to a maximum length."""
+    if len(s) <= max_len:
+        return s
+    return s[: max_len - 3] + "…"
+
+
+def mask_secrets_in_string(text: str) -> str:
+    """Mask sensitive information in a string."""
+    result = text
+    for pattern in SECRET_VALUE_PATTERNS:
+        result = re.sub(pattern, "••••••", result)
+    return result
+
+
+def redact_sensitive(text: str | dict | list) -> str | dict | list:
+    """Redact sensitive information in a string, dict, or list."""
+    if isinstance(text, dict):
+        # Recursively process dictionary values
+        result = {}
+        for key, value in text.items():
+            # Check if the key itself is sensitive
+            key_lower = key.lower()
+            if any(
+                sensitive in key_lower
+                for sensitive in ["password", "secret", "token", "key", "api_key"]
+            ):
+                result[key] = "••••••"
+            elif isinstance(value, dict | list):
+                result[key] = redact_sensitive(value)
+            elif isinstance(value, str):
+                result[key] = redact_sensitive(value)
+            else:
+                result[key] = value
+        return result
+    elif isinstance(text, list):
+        # Recursively process list items
+        return [redact_sensitive(item) for item in text]
+    elif isinstance(text, str):
+        # Process string - first mask secrets, then redact sensitive patterns
+        result = text
+        # First mask secrets
+        for pattern in SECRET_VALUE_PATTERNS:
+            result = re.sub(pattern, "••••••", result)
+        # Then redact sensitive patterns
+        result = re.sub(
+            SENSITIVE_PATTERNS,
+            lambda m: m.group(0).split("=")[0] + "=••••••",
+            result,
+        )
+        return result
+    else:
+        return text
+
+
+def pretty_args(args: dict | None, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
+    """Format arguments in a pretty way."""
+    if not args:
+        return "{}"
+
+    # Mask secrets first by recursively processing the structure
+    try:
+        masked_args = redact_sensitive(args)
+    except Exception:
+        # Fallback to original args if redact_sensitive fails
+        masked_args = args
+
+    # Convert to JSON string and truncate if needed
+    try:
+        import json
+
+        args_str = json.dumps(masked_args, ensure_ascii=False)
+        return _truncate_string(args_str, max_len)
+    except (TypeError, ValueError, Exception):
+        # Fallback to string representation if JSON serialization fails
+        args_str = str(masked_args)
+        return _truncate_string(args_str, max_len)
+
+
+def pretty_out(output: any, max_len: int = DEFAULT_ARGS_MAX_LEN) -> str:
+    """Format output in a pretty way."""
+    if output is None:
+        return "None"
+
+    if isinstance(output, str):
+        # Mask secrets in string output
+        masked_output = mask_secrets_in_string(output)
+        # Strip leading/trailing whitespace but preserve internal spacing
+        masked_output = masked_output.strip()
+        # Replace newlines with spaces to preserve formatting
+        masked_output = masked_output.replace("\n", " ")
+        return _truncate_string(masked_output, max_len)
+
+    # For other types, convert to string and truncate
+    output_str = str(output)
+    return _truncate_string(output_str, max_len)
+
+
+def get_spinner_char() -> str:
+    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":
+        return "⚙️"  # Gear emoji for tool
+    if step_kind == "delegate":
+        return "🤝"  # Handshake for delegate
+    if step_kind == "agent":
+        return "🧠"  # Brain emoji for agent
+    return ""
+
+
+def is_step_finished(step) -> bool:
+    """Check if a step is finished.
+
+    Args:
+        step: The step object to check
+
+    Returns:
+        True if the step status is "finished", False otherwise
+    """
+    return getattr(step, "status", None) == "finished"
+
+
+def format_main_title(
+    header_text: str, has_running_steps: bool, get_spinner_char: callable
+) -> str:
+    """Generate the main panel title with dynamic status indicators.
+
+    Args:
+        header_text: The header text from the renderer
+        has_running_steps: Whether there are running steps
+        get_spinner_char: Function to get spinner character
+
+    Returns:
+        A formatted title string showing the agent name and status.
+    """
+    # base name
+    name = (header_text or "").strip() or "Assistant"
+    # strip leading rule emojis if present
+    name = name.replace("—", " ").strip()
+    # spinner if still working
+    mark = "✓" if not has_running_steps else get_spinner_char()
+    return f"{name}  {mark}"
+
+
+def print_header_once(
+    console, text: str, last_header: str, rules_enabled: bool, style: str | None = None
+) -> str:
+    """Print header text only when it changes to avoid duplicate output.
+
+    Args:
+        console: Rich console instance
+        text: The header text to display
+        last_header: The last header text that was printed
+        rules_enabled: Whether header rules are enabled
+        style: Optional Rich style for the header rule
+
+    Returns:
+        The updated last_header value
+    """
+    if not rules_enabled:
+        return text
+    if text and text != last_header:
+        try:
+            console.rule(text, style=style)
+        except Exception:
+            console.print(text)
+        return text
+    return last_header

glaip_sdk/utils/rendering/models.py

@@ -0,0 +1,53 @@
+"""Rendering utilities.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from time import monotonic
+from typing import Any
+
+
+@dataclass(slots=True)
+class Step:
+    step_id: str
+    kind: str  # "tool" | "delegate" | "agent"
+    name: str
+    status: str = "running"
+    args: dict = field(default_factory=dict)
+    output: str = ""
+    parent_id: str | None = None
+    task_id: str | None = None
+    context_id: str | None = None
+    started_at: float = field(default_factory=monotonic)
+    duration_ms: int | None = None
+
+    def finish(self, duration_raw: float | None):
+        if isinstance(duration_raw, int | float) and duration_raw > 0:
+            # Use provided duration if it's a positive number (even if very small)
+            self.duration_ms = round(float(duration_raw) * 1000)
+        else:
+            # Calculate from started_at if duration_raw is None, negative, or zero
+            self.duration_ms = int((monotonic() - self.started_at) * 1000)
+        self.status = "finished"
+
+
+@dataclass(slots=True)
+class RunStats:
+    started_at: float = field(default_factory=monotonic)
+    finished_at: float | None = None
+    usage: dict[str, Any] = field(default_factory=dict)
+
+    def stop(self) -> None:
+        self.finished_at = monotonic()
+
+    @property
+    def duration_s(self) -> float | None:
+        return (
+            None
+            if self.finished_at is None
+            else round(self.finished_at - self.started_at, 2)
+        )

glaip_sdk/utils/rendering/renderer/__init__.py

@@ -0,0 +1,38 @@
+"""Renderer package for modular streaming output.
+
+This package provides modular components for rendering agent execution streams,
+with clean separation of concerns between configuration, console handling,
+debug output, panel rendering, progress tracking, and event routing.
+"""
+
+from .base import RichStreamRenderer
+from .config import RendererConfig
+from .console import CapturingConsole
+from .debug import render_debug_event
+from .panels import (
+    create_context_panel,
+    create_final_panel,
+    create_main_panel,
+    create_tool_panel,
+)
+from .progress import (
+    format_tool_title,
+    is_delegation_tool,
+)
+from .stream import StreamProcessor
+
+__all__ = [
+    # Main classes
+    "RichStreamRenderer",
+    "RendererConfig",
+    "CapturingConsole",
+    "StreamProcessor",
+    # Key functions
+    "render_debug_event",
+    "create_main_panel",
+    "create_tool_panel",
+    "create_context_panel",
+    "create_final_panel",
+    "format_tool_title",
+    "is_delegation_tool",
+]