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

glaip_sdk/utils/a2a/event_processor.py

@@ -0,0 +1,188 @@
+"""A2A event stream processing utilities.
+
+This module provides helpers for processing the A2AEvent stream emitted by
+agent execution backends (e.g., `arun_a2a_stream()`).
+
+The MVP implementation focuses on extracting final response text;
+full A2AConnector-equivalent normalization is deferred to follow-up PRs.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from gllm_core.utils import LoggerManager
+
+logger = LoggerManager().get_logger(__name__)
+
+# A2A event type constants (matching aip_agents.schema.a2a.A2AStreamEventType)
+EVENT_TYPE_FINAL_RESPONSE = "final_response"
+EVENT_TYPE_STATUS_UPDATE = "status_update"
+EVENT_TYPE_TOOL_CALL = "tool_call"
+EVENT_TYPE_TOOL_RESULT = "tool_result"
+EVENT_TYPE_ERROR = "error"
+
+
+@dataclass(frozen=True, slots=True)
+class A2AEventStreamProcessor:
+    """Processor for `arun_a2a_stream()` event dictionaries.
+
+    The SDK uses lightweight dictionaries to represent A2A stream events.
+    This helper centralizes event-type normalization and MVP final-text extraction.
+
+    Example:
+        >>> processor = A2AEventStreamProcessor()
+        >>> events = [{"event_type": "final_response", "content": "Hello!", "is_final": True}]
+        >>> result = processor.extract_final_response(events)
+        >>> print(result)
+        Hello!
+    """
+
+    def extract_final_response(self, events: list[dict[str, Any]]) -> str:
+        """Extract the final response text from a list of A2AEvents.
+
+        Scans the event list for the final_response event and returns its content.
+        If no final_response is found, raises a RuntimeError.
+
+        Args:
+            events: List of A2AEvent dictionaries from arun_a2a_stream().
+
+        Returns:
+            The content string from the final_response event.
+
+        Raises:
+            RuntimeError: If no final_response event is found in the stream.
+        """
+        for event in reversed(events):
+            if self._is_final_response_event(event):
+                content = event.get("content", "")
+                logger.debug("Extracted final response: %d characters", len(str(content)))
+                return str(content)
+
+        # Fallback: check for events with is_final=True
+        for event in reversed(events):
+            if event.get("is_final", False):
+                content = event.get("content", "")
+                if content:
+                    logger.debug("Extracted final from is_final flag: %d chars", len(str(content)))
+                    return str(content)
+
+        raise RuntimeError(
+            "No final response received from the agent. The agent execution completed without producing a final answer."
+        )
+
+    def get_event_type(self, event: dict[str, Any]) -> str:
+        """Get the normalized event type string from an A2AEvent.
+
+        Args:
+            event: An A2AEvent dictionary.
+
+        Returns:
+            The event type as a lowercase string.
+        """
+        event_type = event.get("event_type", "unknown")
+        if isinstance(event_type, str):
+            return event_type.lower()
+        # Handle enum types (A2AStreamEventType)
+        return getattr(event_type, "value", str(event_type)).lower()
+
+    def is_tool_event(self, event: dict[str, Any]) -> bool:
+        """Check if an event is a tool-related event.
+
+        Args:
+            event: An A2AEvent dictionary.
+
+        Returns:
+            True if this is a tool_call or tool_result event.
+        """
+        event_type = self.get_event_type(event)
+        return event_type in (EVENT_TYPE_TOOL_CALL, EVENT_TYPE_TOOL_RESULT)
+
+    def is_error_event(self, event: dict[str, Any]) -> bool:
+        """Check if an event is an error event.
+
+        Args:
+            event: An A2AEvent dictionary.
+
+        Returns:
+            True if this is an error event.
+        """
+        return self.get_event_type(event) == EVENT_TYPE_ERROR
+
+    def _is_final_response_event(self, event: dict[str, Any]) -> bool:
+        """Check if an event is a final_response event.
+
+        Args:
+            event: An A2AEvent dictionary.
+
+        Returns:
+            True if this is a final_response event, False otherwise.
+        """
+        return self.get_event_type(event) == EVENT_TYPE_FINAL_RESPONSE
+
+
+# Default processor instance for convenience functions
+_DEFAULT_PROCESSOR = A2AEventStreamProcessor()
+
+
+def extract_final_response(events: list[dict[str, Any]]) -> str:
+    """Extract the final response text from a list of A2AEvents.
+
+    Convenience function that uses the default A2AEventStreamProcessor.
+
+    Args:
+        events: List of A2AEvent dictionaries from arun_a2a_stream().
+
+    Returns:
+        The content string from the final_response event.
+
+    Raises:
+        RuntimeError: If no final_response event is found in the stream.
+    """
+    return _DEFAULT_PROCESSOR.extract_final_response(events)
+
+
+def get_event_type(event: dict[str, Any]) -> str:
+    """Get the normalized event type string from an A2AEvent.
+
+    Convenience function that uses the default A2AEventStreamProcessor.
+
+    Args:
+        event: An A2AEvent dictionary.
+
+    Returns:
+        The event type as a lowercase string.
+    """
+    return _DEFAULT_PROCESSOR.get_event_type(event)
+
+
+def is_tool_event(event: dict[str, Any]) -> bool:
+    """Check if an event is a tool-related event.
+
+    Convenience function that uses the default A2AEventStreamProcessor.
+
+    Args:
+        event: An A2AEvent dictionary.
+
+    Returns:
+        True if this is a tool_call or tool_result event.
+    """
+    return _DEFAULT_PROCESSOR.is_tool_event(event)
+
+
+def is_error_event(event: dict[str, Any]) -> bool:
+    """Check if an event is an error event.
+
+    Convenience function that uses the default A2AEventStreamProcessor.
+
+    Args:
+        event: An A2AEvent dictionary.
+
+    Returns:
+        True if this is an error event.
+    """
+    return _DEFAULT_PROCESSOR.is_error_event(event)

glaip_sdk/utils/agent_config.py

@@ -54,17 +54,11 @@ def sanitize_agent_config(
         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"}
-        }
+        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]:
+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:
@@ -98,17 +92,13 @@ def resolve_language_model_selection(
     # 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
+        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]:
+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
@@ -134,25 +124,51 @@ def normalize_agent_config_for_import(
     if not isinstance(agent_config, dict):
         return normalized_data
 
-    # Priority 1: CLI --model flag (highest priority)
+    # Apply normalization based on priority order
     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
+        return _apply_cli_model_override(normalized_data, cli_model)
 
-    # 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 _cleanup_existing_language_model(normalized_data, agent_config)
+
+    return _extract_lm_from_agent_config(normalized_data, agent_config)
+
+
+def _apply_cli_model_override(normalized_data: dict, cli_model: str) -> dict:
+    """Apply CLI model override (highest priority)."""
+    normalized_data["model"] = cli_model
+    return normalized_data
+
+
+def _cleanup_existing_language_model(normalized_data: dict, agent_config: dict) -> dict:
+    """Clean up agent_config when language_model_id already exists."""
+    # 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
+
+
+def _extract_lm_from_agent_config(normalized_data: dict, agent_config: dict) -> dict:
+    """Extract LM settings from agent_config (lowest priority)."""
+    extracted_lm = _extract_lm_settings(agent_config)
+
+    if not extracted_lm:
         return normalized_data
 
-    # Priority 3: Extract LM settings from agent_config
+    # 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 = _sanitize_agent_config(agent_config)
+    normalized_data["agent_config"] = sanitized_config
+
+    return normalized_data
+
+
+def _extract_lm_settings(agent_config: dict) -> dict[str, Any]:
+    """Extract LM settings from agent_config."""
     extracted_lm = {}
 
     # Extract lm_name if present
@@ -163,19 +179,16 @@ def normalize_agent_config_for_import(
     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)
+    return 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)
+def _sanitize_agent_config(agent_config: dict) -> dict:
+    """Create sanitized agent_config by removing LM identity keys."""
+    sanitized_config = agent_config.copy()
 
-        normalized_data["agent_config"] = sanitized_config
+    # 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)
 
-    return normalized_data
+    return sanitized_config

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()