glaip-sdk 0.0.7__py3-none-any.whl → 0.6.5b6__py3-none-any.whl

glaip_sdk/utils/client_utils.py

@@ -15,8 +15,10 @@ from pathlib import Path
 from typing import Any, BinaryIO, NoReturn
 
 import httpx
-
 from glaip_sdk.exceptions import AgentTimeoutError
+from glaip_sdk.models import AgentResponse, MCPResponse, ToolResponse
+from glaip_sdk.utils.resource_refs import extract_ids as extract_ids_new
+from glaip_sdk.utils.resource_refs import find_by_name as find_by_name_new
 
 # Set up module-level logger
 logger = logging.getLogger("glaip_sdk.client_utils")
@@ -41,6 +43,11 @@ class MultipartData:
         self._exit_stack.close()
 
     def __enter__(self) -> "MultipartData":
+        """Enter context manager.
+
+        Returns:
+            Self instance for context manager protocol
+        """
         return self
 
     def __exit__(
@@ -49,6 +56,13 @@ class MultipartData:
         _exc_val: BaseException | None,
         _exc_tb: Any,
     ) -> None:
+        """Exit context manager and close all file handles.
+
+        Args:
+            _exc_type: Exception type (unused)
+            _exc_val: Exception value (unused)
+            _exc_tb: Exception traceback (unused)
+        """
         self.close()
 
 
@@ -65,8 +79,6 @@ def extract_ids(items: list[str | Any] | None) -> list[str] | None:
         This function maintains backward compatibility by returning None for empty input.
         New code should use glaip_sdk.utils.resource_refs.extract_ids which returns [].
     """
-    from .resource_refs import extract_ids as extract_ids_new
-
     if not items:
         return None
 
@@ -74,14 +86,16 @@ def extract_ids(items: list[str | Any] | None) -> list[str] | None:
     return result if result else None
 
 
-def create_model_instances(
-    data: list[dict] | None, model_class: type, client: Any
-) -> list[Any]:
+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.
 
+    For runtime classes (Agent, Tool, MCP) that have a from_response method,
+    this function will use the corresponding Response model to parse the API data
+    and then create the runtime instance using from_response.
+
     Args:
         data: List of dictionaries from API response
         model_class: The model class to instantiate
@@ -93,12 +107,29 @@ def create_model_instances(
     if not data:
         return []
 
+    # Check if the model_class has a from_response method (runtime class pattern)
+    if hasattr(model_class, "from_response"):
+        # Map runtime classes to their response models
+        response_model_map = {
+            "Agent": AgentResponse,
+            "Tool": ToolResponse,
+            "MCP": MCPResponse,
+        }
+
+        response_model = response_model_map.get(model_class.__name__)
+        if response_model:
+            instances = []
+            for item_data in data:
+                response = response_model(**item_data)
+                instance = model_class.from_response(response, client=client)
+                instances.append(instance)
+            return instances
+
+    # Fallback to direct instantiation for other classes
     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]:
+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
@@ -115,8 +146,6 @@ def find_by_name(
     Note:
         This function now delegates to glaip_sdk.utils.resource_refs.find_by_name.
     """
-    from .resource_refs import find_by_name as find_by_name_new
-
     return find_by_name_new(items, name, case_sensitive)
 
 
@@ -220,9 +249,7 @@ def _handle_streaming_error(
     if isinstance(e, httpx.ReadTimeout):
         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"
-        )
+        logger.error("Consider increasing the timeout value or checking backend performance")
         raise AgentTimeoutError(timeout_seconds or 30.0, agent_name)
 
     elif isinstance(e, httpx.TimeoutException):
@@ -261,9 +288,7 @@ def _yield_event_data(event_data: dict[str, Any] | None) -> Iterator[dict[str, A
         yield event_data
 
 
-def _flush_remaining_buffer(
-    buf: list[str], event_type: str | None, event_id: str | None
-) -> Iterator[dict[str, Any]]:
+def _flush_remaining_buffer(buf: list[str], event_type: str | None, event_id: str | None) -> Iterator[dict[str, Any]]:
     """Flush any remaining data in buffer."""
     if buf:
         yield {
@@ -303,9 +328,7 @@ def iter_sse_events(
             if line is None:
                 continue
 
-            buf, event_type, event_id, event_data, completed = _process_sse_line(
-                line, buf, event_type, event_id
-            )
+            buf, event_type, event_id, event_data, completed = _process_sse_line(line, buf, event_type, event_id)
 
             yield from _yield_event_data(event_data)
             if completed:
@@ -371,9 +394,7 @@ def _create_form_data(message: str) -> dict[str, Any]:
     return {"input": message, "message": message, "stream": True}
 
 
-def _prepare_file_entry(
-    item: str | BinaryIO, stack: ExitStack
-) -> tuple[str, tuple[str, BinaryIO, str]]:
+def _prepare_file_entry(item: str | BinaryIO, stack: ExitStack) -> tuple[str, tuple[str, BinaryIO, str]]:
     """Prepare a single file entry for multipart data."""
     if isinstance(item, str):
         return _prepare_path_entry(item, stack)
@@ -381,9 +402,7 @@ def _prepare_file_entry(
         return _prepare_stream_entry(item)
 
 
-def _prepare_path_entry(
-    path_str: str, stack: ExitStack
-) -> tuple[str, tuple[str, BinaryIO, str]]:
+def _prepare_path_entry(path_str: str, stack: ExitStack) -> tuple[str, tuple[str, BinaryIO, str]]:
     """Prepare a file path entry."""
     file_path = Path(path_str)
     if not file_path.exists():
@@ -426,6 +445,19 @@ def _prepare_stream_entry(
     )
 
 
+def add_kwargs_to_payload(payload: dict[str, Any], kwargs: dict[str, Any], excluded_keys: set[str]) -> None:
+    """Add kwargs to payload excluding specified keys.
+
+    Args:
+        payload: Payload dictionary to update.
+        kwargs: Keyword arguments to add.
+        excluded_keys: Keys to exclude from kwargs.
+    """
+    for key, value in kwargs.items():
+        if key not in excluded_keys:
+            payload[key] = value
+
+
 def prepare_multipart_data(message: str, files: list[str | BinaryIO]) -> MultipartData:
     """Prepare multipart form data for file uploads.
 

glaip_sdk/utils/datetime_helpers.py

@@ -0,0 +1,58 @@
+"""Shared datetime parsing helpers used across CLI and rendering modules."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+__all__ = ["coerce_datetime", "from_numeric_timestamp"]
+
+_Z_SUFFIX = "+00:00"
+
+
+def from_numeric_timestamp(raw_value: Any) -> datetime | None:
+    """Convert unix timestamp-like values to datetime with sanity checks."""
+    try:
+        candidate = float(raw_value)
+    except Exception:
+        return None
+
+    if candidate < 1_000_000_000:
+        return None
+
+    try:
+        return datetime.fromtimestamp(candidate, tz=timezone.utc)
+    except Exception:
+        return None
+
+
+def _parse_iso(value: str | None) -> datetime | None:
+    """Parse ISO8601 strings while tolerating legacy 'Z' suffixes."""
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", _Z_SUFFIX))
+    except Exception:
+        return None
+
+
+def coerce_datetime(value: Any) -> datetime | None:
+    """Best-effort conversion of assorted timestamp inputs to aware UTC datetimes."""
+    if value is None:
+        return None
+
+    if isinstance(value, datetime):
+        dt = value
+    elif isinstance(value, (int, float)):
+        dt = from_numeric_timestamp(value)
+    elif isinstance(value, str):
+        dt = _parse_iso(value) or from_numeric_timestamp(value)
+    else:
+        return None
+
+    if dt is None:
+        return None
+
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)

glaip_sdk/utils/discovery.py

@@ -0,0 +1,78 @@
+"""Agent and tool discovery functions.
+
+This module provides functions for finding agents and tools
+from the GLAIP backend.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from gllm_core.utils import LoggerManager
+
+if TYPE_CHECKING:
+    from glaip_sdk.agents import Agent
+    from glaip_sdk.tools import Tool
+
+logger = LoggerManager().get_logger(__name__)
+
+
+def find_agent(name: str) -> Agent | None:
+    """Find an agent by name using GLAIP SDK.
+
+    Args:
+        name: The name of the agent to find.
+
+    Returns:
+        The agent if found, None otherwise.
+
+    Example:
+        >>> from glaip_sdk.utils.discovery import find_agent
+        >>> agent = find_agent("weather_reporter")
+        >>> if agent:
+        ...     print(f"Found agent: {agent.name}")
+    """
+    from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+    client = get_client()
+    try:
+        agents = client.list_agents()
+        for agent in agents:
+            if agent.name == name:
+                return agent
+        return None
+    except Exception as e:
+        logger.error("Error finding agent '%s': %s", name, e)
+        return None
+
+
+def find_tool(name: str) -> Tool | None:
+    """Find a tool by name using GLAIP SDK.
+
+    Args:
+        name: The name of the tool to find.
+
+    Returns:
+        The tool if found, None otherwise.
+
+    Example:
+        >>> from glaip_sdk.utils.discovery import find_tool
+        >>> tool = find_tool("weather_api")
+        >>> if tool:
+        ...     print(f"Found tool: {tool.name}")
+    """
+    from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+    client = get_client()
+    try:
+        tools = client.find_tools(name)
+        for tool in tools:
+            if tool.name == name:
+                return tool
+        return None
+    except Exception as e:
+        logger.error("Error finding tool '%s': %s", name, e)
+        return None

glaip_sdk/utils/display.py

@@ -4,9 +4,59 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
-from typing import Any
+from __future__ import annotations
 
-from glaip_sdk.utils.rich_utils import RICH_AVAILABLE
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+from glaip_sdk.branding import SUCCESS, SUCCESS_STYLE
+from glaip_sdk.icons import ICON_AGENT
+
+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 AIPanel
+else:  # pragma: no cover - runtime fallback for type checking
+    AIPanel = Any  # type: ignore[assignment]
+
+
+def _check_rich_available() -> bool:
+    """Return True when core Rich display dependencies are importable."""
+    try:
+        __import__("rich.console")
+        __import__("rich.text")
+        __import__("glaip_sdk.rich_components")
+    except Exception:
+        return False
+    return True
+
+
+RICH_AVAILABLE = _check_rich_available()
+
+
+def _create_console() -> Console:
+    """Return a Console instance with lazy import to ease mocking."""
+    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:
+    """Return a Text instance with lazy import to ease mocking."""
+    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)
+
+
+def _create_panel(*args: Any, **kwargs: Any) -> AIPanel:
+    """Return an AIPPanel instance with lazy import to ease mocking."""
+    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:
@@ -17,17 +67,11 @@ def print_agent_output(output: str, title: str = "Agent Output") -> None:
         title: Title for the output panel
     """
     if RICH_AVAILABLE:
-        # Lazy import Rich components
-        from rich.console import Console
-        from rich.text import Text
-
-        from glaip_sdk.rich_components import AIPPanel
-
-        console = Console()
-        panel = AIPPanel(
-            Text(output, style="green"),
+        console = _create_console()
+        panel = _create_panel(
+            _create_text(output, style=SUCCESS),
             title=title,
-            border_style="green",
+            border_style=SUCCESS,
         )
         console.print(panel)
     else:
@@ -36,7 +80,7 @@ def print_agent_output(output: str, title: str = "Agent Output") -> None:
         print("=" * (len(title) + 8))
 
 
-def print_agent_created(agent: Any, title: str = "🤖 Agent Created") -> None:
+def print_agent_created(agent: Any, title: str = f"{ICON_AGENT} Agent Created") -> None:
     """Print agent creation success with rich formatting.
 
     Args:
@@ -44,21 +88,16 @@ def print_agent_created(agent: Any, title: str = "🤖 Agent Created") -> None:
         title: Title for the output panel
     """
     if RICH_AVAILABLE:
-        # Lazy import Rich components
-        from rich.console import Console
-
-        from glaip_sdk.rich_components import AIPPanel
-
-        console = Console()
-        panel = AIPPanel(
-            f"[green]✅ Agent '{agent.name}' created successfully![/green]\n\n"
+        console = _create_console()
+        panel = _create_panel(
+            f"[{SUCCESS_STYLE}]✅ Agent '{agent.name}' created successfully![/]\n\n"
             f"ID: {agent.id}\n"
             f"Model: {getattr(agent, 'model', 'N/A')}\n"
             f"Type: {getattr(agent, 'type', 'config')}\n"
             f"Framework: {getattr(agent, 'framework', 'langchain')}\n"
             f"Version: {getattr(agent, 'version', '1.0')}",
             title=title,
-            border_style="green",
+            border_style=SUCCESS,
         )
         console.print(panel)
     else:
@@ -77,11 +116,8 @@ def print_agent_updated(agent: Any) -> None:
         agent: The updated agent object
     """
     if RICH_AVAILABLE:
-        # Lazy import Rich components
-        from rich.console import Console
-
-        console = Console()
-        console.print(f"[green]✅ Agent '{agent.name}' updated successfully[/green]")
+        console = _create_console()
+        console.print(f"[{SUCCESS_STYLE}]✅ Agent '{agent.name}' updated successfully[/]")
     else:
         print(f"✅ Agent '{agent.name}' updated successfully")
 
@@ -93,10 +129,7 @@ def print_agent_deleted(agent_id: str) -> None:
         agent_id: The deleted agent's ID
     """
     if RICH_AVAILABLE:
-        # Lazy import Rich components
-        from rich.console import Console
-
-        console = Console()
-        console.print(f"[green]✅ Agent deleted successfully (ID: {agent_id})[/green]")
+        console = _create_console()
+        console.print(f"[{SUCCESS_STYLE}]✅ Agent deleted successfully (ID: {agent_id})[/]")
     else:
         print(f"✅ Agent deleted successfully (ID: {agent_id})")

glaip_sdk/utils/export.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Export utilities for remote agent run transcripts.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from glaip_sdk.models.agent_runs import RunWithOutput, RunOutputChunk
+
+
+def export_remote_transcript_jsonl(
+    run: RunWithOutput,
+    destination: Path,
+    *,
+    overwrite: bool = False,
+    agent_name: str | None = None,
+    model: str | None = None,
+) -> Path:
+    """Export a remote run transcript to JSONL format compatible with local transcript viewers.
+
+    Args:
+        run: RunWithOutput instance to export
+        destination: Target file path for JSONL export
+        overwrite: Whether to overwrite existing file
+        agent_name: Optional agent name for metadata
+        model: Optional model name for metadata (extracted from run.config if not provided)
+
+    Returns:
+        Path to the exported file
+
+    Raises:
+        FileExistsError: If destination exists and overwrite is False
+        OSError: If file cannot be written
+    """
+    if destination.exists() and not overwrite:
+        raise FileExistsError(f"File already exists: {destination}")
+
+    # Ensure parent directory exists
+    destination.parent.mkdir(parents=True, exist_ok=True)
+
+    model_name = model or _extract_model(run)
+    final_output_text = _extract_final_output(run.output) or ""
+
+    meta_payload = _build_meta_payload(run, agent_name, model_name)
+    meta_record = _build_meta_record(run, agent_name, model_name, final_output_text, meta_payload)
+
+    _write_jsonl_file(destination, meta_record, run.output)
+
+    return destination
+
+
+def _build_meta_payload(run: RunWithOutput, agent_name: str | None, model_name: str | None) -> dict[str, Any]:
+    """Build the meta payload dictionary."""
+    return {
+        "agent_name": agent_name,
+        "model": model_name,
+        "input_message": run.input,
+        "status": run.status,
+        "run_type": run.run_type,
+        "schedule_id": str(run.schedule_id) if run.schedule_id else None,
+        "config": run.config or {},
+        "created_at": run.created_at.isoformat() if run.created_at else None,
+        "updated_at": run.updated_at.isoformat() if run.updated_at else None,
+        "event_count": len(run.output),
+    }
+
+
+def _build_meta_record(
+    run: RunWithOutput,
+    agent_name: str | None,
+    model_name: str | None,
+    final_output_text: str,
+    meta_payload: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the meta record dictionary."""
+    return {
+        "type": "meta",
+        "run_id": str(run.id),
+        "agent_id": str(run.agent_id),
+        "agent_name": agent_name,
+        "model": model_name,
+        "created_at": run.created_at.isoformat() if run.created_at else None,
+        "default_output": final_output_text,
+        "final_output": final_output_text,
+        "server_run_id": str(run.id),
+        "started_at": run.started_at.isoformat() if run.started_at else None,
+        "finished_at": run.completed_at.isoformat() if run.completed_at else None,
+        "meta": meta_payload,
+        "source": "remote_history",
+        # Back-compat fields used by older tooling
+        "run_type": run.run_type,
+        "schedule_id": str(run.schedule_id) if run.schedule_id else None,
+        "status": run.status,
+        "input": run.input,
+        "config": run.config or {},
+        "updated_at": run.updated_at.isoformat() if run.updated_at else None,
+    }
+
+
+def _write_jsonl_file(destination: Path, meta_record: dict[str, Any], events: list[RunOutputChunk]) -> None:
+    """Write the JSONL file with meta and event records."""
+    records: list[dict[str, Any]] = [meta_record]
+    records.extend({"type": "event", "event": event} for event in events)
+
+    with destination.open("w", encoding="utf-8") as fh:
+        for idx, record in enumerate(records):
+            json.dump(record, fh, ensure_ascii=False, indent=2, default=_json_default)
+            fh.write("\n")
+            if idx != len(records) - 1:
+                fh.write("\n")
+
+
+def _extract_model(run: RunWithOutput) -> str | None:
+    """Best-effort extraction of the model name from run metadata."""
+    config = run.config or {}
+    if isinstance(config, dict):
+        model = config.get("model") or config.get("llm", {}).get("model")
+        if isinstance(model, str):
+            return model
+    return None
+
+
+def _extract_final_output(events: list[RunOutputChunk]) -> str | None:
+    """Return the final response content from the event stream."""
+    for chunk in reversed(events):
+        content = chunk.get("content")
+        if not content:
+            continue
+        if chunk.get("event_type") == "final_response" or chunk.get("final"):
+            return str(content)
+    return None
+
+
+def _json_default(obj: Any) -> Any:
+    """JSON serializer for datetime objects."""
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    raise TypeError(f"Type {type(obj)} not serializable")

glaip_sdk/utils/general.py

@@ -4,46 +4,13 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
-import re
 from collections.abc import Iterable, Iterator
 from datetime import datetime
 from typing import Any
-from uuid import UUID
 
 import click
 
 
-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 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 format_file_size(size_bytes: int) -> str:
     """Format file size in human readable format.
 
@@ -76,9 +43,7 @@ def format_datetime(dt: datetime | str | None) -> str:
     return str(dt)
 
 
-def progress_bar(
-    iterable: Iterable[Any], description: str = "Processing"
-) -> Iterator[Any]:
+def progress_bar(iterable: Iterable[Any], description: str = "Processing") -> Iterator[Any]:
     """Simple progress bar using click.
 
     Args: