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

glaip_sdk/utils/a2a/__init__.py

@@ -0,0 +1,34 @@
+"""A2A (Agent-to-Agent) event processing utilities.
+
+This module provides utilities for processing A2A stream events emitted by
+agent execution backends. Used by the runner module and CLI rendering.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from glaip_sdk.utils.a2a.event_processor import (
+    EVENT_TYPE_ERROR,
+    EVENT_TYPE_FINAL_RESPONSE,
+    EVENT_TYPE_STATUS_UPDATE,
+    EVENT_TYPE_TOOL_CALL,
+    EVENT_TYPE_TOOL_RESULT,
+    A2AEventStreamProcessor,
+    extract_final_response,
+    get_event_type,
+    is_error_event,
+    is_tool_event,
+)
+
+__all__ = [
+    "A2AEventStreamProcessor",
+    "EVENT_TYPE_ERROR",
+    "EVENT_TYPE_FINAL_RESPONSE",
+    "EVENT_TYPE_STATUS_UPDATE",
+    "EVENT_TYPE_TOOL_CALL",
+    "EVENT_TYPE_TOOL_RESULT",
+    "extract_final_response",
+    "get_event_type",
+    "is_error_event",
+    "is_tool_event",
+]

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

@@ -83,7 +83,9 @@ def resolve_language_model_selection(merged_data: dict[str, Any], cli_model: str
     """
     # Priority 1: CLI --model flag
     if cli_model:
-        return {"model": cli_model}, False
+        from glaip_sdk.models._validation import _validate_model  # noqa: PLC0415
+
+        return {"model": _validate_model(cli_model)}, False
 
     # Priority 2: language_model_id from import
     if merged_data.get("language_model_id"):
@@ -92,7 +94,11 @@ def resolve_language_model_selection(merged_data: dict[str, Any], cli_model: str
     # 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
+        from glaip_sdk.models._validation import _validate_model  # noqa: PLC0415
+
+        return {
+            "model": _validate_model(agent_config["lm_name"])
+        }, True  # Strip LM identity when extracting from agent_config
 
     # No LM selection found
     return {}, False

glaip_sdk/utils/bundler.py

@@ -14,6 +14,7 @@ import inspect
 from pathlib import Path
 
 from glaip_sdk.utils.import_resolver import ImportResolver
+from glaip_sdk.utils.tool_detection import is_tool_plugin_decorator
 
 
 class ToolBundler:
@@ -50,9 +51,14 @@ class ToolBundler:
         self.tool_dir = self.tool_file.parent
         self._import_resolver = ImportResolver(self.tool_dir)
 
-    def bundle(self) -> str:
+    def bundle(self, add_tool_plugin_decorator: bool = True) -> str:
         """Bundle tool source code with inlined local imports.
 
+        Args:
+            add_tool_plugin_decorator: If True, add @tool_plugin decorator to BaseTool classes.
+                Set to False for newer servers (0.1.85+) where decorator is optional.
+                Defaults to True for backward compatibility with older servers.
+
         Returns:
             Bundled source code with all local dependencies inlined.
         """
@@ -62,6 +68,16 @@ class ToolBundler:
         tree = ast.parse(full_source)
         local_imports, external_imports = self._import_resolver.categorize_imports(tree)
 
+        # NOTE: The @tool_plugin decorator is REQUIRED by older servers (< 0.1.85) for remote execution.
+        # Newer servers (0.1.85+) make the decorator optional.
+        # The server validates uploaded tool code and will reject tools without the decorator
+        # with error: "No classes found with @tool_plugin decorator".
+        # See: docs/resources/reference/schemas/tools.md - "Plugin Requirements"
+        # TESTED: Commenting out this decorator addition causes HTTP 400 ValidationError from older servers.
+        # We try without decorator first (for new servers), then retry with decorator if validation fails.
+        if add_tool_plugin_decorator:
+            self._add_tool_plugin_decorator(tree)
+
         # Extract main code nodes (excluding imports, docstrings, glaip_sdk.Tool subclasses)
         main_code_nodes = self._extract_main_code_nodes(tree)
 
@@ -71,6 +87,13 @@ class ToolBundler:
         # Merge all external imports
         all_external_imports = external_imports + inlined_external_imports
 
+        # NOTE: The gllm_plugin.tools import is REQUIRED when decorator is added.
+        # Without this import, the decorator will cause a NameError when the server executes the code.
+        # TESTED: Commenting out this import causes NameError when server tries to use the decorator.
+        # This import is added automatically during bundling so source files can remain clean.
+        if add_tool_plugin_decorator:
+            self._ensure_tool_plugin_import(all_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))
@@ -109,6 +132,103 @@ class ToolBundler:
             main_code_nodes.append(ast.unparse(node))
         return main_code_nodes
 
+    @staticmethod
+    def _add_tool_plugin_decorator(tree: ast.AST) -> None:
+        """Add @tool_plugin decorator to BaseTool classes that don't have it.
+
+        This allows tools to be clean (without decorator) for local use,
+        while the decorator is automatically added during bundling for remote execution.
+
+        Args:
+            tree: AST tree to modify in-place.
+        """
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+
+            if not ToolBundler._inherits_from_base_tool(node):
+                continue
+
+            if ToolBundler._has_tool_plugin_decorator(node):
+                continue
+
+            decorator_call = ToolBundler._create_tool_plugin_decorator()
+            node.decorator_list.insert(0, decorator_call)
+
+    @staticmethod
+    def _inherits_from_base_tool(class_node: ast.ClassDef) -> bool:
+        """Check if a class inherits from BaseTool.
+
+        Args:
+            class_node: AST ClassDef node to check.
+
+        Returns:
+            True if class inherits from BaseTool.
+        """
+        for base in class_node.bases:
+            if isinstance(base, ast.Name) and base.id == "BaseTool":
+                return True
+            if isinstance(base, ast.Attribute) and base.attr == "BaseTool":
+                # Handle nested attributes like langchain_core.tools.BaseTool
+                # Check if the value chain leads to langchain_core
+                value = base.value
+                while isinstance(value, ast.Attribute):
+                    value = value.value
+                if isinstance(value, ast.Name) and value.id == "langchain_core":
+                    return True
+        return False
+
+    @staticmethod
+    def _has_tool_plugin_decorator(class_node: ast.ClassDef) -> bool:
+        """Check if a class already has the @tool_plugin decorator.
+
+        Args:
+            class_node: AST ClassDef node to check.
+
+        Returns:
+            True if decorator already exists.
+        """
+        for decorator in class_node.decorator_list:
+            if is_tool_plugin_decorator(decorator):
+                return True
+        return False
+
+    @staticmethod
+    def _create_tool_plugin_decorator() -> ast.Call:
+        """Create a @tool_plugin decorator AST node.
+
+        Returns:
+            AST Call node representing @tool_plugin(version="1.0.0").
+        """
+        return ast.Call(
+            func=ast.Name(id="tool_plugin", ctx=ast.Load()),
+            args=[],
+            keywords=[ast.keyword(arg="version", value=ast.Constant(value="1.0.0"))],
+        )
+
+    @staticmethod
+    def _ensure_tool_plugin_import(external_imports: list) -> None:
+        """Ensure gllm_plugin.tools import is present in external imports.
+
+        Args:
+            external_imports: List of external import nodes (modified in-place).
+        """
+        # Check if import already exists
+        for import_node in external_imports:
+            if isinstance(import_node, ast.ImportFrom) and import_node.module == "gllm_plugin.tools":
+                # Check if tool_plugin is in the names
+                for alias in import_node.names:
+                    if alias.name == "tool_plugin":
+                        return  # Import already present
+
+        # Add the import
+        import_node = ast.ImportFrom(
+            module="gllm_plugin.tools",
+            names=[ast.alias(name="tool_plugin")],
+            level=0,
+        )
+        external_imports.append(import_node)
+
     @staticmethod
     def _is_sdk_tool_subclass(node: ast.ClassDef) -> bool:
         """Check if AST class definition inherits from Tool.
@@ -135,7 +255,7 @@ class ToolBundler:
         return False
 
     @classmethod
-    def bundle_from_source(cls, file_path: Path) -> tuple[str, str, str]:
+    def bundle_from_source(cls, file_path: Path, add_tool_plugin_decorator: bool = True) -> 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
@@ -143,6 +263,9 @@ class ToolBundler:
 
         Args:
             file_path: Path to the tool source file.
+            add_tool_plugin_decorator: If True, add @tool_plugin decorator to BaseTool classes.
+                Set to False for newer servers (0.1.85+) where decorator is optional.
+                Defaults to True for backward compatibility with older servers.
 
         Returns:
             Tuple of (name, description, bundled_source_code).
@@ -160,6 +283,12 @@ class ToolBundler:
         tool_dir = file_path.parent
         import_resolver = ImportResolver(tool_dir)
 
+        # NOTE: The @tool_plugin decorator is REQUIRED by older servers (< 0.1.85) for remote execution.
+        # Newer servers (0.1.85+) make the decorator optional.
+        # See bundle() method for detailed explanation.
+        if add_tool_plugin_decorator:
+            cls._add_tool_plugin_decorator(tree)
+
         # Find tool name and description from class definitions
         tool_name, tool_description = cls._extract_tool_metadata(tree, file_path.stem)
 
@@ -180,6 +309,13 @@ class ToolBundler:
 
         # Build bundled code
         all_external_imports = external_imports + inlined_external_imports
+
+        # NOTE: The gllm_plugin.tools import is REQUIRED when decorator is added.
+        # See bundle() method for detailed explanation.
+        # TESTED: Commenting out this import causes NameError when server tries to use the decorator.
+        if add_tool_plugin_decorator:
+            cls._ensure_tool_plugin_import(all_external_imports)
+
         bundled_code = ["# Bundled tool with inlined local imports\n"]
         bundled_code.extend(import_resolver.format_external_imports(all_external_imports))
 

glaip_sdk/utils/import_resolver.py

@@ -13,6 +13,8 @@ import ast
 import importlib
 from pathlib import Path
 
+from glaip_sdk.utils.tool_detection import is_tool_plugin_decorator
+
 
 class ImportResolver:
     """Resolves and categorizes Python imports for tool bundling.
@@ -215,11 +217,49 @@ class ImportResolver:
             True if import should be skipped.
         """
         if isinstance(node, ast.ImportFrom):
-            return node.module and any(node.module.startswith(m) for m in self.EXCLUDED_MODULES)
+            return self._should_skip_import_from(node)
         if isinstance(node, ast.Import):
-            return any(alias.name.startswith(m) for m in self.EXCLUDED_MODULES for alias in node.names)
+            return self._should_skip_regular_import(node)
         return False
 
+    def _should_skip_import_from(self, node: ast.ImportFrom) -> bool:
+        """Check if ImportFrom node should be skipped.
+
+        Args:
+            node: ImportFrom node to check.
+
+        Returns:
+            True if import should be skipped.
+        """
+        if not node.module:
+            return False
+        return self._is_module_excluded(node.module)
+
+    def _should_skip_regular_import(self, node: ast.Import) -> bool:
+        """Check if Import node should be skipped.
+
+        Args:
+            node: Import node to check.
+
+        Returns:
+            True if any alias should be skipped.
+        """
+        return any(self._is_module_excluded(alias.name) for alias in node.names)
+
+    def _is_module_excluded(self, module_name: str) -> bool:
+        """Check if a module name should be excluded.
+
+        Args:
+            module_name: Module name to check.
+
+        Returns:
+            True if module is excluded.
+        """
+        # Exact match for glaip_sdk or match excluded submodules with boundary
+        if module_name == "glaip_sdk":
+            return True
+        return any(module_name == m or module_name.startswith(m + ".") for m in self.EXCLUDED_MODULES)
+
     @staticmethod
     def _build_import_strings(future_imports: list, regular_imports: list) -> list[str]:
         """Build formatted import strings from import nodes.
@@ -444,15 +484,7 @@ class ImportResolver:
         Returns:
             True if decorator is @tool_plugin.
         """
-        if isinstance(decorator, ast.Name) and decorator.id == "tool_plugin":
-            return True
-        if (
-            isinstance(decorator, ast.Call)
-            and isinstance(decorator.func, ast.Name)
-            and decorator.func.id == "tool_plugin"
-        ):
-            return True
-        return False
+        return is_tool_plugin_decorator(decorator)
 
     @staticmethod
     def _filter_bases(bases: list) -> list:

glaip_sdk/utils/rendering/renderer/base.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import json
 import logging
+import sys
 from datetime import datetime, timezone
 from time import monotonic
 from typing import Any
@@ -349,6 +350,9 @@ class RichStreamRenderer(TranscriptModeMixin):
             self._handle_status_event(ev)
         elif kind == "content":
             self._handle_content_event(content)
+        elif kind == "token":
+            # Token events should stream content incrementally with immediate console output
+            self._handle_token_event(content)
         elif kind == "final_response":
             self._handle_final_response_event(content, metadata)
         elif kind in {"agent_step", "agent_thinking_step"}:
@@ -368,6 +372,31 @@ class RichStreamRenderer(TranscriptModeMixin):
             self.state.append_transcript_text(content)
             self._ensure_live()
 
+    def _handle_token_event(self, content: str) -> None:
+        """Handle token streaming events - print immediately for real-time streaming."""
+        if content:
+            self.state.append_transcript_text(content)
+            # Print token content directly to stdout for immediate visibility when not verbose
+            # This bypasses Rich's Live display which has refresh rate limitations
+            if not self.verbose:
+                try:
+                    # Mark that we're streaming tokens directly to prevent Live display from starting
+                    self._streaming_tokens_directly = True
+                    # Stop Live display if active to prevent it from intercepting stdout
+                    # and causing each token to appear on a new line
+                    if self.live is not None:
+                        self._stop_live_display()
+                    # Write directly to stdout - tokens will stream on the same line
+                    # since we're bypassing Rich's console which adds newlines
+                    sys.stdout.write(content)
+                    sys.stdout.flush()
+                except Exception:
+                    # Fallback to live display if direct write fails
+                    self._ensure_live()
+            else:
+                # In verbose mode, use normal live display (debug panels handle the output)
+                self._ensure_live()
+
     def _handle_final_response_event(self, content: str, metadata: dict[str, Any]) -> None:
         """Handle final response events."""
         if content:
@@ -521,6 +550,18 @@ class RichStreamRenderer(TranscriptModeMixin):
         if getattr(self, "_transcript_mode_enabled", False):
             return
 
+        # When verbose=False and tokens were streamed directly, skip final panel
+        # The user's script will print the final result, avoiding duplication
+        if not self.verbose and getattr(self, "_streaming_tokens_directly", False):
+            # Add a newline after streaming tokens for clean separation
+            try:
+                sys.stdout.write("\n")
+                sys.stdout.flush()
+            except Exception:
+                pass
+            self.state.printed_final_output = True
+            return
+
         if self.verbose:
             panel = build_final_panel(
                 self.state,
@@ -597,6 +638,19 @@ class RichStreamRenderer(TranscriptModeMixin):
 
     def _finalize_display(self) -> None:
         """Finalize live display and render final output."""
+        # When verbose=False and tokens were streamed directly, skip live display updates
+        # to avoid showing duplicate final result
+        if not self.verbose and getattr(self, "_streaming_tokens_directly", False):
+            # Just add a newline after streaming tokens for clean separation
+            try:
+                sys.stdout.write("\n")
+                sys.stdout.flush()
+            except Exception:
+                pass
+            self._stop_live_display()
+            self.state.printed_final_output = True
+            return
+
         # Final refresh
         self._ensure_live()
 
@@ -629,6 +683,10 @@ class RichStreamRenderer(TranscriptModeMixin):
         """Ensure live display is updated."""
         if getattr(self, "_transcript_mode_enabled", False):
             return
+        # When verbose=False, don't start Live display if we're streaming tokens directly
+        # This prevents Live from intercepting stdout and causing tokens to appear on separate lines
+        if not self.verbose and getattr(self, "_streaming_tokens_directly", False):
+            return
         if not self._ensure_live_stack():
             return