glaip-sdk 0.6.5b6__py3-none-any.whl → 0.7.12__py3-none-any.whl

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/hitl/__init__.py

@@ -0,0 +1,48 @@
+"""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.
+
+For remote execution, use RemoteHITLHandler to handle HITL events programmatically.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+    GLAIP SDK Team
+"""
+
+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
+
+        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

@@ -0,0 +1,121 @@
+"""Local HITL prompt handler with interactive console support.
+
+Author:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import os
+from typing import Any
+
+try:
+    from aip_agents.agent.hitl.prompt.base import BasePromptHandler
+    from aip_agents.schema.hitl import ApprovalDecision, ApprovalDecisionType, ApprovalRequest
+except ImportError as e:
+    raise ImportError("aip_agents is required for local HITL. Install with: pip install 'glaip-sdk[local]'") from e
+
+from rich.console import Console
+from rich.prompt import Prompt
+
+
+class LocalPromptHandler(BasePromptHandler):
+    """Local HITL prompt handler with interactive console prompts.
+
+    Experimental local HITL implementation with known limitations:
+    - Timeouts are not enforced (interactive prompts wait indefinitely)
+    - Relies on private renderer methods for pause/resume
+    - Only supports interactive terminal environments
+
+    The key insight from Rich documentation is that Live must be stopped before
+    using Prompt/input(), otherwise the input won't render properly.
+
+    Environment variables:
+        GLAIP_HITL_AUTO_APPROVE: Set to "true" (case-insensitive) to auto-approve
+            all requests without user interaction. Useful for integration tests and CI.
+    """
+
+    def __init__(self, *, pause_resume_callback: Any | None = None) -> None:
+        """Initialize the prompt handler.
+
+        Args:
+            pause_resume_callback: Optional callable with pause() and resume() methods
+                to control the live renderer during prompts. This is needed because
+                Rich Live interferes with Prompt/input().
+        """
+        super().__init__()
+        self._pause_resume = pause_resume_callback
+        self._console = Console()
+
+    async def prompt_for_decision(
+        self,
+        request: ApprovalRequest,
+        timeout_seconds: int,
+        context_keys: list[str] | None = None,
+    ) -> ApprovalDecision:
+        """Prompt for approval decision with live renderer pause/resume.
+
+        Supports auto-approval via GLAIP_HITL_AUTO_APPROVE environment variable
+        for integration testing and CI environments. Set to "true" (case-insensitive) to enable.
+        """
+        _ = (timeout_seconds, context_keys)  # Suppress unused parameter warnings.
+
+        # Check for auto-approve mode (for integration tests/CI)
+        auto_approve = os.getenv("GLAIP_HITL_AUTO_APPROVE", "").lower() == "true"
+
+        if auto_approve:
+            # Auto-approve without user interaction
+            return ApprovalDecision(
+                request_id=request.request_id,
+                decision=ApprovalDecisionType.APPROVED,
+                operator_input="auto-approved",
+            )
+
+        # Pause the live renderer if callback is available
+        if self._pause_resume:
+            self._pause_resume.pause()
+
+        try:
+            # POC/MVP: Show what we're approving (still auto-approve for now)
+            self._print_request_info(request)
+
+            # POC/MVP: For testing, we can do actual input here
+            # Uncomment to enable real prompting:
+            response = Prompt.ask(
+                "\n[yellow]Approve this tool call?[/yellow] [dim](y/n/s)[/dim]",
+                console=self._console,
+                default="y",
+            )
+            response = response.lower().strip()
+
+            if response in ("y", "yes"):
+                decision = ApprovalDecisionType.APPROVED
+            elif response in ("n", "no"):
+                decision = ApprovalDecisionType.REJECTED
+            else:
+                decision = ApprovalDecisionType.SKIPPED
+
+            return ApprovalDecision(
+                request_id=request.request_id,
+                decision=decision,
+                operator_input=response if decision != ApprovalDecisionType.SKIPPED else None,
+            )
+        finally:
+            # Always resume the live renderer
+            if self._pause_resume:
+                self._pause_resume.resume()
+
+    def _print_request_info(self, request: ApprovalRequest) -> None:
+        """Print the approval request information."""
+        self._console.print()
+        self._console.rule("[yellow]HITL Approval Request[/yellow]", style="yellow")
+
+        tool_name = request.tool_name or "unknown"
+        self._console.print(f"[cyan]Tool:[/cyan] {tool_name}")
+
+        if hasattr(request, "arguments_preview") and request.arguments_preview:
+            self._console.print(f"[cyan]Arguments:[/cyan] {request.arguments_preview}")
+
+        if request.context:
+            self._console.print(f"[dim]Context: {request.context}[/dim]")
+
+
+__all__ = ["LocalPromptHandler"]