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

glaip_sdk/utils/serialization.py

@@ -7,13 +7,19 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+import importlib
 import json
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import yaml
 
+if TYPE_CHECKING:  # pragma: no cover - type-only imports
+    from rich.console import Console
+
+    from glaip_sdk.models import MCP
+
 
 def read_json(file_path: Path) -> dict[str, Any]:
     """Read data from JSON file.
@@ -61,20 +67,12 @@ def read_yaml(file_path: Path) -> dict[str, Any]:
         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)
-    ):
+    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)
-    ):
+    if isinstance(data, dict) and "instruction" in data and isinstance(data["instruction"], list):
         data["instruction"] = "\n\n".join(data["instruction"])
 
     return data
@@ -90,11 +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:
+    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="|")
@@ -109,9 +116,7 @@ def write_yaml(file_path: Path, data: dict[str, Any]) -> None:
         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
-        )
+        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]:
@@ -131,14 +136,10 @@ def load_resource_from_file(file_path: Path) -> dict[str, Any]:
     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."
-        )
+        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:
+def write_resource_export(file_path: Path, data: dict[str, Any], format: str = "json") -> None:
     """Write resource export data to file.
 
     Args:
@@ -182,15 +183,9 @@ def collect_attributes_for_export(resource: Any) -> dict[str, Any]:
     and callables are filtered out so the result only contains user-configurable
     data.
     """
-
     mapping = _coerce_resource_to_mapping(resource)
-    if (
-        mapping is None
-    ):  # pragma: no cover - defensive fallback when attribute introspection fails
-        items = (
-            (name, _safe_getattr(resource, name))
-            for name in _iter_public_attribute_names(resource)
-        )
+    if mapping is None:  # pragma: no cover - defensive fallback when attribute introspection fails
+        items = ((name, _safe_getattr(resource, name)) for name in _iter_public_attribute_names(resource))
     else:
         items = mapping.items()
 
@@ -198,12 +193,35 @@ def collect_attributes_for_export(resource: Any) -> dict[str, Any]:
     for key, value in items:
         if _should_include_attribute(key, value):
             export[key] = value
+
+    # Post-process agent exports to clean up unwanted transformations
+    if hasattr(resource, "__class__") and resource.__class__.__name__ == "Agent":
+        export = _clean_agent_export_data(export)
+
     return export
 
 
+def _clean_agent_export_data(agent_data: dict[str, Any]) -> dict[str, Any]:
+    """Clean up agent export data to remove unwanted transformations.
+
+    This function addresses the issue where the backend API transforms
+    the 'timeout' field into 'execution_timeout' in an 'agent_config' section
+    during export, which is not desired for clean agent configuration exports.
+    """
+    cleaned = agent_data.copy()
+
+    # Remove execution_timeout from agent_config if it exists
+    if "agent_config" in cleaned and isinstance(cleaned["agent_config"], dict):
+        agent_config = cleaned["agent_config"]
+        if "execution_timeout" in agent_config:
+            # Move execution_timeout back to root level as timeout
+            cleaned["timeout"] = agent_config.pop("execution_timeout")
+
+    return cleaned
+
+
 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):
@@ -217,46 +235,75 @@ def _coerce_resource_to_mapping(resource: Any) -> dict[str, Any] | None:
     if isinstance(resource, dict):
         return resource
 
-    if hasattr(resource, "__dict__"):
-        try:
+    try:
+        if hasattr(resource, "__dict__"):
             return dict(resource.__dict__)
-        except (
-            Exception
-        ):  # pragma: no cover - pathological objects can still defeat coercion
-            return None
+    except Exception:  # pragma: no cover - pathological objects can still defeat coercion
+        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:
+        """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)
                 names.append(candidate)
 
-    _collect(
-        getattr(resource, "__dict__", {}).keys()
-        if hasattr(resource, "__dict__")
-        else None
-    )
-    _collect(getattr(resource, "__annotations__", {}).keys())
+    # Collect from __dict__
+    _collect_from_dict(resource, _collect)
+
+    # Collect from __annotations__
+    _collect_from_annotations(resource, _collect)
+
+    # Collect from __slots__
     _collect(getattr(resource, "__slots__", ()))
 
+    # Fallback to dir() if no names found
     if not names:
-        _collect(name for name in dir(resource) if not name.startswith("__"))
+        _collect_from_dir(resource, _collect)
 
     return iter(names)
 
 
+def _collect_from_dict(resource: Any, collect_func: Callable[[Iterable[str]], None]) -> None:
+    """Safely collect attribute names from __dict__."""
+    try:
+        if hasattr(resource, "__dict__"):
+            dict_keys = getattr(resource, "__dict__", {})
+            if dict_keys:
+                collect_func(dict_keys.keys())
+    except Exception:  # pragma: no cover - defensive programming
+        pass
+
+
+def _collect_from_annotations(resource: Any, collect_func: Callable[[Iterable[str]], None]) -> None:
+    """Safely collect attribute names from __annotations__."""
+    annotations = getattr(resource, "__annotations__", {})
+    if annotations:
+        collect_func(annotations.keys())
+
+
+def _collect_from_dir(resource: Any, collect_func: Callable[[Iterable[str]], None]) -> None:
+    """Safely collect attribute names from dir()."""
+    try:
+        collect_func(name for name in dir(resource) if not name.startswith("__"))
+    except Exception:  # pragma: no cover - defensive programming
+        pass
+
+
 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:
@@ -264,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("_"):
@@ -273,6 +321,91 @@ def _should_include_attribute(key: str, value: Any) -> bool:
     return True
 
 
+def strip_empty_fields(data: dict[str, Any]) -> dict[str, Any]:
+    """Recursively remove None values and empty dictionaries from a dictionary.
+
+    Args:
+        data: Dictionary to clean
+
+    Returns:
+        Cleaned dictionary with None values and empty dicts removed
+    """
+    if not isinstance(data, dict):
+        return data
+
+    cleaned = {}
+    for key, value in data.items():
+        if value is None:
+            continue
+        if isinstance(value, dict):
+            nested = strip_empty_fields(value)
+            if nested:  # Only include non-empty dicts
+                cleaned[key] = nested
+        else:
+            cleaned[key] = value
+
+    return cleaned
+
+
+def build_mcp_export_payload(
+    mcp: "MCP",
+    *,
+    prompt_for_secrets: bool,
+    placeholder: str,
+    console: "Console",
+) -> dict[str, Any]:
+    """Build MCP export payload with authentication secret handling.
+
+    This function prepares an MCP resource for export by:
+    1. Starting from model_dump(exclude_none=True) for API alignment
+    2. Cleaning internal fields (_client, empty metadata)
+    3. Processing authentication with secret capture/placeholder logic
+    4. Removing empty fields recursively
+
+    Args:
+        mcp: MCP model instance to export
+        prompt_for_secrets: Whether to interactively prompt for missing secrets
+        placeholder: Placeholder text for missing secrets
+        console: Rich Console instance for user interaction
+
+    Returns:
+        Dictionary ready for export (JSON/YAML serialization)
+
+    Raises:
+        ImportError: If required modules (auth helpers) are not available
+    """
+    auth_module = importlib.import_module("glaip_sdk.cli.auth")
+    prepare_authentication_export = auth_module.prepare_authentication_export
+
+    # Start with model dump (excludes None values automatically)
+    payload = mcp.model_dump(exclude_none=True)
+
+    # Remove internal/CLI fields
+    payload.pop("_client", None)
+
+    # Remove empty metadata dict
+    if "metadata" in payload and not payload["metadata"]:
+        payload.pop("metadata")
+
+    # Process authentication section
+    if "authentication" in payload:
+        processed_auth = prepare_authentication_export(
+            payload["authentication"],
+            prompt_for_secrets=prompt_for_secrets,
+            placeholder=placeholder,
+            console=console,
+        )
+        if processed_auth:
+            payload["authentication"] = processed_auth
+        else:
+            payload.pop("authentication")
+
+    # Apply final cleanup to remove any remaining empty fields
+    payload = strip_empty_fields(payload)
+
+    return payload
+
+
 def validate_json_string(json_str: str) -> dict[str, Any]:
     """Validate JSON string and return parsed data.
 
@@ -288,4 +421,4 @@ def validate_json_string(json_str: str) -> dict[str, Any]:
     try:
         return json.loads(json_str)
     except json.JSONDecodeError as e:
-        raise ValueError(f"Invalid JSON: {e}")
+        raise ValueError(f"Invalid JSON: {e}") from e

glaip_sdk/utils/sync.py

@@ -0,0 +1,142 @@
+"""Agent and tool synchronization (create/update) operations.
+
+This module provides convenience functions for tool classes that need bundling.
+
+For direct upsert operations, use the client methods:
+    - client.agents.upsert_agent(identifier, **kwargs)
+    - client.tools.upsert_tool(identifier, code, **kwargs)
+    - client.mcps.upsert_mcp(identifier, **kwargs)
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from glaip_sdk.utils.bundler import ToolBundler
+from glaip_sdk.utils.import_resolver import load_class
+from gllm_core.utils import LoggerManager
+
+if TYPE_CHECKING:
+    from glaip_sdk.models import Agent, Tool
+
+logger = LoggerManager().get_logger(__name__)
+
+
+def _extract_tool_name(tool_class: Any) -> str:
+    """Extract tool name from a class, handling Pydantic v2 models."""
+    # Direct attribute access (works for non-Pydantic classes)
+    if hasattr(tool_class, "name"):
+        name = getattr(tool_class, "name", None)
+        if isinstance(name, str):
+            return name
+
+    # Pydantic v2 model - check model_fields
+    if hasattr(tool_class, "model_fields"):
+        model_fields = getattr(tool_class, "model_fields", {})
+        if "name" in model_fields:
+            field_info = model_fields["name"]
+            if hasattr(field_info, "default") and isinstance(field_info.default, str):
+                return field_info.default
+
+    raise ValueError(f"Cannot extract name from tool class: {tool_class}")
+
+
+def _extract_tool_description(tool_class: Any) -> str:
+    """Extract tool description from a class, handling Pydantic v2 models."""
+    # Direct attribute access
+    if hasattr(tool_class, "description"):
+        desc = getattr(tool_class, "description", None)
+        if isinstance(desc, str):
+            return desc
+
+    # Pydantic v2 model - check model_fields
+    if hasattr(tool_class, "model_fields"):
+        model_fields = getattr(tool_class, "model_fields", {})
+        if "description" in model_fields:
+            field_info = model_fields["description"]
+            if hasattr(field_info, "default") and isinstance(field_info.default, str):
+                return field_info.default
+
+    return ""
+
+
+def update_or_create_tool(tool_ref: Any) -> Tool:
+    """Create or update a tool from a tool class with bundled source code.
+
+    This function takes a tool class (LangChain BaseTool), bundles its source
+    code with inlined imports, and creates/updates it in the backend.
+
+    Args:
+        tool_ref: A tool class (LangChain BaseTool subclass) or import path string.
+
+    Returns:
+        The created or updated tool.
+
+    Example:
+        >>> from glaip_sdk.utils.sync import update_or_create_tool
+        >>> from my_tools import WeatherAPITool
+        >>> tool = update_or_create_tool(WeatherAPITool)
+    """
+    from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+    client = get_client()
+
+    # Handle string import path
+    if isinstance(tool_ref, str):
+        tool_class = load_class(tool_ref)
+    else:
+        tool_class = tool_ref
+
+    # Get tool info - handle Pydantic v2 model classes
+    tool_name = _extract_tool_name(tool_class)
+    tool_description = _extract_tool_description(tool_class)
+
+    # Bundle source code
+    bundler = ToolBundler(tool_class)
+    bundled_source = bundler.bundle()
+
+    logger.info("Tool info: name='%s', description='%s...'", tool_name, tool_description[:50])
+    logger.info("Bundled source code: %d characters", len(bundled_source))
+
+    # Use client's upsert method
+    return client.tools.upsert_tool(
+        tool_name,
+        code=bundled_source,
+        description=tool_description,
+    )
+
+
+def update_or_create_agent(agent_config: dict[str, Any]) -> Agent:
+    """Create or update an agent from configuration.
+
+    Args:
+        agent_config: Agent configuration dictionary containing:
+            - name (str): Agent name (required)
+            - description (str): Agent description
+            - instruction (str): Agent instruction
+            - tools (list, optional): List of tool IDs
+            - agents (list, optional): List of sub-agent IDs
+            - metadata (dict, optional): Additional metadata
+
+    Returns:
+        The created or updated agent.
+
+    Example:
+        >>> from glaip_sdk.utils.sync import update_or_create_agent
+        >>> config = {
+        ...     "name": "weather_reporter",
+        ...     "description": "Weather reporting agent",
+        ...     "instruction": "You are a weather reporter.",
+        ... }
+        >>> agent = update_or_create_agent(config)
+    """
+    from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+    client = get_client()
+    agent_name = agent_config.pop("name")
+
+    # Use client's upsert method
+    return client.agents.upsert_agent(agent_name, **agent_config)

glaip_sdk/utils/tool_detection.py

@@ -0,0 +1,33 @@
+"""Shared utilities for tool type detection.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from typing import Any
+
+
+def is_langchain_tool(ref: Any) -> bool:
+    """Check if ref is a LangChain BaseTool class or instance.
+
+    Shared by:
+    - ToolRegistry._is_custom_tool() (for upload detection)
+    - LangChainToolAdapter._is_langchain_tool() (for adaptation)
+
+    Args:
+        ref: Object to check.
+
+    Returns:
+        True if ref is a LangChain BaseTool class or instance.
+    """
+    try:
+        from langchain_core.tools import BaseTool  # noqa: PLC0415
+
+        if isinstance(ref, type) and issubclass(ref, BaseTool):
+            return True
+        if isinstance(ref, BaseTool):
+            return True
+    except ImportError:
+        pass
+
+    return False

glaip_sdk/utils/validation.py

@@ -11,12 +11,23 @@ import re
 from pathlib import Path
 from typing import Any
 
+from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
 from glaip_sdk.utils.resource_refs import validate_name_format
 
 # Constants for validation
 RESERVED_NAMES = ["admin", "root", "system", "api", "test", "demo"]
 
 
+def _validate_named_resource(name: str, resource_type: str) -> str:
+    """Shared validator that prevents reserved-name duplication."""
+    cleaned_name = validate_name_format(name, resource_type)
+
+    if cleaned_name.lower() in RESERVED_NAMES:
+        raise ValueError(f"{resource_type.capitalize()} name '{cleaned_name}' is reserved and cannot be used")
+
+    return cleaned_name
+
+
 def validate_agent_name(name: str) -> str:
     """Validate agent name and return cleaned version.
 
@@ -29,13 +40,7 @@ def validate_agent_name(name: str) -> str:
     Raises:
         ValueError: If name is invalid
     """
-    cleaned_name = validate_name_format(name, "agent")
-
-    # Check for reserved names
-    if cleaned_name.lower() in RESERVED_NAMES:
-        raise ValueError(f"'{cleaned_name}' is a reserved name and cannot be used")
-
-    return cleaned_name
+    return _validate_named_resource(name, "agent")
 
 
 def validate_agent_instruction(instruction: str) -> str:
@@ -73,13 +78,7 @@ def validate_tool_name(name: str) -> str:
     Raises:
         ValueError: If name is invalid
     """
-    cleaned_name = validate_name_format(name, "tool")
-
-    # Check for reserved names
-    if cleaned_name.lower() in RESERVED_NAMES:
-        raise ValueError(f"'{cleaned_name}' is a reserved name and cannot be used")
-
-    return cleaned_name
+    return _validate_named_resource(name, "tool")
 
 
 def validate_mcp_name(name: str) -> str:
@@ -94,13 +93,7 @@ def validate_mcp_name(name: str) -> str:
     Raises:
         ValueError: If name is invalid
     """
-    cleaned_name = validate_name_format(name, "mcp")
-
-    # Check for reserved names
-    if cleaned_name.lower() in RESERVED_NAMES:
-        raise ValueError(f"'{cleaned_name}' is a reserved name and cannot be used")
-
-    return cleaned_name
+    return _validate_named_resource(name, "mcp")
 
 
 def validate_timeout(timeout: int) -> int:
@@ -142,8 +135,6 @@ def coerce_timeout(value: Any) -> int:
         coerce_timeout("300") -> 300
         coerce_timeout(None) -> 300  # Uses DEFAULT_AGENT_RUN_TIMEOUT
     """
-    from glaip_sdk.config.constants import DEFAULT_AGENT_RUN_TIMEOUT
-
     if value is None:
         return DEFAULT_AGENT_RUN_TIMEOUT
     elif isinstance(value, int):
@@ -156,13 +147,13 @@ def coerce_timeout(value: Any) -> int:
         try:
             fval = float(value)
             return validate_timeout(int(fval))
-        except ValueError:
-            raise ValueError(f"Invalid timeout value: {value}")
+        except ValueError as err:
+            raise ValueError(f"Invalid timeout value: {value}") from err
     else:
         try:
             return validate_timeout(int(value))
-        except (TypeError, ValueError):
-            raise ValueError(f"Invalid timeout value: {value}")
+        except (TypeError, ValueError) as err:
+            raise ValueError(f"Invalid timeout value: {value}") from err
 
 
 def validate_file_path(file_path: str | Path, must_exist: bool = True) -> Path:
@@ -214,7 +205,7 @@ def validate_directory_path(dir_path: str | Path, must_exist: bool = True) -> Pa
 
 
 def validate_url(url: str) -> str:
-    """Validate URL format.
+    """Validate URL format (HTTPS only).
 
     Args:
         url: URL to validate
@@ -226,7 +217,7 @@ def validate_url(url: str) -> str:
         ValueError: If URL is invalid
     """
     url_pattern = re.compile(
-        r"^https?://"  # http:// or https://
+        r"^https://"  # https:// only
         r"(?:(?:[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?\.)+[A-Z]{2,6}\.?|"  # domain...
         r"localhost|"  # localhost...
         r"\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})"  # ...or ip
@@ -236,7 +227,7 @@ def validate_url(url: str) -> str:
     )
 
     if not url_pattern.match(url):
-        raise ValueError(f"Invalid URL format: {url}")
+        raise ValueError("API URL must start with https:// and be a valid host.")
 
     return url