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

glaip_sdk/guardrails/serializer.py

@@ -0,0 +1,91 @@
+"""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.
+    """
+    try:
+        from glaip_sdk.guardrails import NemoGuardrailEngine, PhraseMatcherEngine  # noqa: PLC0415
+    except ImportError:
+        enabled = getattr(manager, "enabled", True)
+        return {"enabled": enabled, "engines": []}
+
+    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)})
+            # Unknown engines are skipped.
+
+    enabled = getattr(manager, "enabled", True)
+    return {"enabled": enabled, "engines": engines_config}

glaip_sdk/hitl/__init__.py

@@ -6,10 +6,43 @@ and remote agent execution modes.
 For local development, LocalPromptHandler is automatically injected when
 agent_config.hitl_enabled is True. No manual setup required.
 
+For remote execution, use RemoteHITLHandler to handle HITL events programmatically.
+
 Authors:
     Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+    GLAIP SDK Team
 """
 
-from glaip_sdk.hitl.local import LocalPromptHandler, PauseResumeCallback
+from typing import TYPE_CHECKING, Any
+
+# These don't require aip_agents, so import them directly
+from glaip_sdk.hitl.base import HITLCallback, HITLDecision, HITLRequest, HITLResponse
+from glaip_sdk.hitl.callback import PauseResumeCallback
+from glaip_sdk.hitl.remote import RemoteHITLHandler
+
+if TYPE_CHECKING:
+    from glaip_sdk.hitl.local import LocalPromptHandler
+
+__all__ = [
+    "LocalPromptHandler",
+    "PauseResumeCallback",
+    "HITLCallback",
+    "HITLDecision",
+    "HITLRequest",
+    "HITLResponse",
+    "RemoteHITLHandler",
+]
+
+
+def __getattr__(name: str) -> Any:  # noqa: ANN401
+    """Lazy import for LocalPromptHandler.
+
+    This defers the import of aip_agents until LocalPromptHandler is actually accessed,
+    preventing ImportError when aip-agents is not installed but HITL is not being used.
+    """
+    if name == "LocalPromptHandler":
+        from glaip_sdk.hitl.local import LocalPromptHandler  # noqa: PLC0415
 
-__all__ = ["LocalPromptHandler", "PauseResumeCallback"]
+        globals()["LocalPromptHandler"] = LocalPromptHandler
+        return LocalPromptHandler
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

glaip_sdk/hitl/base.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Base types for HITL approval handling.
+
+Authors:
+    GLAIP SDK Team
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Protocol, runtime_checkable
+
+
+class HITLDecision(str, Enum):
+    """HITL decision types."""
+
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class HITLRequest:
+    """HITL approval request from SSE stream."""
+
+    request_id: str
+    tool_name: str
+    tool_args: dict[str, Any]
+    timeout_at: str  # ISO 8601, authoritative deadline
+    timeout_seconds: int  # Informational, fallback only
+
+    # Raw metadata for advanced use cases
+    hitl_metadata: dict[str, Any]
+    tool_metadata: dict[str, Any]
+
+
+@dataclass
+class HITLResponse:
+    """HITL decision response."""
+
+    decision: HITLDecision
+    operator_input: str | None = None
+
+
+@runtime_checkable
+class HITLCallback(Protocol):
+    """Protocol for HITL approval callbacks.
+
+    Callbacks should complete within the computed callback timeout.
+    Callbacks should handle exceptions internally or let them propagate.
+    """
+
+    def __call__(self, request: HITLRequest) -> HITLResponse:
+        """Handle HITL approval request.
+
+        Args:
+            request: HITL request with tool info and metadata
+
+        Returns:
+            HITLResponse with decision and optional operator input
+
+        Raises:
+            Any exception will be caught, logged, and treated as REJECTED.
+        """
+        ...

glaip_sdk/hitl/callback.py

@@ -0,0 +1,43 @@
+"""Pause/resume callback for HITL renderer control.
+
+This module provides PauseResumeCallback which allows HITL prompt handlers
+to control the live renderer without directly coupling to the renderer implementation.
+
+Author:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from typing import Any
+
+
+class PauseResumeCallback:
+    """Simple callback object for pausing/resuming the live renderer.
+
+    This allows the LocalPromptHandler to control the renderer without
+    directly coupling to the renderer implementation.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the callback."""
+        self._renderer: Any | None = None
+
+    def set_renderer(self, renderer: Any) -> None:
+        """Set the renderer instance.
+
+        Args:
+            renderer: RichStreamRenderer instance with pause_live() and resume_live() methods.
+        """
+        self._renderer = renderer
+
+    def pause(self) -> None:
+        """Pause the live renderer before prompting."""
+        if self._renderer and hasattr(self._renderer, "_shutdown_live"):
+            self._renderer._shutdown_live()
+
+    def resume(self) -> None:
+        """Resume the live renderer after prompting."""
+        if self._renderer and hasattr(self._renderer, "_ensure_live"):
+            self._renderer._ensure_live()
+
+
+__all__ = ["PauseResumeCallback"]

glaip_sdk/hitl/local.py

@@ -118,34 +118,4 @@ class LocalPromptHandler(BasePromptHandler):
             self._console.print(f"[dim]Context: {request.context}[/dim]")
 
 
-class PauseResumeCallback:
-    """Simple callback object for pausing/resuming the live renderer.
-
-    This allows the LocalPromptHandler to control the renderer without
-    directly coupling to the renderer implementation.
-    """
-
-    def __init__(self) -> None:
-        """Initialize the callback."""
-        self._renderer: Any | None = None
-
-    def set_renderer(self, renderer: Any) -> None:
-        """Set the renderer instance.
-
-        Args:
-            renderer: RichStreamRenderer instance with pause_live() and resume_live() methods.
-        """
-        self._renderer = renderer
-
-    def pause(self) -> None:
-        """Pause the live renderer before prompting."""
-        if self._renderer and hasattr(self._renderer, "_shutdown_live"):
-            self._renderer._shutdown_live()
-
-    def resume(self) -> None:
-        """Resume the live renderer after prompting."""
-        if self._renderer and hasattr(self._renderer, "_ensure_live"):
-            self._renderer._ensure_live()
-
-
-__all__ = ["LocalPromptHandler", "PauseResumeCallback"]
+__all__ = ["LocalPromptHandler"]