glaip-sdk 0.7.9__py3-none-any.whl → 0.7.11__py3-none-any.whl

glaip_sdk/cli/slash/tui/toast.py

@@ -1,18 +1,20 @@
-"""Toast notification helpers for Textual TUIs.
-
-Authors:
-    Raymond Christopher (raymond.christopher@gdplabs.id)
-"""
+"""Toast widgets and state management for the TUI."""
 
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Callable
 from dataclasses import dataclass
 from enum import Enum
+from typing import Any, cast
+
+from rich.text import Text
+from textual.message import Message
+from textual.widgets import Static
 
 
 class ToastVariant(str, Enum):
-    """Toast message variant."""
+    """Toast message variant for styling and behavior."""
 
     INFO = "info"
     SUCCESS = "success"
@@ -30,7 +32,7 @@ DEFAULT_TOAST_DURATIONS_SECONDS: dict[ToastVariant, float] = {
 
 @dataclass(frozen=True, slots=True)
 class ToastState:
-    """Immutable toast payload."""
+    """Immutable toast notification state."""
 
     message: str
     variant: ToastVariant
@@ -38,16 +40,25 @@ class ToastState:
 
 
 class ToastBus:
-    """Single-toast state holder with auto-dismiss."""
+    """Toast state manager with auto-dismiss functionality."""
 
-    def __init__(self) -> None:
-        """Initialize the bus."""
+    class Changed(Message):
+        """Message sent when toast state changes."""
+
+        def __init__(self, state: ToastState | None) -> None:
+            """Initialize the changed message with new toast state."""
+            super().__init__()
+            self.state = state
+
+    def __init__(self, on_change: Callable[[ToastBus.Changed], None] | None = None) -> None:
+        """Initialize the toast bus with optional change callback."""
         self._state: ToastState | None = None
         self._dismiss_task: asyncio.Task[None] | None = None
+        self._on_change = on_change
 
     @property
     def state(self) -> ToastState | None:
-        """Return the current toast state."""
+        """Return the current toast state, or None if no toast is shown."""
         return self._state
 
     def show(
@@ -57,7 +68,14 @@ class ToastBus:
         *,
         duration_seconds: float | None = None,
     ) -> None:
-        """Set toast state and schedule auto-dismiss."""
+        """Show a toast notification with the given message and variant.
+
+        Args:
+            message: The message to display in the toast.
+            variant: The visual variant of the toast (INFO, SUCCESS, WARNING, ERROR).
+            duration_seconds: Optional custom duration in seconds. If None, uses default
+                duration for the variant (2s for SUCCESS, 3s for INFO/WARNING, 5s for ERROR).
+        """
         resolved_variant = self._coerce_variant(variant)
         resolved_duration = (
             DEFAULT_TOAST_DURATIONS_SECONDS[resolved_variant] if duration_seconds is None else float(duration_seconds)
@@ -80,23 +98,26 @@ class ToastBus:
             ) from None
 
         self._dismiss_task = loop.create_task(self._auto_dismiss(resolved_duration))
+        self._notify_changed()
 
     def clear(self) -> None:
-        """Clear the current toast."""
+        """Clear the current toast notification immediately."""
         self._cancel_dismiss_task()
         self._state = None
+        self._notify_changed()
 
     def copy_success(self, label: str | None = None) -> None:
-        """Show clipboard success toast."""
+        """Show a success toast for clipboard copy operations.
+
+        Args:
+            label: Optional label for what was copied (e.g., "Run ID", "JSON").
+        """
         message = "Copied to clipboard" if not label else f"Copied {label} to clipboard"
         self.show(message=message, variant=ToastVariant.SUCCESS)
 
     def copy_failed(self) -> None:
-        """Show clipboard failure toast."""
-        self.show(
-            message="Clipboard unavailable. Text printed below",
-            variant=ToastVariant.WARNING,
-        )
+        """Show a warning toast when clipboard copy fails."""
+        self.show(message="Clipboard unavailable. Text printed below.", variant=ToastVariant.WARNING)
 
     def _coerce_variant(self, variant: ToastVariant | str) -> ToastVariant:
         if isinstance(variant, ToastVariant):
@@ -121,3 +142,233 @@ class ToastBus:
 
         self._state = None
         self._dismiss_task = None
+        self._notify_changed()
+
+    def _notify_changed(self) -> None:
+        if self._on_change:
+            self._on_change(ToastBus.Changed(self._state))
+
+
+class ToastHandlerMixin:
+    """Mixin providing common toast handling functionality.
+
+    Classes that inherit from this mixin can handle ToastBus.Changed messages
+    by automatically updating all Toast widgets in the component tree.
+    """
+
+    def on_toast_bus_changed(self, message: ToastBus.Changed) -> None:
+        """Refresh the toast widget when the toast bus updates.
+
+        Args:
+            message: The toast bus changed message containing the new state.
+        """
+        try:
+            for toast in self.query(Toast):
+                toast.update_state(message.state)
+        except Exception:
+            pass
+
+
+class ClipboardToastMixin:
+    """Mixin providing clipboard and toast orchestration functionality.
+
+    Classes that inherit from this mixin get shared clipboard adapter selection,
+    OSC52 writer setup, toast bus lookup, and copy-success/failure orchestration.
+    This consolidates duplicate clipboard/toast logic across TUI apps.
+
+    Expected attributes:
+        _ctx: TUIContext | None - Shared TUI context (optional)
+        _clipboard: ClipboardAdapter | None - Cached clipboard adapter (optional)
+        _local_toasts: ToastBus | None - Local toast bus instance (optional)
+    """
+
+    def _clipboard_adapter(self) -> Any:  # ClipboardAdapter
+        """Get or create a clipboard adapter instance.
+
+        Returns:
+            ClipboardAdapter instance, preferring context's adapter if available.
+        """
+        # Import here to avoid circular dependency
+        from glaip_sdk.cli.slash.tui.clipboard import ClipboardAdapter  # noqa: PLC0415
+
+        ctx = getattr(self, "_ctx", None)
+        clipboard = getattr(self, "_clipboard", None)
+
+        if ctx is not None and ctx.clipboard is not None:
+            return cast(ClipboardAdapter, ctx.clipboard)
+        if clipboard is not None:
+            return clipboard
+
+        adapter = ClipboardAdapter(terminal=ctx.terminal if ctx else None)
+        if ctx is not None:
+            ctx.clipboard = adapter
+        else:
+            self._clipboard = adapter
+        return adapter
+
+    def _osc52_writer(self) -> Callable[[str], Any] | None:
+        """Get an OSC52 writer function if console output is available.
+
+        Returns:
+            Writer function that writes OSC52 sequences to console output, or None.
+        """
+        try:
+            # Try self.app.console first (for Screen subclasses)
+            if hasattr(self, "app") and hasattr(self.app, "console"):
+                console = self.app.console
+            # Fall back to self.console (for App subclasses)
+            else:
+                console = getattr(self, "console", None)
+        except Exception:
+            return None
+
+        if console is None:
+            return None
+
+        output = getattr(console, "file", None)
+        if output is None:
+            return None
+
+        def _write(sequence: str, _output: Any = output) -> None:
+            _output.write(sequence)
+            _output.flush()
+
+        return _write
+
+    def _toast_bus(self) -> ToastBus | None:
+        """Get the toast bus instance.
+
+        Returns:
+            ToastBus instance, preferring context's bus if available, or None.
+        """
+        local_toasts = getattr(self, "_local_toasts", None)
+        ctx = getattr(self, "_ctx", None)
+
+        if local_toasts is not None:
+            return local_toasts
+        if ctx is not None and ctx.toasts is not None:
+            return ctx.toasts
+        return None
+
+    def _copy_to_clipboard(self, text: str, *, label: str | None = None) -> None:
+        """Copy text to clipboard and show toast notification.
+
+        Args:
+            text: The text to copy to clipboard.
+            label: Optional label for what was copied (e.g., "Run ID", "JSON").
+        """
+        adapter = self._clipboard_adapter()
+        writer = self._osc52_writer()
+        if writer:
+            result = adapter.copy(text, writer=writer)
+        else:
+            result = adapter.copy(text)
+
+        toasts = self._toast_bus()
+        if result.success:
+            if toasts:
+                toasts.copy_success(label)
+            else:
+                # Fallback to status announcement if toast bus unavailable
+                if hasattr(self, "_announce_status"):
+                    if label:
+                        self._announce_status(f"Copied {label} to clipboard.")
+                    else:
+                        self._announce_status("Copied to clipboard.")
+            return
+
+        # Copy failed
+        if toasts:
+            toasts.copy_failed()
+        else:
+            # Fallback to status announcement if toast bus unavailable
+            if hasattr(self, "_announce_status"):
+                self._announce_status("Clipboard unavailable. Text printed below.")
+
+        # Append fallback text output
+        if hasattr(self, "_append_copy_fallback"):
+            self._append_copy_fallback(text)
+
+
+class Toast(Static):
+    """A Textual widget that displays toast notifications at the top-right of the screen.
+
+    The Toast widget is updated via `update_state()` calls from message handlers
+    (e.g., `on_toast_bus_changed`). The widget does not auto-subscribe to ToastBus
+    state changes; the app must call `update_state()` when toast state changes.
+    """
+
+    DEFAULT_CSS = """
+    #toast-container {
+        width: 100%;
+        height: auto;
+        dock: top;
+        align: right top;
+    }
+
+    Toast {
+        width: auto;
+        min-width: 20;
+        max-width: 40;
+        height: auto;
+        padding: 0 1;
+        margin: 1 2;
+        background: $surface;
+        color: $text;
+        border: solid $primary;
+        display: none;
+    }
+
+    Toast.visible {
+        display: block;
+    }
+
+    Toast.info {
+        border: solid $accent;
+    }
+
+    Toast.success {
+        border: solid $success;
+    }
+
+    Toast.warning {
+        border: solid $warning;
+    }
+
+    Toast.error {
+        border: solid $error;
+    }
+    """
+
+    def __init__(self) -> None:
+        """Initialize the Toast widget.
+
+        The widget is updated via `update_state()` calls from message handlers
+        (e.g., `on_toast_bus_changed`). The widget does not auto-subscribe to
+        a ToastBus; the app must call `update_state()` when toast state changes.
+        """
+        super().__init__("")
+
+    def update_state(self, state: ToastState | None) -> None:
+        """Update the toast display based on the provided state.
+
+        Args:
+            state: The toast state to display, or None to hide the toast.
+        """
+        if not state:
+            self.remove_class("visible")
+            return
+
+        icon = "ℹ️"
+        if state.variant == ToastVariant.SUCCESS:
+            icon = "✅"
+        elif state.variant == ToastVariant.WARNING:
+            icon = "⚠️"
+        elif state.variant == ToastVariant.ERROR:
+            icon = "❌"
+
+        self.update(Text.assemble((f"{icon} ", "bold"), state.message))
+
+        self.remove_class("info", "success", "warning", "error")
+        self.add_class(state.variant.value)
+        self.add_class("visible")

glaip_sdk/client/run_rendering.py

@@ -172,6 +172,63 @@ class AgentRunRenderingManager:
         finished_monotonic = monotonic()
         return final_text, stats_usage, started_monotonic, finished_monotonic
 
+    async def _consume_event_stream(
+        self,
+        event_stream: AsyncIterable[dict[str, Any]],
+        renderer: RichStreamRenderer,
+        final_text: str,
+        stats_usage: dict[str, Any],
+        meta: dict[str, Any],
+        skip_final_render: bool,
+        last_rendered_content: str | None,
+        controller: Any | None,
+    ) -> tuple[str, dict[str, Any], float | None]:
+        """Consume event stream and update state.
+
+        Args:
+            event_stream: Async iterable yielding SSE-like event dicts.
+            renderer: Renderer to use for displaying events.
+            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.
+            controller: Controller instance.
+
+        Returns:
+            Tuple of (final_text, stats_usage, started_monotonic).
+        """
+        started_monotonic: float | None = None
+
+        async for event in event_stream:
+            if started_monotonic is None:
+                started_monotonic = monotonic()
+
+            parsed_event = self._parse_event(event)
+            if parsed_event is None:
+                continue
+
+            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,
+            )
+
+            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
+
+        return final_text, stats_usage, started_monotonic
+
     async def async_process_stream_events(
         self,
         event_stream: AsyncIterable[dict[str, Any]],
@@ -207,35 +264,25 @@ class AgentRunRenderingManager:
             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
+            final_text, stats_usage, started_monotonic = await self._consume_event_stream(
+                event_stream,
+                renderer,
+                final_text,
+                stats_usage,
+                meta,
+                skip_final_render,
+                last_rendered_content,
+                controller,
+            )
+        except Exception as e:
+            err_msg = str(e)
+            reason = getattr(getattr(e, "result", None), "reason", None)
+            if reason:
+                final_text = f"⚠️ Guardrail violation: {reason}"
+            elif "⚠️ Guardrail violation" in err_msg or "Content blocked by guardrails" in err_msg:
+                final_text = err_msg
+            else:
+                raise e
         finally:
             if controller and getattr(controller, "enabled", False):
                 controller.on_stream_complete()

glaip_sdk/guardrails/__init__.py

@@ -0,0 +1,80 @@
+"""Guardrails package for content filtering and safety checks.
+
+This package provides modular guardrail engines and managers for filtering
+harmful content in AI agent interactions. All components support lazy loading
+from aip-agents to maintain Principle VII compliance.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aip_agents.guardrails.engines.nemo import NemoGuardrailEngine
+    from aip_agents.guardrails.engines.phrase_matcher import PhraseMatcherEngine
+    from aip_agents.guardrails.manager import GuardrailManager
+    from aip_agents.guardrails.schemas import GuardrailMode
+
+
+class ImportableName(StrEnum):
+    """Names of the importable attributes."""
+
+    GUARDRAIL_MANAGER = "GuardrailManager"
+    PHRASE_MATCHER_ENGINE = "PhraseMatcherEngine"
+    NEMO_GUARDRAIL_ENGINE = "NemoGuardrailEngine"
+    GUARDRAIL_MODE = "GuardrailMode"
+
+
+# Lazy loading support - components are only imported when actually used
+_LAZY_IMPORTS = {}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import to avoid eager loading of optional aip-agents dependency.
+
+    This function is called by Python when an attribute is not found in the module.
+    It performs the import from aip_agents.guardrails at runtime.
+
+    Args:
+        name: The name of the attribute to get.
+
+    Returns:
+        The attribute value from aip_agents.
+
+    Raises:
+        AttributeError: If the attribute doesn't exist.
+        ImportError: If aip-agents is not installed but a component is accessed.
+    """
+    if name in _LAZY_IMPORTS:
+        return _LAZY_IMPORTS[name]
+
+    if name == ImportableName.GUARDRAIL_MANAGER:
+        from aip_agents.guardrails.manager import GuardrailManager  # noqa: PLC0415
+
+        _LAZY_IMPORTS[name] = GuardrailManager
+        return GuardrailManager
+
+    if name == ImportableName.PHRASE_MATCHER_ENGINE:
+        from aip_agents.guardrails.engines.phrase_matcher import (  # noqa: PLC0415
+            PhraseMatcherEngine,
+        )
+
+        _LAZY_IMPORTS[name] = PhraseMatcherEngine
+        return PhraseMatcherEngine
+
+    if name == ImportableName.NEMO_GUARDRAIL_ENGINE:
+        from aip_agents.guardrails.engines.nemo import NemoGuardrailEngine  # noqa: PLC0415
+
+        _LAZY_IMPORTS[name] = NemoGuardrailEngine
+        return NemoGuardrailEngine
+
+    if name == ImportableName.GUARDRAIL_MODE:
+        from aip_agents.guardrails.schemas import GuardrailMode  # noqa: PLC0415
+
+        _LAZY_IMPORTS[name] = GuardrailMode
+        return GuardrailMode
+
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

glaip_sdk/guardrails/serializer.py

@@ -0,0 +1,89 @@
+"""Guardrail serialization logic.
+
+This module provides functionality to serialize GuardrailManager and its engines
+into the JSON format expected by the GL AIP backend. This keeps the serialization
+logic within the SDK rather than polluting the core aip-agents logic.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from glaip_sdk.guardrails import (
+        GuardrailManager,
+        NemoGuardrailEngine,
+        PhraseMatcherEngine,
+    )
+
+
+def _serialize_phrase_matcher(engine: PhraseMatcherEngine) -> dict[str, Any]:
+    """Serialize a PhraseMatcherEngine configuration."""
+    config: dict[str, Any] = {}
+
+    # Extract config from BaseGuardrailEngineConfig
+    if hasattr(engine, "config") and engine.config:
+        config.update(engine.config.model_dump())
+
+    # Extract specific fields
+    if hasattr(engine, "banned_phrases"):
+        config["banned_phrases"] = engine.banned_phrases
+
+    return config
+
+
+def _serialize_nemo(engine: NemoGuardrailEngine) -> dict[str, Any]:
+    """Serialize a NemoGuardrailEngine configuration."""
+    config: dict[str, Any] = {}
+
+    # Extract config from BaseGuardrailEngineConfig
+    if hasattr(engine, "config") and engine.config:
+        config.update(engine.config.model_dump())
+
+    # Extract specific fields
+    nemo_fields = [
+        "topic_safety_mode",
+        "allowed_topics",
+        "denied_topics",
+        "include_core_restrictions",
+        "core_restriction_categories",
+        "config_dict",
+        "denial_phrases",
+    ]
+    for field in nemo_fields:
+        if hasattr(engine, field):
+            val = getattr(engine, field)
+            if val is not None:
+                config[field] = val
+
+    return config
+
+
+def serialize_guardrail_manager(manager: GuardrailManager) -> dict[str, Any]:
+    """Serialize a GuardrailManager into the backend JSON format.
+
+    Args:
+        manager: The GuardrailManager instance to serialize.
+
+    Returns:
+        A dictionary matching the agent_config.guardrails schema.
+    """
+    from glaip_sdk.guardrails import NemoGuardrailEngine, PhraseMatcherEngine  # noqa: PLC0415
+
+    engines_config = []
+
+    if hasattr(manager, "engines"):
+        for engine in manager.engines:
+            if isinstance(engine, PhraseMatcherEngine):
+                engines_config.append({"type": "phrase_matcher", "config": _serialize_phrase_matcher(engine)})
+            elif isinstance(engine, NemoGuardrailEngine):
+                engines_config.append({"type": "nemo", "config": _serialize_nemo(engine)})
+            else:
+                # Fallback for unknown engines
+                continue
+
+    enabled = getattr(manager, "enabled", True)
+    return {"enabled": enabled, "engines": engines_config}

glaip_sdk/payload_schemas/agent.py

@@ -57,6 +57,7 @@ AGENT_FIELD_RULES: Mapping[str, FieldRule] = {
     "timeout": FieldRule(cli_managed_create=True, cli_managed_update=True),
     # Fields requiring sanitisation before sending to the API
     "agent_config": FieldRule(requires_sanitization=True),
+    "guardrail": FieldRule(requires_sanitization=True),
 }
 
 

glaip_sdk/payload_schemas/guardrails.py

@@ -0,0 +1,34 @@
+"""Guardrail payload schemas for API communication.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class GuardrailEnginePayload(BaseModel):
+    """Payload schema for a single guardrail engine configuration.
+
+    This model defines the structure for individual safety engines (e.g., phrase_matcher, nemo)
+    when communicating with the GL AIP backend.
+    """
+
+    type: str = Field(..., description="The type of guardrail engine (e.g., 'phrase_matcher', 'nemo')")
+    config: Mapping[str, Any] = Field(..., description="Engine-specific configuration parameters")
+
+
+class GuardrailPayload(BaseModel):
+    """Payload schema for global guardrail settings.
+
+    This model acts as the container for all guardrail configurations within the agent_config.
+    """
+
+    enabled: bool = Field(default=True, description="Global toggle to enable or disable all guardrails")
+    engines: Sequence[GuardrailEnginePayload] = Field(
+        default_factory=list,
+        description="List of configured guardrail engines",
+    )

glaip_sdk/runner/langgraph.py

@@ -387,6 +387,7 @@ class LangGraphRunner(BaseRunner):
             agents=sub_agent_instances if sub_agent_instances else None,
             tool_configs=tool_configs if tool_configs else None,
             tool_output_manager=tool_output_manager,
+            guardrail=agent.guardrail,
             **agent_config_params,
             **agent_config_kwargs,
         )