glaip-sdk 0.0.4__py3-none-any.whl → 0.0.5b1__py3-none-any.whl

glaip_sdk/utils/agent_config.py

@@ -0,0 +1,181 @@
+"""Agent configuration utilities for import/export normalization and LM selection.
+
+This module consolidates language model selection logic and agent configuration
+sanitization that was previously split between CLI and SDK layers.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from typing import Any
+
+
+def _strip_agent_config_credentials(agent_config: dict | None) -> dict:
+    """Return agent_config without sensitive credentials; keep all other keys.
+
+    We intentionally keep keys like memory and agent_id so that backends supporting
+    mem0 memory (gllm-agents-binary>=0.4.6) receive them under agent_config.
+
+    Args:
+        agent_config: The agent configuration dictionary
+
+    Returns:
+        Agent config with credentials stripped but mem0 keys preserved
+    """
+    if not isinstance(agent_config, dict):
+        return {}
+    return {k: v for k, v in agent_config.items() if k != "lm_credentials"}
+
+
+def sanitize_agent_config(
+    agent_config: dict | None,
+    *,
+    strip_credentials: bool = True,
+    strip_lm_identity: bool = False,
+) -> dict:
+    """Sanitize agent_config based on chosen LM selection method.
+
+    Args:
+        agent_config: The agent configuration to sanitize
+        strip_credentials: Always drop lm_credentials (default: True)
+        strip_lm_identity: Also drop lm_provider/lm_name/lm_base_url when True
+
+    Returns:
+        Sanitized agent configuration
+
+    Notes:
+        - Always drops lm_credentials to prevent credential leakage
+        - When strip_lm_identity=True, also drops LM identity keys to avoid conflicts
+        - Never drops mem0 keys (memory, agent_id) as they're needed by backends
+    """
+    if strip_credentials:
+        cfg = _strip_agent_config_credentials(agent_config)
+    else:
+        cfg = agent_config or {}
+
+    if strip_lm_identity and isinstance(cfg, dict):
+        cfg = {
+            k: v
+            for k, v in cfg.items()
+            if k not in {"lm_provider", "lm_name", "lm_base_url"}
+        }
+    return cfg
+
+
+def resolve_language_model_selection(
+    merged_data: dict[str, Any], cli_model: str | None
+) -> tuple[dict[str, Any], bool]:
+    """Resolve language model selection from merged data and CLI args.
+
+    Implements the LM selection priority:
+    1. CLI --model (maps to provider/model_name)
+    2. language_model_id from import
+    3. agent_config.lm_name from import (legacy)
+
+    Args:
+        merged_data: Merged import data and CLI args
+        cli_model: Model specified via CLI --model flag
+
+    Returns:
+        Tuple of (lm_selection_dict, should_strip_lm_identity)
+        - lm_selection_dict: Dict with exactly one LM method: {"language_model_id": "..."} OR {"model": "..."}
+        - should_strip_lm_identity: True when LM identity keys should be stripped from agent_config
+
+    Notes:
+        - Returns exactly one LM selection method to avoid conflicts
+        - CLI model takes highest priority
+        - language_model_id is preferred over legacy lm_name
+        - When extracting from agent_config, signals that LM identity should be stripped
+    """
+    # Priority 1: CLI --model flag
+    if cli_model:
+        return {"model": cli_model}, False
+
+    # Priority 2: language_model_id from import
+    if merged_data.get("language_model_id"):
+        return {"language_model_id": merged_data["language_model_id"]}, True
+
+    # Priority 3: Legacy lm_name from agent_config
+    agent_config = merged_data.get("agent_config") or {}
+    if isinstance(agent_config, dict) and agent_config.get("lm_name"):
+        return {
+            "model": agent_config["lm_name"]
+        }, True  # Strip LM identity when extracting from agent_config
+
+    # No LM selection found
+    return {}, False
+
+
+def normalize_agent_config_for_import(
+    agent_data: dict[str, Any], cli_model: str | None = None
+) -> dict[str, Any]:
+    """Automatically normalize agent configuration by extracting LM settings from agent_config.
+
+    This function addresses the common issue where exported agent configurations contain
+    language model settings in agent_config, but the backend expects them at the top level
+    to avoid conflicts.
+
+    Args:
+        agent_data: Raw agent configuration data (from import file)
+        cli_model: CLI model override (highest priority)
+
+    Returns:
+        Normalized agent configuration with LM settings properly positioned
+
+    Notes:
+        - Automatically extracts lm_provider/lm_name from agent_config to top level
+        - Preserves memory settings (memory, agent_id) in agent_config
+        - Handles conflicts by prioritizing CLI model > existing language_model_id > extracted lm_name
+        - Strips redundant LM settings from agent_config after extraction
+    """
+    normalized_data = agent_data.copy()
+    agent_config = normalized_data.get("agent_config", {})
+
+    if not isinstance(agent_config, dict):
+        return normalized_data
+
+    # Priority 1: CLI --model flag (highest priority)
+    if cli_model:
+        # When CLI model is specified, set it and don't extract from agent_config
+        normalized_data["model"] = cli_model
+        return normalized_data
+
+    # Priority 2: language_model_id already exists - clean up agent_config
+    if normalized_data.get("language_model_id"):
+        # If language_model_id exists, we should still clean up any conflicting
+        # LM settings from agent_config to prevent backend validation errors
+        if isinstance(agent_config, dict):
+            # Remove LM identity keys from agent_config since language_model_id takes precedence
+            lm_keys_to_remove = {"lm_provider", "lm_name", "lm_base_url"}
+            for key in lm_keys_to_remove:
+                agent_config.pop(key, None)
+            normalized_data["agent_config"] = agent_config
+        return normalized_data
+
+    # Priority 3: Extract LM settings from agent_config
+    extracted_lm = {}
+
+    # Extract lm_name if present
+    if "lm_name" in agent_config:
+        extracted_lm["model"] = agent_config["lm_name"]
+
+    # Extract lm_provider if present (for completeness)
+    if "lm_provider" in agent_config:
+        extracted_lm["lm_provider"] = agent_config["lm_provider"]
+
+    # If we extracted LM settings, update the normalized data
+    if extracted_lm:
+        # Add extracted LM settings to top level
+        normalized_data.update(extracted_lm)
+
+        # Create sanitized agent_config (remove extracted LM settings but keep memory)
+        sanitized_config = agent_config.copy()
+
+        # Remove LM identity keys but preserve memory and other settings
+        lm_keys_to_remove = {"lm_provider", "lm_name", "lm_base_url"}
+        for key in lm_keys_to_remove:
+            sanitized_config.pop(key, None)
+
+        normalized_data["agent_config"] = sanitized_config
+
+    return normalized_data

glaip_sdk/utils/client_utils.py

@@ -9,6 +9,7 @@ Authors:
 """
 
 import logging
+from collections.abc import AsyncGenerator
 from contextlib import ExitStack
 from pathlib import Path
 from typing import Any, BinaryIO
@@ -42,7 +43,7 @@ class MultipartData:
     def __enter__(self):
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def __exit__(self, _exc_type, _exc_val, _exc_tb):
         self.close()
 
 
@@ -54,21 +55,18 @@ def extract_ids(items: list[str | Any] | None) -> list[str] | None:
 
     Returns:
         List of extracted IDs, or None if items is empty/None
+
+    Note:
+        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
 
-    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
+    result = extract_ids_new(items)
+    return result if result else None
 
 
 def create_model_instances(
@@ -108,14 +106,96 @@ def find_by_name(
 
     Returns:
         Filtered list of items matching the name
+
+    Note:
+        This function now delegates to glaip_sdk.utils.resource_refs.find_by_name.
     """
-    if not name:
-        return items
+    from .resource_refs import find_by_name as find_by_name_new
+
+    return find_by_name_new(items, name, case_sensitive)
+
+
+def _parse_sse_line(line: str, buf: list, event_type: str = None, event_id: str = None):
+    """Parse a single SSE line and return updated buffer and event metadata."""
+    # Normalize CRLF and treat whitespace-only as blank
+    line = line.rstrip("\r")
+
+    if not line.strip():  # blank line
+        if buf:
+            data = "\n".join(buf)
+            return (
+                [],
+                None,
+                None,
+                {
+                    "event": event_type or "message",
+                    "id": event_id,
+                    "data": data,
+                },
+                False,
+            )  # no completion
+        return buf, event_type, event_id, None, False
+
+    if line.startswith(":"):  # comment
+        return buf, event_type, event_id, None, False
+
+    if line.startswith("data:"):
+        data_line = line[5:].lstrip()
+        if data_line.strip() == "[DONE]":  # sentinel end marker
+            if buf:
+                data = "\n".join(buf)
+                return (
+                    [],
+                    None,
+                    None,
+                    {
+                        "event": event_type or "message",
+                        "id": event_id,
+                        "data": data,
+                    },
+                    True,
+                )  # signal completion
+            return buf, event_type, event_id, None, True
+        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
+
+    return buf, event_type, event_id, None, False
+
+
+def _handle_streaming_error(
+    e: Exception, timeout_seconds: float = None, agent_name: str = None
+):
+    """Handle different types of streaming errors with appropriate logging and exceptions."""
+    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"
+        )
+        raise AgentTimeoutError(timeout_seconds or 30.0, agent_name)
+
+    elif isinstance(e, httpx.TimeoutException):
+        logger.error(f"General timeout during streaming: {e}")
+        raise AgentTimeoutError(timeout_seconds or 30.0, agent_name)
+
+    elif isinstance(e, httpx.StreamClosed):
+        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
+
+    elif isinstance(e, httpx.ConnectError):
+        logger.error(f"Connection error during streaming: {e}")
+        logger.error("Check your network connection and backend availability")
+        raise
 
-    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()]
+        logger.error(f"Unexpected error during streaming: {e}")
+        logger.error(f"Error type: {type(e).__name__}")
+        raise
 
 
 def iter_sse_events(
@@ -146,41 +226,69 @@ def iter_sse_events(
             if line is None:
                 continue
 
-            # Normalize CRLF and treat whitespace-only as blank
-            line = line.rstrip("\r")
+            result = _parse_sse_line(line, buf, event_type, event_id)
+            if len(result) == 5:  # completion signal included
+                buf, event_type, event_id, event_data, completed = result
+            else:  # normal case
+                buf, event_type, event_id, event_data = result
+                completed = False
 
-            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 event_data:
+                yield event_data
+            if completed:
+                return
+
+        # Flush any remaining data
+        if buf:
+            yield {
+                "event": event_type or "message",
+                "id": event_id,
+                "data": "\n".join(buf),
+            }
+
+    except Exception as e:
+        _handle_streaming_error(e, timeout_seconds, agent_name)
+
+
+async def aiter_sse_events(
+    response: httpx.Response, timeout_seconds: float = None, agent_name: str = None
+) -> AsyncGenerator[dict, None]:
+    """Async 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
 
-            if line.startswith(":"):  # comment
+    try:
+        async for raw in response.aiter_lines():
+            line = raw
+            if line is None:
                 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
+
+            result = _parse_sse_line(line, buf, event_type, event_id)
+            if len(result) == 5:  # completion signal included
+                buf, event_type, event_id, event_data, completed = result
+            else:  # normal case
+                buf, event_type, event_id, event_data = result
+                completed = False
+
+            if event_data:
+                yield event_data
+            if completed:
+                return
 
         # Flush any remaining data
         if buf:
@@ -189,37 +297,9 @@ def iter_sse_events(
                 "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
+        _handle_streaming_error(e, timeout_seconds, agent_name)
 
 
 def prepare_multipart_data(message: str, files: list[str | BinaryIO]) -> MultipartData:

glaip_sdk/utils/display.py

@@ -0,0 +1,100 @@
+"""Rich display utilities for enhanced output.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from glaip_sdk.utils.rich_utils import RICH_AVAILABLE
+
+
+def print_agent_output(output: str, title: str = "Agent Output") -> None:
+    """Print agent output with rich formatting.
+
+    Args:
+        output: The agent's response text
+        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"),
+            title=title,
+            border_style="green",
+        )
+        console.print(panel)
+    else:
+        print(f"\n=== {title} ===")
+        print(output)
+        print("=" * (len(title) + 8))
+
+
+def print_agent_created(agent, title: str = "🤖 Agent Created") -> None:
+    """Print agent creation success with rich formatting.
+
+    Args:
+        agent: The created agent object
+        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"
+            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",
+        )
+        console.print(panel)
+    else:
+        print(f"✅ Agent '{agent.name}' created successfully!")
+        print(f"ID: {agent.id}")
+        print(f"Model: {getattr(agent, 'model', 'N/A')}")
+        print(f"Type: {getattr(agent, 'type', 'config')}")
+        print(f"Framework: {getattr(agent, 'framework', 'langchain')}")
+        print(f"Version: {getattr(agent, 'version', '1.0')}")
+
+
+def print_agent_updated(agent) -> None:
+    """Print agent update success with rich formatting.
+
+    Args:
+        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]")
+    else:
+        print(f"✅ Agent '{agent.name}' updated successfully")
+
+
+def print_agent_deleted(agent_id: str) -> None:
+    """Print agent deletion success with rich formatting.
+
+    Args:
+        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]")
+    else:
+        print(f"✅ Agent deleted successfully (ID: {agent_id})")

glaip_sdk/utils/general.py

@@ -0,0 +1,94 @@
+"""General utility functions for AIP SDK.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import re
+from datetime import datetime
+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.
+
+    Args:
+        size_bytes: Size in bytes
+
+    Returns:
+        Human readable size string (e.g., "1.5 MB")
+    """
+    for unit in ["B", "KB", "MB", "GB"]:
+        if size_bytes < 1024.0:
+            return f"{size_bytes:.1f} {unit}"
+        size_bytes /= 1024.0
+    return f"{size_bytes:.1f} TB"
+
+
+def format_datetime(dt):
+    """Format datetime object to readable string.
+
+    Args:
+        dt: Datetime object or string to format
+
+    Returns:
+        Formatted datetime string or "N/A" if None
+    """
+    if isinstance(dt, datetime):
+        return dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+    elif dt is None:
+        return "N/A"
+    return str(dt)
+
+
+def progress_bar(iterable, description: str = "Processing"):
+    """Simple progress bar using click.
+
+    Args:
+        iterable: Iterable to process
+        description: Progress description
+
+    Yields:
+        Items from iterable with progress display
+    """
+    try:
+        with click.progressbar(iterable, label=description) as bar:
+            for item in bar:
+                yield item
+    except ImportError:
+        # Fallback if click not available
+        for item in iterable:
+            yield item