glaip-sdk 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

glaip_sdk/utils/rendering/renderer/debug.py

@@ -11,7 +11,8 @@ from typing import Any
 
 from rich.console import Console
 from rich.markdown import Markdown
-from rich.panel import Panel
+
+from glaip_sdk.rich_components import AIPPanel
 
 
 def render_debug_event(
@@ -76,7 +77,7 @@ def render_debug_event(
 
         # Render using Markdown with JSON code block (consistent with tool panels)
         md = Markdown(f"```json\n{event_json}\n```", code_theme="monokai")
-        console.print(Panel(md, title=title, border_style=border))
+        console.print(AIPPanel(md, title=title, border_style=border))
     except Exception as e:
         # Debug helpers must not break streaming
         print(f"Debug error: {e}")  # Fallback debug output

glaip_sdk/utils/rendering/renderer/panels.py

@@ -7,11 +7,12 @@ Authors:
 from __future__ import annotations
 
 from rich.markdown import Markdown
-from rich.panel import Panel
 from rich.text import Text
 
+from glaip_sdk.rich_components import AIPPanel
 
-def create_main_panel(content: str, title: str, theme: str = "dark") -> Panel:
+
+def create_main_panel(content: str, title: str, theme: str = "dark") -> AIPPanel:
     """Create a main content panel.
 
     Args:
@@ -23,7 +24,7 @@ def create_main_panel(content: str, title: str, theme: str = "dark") -> Panel:
         Rich Panel instance
     """
     if content.strip():
-        return Panel(
+        return AIPPanel(
             Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
             title=title,
             border_style="green",
@@ -31,7 +32,7 @@ def create_main_panel(content: str, title: str, theme: str = "dark") -> Panel:
     else:
         # Placeholder panel
         placeholder = Text("Processing...", style="dim")
-        return Panel(
+        return AIPPanel(
             placeholder,
             title=title,
             border_style="green",
@@ -44,7 +45,7 @@ def create_tool_panel(
     status: str = "running",
     theme: str = "dark",
     is_delegation: bool = False,
-) -> Panel:
+) -> AIPPanel:
     """Create a tool execution panel.
 
     Args:
@@ -60,7 +61,7 @@ def create_tool_panel(
     mark = "✓" if status == "finished" else "⟳"
     border_style = "magenta" if is_delegation else "blue"
 
-    return Panel(
+    return AIPPanel(
         Markdown(
             content or "Processing...",
             code_theme=("monokai" if theme == "dark" else "github"),
@@ -76,7 +77,7 @@ def create_context_panel(
     status: str = "running",
     theme: str = "dark",
     is_delegation: bool = False,
-) -> Panel:
+) -> AIPPanel:
     """Create a context/sub-agent panel.
 
     Args:
@@ -92,7 +93,7 @@ def create_context_panel(
     mark = "✓" if status == "finished" else "⟳"
     border_style = "magenta" if is_delegation else "cyan"
 
-    return Panel(
+    return AIPPanel(
         Markdown(
             content,
             code_theme=("monokai" if theme == "dark" else "github"),
@@ -104,7 +105,7 @@ def create_context_panel(
 
 def create_final_panel(
     content: str, title: str = "Final Result", theme: str = "dark"
-) -> Panel:
+) -> AIPPanel:
     """Create a final result panel.
 
     Args:
@@ -115,7 +116,7 @@ def create_final_panel(
     Returns:
         Rich Panel instance
     """
-    return Panel(
+    return AIPPanel(
         Markdown(content, code_theme=("monokai" if theme == "dark" else "github")),
         title=title,
         border_style="green",

glaip_sdk/utils/rendering/steps.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from collections.abc import Iterator
 
-from .models import Step
+from glaip_sdk.utils.rendering.models import Step
 
 
 class StepManager:

glaip_sdk/utils/resource_refs.py

@@ -0,0 +1,192 @@
+"""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_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 []
+
+    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
+
+
+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/rich_utils.py

@@ -0,0 +1,29 @@
+"""Rich utility functions and availability checking.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+
+def _check_rich_available():
+    """Check if Rich is available by attempting imports."""
+    try:
+        import importlib.util
+
+        # Check if rich modules are available without importing them
+        if (
+            importlib.util.find_spec("rich.console") is None
+            or importlib.util.find_spec("rich.text") is None
+        ):
+            return False
+
+        # Check if our rich components are available
+        if importlib.util.find_spec("glaip_sdk.rich_components") is None:
+            return False
+
+        return True
+    except Exception:
+        return False
+
+
+RICH_AVAILABLE = _check_rich_available()

glaip_sdk/utils/serialization.py

@@ -0,0 +1,285 @@
+"""Serialization utilities for JSON/YAML read/write and resource attribute collection.
+
+This module provides pure functions for file I/O operations and data serialization
+that can be used by both CLI and SDK layers without coupling to Click or Rich.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import json
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def read_json(file_path: Path) -> dict[str, Any]:
+    """Read data from JSON file.
+
+    Args:
+        file_path: Path to JSON file
+
+    Returns:
+        Parsed JSON data as dictionary
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValueError: If file is not valid JSON
+    """
+    with open(file_path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def write_json(file_path: Path, data: dict[str, Any], indent: int = 2) -> None:
+    """Write data to JSON file.
+
+    Args:
+        file_path: Path to write JSON file
+        data: Data to write
+        indent: JSON indentation level (default: 2)
+    """
+    with open(file_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=indent, default=str)
+
+
+def read_yaml(file_path: Path) -> dict[str, Any]:
+    """Read data from YAML file.
+
+    Args:
+        file_path: Path to YAML file
+
+    Returns:
+        Parsed YAML data as dictionary
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        ValueError: If file is not valid YAML
+    """
+    with open(file_path, encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    # Handle instruction_lines array format for user-friendly YAML
+    if (
+        isinstance(data, dict)
+        and "instruction_lines" in data
+        and isinstance(data["instruction_lines"], list)
+    ):
+        data["instruction"] = "\n\n".join(data["instruction_lines"])
+        del data["instruction_lines"]
+
+    # Handle instruction as list from YAML export (convert back to string)
+    if (
+        isinstance(data, dict)
+        and "instruction" in data
+        and isinstance(data["instruction"], list)
+    ):
+        data["instruction"] = "\n\n".join(data["instruction"])
+
+    return data
+
+
+def write_yaml(file_path: Path, data: dict[str, Any]) -> None:
+    """Write data to YAML file with user-friendly formatting.
+
+    Args:
+        file_path: Path to write YAML file
+        data: Data to write
+    """
+
+    # Custom YAML dumper for user-friendly instruction formatting
+    class LiteralString(str):
+        pass
+
+    def literal_string_representer(dumper, data):
+        # 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="|")
+        return dumper.represent_scalar("tag:yaml.org,2002:str", data)
+
+    # Add custom representer to the YAML dumper
+    yaml.add_representer(LiteralString, literal_string_representer)
+
+    # Convert instruction to LiteralString for proper formatting
+    if isinstance(data, dict) and "instruction" in data and data["instruction"]:
+        data = data.copy()  # Don't modify original
+        data["instruction"] = LiteralString(data["instruction"])
+
+    with open(file_path, "w", encoding="utf-8") as f:
+        yaml.dump(
+            data, f, default_flow_style=False, allow_unicode=True, sort_keys=False
+        )
+
+
+def load_resource_from_file(file_path: Path) -> dict[str, Any]:
+    """Load resource data from JSON or YAML file.
+
+    Args:
+        file_path: Path to the file
+
+    Returns:
+        Dictionary with resource data
+
+    Raises:
+        ValueError: If file format is not supported
+    """
+    if file_path.suffix.lower() in [".yaml", ".yml"]:
+        return read_yaml(file_path)
+    elif file_path.suffix.lower() == ".json":
+        return read_json(file_path)
+    else:
+        raise ValueError(
+            f"Unsupported file format: {file_path.suffix}. Only JSON and YAML files are supported."
+        )
+
+
+def write_resource_export(
+    file_path: Path, data: dict[str, Any], format: str = "json"
+) -> None:
+    """Write resource export data to file.
+
+    Args:
+        file_path: Path to export file
+        data: Resource data to export
+        format: Export format ("json" or "yaml")
+    """
+    if format.lower() == "yaml" or file_path.suffix.lower() in [".yaml", ".yml"]:
+        write_yaml(file_path, data)
+    else:
+        write_json(file_path, data)
+
+
+_EXCLUDED_ATTRS = {
+    "id",
+    "created_at",
+    "updated_at",
+    "_client",
+    "_raw_data",
+}
+_EXCLUDED_NAMES = {
+    "model_dump",
+    "dict",
+    "json",
+    "get",
+    "post",
+    "put",
+    "delete",
+    "save",
+    "refresh",
+    "update",
+}
+_PREFERRED_MAPPERS: tuple[str, ...] = ("model_dump", "dict", "to_dict")
+
+
+def collect_attributes_for_export(resource: Any) -> dict[str, Any]:
+    """Collect resource attributes suitable for export.
+
+    The helper prefers structured dump methods when available and gracefully
+    falls back to the object's attribute space. Internal fields, identifiers,
+    and callables are filtered out so the result only contains user-configurable
+    data.
+    """
+
+    mapping = _coerce_resource_to_mapping(resource)
+    if mapping is None:
+        items = (
+            (name, _safe_getattr(resource, name))
+            for name in _iter_public_attribute_names(resource)
+        )
+    else:
+        items = mapping.items()
+
+    export: dict[str, Any] = {}
+    for key, value in items:
+        if _should_include_attribute(key, value):
+            export[key] = value
+    return export
+
+
+def _coerce_resource_to_mapping(resource: Any) -> dict[str, Any] | None:
+    """Return a mapping representation of ``resource`` when possible."""
+
+    for attr in _PREFERRED_MAPPERS:
+        method = getattr(resource, attr, None)
+        if callable(method):
+            try:
+                data = method()
+            except Exception:
+                continue
+            if isinstance(data, dict):
+                return data
+
+    if isinstance(resource, dict):
+        return resource
+
+    if hasattr(resource, "__dict__"):
+        try:
+            return dict(resource.__dict__)
+        except Exception:
+            return None
+
+    return None
+
+
+def _iter_public_attribute_names(resource: Any) -> Iterable[str]:
+    """Yield attribute names we should inspect on ``resource``."""
+
+    seen: set[str] = set()
+    names: list[str] = []
+
+    def _collect(candidates: Iterable[str] | None) -> None:
+        if candidates is None:
+            return
+        for candidate in candidates:
+            if candidate not in seen:
+                seen.add(candidate)
+                names.append(candidate)
+
+    _collect(
+        getattr(resource, "__dict__", {}).keys()
+        if hasattr(resource, "__dict__")
+        else None
+    )
+    _collect(getattr(resource, "__annotations__", {}).keys())
+    _collect(getattr(resource, "__slots__", ()))
+
+    if not names:
+        _collect(name for name in dir(resource) if not name.startswith("__"))
+
+    return iter(names)
+
+
+def _safe_getattr(resource: Any, name: str) -> Any:
+    try:
+        return getattr(resource, name)
+    except Exception:
+        return None
+
+
+def _should_include_attribute(key: str, value: Any) -> bool:
+    if key in _EXCLUDED_ATTRS or key in _EXCLUDED_NAMES:
+        return False
+    if key.startswith("_"):
+        return False
+    if callable(value):
+        return False
+    return True
+
+
+def validate_json_string(json_str: str) -> dict[str, Any]:
+    """Validate JSON string and return parsed data.
+
+    Args:
+        json_str: JSON string to validate
+
+    Returns:
+        Parsed JSON data
+
+    Raises:
+        ValueError: If JSON is invalid
+    """
+    try:
+        return json.loads(json_str)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON: {e}")