glaip-sdk 0.1.2__py3-none-any.whl → 0.6.5b3__py3-none-any.whl

glaip_sdk/utils/bundler.py

@@ -0,0 +1,267 @@
+"""Tool source code bundling with import inlining.
+
+This module provides the ToolBundler class for bundling Python tool source
+code with all local dependencies inlined.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import ast
+import inspect
+from pathlib import Path
+
+from glaip_sdk.utils.import_resolver import ImportResolver
+
+
+class ToolBundler:
+    """Bundles tool source code with inlined local imports.
+
+    This class handles the complex process of taking a tool class and
+    producing a single, self-contained source file with all local
+    dependencies inlined.
+
+    Attributes:
+        tool_class: The tool class to bundle.
+        tool_file: Path to the file containing the tool class.
+        tool_dir: Directory containing the tool file.
+
+    Example:
+        >>> bundler = ToolBundler(MyToolClass)
+        >>> bundled_source = bundler.bundle()
+    """
+
+    def __init__(self, tool_class: type) -> None:
+        """Initialize the ToolBundler.
+
+        Args:
+            tool_class: The tool class or decorated function to bundle.
+        """
+        # If it's a gllm_core Tool, get the underlying function
+        if hasattr(tool_class, "__wrapped__"):
+            actual_func = tool_class.__wrapped__
+        else:
+            actual_func = tool_class
+
+        self.tool_class = tool_class
+        self.tool_file = Path(inspect.getfile(actual_func))
+        self.tool_dir = self.tool_file.parent
+        self._import_resolver = ImportResolver(self.tool_dir)
+
+    def bundle(self) -> str:
+        """Bundle tool source code with inlined local imports.
+
+        Returns:
+            Bundled source code with all local dependencies inlined.
+        """
+        with open(self.tool_file, encoding="utf-8") as f:
+            full_source = f.read()
+
+        tree = ast.parse(full_source)
+        local_imports, external_imports = self._import_resolver.categorize_imports(tree)
+
+        # Extract main code nodes (excluding imports, docstrings, glaip_sdk.Tool subclasses)
+        main_code_nodes = self._extract_main_code_nodes(tree)
+
+        # Inline local imports and collect their external imports
+        inlined_code, inlined_external_imports = self._import_resolver.inline_local_imports(local_imports)
+
+        # Merge all external imports
+        all_external_imports = external_imports + inlined_external_imports
+
+        # Build bundled code
+        bundled_code = ["# Bundled tool with inlined local imports\n"]
+        bundled_code.extend(self._import_resolver.format_external_imports(all_external_imports))
+
+        # Add inlined dependencies FIRST (before main tool code)
+        bundled_code.extend(inlined_code)
+
+        # Then add main tool code
+        bundled_code.append("# Main tool code\n")
+        for node_code in main_code_nodes:
+            bundled_code.append(node_code + "\n")
+        bundled_code.append("\n")
+
+        return "".join(bundled_code)
+
+    def _extract_main_code_nodes(self, tree: ast.AST) -> list[str]:
+        """Extract main code nodes from AST, excluding imports and Tool subclasses.
+
+        Args:
+            tree: AST tree of the source file.
+
+        Returns:
+            List of unparsed code node strings.
+        """
+        main_code_nodes = []
+        for node in tree.body:
+            # Skip imports
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                continue
+            # Skip module docstrings
+            if isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant):
+                continue
+            # Skip glaip_sdk.Tool subclasses
+            if isinstance(node, ast.ClassDef) and self._is_sdk_tool_subclass(node):
+                continue
+            main_code_nodes.append(ast.unparse(node))
+        return main_code_nodes
+
+    @staticmethod
+    def _is_sdk_tool_subclass(node: ast.ClassDef) -> bool:
+        """Check if AST class definition inherits from Tool.
+
+        These classes are only needed locally for upload configuration
+        and should be excluded from bundled code.
+
+        Args:
+            node: AST ClassDef node to check.
+
+        Returns:
+            True if class inherits from Tool.
+        """
+        for base in node.bases:
+            if isinstance(base, ast.Name) and base.id == "Tool":
+                return True
+            if (
+                isinstance(base, ast.Attribute)
+                and base.attr == "Tool"
+                and isinstance(base.value, ast.Name)
+                and base.value.id in ("glaip_sdk",)
+            ):
+                return True
+        return False
+
+    @classmethod
+    def bundle_from_source(cls, file_path: Path) -> tuple[str, str, str]:
+        """Extract tool info directly from source file without importing.
+
+        This is used as a fallback when the tool class cannot be imported
+        due to missing dependencies.
+
+        Args:
+            file_path: Path to the tool source file.
+
+        Returns:
+            Tuple of (name, description, bundled_source_code).
+
+        Raises:
+            FileNotFoundError: If the source file doesn't exist.
+        """
+        if not file_path.exists():
+            raise FileNotFoundError(f"Tool source file not found: {file_path}")
+
+        with open(file_path, encoding="utf-8") as f:
+            source_code = f.read()
+
+        tree = ast.parse(source_code)
+        tool_dir = file_path.parent
+        import_resolver = ImportResolver(tool_dir)
+
+        # Find tool name and description from class definitions
+        tool_name, tool_description = cls._extract_tool_metadata(tree, file_path.stem)
+
+        # Categorize imports
+        local_imports, external_imports = import_resolver.categorize_imports(tree)
+
+        # Extract main code nodes
+        main_code_nodes = []
+        for node in tree.body:
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                continue
+            if isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant):
+                continue
+            main_code_nodes.append(ast.unparse(node))
+
+        # Inline local imports
+        inlined_code, inlined_external_imports = import_resolver.inline_local_imports(local_imports)
+
+        # Build bundled code
+        all_external_imports = external_imports + inlined_external_imports
+        bundled_code = ["# Bundled tool with inlined local imports\n"]
+        bundled_code.extend(import_resolver.format_external_imports(all_external_imports))
+
+        # Add main tool code
+        bundled_code.append("# Main tool code\n")
+        for node_code in main_code_nodes:
+            bundled_code.append(node_code + "\n")
+        bundled_code.append("\n")
+
+        # Then add inlined dependencies
+        bundled_code.extend(inlined_code)
+
+        bundled_source = "".join(bundled_code)
+
+        return tool_name, tool_description, bundled_source
+
+    @staticmethod
+    def _extract_tool_metadata(tree: ast.AST, fallback_name: str) -> tuple[str, str]:
+        """Extract tool name and description from AST.
+
+        Args:
+            tree: AST tree of the source file.
+            fallback_name: Name to use if not found in source.
+
+        Returns:
+            Tuple of (tool_name, tool_description).
+        """
+        tool_name, tool_description = ToolBundler._find_class_attributes(tree)
+
+        if not tool_name:
+            # Convert class name to snake_case as fallback
+            tool_name = "".join(["_" + c.lower() if c.isupper() else c for c in fallback_name]).lstrip("_")
+
+        if not tool_description:
+            tool_description = f"Tool: {fallback_name}"
+
+        return tool_name, tool_description
+
+    @staticmethod
+    def _find_class_attributes(tree: ast.AST) -> tuple[str | None, str | None]:
+        """Find name and description attributes in class definitions.
+
+        Args:
+            tree: AST tree to search.
+
+        Returns:
+            Tuple of (name, description) if found.
+        """
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+            name, description = ToolBundler._extract_class_name_description(node)
+            if name or description:
+                return name, description
+        return None, None
+
+    @staticmethod
+    def _extract_class_name_description(
+        class_node: ast.ClassDef,
+    ) -> tuple[str | None, str | None]:
+        """Extract name and description from a single class definition.
+
+        Args:
+            class_node: AST ClassDef node.
+
+        Returns:
+            Tuple of (name, description) if found.
+        """
+        name = None
+        description = None
+
+        for item in class_node.body:
+            if not isinstance(item, ast.AnnAssign):
+                continue
+            if not isinstance(item.target, ast.Name):
+                continue
+            if not isinstance(item.value, ast.Constant):
+                continue
+
+            if item.target.id == "name":
+                name = item.value.value
+            elif item.target.id == "description":
+                description = item.value.value
+
+        return name, description

glaip_sdk/utils/client.py

@@ -0,0 +1,111 @@
+"""Client singleton management for GLAIP SDK.
+
+This module provides a singleton pattern for the GLAIP SDK client instance
+used by the agents runtime. Uses a class-based singleton pattern consistent
+with the registry implementations.
+
+Thread Safety:
+    The singleton is created lazily on first access. In Python, the GIL ensures
+    that class attribute assignment is atomic, making this pattern safe for
+    multi-threaded access. For multiprocessing, each process gets its own
+    client instance (no shared state across processes).
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dotenv import load_dotenv
+from glaip_sdk.client import Client
+
+
+class _ClientSingleton:
+    """Singleton holder for GLAIP SDK Client.
+
+    This class follows the same pattern as registry singletons
+    (_ToolRegistrySingleton, _MCPRegistrySingleton, _AgentRegistrySingleton).
+    """
+
+    _instance: Client | None = None
+
+    @classmethod
+    def get_instance(cls) -> Client:
+        """Get or create the singleton client instance.
+
+        Returns:
+            The singleton client instance.
+
+        Example:
+            >>> from glaip_sdk.utils.client import get_client
+            >>> client = get_client()
+            >>> agents = client.list_agents()
+        """
+        if cls._instance is None:
+            load_dotenv()
+            cls._instance = Client()
+        return cls._instance
+
+    @classmethod
+    def set_instance(cls, client: Client) -> None:
+        """Set the singleton client instance.
+
+        Useful for testing or when you need to configure the client manually.
+
+        Args:
+            client: The client instance to use.
+
+        Example:
+            >>> from glaip_sdk import Client
+            >>> from glaip_sdk.utils.client import set_client
+            >>> client = Client(api_key="my-key")
+            >>> set_client(client)
+        """
+        cls._instance = client
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton client instance.
+
+        Useful for testing to ensure a fresh client is created.
+        """
+        cls._instance = None
+
+
+def get_client() -> Client:
+    """Get or create singleton client instance.
+
+    Returns:
+        The singleton client instance.
+
+    Example:
+        >>> from glaip_sdk.utils.client import get_client
+        >>> client = get_client()
+        >>> agents = client.list_agents()
+    """
+    return _ClientSingleton.get_instance()
+
+
+def set_client(client: Client) -> None:
+    """Set the singleton client instance.
+
+    Useful for testing or when you need to configure the client manually.
+
+    Args:
+        client: The client instance to use.
+
+    Example:
+        >>> from glaip_sdk import Client
+        >>> from glaip_sdk.utils.client import set_client
+        >>> client = Client(api_key="my-key")
+        >>> set_client(client)
+    """
+    _ClientSingleton.set_instance(client)
+
+
+def reset_client() -> None:
+    """Reset the singleton client instance.
+
+    Useful for testing to ensure a fresh client is created.
+    """
+    _ClientSingleton.reset()

glaip_sdk/utils/client_utils.py

@@ -15,14 +15,10 @@ from pathlib import Path
 from typing import Any, BinaryIO, NoReturn
 
 import httpx
-
 from glaip_sdk.exceptions import AgentTimeoutError
-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,
-)
+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")
@@ -96,6 +92,10 @@ def create_model_instances(data: list[dict] | None, model_class: type, client: A
     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
@@ -107,6 +107,25 @@ def create_model_instances(data: list[dict] | None, model_class: type, client: A
     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]
 
 
@@ -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,6 +4,9 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+from __future__ import annotations
+
+from importlib import import_module
 from typing import TYPE_CHECKING, Any
 
 from glaip_sdk.branding import SUCCESS, SUCCESS_STYLE
@@ -13,42 +16,47 @@ 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 AIPPanel
+    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:
-    """Check if Rich and our custom components can be imported."""
+    """Return True when core Rich display dependencies are importable."""
     try:
         __import__("rich.console")
         __import__("rich.text")
         __import__("glaip_sdk.rich_components")
-        return True
     except Exception:
         return False
+    return True
 
 
 RICH_AVAILABLE = _check_rich_available()
 
 
-def _create_console() -> "Console":
+def _create_console() -> Console:
     """Return a Console instance with lazy import to ease mocking."""
-    from rich.console import Console  # Local import for test friendliness
-
-    return Console()
+    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":
+def _create_text(*args: Any, **kwargs: Any) -> Text:
     """Return a Text instance with lazy import to ease mocking."""
-    from rich.text import Text  # Local import for test friendliness
+    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)
 
-    return Text(*args, **kwargs)
 
-
-def _create_panel(*args: Any, **kwargs: Any) -> "AIPPanel":
+def _create_panel(*args: Any, **kwargs: Any) -> AIPanel:
     """Return an AIPPanel instance with lazy import to ease mocking."""
-    from glaip_sdk.rich_components import AIPPanel  # Local import for test friendliness
-
-    return AIPPanel(*args, **kwargs)
+    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: