glaip-sdk 0.6.10__py3-none-any.whl → 0.6.19__py3-none-any.whl

glaip_sdk/__init__.py

@@ -4,12 +4,49 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
 from glaip_sdk._version import __version__
-from glaip_sdk.client import Client
-from glaip_sdk.exceptions import AIPError
-from glaip_sdk.agents import Agent
-from glaip_sdk.tools import Tool
-from glaip_sdk.mcps import MCP
 
+if TYPE_CHECKING:  # pragma: no cover - import only for type checking
+    from glaip_sdk.agents import Agent
+    from glaip_sdk.client import Client
+    from glaip_sdk.exceptions import AIPError
+    from glaip_sdk.mcps import MCP
+    from glaip_sdk.tools import Tool
 
 __all__ = ["Client", "Agent", "Tool", "MCP", "AIPError", "__version__"]
+
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "Client": ("glaip_sdk.client", "Client"),
+    "Agent": ("glaip_sdk.agents", "Agent"),
+    "Tool": ("glaip_sdk.tools", "Tool"),
+    "MCP": ("glaip_sdk.mcps", "MCP"),
+    "AIPError": ("glaip_sdk.exceptions", "AIPError"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy attribute access for public SDK symbols to defer heavy imports."""
+    if name == "__version__":
+        # Import __version__ when accessed via __getattr__
+        # This ensures coverage even if __version__ was removed from __dict__ for testing
+        from glaip_sdk._version import __version__ as version  # noqa: PLC0415
+
+        globals()["__version__"] = version
+        return version
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        module = importlib.import_module(module_path)
+        attr = getattr(module, attr_name)
+        globals()[name] = attr
+        return attr
+    raise AttributeError(f"module 'glaip_sdk' has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return module attributes for dir()."""
+    return sorted(__all__)

glaip_sdk/agents/base.py

@@ -52,14 +52,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from glaip_sdk.registry import get_agent_registry, get_mcp_registry, get_tool_registry
-from glaip_sdk.runner import get_default_runner
-from glaip_sdk.runner.deps import (
-    check_local_runtime_available,
-    get_local_runtime_missing_message,
-)
-from glaip_sdk.utils.discovery import find_agent
 from glaip_sdk.utils.resource_refs import is_uuid
-from glaip_sdk.utils.runtime_config import normalize_runtime_config_keys
 
 if TYPE_CHECKING:
     from glaip_sdk.models import AgentResponse
@@ -520,6 +513,8 @@ class Agent:
         from glaip_sdk.utils.client import get_client  # noqa: PLC0415
 
         client = get_client()
+        from glaip_sdk.utils.discovery import find_agent  # noqa: PLC0415
+
         response = self._create_or_update_agent(config, client, find_agent)
 
         # Update self with deployed info
@@ -885,6 +880,10 @@ class Agent:
         }
 
         if runtime_config is not None:
+            from glaip_sdk.utils.runtime_config import (  # noqa: PLC0415
+                normalize_runtime_config_keys,
+            )
+
             call_kwargs["runtime_config"] = normalize_runtime_config_keys(
                 runtime_config,
                 tool_registry=get_tool_registry(),
@@ -904,6 +903,12 @@ class Agent:
         Raises:
             ValueError: If local runtime is not available.
         """
+        from glaip_sdk.runner import get_default_runner  # noqa: PLC0415
+        from glaip_sdk.runner.deps import (  # noqa: PLC0415
+            check_local_runtime_available,
+            get_local_runtime_missing_message,
+        )
+
         if check_local_runtime_available():
             return get_default_runner()
         raise ValueError(f"{_AGENT_NOT_DEPLOYED_MSG}\n\n{get_local_runtime_missing_message()}")

glaip_sdk/cli/commands/common_config.py

@@ -1,14 +1,19 @@
 """Shared helpers for configuration/account flows."""
 
-import click
+from __future__ import annotations
+
 import logging
+from typing import TYPE_CHECKING
+
+import click
 from rich.console import Console
 from rich.text import Text
-
-from glaip_sdk import Client
 from glaip_sdk.branding import PRIMARY, SUCCESS_STYLE, WARNING_STYLE, AIPBranding
 from glaip_sdk.cli.utils import sdk_version
 
+if TYPE_CHECKING:  # pragma: no cover - type checking only
+    from glaip_sdk import Client
+
 
 def render_branding_header(console: Console, rule_text: str) -> None:
     """Render the standard CLI branding header with a custom rule text."""
@@ -36,11 +41,10 @@ def check_connection(
     console.print("\n🔌 Testing connection...")
     client: Client | None = None
     try:
-        # Import lazily so test patches targeting glaip_sdk.Client are honored
-        from importlib import import_module  # noqa: PLC0415
+        # Import lazily to avoid pulling in SDK dependencies during CLI startup.
+        from glaip_sdk import Client  # noqa: PLC0415
 
-        client_module = import_module("glaip_sdk")
-        client = client_module.Client(api_url=api_url, api_key=api_key)
+        client = Client(api_url=api_url, api_key=api_key)
         try:
             agents = client.list_agents()
             console.print(Text(f"✅ Connection successful! Found {len(agents)} agents", style=SUCCESS_STYLE))
@@ -75,11 +79,10 @@ def check_connection_with_reason(
     """Test connectivity and return structured reason."""
     client: Client | None = None
     try:
-        # Import lazily so test patches targeting glaip_sdk.Client are honored
-        from importlib import import_module  # noqa: PLC0415
+        # Import lazily to avoid pulling in SDK dependencies during CLI startup.
+        from glaip_sdk import Client  # noqa: PLC0415
 
-        client_module = import_module("glaip_sdk")
-        client = client_module.Client(api_url=api_url, api_key=api_key)
+        client = Client(api_url=api_url, api_key=api_key)
         try:
             client.list_agents()
             return True, ""

glaip_sdk/cli/core/output.py

@@ -29,12 +29,6 @@ from glaip_sdk.cli.io import export_resource_to_file_with_validation
 from glaip_sdk.cli.rich_helpers import markup_text, print_markup
 from glaip_sdk.rich_components import AIPPanel, AIPTable
 from glaip_sdk.utils import format_datetime, is_uuid
-
-try:
-    from glaip_sdk import _version as _version_module
-except ImportError:  # pragma: no cover - defensive import
-    _version_module = None
-
 from .prompting import (
     _fuzzy_pick,
     _fuzzy_pick_for_resources,
@@ -43,6 +37,9 @@ from .prompting import (
 )
 from .rendering import _spinner_stop, _spinner_update, spinner_context
 
+_VERSION_MODULE_MISSING = object()
+_version_module: Any | None = _VERSION_MODULE_MISSING
+
 console = Console()
 pager.console = console
 logger = logging.getLogger("glaip_sdk.cli.core.output")
@@ -236,7 +233,15 @@ def handle_resource_export(
 
 def sdk_version() -> str:
     """Return the current SDK version, warning if metadata is unavailable."""
-    global _WARNED_SDK_VERSION_FALLBACK
+    global _WARNED_SDK_VERSION_FALLBACK, _version_module
+
+    if _version_module is _VERSION_MODULE_MISSING:
+        try:
+            from importlib import import_module  # noqa: PLC0415
+
+            _version_module = import_module("glaip_sdk._version")
+        except Exception:  # pragma: no cover - defensive fallback
+            _version_module = None
 
     if _version_module is None:
         if not _WARNED_SDK_VERSION_FALLBACK:

glaip_sdk/cli/main.py

@@ -11,8 +11,6 @@ from typing import Any
 
 import click
 from rich.console import Console
-
-from glaip_sdk import Client
 from glaip_sdk.branding import (
     ERROR,
     ERROR_STYLE,
@@ -49,6 +47,18 @@ from glaip_sdk.config.constants import (
 from glaip_sdk.icons import ICON_AGENT
 from glaip_sdk.rich_components import AIPPanel, AIPTable
 
+Client: type[Any] | None = None
+
+
+def _resolve_client_class() -> type[Any]:
+    """Resolve the Client class lazily to avoid heavy imports at CLI startup."""
+    global Client
+    if Client is None:
+        from glaip_sdk import Client as ClientClass  # noqa: PLC0415
+
+        Client = ClientClass
+    return Client
+
 
 def _suppress_chatty_loggers() -> None:
     """Silence noisy SDK/httpx logs for CLI output."""
@@ -339,14 +349,15 @@ def _safe_list_call(obj: Any, attr: str) -> list[Any]:
 
 def _get_client_from_config(config: dict) -> Any:
     """Return a Client instance built from config."""
-    return Client(
+    client_class = _resolve_client_class()
+    return client_class(
         api_url=config["api_url"],
         api_key=config["api_key"],
         timeout=config.get("timeout", 30.0),
     )
 
 
-def _create_and_test_client(config: dict, console: Console, *, compact: bool = False) -> Client:
+def _create_and_test_client(config: dict, console: Console, *, compact: bool = False) -> Any:
     """Create client and test connection by fetching resources."""
     client: Any = _get_client_from_config(config)
 

glaip_sdk/client/agents.py

@@ -453,13 +453,11 @@ class AgentClient(BaseClient):
         Returns:
             Final text string.
         """
+        from glaip_sdk.client.run_rendering import finalize_render_manager  # noqa: PLC0415
+
         manager = self._get_renderer_manager()
-        return manager.finalize_renderer(
-            renderer,
-            final_text,
-            stats_usage,
-            started_monotonic,
-            finished_monotonic,
+        return finalize_render_manager(
+            manager, renderer, final_text, stats_usage, started_monotonic, finished_monotonic
         )
 
     def _get_tool_client(self) -> ToolClient:

glaip_sdk/client/run_rendering.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import json
 import logging
-from collections.abc import Callable
+from collections.abc import AsyncIterable, Callable
 from time import monotonic
 from typing import Any
 
@@ -30,6 +30,7 @@ from glaip_sdk.utils.rendering.renderer import (
 from glaip_sdk.utils.rendering.state import TranscriptBuffer
 
 NO_AGENT_RESPONSE_FALLBACK = "No agent response received."
+_FINAL_EVENT_TYPES = {"final_response", "error", "step_limit_exceeded"}
 
 
 def _coerce_to_string(value: Any) -> str:
@@ -156,6 +157,9 @@ class AgentRunRenderingManager:
 
                 if controller and getattr(controller, "enabled", False):
                     controller.poll(renderer)
+                parsed_event = self._parse_event(event)
+                if parsed_event and self._is_final_event(parsed_event):
+                    break
         finally:
             if controller and getattr(controller, "enabled", False):
                 controller.on_stream_complete()
@@ -163,6 +167,300 @@ class AgentRunRenderingManager:
         finished_monotonic = monotonic()
         return final_text, stats_usage, started_monotonic, finished_monotonic
 
+    async def async_process_stream_events(
+        self,
+        event_stream: AsyncIterable[dict[str, Any]],
+        renderer: RichStreamRenderer,
+        meta: dict[str, Any],
+        *,
+        skip_final_render: bool = True,
+    ) -> tuple[str, dict[str, Any], float | None, float | None]:
+        """Process streaming events from an async event source.
+
+        This method provides unified stream processing for both remote (HTTP)
+        and local (LangGraph) agent execution, ensuring consistent behavior.
+
+        Args:
+            event_stream: Async iterable yielding SSE-like event dicts.
+                Each event should have a "data" key with JSON string, or be
+                a pre-parsed dict with "content", "metadata", etc.
+            renderer: Renderer to use for displaying events.
+            meta: Metadata dictionary for renderer context.
+            skip_final_render: If True, skip rendering final_response events
+                (they are rendered separately via finalize_renderer).
+
+        Returns:
+            Tuple of (final_text, stats_usage, started_monotonic, finished_monotonic).
+        """
+        final_text = ""
+        stats_usage: dict[str, Any] = {}
+        started_monotonic: float | None = None
+        last_rendered_content: str | None = None
+
+        controller = getattr(renderer, "transcript_controller", None)
+        if controller and getattr(controller, "enabled", False):
+            controller.on_stream_start(renderer)
+
+        try:
+            async for event in event_stream:
+                if started_monotonic is None:
+                    started_monotonic = monotonic()
+
+                # Parse event if needed (handles both raw SSE and pre-parsed dicts)
+                parsed_event = self._parse_event(event)
+                if parsed_event is None:
+                    continue
+
+                # Process the event and update accumulators
+                final_text, stats_usage = self._handle_parsed_event(
+                    parsed_event,
+                    renderer,
+                    final_text,
+                    stats_usage,
+                    meta,
+                    skip_final_render=skip_final_render,
+                    last_rendered_content=last_rendered_content,
+                )
+
+                # Track last rendered content to avoid duplicates
+                content_str = self._extract_content_string(parsed_event)
+                if content_str:
+                    last_rendered_content = content_str
+
+                if controller and getattr(controller, "enabled", False):
+                    controller.poll(renderer)
+                if parsed_event and self._is_final_event(parsed_event):
+                    break
+        finally:
+            if controller and getattr(controller, "enabled", False):
+                controller.on_stream_complete()
+
+        finished_monotonic = monotonic()
+        return final_text, stats_usage, started_monotonic, finished_monotonic
+
+    def _parse_event(self, event: dict[str, Any]) -> dict[str, Any] | None:
+        """Parse an SSE event dict into a usable format.
+
+        Args:
+            event: Raw event dict, either with "data" key (SSE format) or
+                pre-parsed with "content", "metadata", etc.
+
+        Returns:
+            Parsed event dict, or None if parsing fails.
+        """
+        if "data" in event:
+            try:
+                return json.loads(event["data"])
+            except json.JSONDecodeError:
+                self._logger.debug("Non-JSON SSE fragment skipped")
+                return None
+        # Already parsed (e.g., from local runner)
+        return event if event else None
+
+    def _handle_parsed_event(
+        self,
+        ev: dict[str, Any],
+        renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        meta: dict[str, Any],
+        *,
+        skip_final_render: bool = True,
+        last_rendered_content: str | None = None,
+    ) -> tuple[str, dict[str, Any]]:
+        """Handle a parsed event and update accumulators.
+
+        Args:
+            ev: Parsed event dictionary.
+            renderer: Renderer instance.
+            final_text: Current accumulated final text.
+            stats_usage: Usage statistics dictionary.
+            meta: Metadata dictionary.
+            skip_final_render: If True, skip rendering final_response events.
+            last_rendered_content: Last rendered content to avoid duplicates.
+
+        Returns:
+            Tuple of (updated_final_text, updated_stats_usage).
+        """
+        kind = self._get_event_kind(ev)
+
+        # Dispatch to specialized handlers based on event kind
+        handler = self._get_event_handler(kind, ev)
+        if handler:
+            return handler(ev, renderer, final_text, stats_usage, meta, skip_final_render)
+
+        # Default: handle content events
+        return self._handle_content_event_async(ev, renderer, final_text, stats_usage, last_rendered_content)
+
+    def _get_event_handler(
+        self,
+        kind: str | None,
+        ev: dict[str, Any],
+    ) -> Callable[..., tuple[str, dict[str, Any]]] | None:
+        """Get the appropriate handler for an event kind.
+
+        Args:
+            kind: Event kind string.
+            ev: Event dictionary (for checking is_final flag).
+
+        Returns:
+            Handler function or None for default content handling.
+        """
+        if kind == "usage":
+            return self._handle_usage_event
+        if kind == "final_response" or ev.get("is_final"):
+            return self._handle_final_response_event
+        if kind == "run_info":
+            return self._handle_run_info_event_wrapper
+        if kind in ("artifact", "status_update"):
+            return self._handle_render_only_event
+        return None
+
+    def _handle_usage_event(
+        self,
+        ev: dict[str, Any],
+        _renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        _meta: dict[str, Any],
+        _skip_final_render: bool,
+    ) -> tuple[str, dict[str, Any]]:
+        """Handle usage events."""
+        stats_usage.update(ev.get("usage") or {})
+        return final_text, stats_usage
+
+    def _handle_final_response_event(
+        self,
+        ev: dict[str, Any],
+        renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        _meta: dict[str, Any],
+        skip_final_render: bool,
+    ) -> tuple[str, dict[str, Any]]:
+        """Handle final_response events."""
+        content = ev.get("content")
+        if content:
+            final_text = str(content)
+        if not skip_final_render:
+            renderer.on_event(ev)
+        return final_text, stats_usage
+
+    def _handle_run_info_event_wrapper(
+        self,
+        ev: dict[str, Any],
+        renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        meta: dict[str, Any],
+        _skip_final_render: bool,
+    ) -> tuple[str, dict[str, Any]]:
+        """Handle run_info events."""
+        self._handle_run_info_event(ev, meta, renderer)
+        return final_text, stats_usage
+
+    def _handle_render_only_event(
+        self,
+        ev: dict[str, Any],
+        renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        _meta: dict[str, Any],
+        _skip_final_render: bool,
+    ) -> tuple[str, dict[str, Any]]:
+        """Handle events that only need rendering (artifact, status_update)."""
+        renderer.on_event(ev)
+        return final_text, stats_usage
+
+    def _handle_content_event_async(
+        self,
+        ev: dict[str, Any],
+        renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        last_rendered_content: str | None,
+    ) -> tuple[str, dict[str, Any]]:
+        """Handle content events with deduplication."""
+        content = ev.get("content")
+        if content:
+            content_str = str(content)
+            if not content_str.startswith("Artifact received:"):
+                kind = self._get_event_kind(ev)
+                # Skip accumulating content for status updates and agent steps
+                if kind in ("agent_step", "status_update"):
+                    renderer.on_event(ev)
+                    return final_text, stats_usage
+
+                if self._is_token_event(ev):
+                    renderer.on_event(ev)
+                    final_text = f"{final_text}{content_str}"
+                else:
+                    if content_str != last_rendered_content:
+                        renderer.on_event(ev)
+                    final_text = content_str
+        else:
+            renderer.on_event(ev)
+        return final_text, stats_usage
+
+    def _get_event_kind(self, ev: dict[str, Any]) -> str | None:
+        """Extract normalized event kind from parsed event.
+
+        Args:
+            ev: Parsed event dictionary.
+
+        Returns:
+            Event kind string or None.
+        """
+        metadata = ev.get("metadata") or {}
+        kind = metadata.get("kind")
+        if kind:
+            return str(kind)
+        event_type = ev.get("event_type")
+        return str(event_type) if event_type else None
+
+    def _is_token_event(self, ev: dict[str, Any]) -> bool:
+        """Return True when the event represents token streaming output.
+
+        Args:
+            ev: Parsed event dictionary.
+
+        Returns:
+            True when the event is a token chunk, otherwise False.
+        """
+        metadata = ev.get("metadata") or {}
+        kind = metadata.get("kind")
+        return str(kind).lower() == "token"
+
+    def _is_final_event(self, ev: dict[str, Any]) -> bool:
+        """Return True when the event marks stream termination.
+
+        Args:
+            ev: Parsed event dictionary.
+
+        Returns:
+            True when the event is terminal, otherwise False.
+        """
+        if ev.get("is_final") is True or ev.get("final") is True:
+            return True
+        kind = self._get_event_kind(ev)
+        return kind in _FINAL_EVENT_TYPES
+
+    def _extract_content_string(self, event: dict[str, Any]) -> str | None:
+        """Extract textual content from a parsed event.
+
+        Args:
+            event: Parsed event dictionary.
+
+        Returns:
+            Content string or None.
+        """
+        if not event:
+            return None
+        content = event.get("content")
+        if content:
+            return str(content)
+        return None
+
     def _capture_request_id(
         self,
         stream_response: httpx.Response,
@@ -239,7 +537,9 @@ class AgentRunRenderingManager:
         if handled is not None:
             return handled
 
-        if ev.get("content"):
+        # Only accumulate content for actual content events, not status updates or agent steps
+        # Status updates (agent_step) should be rendered but not accumulated in final_text
+        if ev.get("content") and kind not in ("agent_step", "status_update"):
             final_text = self._handle_content_event(ev, final_text)
 
         return final_text, stats_usage
@@ -285,6 +585,8 @@ class AgentRunRenderingManager:
         """
         content = ev.get("content", "")
         if not content.startswith("Artifact received:"):
+            if self._is_token_event(ev):
+                return f"{final_text}{content}"
             return content
         return final_text
 
@@ -413,3 +715,33 @@ def compute_timeout_seconds(kwargs: dict[str, Any]) -> float:
         if not specified in kwargs.
     """
     return kwargs.get("timeout", DEFAULT_AGENT_RUN_TIMEOUT)
+
+
+def finalize_render_manager(
+    manager: AgentRunRenderingManager,
+    renderer: RichStreamRenderer,
+    final_text: str,
+    stats_usage: dict[str, Any],
+    started_monotonic: float | None,
+    finished_monotonic: float | None,
+) -> str:
+    """Helper to finalize renderer via manager and return final text.
+
+    Args:
+        manager: The rendering manager instance.
+        renderer: Renderer to finalize.
+        final_text: Final text content.
+        stats_usage: Usage statistics dictionary.
+        started_monotonic: Start time (monotonic).
+        finished_monotonic: Finish time (monotonic).
+
+    Returns:
+        Final text string.
+    """
+    return manager.finalize_renderer(
+        renderer,
+        final_text,
+        stats_usage,
+        started_monotonic,
+        finished_monotonic,
+    )

glaip_sdk/hitl/__init__.py

@@ -0,0 +1,15 @@
+"""Human-in-the-Loop (HITL) utilities for glaip-sdk.
+
+This package provides utilities for HITL approval workflows in both local
+and remote agent execution modes.
+
+For local development, LocalPromptHandler is automatically injected when
+agent_config.hitl_enabled is True. No manual setup required.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from glaip_sdk.hitl.local import LocalPromptHandler, PauseResumeCallback
+
+__all__ = ["LocalPromptHandler", "PauseResumeCallback"]