glaip-sdk 0.6.5b6__py3-none-any.whl → 0.7.12__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

@@ -50,16 +50,11 @@ 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.client.schedules import AgentScheduleManager
+    from glaip_sdk.guardrails import GuardrailManager
     from glaip_sdk.models import AgentResponse
     from glaip_sdk.registry import AgentRegistry, MCPRegistry, ToolRegistry
 
@@ -136,6 +131,7 @@ class Agent:
         agents: list | None = None,
         mcps: list | None = None,
         model: str | None = _UNSET,  # type: ignore[assignment]
+        guardrail: GuardrailManager | None = None,
         _client: Any = None,
         **kwargs: Any,
     ) -> None:
@@ -153,7 +149,9 @@ class Agent:
             agents: List of sub-agents (Agent classes, instances, or strings).
             mcps: List of MCPs.
             model: Model identifier.
+            guardrail: The guardrail manager for content safety.
             _client: Internal client reference (set automatically).
+
             **kwargs: Additional configuration parameters:
                 - timeout: Execution timeout in seconds.
                 - metadata: Optional metadata dictionary.
@@ -179,6 +177,7 @@ class Agent:
         self._agents = agents
         self._mcps = mcps
         self._model = model
+        self._guardrail = guardrail
         self._language_model_id: str | None = None
         # Extract parameters from kwargs with _UNSET defaults
         self._timeout = kwargs.pop("timeout", Agent._UNSET)  # type: ignore[assignment]
@@ -458,6 +457,11 @@ class Agent:
             return self._mcp_configs
         return None
 
+    @property
+    def guardrail(self) -> GuardrailManager | None:
+        """The guardrail manager for content safety."""
+        return self._guardrail
+
     @property
     def a2a_profile(self) -> dict[str, Any] | None:
         """A2A (Agent-to-Agent) profile configuration.
@@ -518,6 +522,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
@@ -551,11 +557,20 @@ class Agent:
 
         # Handle agent_config with timeout
         # The timeout property is a convenience that maps to agent_config.execution_timeout
-        agent_config = dict(self.agent_config) if self.agent_config else {}
+        raw_config = self.agent_config if self.agent_config is not self._UNSET else {}
+        agent_config = dict(raw_config) if raw_config else {}
+
         if self.timeout and "execution_timeout" not in agent_config:
             agent_config["execution_timeout"] = self.timeout
-        if agent_config:
-            config["agent_config"] = agent_config
+
+        if self.guardrail:
+            from glaip_sdk.guardrails.serializer import (  # noqa: PLC0415
+                serialize_guardrail_manager,
+            )
+
+            agent_config["guardrails"] = serialize_guardrail_manager(self.guardrail)
+
+        config["agent_config"] = agent_config
 
         # Handle tool_configs - resolve tool names/classes to IDs
         if self.tool_configs:
@@ -587,11 +602,20 @@ class Agent:
 
         Returns:
             List of resolved MCP IDs for the API payload.
+
+        Raises:
+            ValueError: If an MCP fails to resolve to a valid ID.
         """
         if not self.mcps:
             return []
 
-        return [registry.resolve(mcp_ref).id for mcp_ref in self.mcps]
+        resolved_ids: list[str] = []
+        for mcp_ref in self.mcps:
+            mcp = registry.resolve(mcp_ref)
+            if not mcp.id:
+                raise ValueError(f"Failed to resolve ID for MCP: {mcp_ref}")
+            resolved_ids.append(mcp.id)
+        return resolved_ids
 
     def _resolve_tools(self, registry: ToolRegistry) -> list[str]:
         """Resolve tool references to IDs using ToolRegistry.
@@ -605,12 +629,20 @@ class Agent:
 
         Returns:
             List of resolved tool IDs for the API payload.
+
+        Raises:
+            ValueError: If a tool fails to resolve to a valid ID.
         """
         if not self.tools:
             return []
 
-        # Resolve each tool reference to a Tool object, extract ID
-        return [registry.resolve(tool_ref).id for tool_ref in self.tools]
+        resolved_ids: list[str] = []
+        for tool_ref in self.tools:
+            tool = registry.resolve(tool_ref)
+            if not tool.id:
+                raise ValueError(f"Failed to resolve ID for tool: {tool_ref}")
+            resolved_ids.append(tool.id)
+        return resolved_ids
 
     def _resolve_tool_configs(self, registry: ToolRegistry) -> dict[str, Any]:
         """Resolve tool_configs keys from tool names/classes to tool IDs.
@@ -653,6 +685,8 @@ class Agent:
             try:
                 # Resolve key (tool name/class) to Tool object, get ID
                 tool = registry.resolve(key)
+                if not tool.id:
+                    raise ValueError(f"Resolved tool has no ID: {key}")
                 resolved[tool.id] = config
             except (ValueError, KeyError) as e:
                 raise ValueError(f"Failed to resolve tool config key: {key}") from e
@@ -688,6 +722,8 @@ class Agent:
                     resolved_id = key
                 else:
                     mcp = registry.resolve(key)
+                    if not mcp.id:
+                        raise ValueError(f"Resolved MCP has no ID: {key}")
                     resolved_id = mcp.id
 
                 if resolved_id in resolved:
@@ -703,7 +739,7 @@ class Agent:
 
         return resolved
 
-    def _resolve_agents(self, registry: AgentRegistry) -> list:
+    def _resolve_agents(self, registry: AgentRegistry) -> list[str]:
         """Resolve sub-agent references using AgentRegistry.
 
         Uses the global AgentRegistry to cache Agent objects across deployments.
@@ -715,12 +751,20 @@ class Agent:
 
         Returns:
             List of resolved agent IDs for the API payload.
+
+        Raises:
+            ValueError: If an agent fails to resolve to a valid ID.
         """
         if not self.agents:
             return []
 
-        # Resolve each agent reference to a deployed Agent, extract ID
-        return [registry.resolve(agent_ref).id for agent_ref in self.agents]
+        resolved_ids: list[str] = []
+        for agent_ref in self.agents:
+            agent = registry.resolve(agent_ref)
+            if not agent.id:
+                raise ValueError(f"Failed to resolve ID for agent: {agent_ref}")
+            resolved_ids.append(agent.id)
+        return resolved_ids
 
     def _create_or_update_agent(
         self,
@@ -811,6 +855,8 @@ class Agent:
         Returns:
             Dictionary containing Agent attributes.
         """
+        config = self._build_config(get_tool_registry(), get_mcp_registry())
+
         data = {
             "id": self._id,
             "name": self.name,
@@ -824,10 +870,11 @@ class Agent:
             "mcps": self.mcps,
             "timeout": self.timeout,
             "metadata": self.metadata,
-            "agent_config": self.agent_config,
+            "agent_config": config.get("agent_config"),
             "tool_configs": self.tool_configs,
             "mcp_configs": self.mcp_configs,
             "a2a_profile": self.a2a_profile,
+            "guardrail": self.guardrail,
             "created_at": self._created_at,
             "updated_at": self._updated_at,
         }
@@ -847,6 +894,36 @@ class Agent:
         self._client = client
         return self
 
+    @property
+    def schedule(self) -> AgentScheduleManager:
+        """Get the schedule manager for this agent.
+
+        Provides a convenient interface for managing schedules scoped to this agent.
+
+        Returns:
+            AgentScheduleManager for schedule operations
+
+        Raises:
+            ValueError: If agent is not deployed
+            RuntimeError: If agent is not bound to a client
+
+        Example:
+            >>> agent = client.get_agent_by_id("agent-id")
+            >>> schedules = agent.schedule.list()
+            >>> new_schedule = agent.schedule.create(
+            ...     input="Daily task",
+            ...     schedule="0 9 * * 1-5"
+            ... )
+        """
+        if not self.id:
+            raise ValueError(_AGENT_NOT_DEPLOYED_MSG)
+        if not self._client:
+            raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
+
+        from glaip_sdk.client.schedules import AgentScheduleManager  # noqa: PLC0415
+
+        return AgentScheduleManager(self, self._client.schedules)
+
     def _prepare_run_kwargs(
         self,
         message: str,
@@ -869,7 +946,7 @@ class Agent:
             ValueError: If the agent hasn't been deployed yet.
             RuntimeError: If client is not available.
         """
-        if not self.id:
+        if not self.id:  # pragma: no cover - defensive: called only when self.id is truthy
             raise ValueError(_AGENT_NOT_DEPLOYED_MSG)
         if not self._client:
             raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
@@ -883,6 +960,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(),
@@ -893,10 +974,68 @@ class Agent:
         call_kwargs.update(kwargs)
         return agent_client, call_kwargs
 
+    def _get_local_runner_or_raise(self) -> Any:
+        """Get the local runner if available, otherwise raise ValueError.
+
+        Returns:
+            The default local runner instance.
+
+        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()
+
+        # If agent is not deployed, it *must* use local runtime
+        if not self.id:
+            raise ValueError(f"{_AGENT_NOT_DEPLOYED_MSG}\n\n{get_local_runtime_missing_message()}")
+
+        # If agent IS deployed but local execution was forced (local=True)
+        raise ValueError(
+            f"Local execution override was requested, but local runtime is missing.\n\n"
+            f"{get_local_runtime_missing_message()}"
+        )
+
+    def _prepare_local_runner_kwargs(
+        self,
+        message: str,
+        verbose: bool,
+        runtime_config: dict[str, Any] | None,
+        chat_history: list[dict[str, str]] | None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Prepare kwargs for local runner execution.
+
+        Args:
+            message: The message to send to the agent.
+            verbose: If True, print streaming output to console.
+            runtime_config: Optional runtime configuration.
+            chat_history: Optional list of prior conversation messages.
+            **kwargs: Additional arguments.
+
+        Returns:
+            Dictionary of prepared kwargs for runner.run() or runner.arun().
+        """
+        return {
+            "agent": self,
+            "message": message,
+            "verbose": verbose,
+            "runtime_config": runtime_config,
+            "chat_history": chat_history,
+            **kwargs,
+        }
+
     def run(
         self,
         message: str,
         verbose: bool = False,
+        local: bool = False,
         runtime_config: dict[str, Any] | None = None,
         chat_history: list[dict[str, str]] | None = None,
         **kwargs: Any,
@@ -909,9 +1048,13 @@ class Agent:
         - **Local**: When the agent is not deployed and glaip-sdk[local] is installed,
           execution happens locally via aip-agents (no server required).
 
+        You can force local execution for a deployed agent by passing `local=True`.
+
         Args:
             message: The message to send to the agent.
             verbose: If True, print streaming output to console. Defaults to False.
+            local: If True, force local execution even if the agent is deployed.
+                Defaults to False.
             runtime_config: Optional runtime configuration for tools, MCPs, and agents.
                 Keys can be SDK objects, UUIDs, or names. Example:
                 {
@@ -933,42 +1076,47 @@ class Agent:
             RuntimeError: If server-backed execution fails due to client issues.
         """
         # Backend routing: deployed agents use server, undeployed use local (if available)
-        if self.id:
+        if self.id and not local:
             # Server-backed execution path (agent is deployed)
             agent_client, call_kwargs = self._prepare_run_kwargs(
-                message, verbose, runtime_config or kwargs.get("runtime_config"), **kwargs
+                message,
+                verbose,
+                runtime_config or kwargs.get("runtime_config"),
+                **kwargs,
             )
             if chat_history is not None:
                 call_kwargs["chat_history"] = chat_history
             return agent_client.run_agent(**call_kwargs)
 
-        # Local execution path (agent is not deployed)
-        if check_local_runtime_available():
-            runner = get_default_runner()
-            return runner.run(
-                agent=self,
-                message=message,
-                verbose=verbose,
-                runtime_config=runtime_config,
-                chat_history=chat_history,
-                **kwargs,
-            )
-
-        # Neither deployed nor local runtime available - provide actionable error
-        raise ValueError(f"{_AGENT_NOT_DEPLOYED_MSG}\n\n{get_local_runtime_missing_message()}")
+        # Local execution path (agent is not deployed OR local=True)
+        runner = self._get_local_runner_or_raise()
+        local_kwargs = self._prepare_local_runner_kwargs(message, verbose, runtime_config, chat_history, **kwargs)
+        return runner.run(**local_kwargs)
 
     async def arun(
         self,
         message: str,
         verbose: bool = False,
+        local: bool = False,
         runtime_config: dict[str, Any] | None = None,
+        chat_history: list[dict[str, str]] | None = None,
         **kwargs: Any,
     ) -> AsyncGenerator[dict, None]:
         """Run the agent asynchronously with streaming output.
 
+        Supports two execution modes:
+        - **Server-backed**: When the agent is deployed (has an ID), execution
+          happens via the AIP backend server with streaming.
+        - **Local**: When the agent is not deployed and glaip-sdk[local] is installed,
+          execution happens locally via aip-agents (no server required).
+
+        You can force local execution for a deployed agent by passing `local=True`.
+
         Args:
             message: The message to send to the agent.
-            verbose: If True, print streaming output to console.
+            verbose: If True, print streaming output to console. Defaults to False.
+            local: If True, force local execution even if the agent is deployed.
+                Defaults to False.
             runtime_config: Optional runtime configuration for tools, MCPs, and agents.
                 Keys can be SDK objects, UUIDs, or names. Example:
                 {
@@ -976,20 +1124,47 @@ class Agent:
                     "mcp_configs": {"mcp-id": {"setting": "on"}},
                     "agent_config": {"planning": True},
                 }
+                Defaults to None.
+            chat_history: Optional list of prior conversation messages for context.
+                Each message is a dict with "role" and "content" keys.
+                Defaults to None.
             **kwargs: Additional arguments to pass to the run API.
 
         Yields:
             Streaming response chunks from the agent.
 
         Raises:
-            ValueError: If the agent hasn't been deployed yet.
-            RuntimeError: If client is not available.
+            ValueError: If the agent is not deployed and local runtime is not available.
+            RuntimeError: If server-backed execution fails due to client issues.
         """
-        agent_client, call_kwargs = self._prepare_run_kwargs(
-            message, verbose, runtime_config or kwargs.get("runtime_config"), **kwargs
-        )
-        async for chunk in agent_client.arun_agent(**call_kwargs):
-            yield chunk
+        # Backend routing: deployed agents use server, undeployed use local (if available)
+        if self.id and not local:
+            # Server-backed execution path (agent is deployed)
+            agent_client, call_kwargs = self._prepare_run_kwargs(
+                message,
+                verbose,
+                runtime_config or kwargs.get("runtime_config"),
+                **kwargs,
+            )
+            if chat_history is not None:
+                call_kwargs["chat_history"] = chat_history
+
+            async for chunk in agent_client.arun_agent(**call_kwargs):
+                yield chunk
+            return
+
+        # Local execution path (agent is not deployed OR local=True)
+        runner = self._get_local_runner_or_raise()
+        local_kwargs = self._prepare_local_runner_kwargs(message, verbose, runtime_config, chat_history, **kwargs)
+        result = await runner.arun(**local_kwargs)
+        # Yield a final_response event for consistency with server-backed execution
+        # Include event_type for A2A event shape parity
+        yield {
+            "event_type": "final_response",
+            "metadata": {"kind": "final_response"},
+            "content": result,
+            "is_final": True,
+        }
 
     def update(self, **kwargs: Any) -> Agent:
         """Update the deployed agent with new configuration.

glaip_sdk/branding.py

@@ -17,6 +17,7 @@ import platform
 import sys
 
 from rich.console import Console
+from rich.text import Text
 
 from glaip_sdk._version import __version__ as SDK_VERSION
 from glaip_sdk.rich_components import AIPPanel
@@ -110,9 +111,13 @@ GDP Labs AI Agents Package
         return SDK_VERSION
 
     @staticmethod
-    def _make_console() -> Console:
+    def _make_console(force_terminal: bool | None = None, *, soft_wrap: bool = True) -> Console:
         """Create a Rich Console instance respecting NO_COLOR environment variables.
 
+        Args:
+            force_terminal: Override terminal detection when True/False.
+            soft_wrap: Whether to enable soft wrapping in the console.
+
         Returns:
             Console instance with color system configured based on environment.
         """
@@ -124,7 +129,12 @@ GDP Labs AI Agents Package
         else:
             color_system = "auto"
             no_color = False
-        return Console(color_system=color_system, no_color=no_color, soft_wrap=True)
+        return Console(
+            color_system=color_system,
+            no_color=no_color,
+            soft_wrap=soft_wrap,
+            force_terminal=force_terminal,
+        )
 
     # ---- public API -----------------------------------------------------------
     def get_welcome_banner(self) -> str:
@@ -209,3 +219,104 @@ GDP Labs AI Agents Package
             AIPBranding instance
         """
         return cls(version=sdk_version, package_name=package_name)
+
+
+class LogoAnimator:
+    """Animated logo with pulse effect for CLI startup.
+
+    Provides a "Knight Rider" style light pulse animation that sweeps across
+    the GL AIP logo during initialization tasks. Respects NO_COLOR and non-TTY
+    environments with graceful degradation.
+    """
+
+    # Animation colors from GDP Labs brand palette
+    BASE_BLUE = SECONDARY_MEDIUM  # "#005CB8" - Medium Blue
+    HIGHLIGHT = SECONDARY_LIGHT  # "#40B4E5" - Light Blue
+    WHITE = "#FFFFFF"  # Bright white center
+
+    def __init__(self, console: Console | None = None) -> None:
+        """Initialize LogoAnimator.
+
+        Args:
+            console: Optional console instance. If None, creates a default console.
+        """
+        self.console = console or AIPBranding._make_console()
+        self.logo = AIPBranding.AIP_LOGO
+        self.lines = self.logo.split("\n")
+        self.max_width = max(len(line) for line in self.lines) if self.lines else 0
+
+    def generate_frame(self, step: int, status_text: str = "") -> Text:
+        """Generate a single animation frame with logo pulse and status.
+
+        Args:
+            step: Current animation step (position of the pulse).
+            status_text: Optional status text to display below the logo.
+
+        Returns:
+            Text object with styled logo and status.
+        """
+        text = Text()
+
+        for line in self.lines:
+            for x, char in enumerate(line):
+                distance = abs(x - step)
+
+                if distance == 0:
+                    style = f"bold {self.WHITE}"  # Bright white center
+                elif distance <= 3:
+                    style = f"bold {self.HIGHLIGHT}"  # Light blue glow
+                else:
+                    style = self.BASE_BLUE  # Base blue
+
+                text.append(char, style=style)
+            text.append("\n")
+
+        # Add status area below the logo
+        if status_text:
+            text.append(f"\n{status_text}\n")
+
+        return text
+
+    def should_animate(self) -> bool:
+        """Check if animation should be used.
+
+        Returns:
+            True if animation should be used (interactive TTY with colors),
+            False otherwise (NO_COLOR set or non-TTY).
+        """
+        # Check for NO_COLOR environment variables
+        no_color = os.getenv("NO_COLOR") is not None or os.getenv("AIP_NO_COLOR") is not None
+        if no_color:
+            return False
+
+        # Check if console is a TTY
+        if not self.console.is_terminal:
+            return False
+
+        # Check if console explicitly disables colors
+        if self.console.no_color:
+            return False
+
+        # If we get here, we have a TTY without NO_COLOR set
+        # Rich will handle color detection, so we can animate
+        return True
+
+    def display_static_logo(self, status_text: str = "") -> None:
+        """Display static logo without animation (for non-TTY or NO_COLOR).
+
+        Args:
+            status_text: Optional status text to display below the logo.
+        """
+        self.console.print(self.static_frame(status_text))
+
+    def static_frame(self, status_text: str = "") -> Text:
+        """Return a static logo frame for use in non-animated renders.
+
+        Args:
+            status_text: Optional status text to display below the logo.
+        """
+        logo_text = Text(self.logo, style=self.BASE_BLUE)
+        if status_text:
+            logo_text.append("\n")
+            logo_text.append(status_text)
+        return logo_text

glaip_sdk/cli/account_store.py

@@ -523,6 +523,21 @@ class AccountStore:
 
         self._save_config(config)
 
+    def save_config_updates(self, config: dict[str, Any]) -> None:
+        """Save config updates, preserving all existing keys.
+
+        This method allows external code to update arbitrary config keys
+        (e.g., TUI preferences) while preserving the full config structure.
+
+        Args:
+            config: Complete configuration dictionary to save. This should
+                include all keys that should be preserved, not just updates.
+
+        Raises:
+            AccountStoreError: If config file cannot be written.
+        """
+        self._save_config(config)
+
 
 # Global instance for convenience
 _account_store = AccountStore()