aip-agents-binary 0.5.25b1__py3-none-macosx_13_0_arm64.whl

aip_agents/guardrails/engines/base.py

@@ -0,0 +1,90 @@
+"""Base interfaces and protocols for guardrail engines.
+
+This module defines the base protocol that all guardrail engines must implement,
+providing a consistent interface for content safety checking.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from abc import ABC, abstractmethod
+from typing import Protocol
+
+from aip_agents.guardrails.schemas import (
+    BaseGuardrailEngineConfig,
+    GuardrailResult,
+)
+
+
+class GuardrailEngine(Protocol):
+    """Protocol defining the interface for guardrail engines.
+
+    All guardrail engines must implement this protocol to be compatible
+    with GuardrailManager. Engines check content for safety violations.
+
+    Attributes:
+        config: Configuration for this engine's behavior
+    """
+
+    config: BaseGuardrailEngineConfig
+
+    @abstractmethod
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content for safety violations.
+
+        Args:
+            content: The user input content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+        ...
+
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations.
+
+        Args:
+            content: The AI output content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+        ...
+
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        ...
+
+
+class BaseGuardrailEngine(ABC):
+    """Abstract base class for guardrail engines.
+
+    Provides common functionality and ensures proper configuration handling.
+    Concrete engines should inherit from this class.
+    """
+
+    def __init__(self, config: BaseGuardrailEngineConfig | None = None) -> None:
+        """Initialize the engine with configuration.
+
+        Args:
+            config: Engine configuration. Uses defaults if None provided.
+        """
+        self.config = config or BaseGuardrailEngineConfig()
+
+    @abstractmethod
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content for safety violations."""
+        ...
+
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations."""
+        ...
+
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        ...

aip_agents/guardrails/engines/base.pyi

@@ -0,0 +1,61 @@
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from aip_agents.guardrails.schemas import BaseGuardrailEngineConfig as BaseGuardrailEngineConfig, GuardrailResult as GuardrailResult
+from typing import Protocol
+
+class GuardrailEngine(Protocol):
+    """Protocol defining the interface for guardrail engines.
+
+    All guardrail engines must implement this protocol to be compatible
+    with GuardrailManager. Engines check content for safety violations.
+
+    Attributes:
+        config: Configuration for this engine's behavior
+    """
+    config: BaseGuardrailEngineConfig
+    @abstractmethod
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content for safety violations.
+
+        Args:
+            content: The user input content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations.
+
+        Args:
+            content: The AI output content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+
+class BaseGuardrailEngine(ABC):
+    """Abstract base class for guardrail engines.
+
+    Provides common functionality and ensures proper configuration handling.
+    Concrete engines should inherit from this class.
+    """
+    config: Incomplete
+    def __init__(self, config: BaseGuardrailEngineConfig | None = None) -> None:
+        """Initialize the engine with configuration.
+
+        Args:
+            config: Engine configuration. Uses defaults if None provided.
+        """
+    @abstractmethod
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content for safety violations."""
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations."""
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""

aip_agents/guardrails/engines/nemo.py

@@ -0,0 +1,101 @@
+"""NemoGuardrailEngine wrapper for GL SDK guardrails.
+
+This module wraps the GL SDK's NemoGuardrailEngine to provide advanced
+LLM-based content filtering capabilities.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from typing import Any
+
+from aip_agents.guardrails.engines.base import BaseGuardrailEngine
+from aip_agents.guardrails.schemas import (
+    BaseGuardrailEngineConfig,
+    GuardrailResult,
+)
+from aip_agents.guardrails.utils import convert_guardrail_mode_to_gl_sdk
+
+
+class NemoGuardrailEngine(BaseGuardrailEngine):
+    """Wrapper for GL SDK NemoGuardrailEngine with aip-agents interface.
+
+    This engine provides advanced LLM-based content filtering using NVIDIA's
+    NeMo Guardrails. It can detect more complex safety violations beyond
+    simple phrase matching.
+
+    Note: Import of gllm_guardrail is deferred to __init__ to support
+    lazy loading when guardrails are optional dependency.
+    """
+
+    def __init__(self, config: BaseGuardrailEngineConfig | None = None, **nemo_config: dict[str, Any]) -> None:
+        """Initialize the NemoGuardrailEngine.
+
+        Args:
+            config: Engine configuration. Uses defaults if None provided.
+            **nemo_config: Additional configuration passed to the underlying
+                          NeMo engine (e.g., model paths, thresholds, etc.)
+
+        Raises:
+            ImportError: If gllm-guardrail is not installed.
+        """
+        super().__init__(config)
+
+        # Lazy import to support optional dependency and avoid import errors
+        # when gllm-guardrail is not installed
+        try:
+            from gllm_guardrail import NemoGuardrailEngine as GLNemoGuardrailEngine
+            from gllm_guardrail.engine.nemo_engine import NemoGuardrailEngineConfig as GLNemoGuardrailEngineConfig
+        except ImportError as e:
+            raise ImportError(
+                "gllm-guardrail is required for guardrails. Install with: pip install 'aip-agents[guardrails]'"
+            ) from e
+
+        # Convert our GuardrailMode to GL SDK's GuardrailMode
+        gl_mode = convert_guardrail_mode_to_gl_sdk(self.config.guardrail_mode)
+
+        # Create GL SDK config with guardrail_mode and any additional NeMo config
+        # NemoGuardrailEngineConfig accepts guardrail_mode and other NeMo-specific params directly
+        gl_config = GLNemoGuardrailEngineConfig(guardrail_mode=gl_mode, **nemo_config)
+
+        # Initialize the underlying GL SDK engine
+        self._engine = GLNemoGuardrailEngine(config=gl_config)
+
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content using wrapped GL SDK NeMo engine.
+
+        Args:
+            content: The user input content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+        gl_result = await self._engine.check_input(content)
+        return GuardrailResult(
+            is_safe=gl_result.is_safe,
+            reason=gl_result.reason,
+            filtered_content=gl_result.filtered_content,
+        )
+
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content using wrapped GL SDK NeMo engine.
+
+        Args:
+            content: The AI output content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+        gl_result = await self._engine.check_output(content)
+        return GuardrailResult(
+            is_safe=gl_result.is_safe,
+            reason=gl_result.reason,
+            filtered_content=gl_result.filtered_content,
+        )
+
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        return {
+            "type": "nemo",
+            "config": self._engine.config.model_dump(),
+        }

aip_agents/guardrails/engines/nemo.pyi

@@ -0,0 +1,46 @@
+from aip_agents.guardrails.engines.base import BaseGuardrailEngine as BaseGuardrailEngine
+from aip_agents.guardrails.schemas import BaseGuardrailEngineConfig as BaseGuardrailEngineConfig, GuardrailResult as GuardrailResult
+from aip_agents.guardrails.utils import convert_guardrail_mode_to_gl_sdk as convert_guardrail_mode_to_gl_sdk
+from typing import Any
+
+class NemoGuardrailEngine(BaseGuardrailEngine):
+    """Wrapper for GL SDK NemoGuardrailEngine with aip-agents interface.
+
+    This engine provides advanced LLM-based content filtering using NVIDIA's
+    NeMo Guardrails. It can detect more complex safety violations beyond
+    simple phrase matching.
+
+    Note: Import of gllm_guardrail is deferred to __init__ to support
+    lazy loading when guardrails are optional dependency.
+    """
+    def __init__(self, config: BaseGuardrailEngineConfig | None = None, **nemo_config: dict[str, Any]) -> None:
+        """Initialize the NemoGuardrailEngine.
+
+        Args:
+            config: Engine configuration. Uses defaults if None provided.
+            **nemo_config: Additional configuration passed to the underlying
+                          NeMo engine (e.g., model paths, thresholds, etc.)
+
+        Raises:
+            ImportError: If gllm-guardrail is not installed.
+        """
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content using wrapped GL SDK NeMo engine.
+
+        Args:
+            content: The user input content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content using wrapped GL SDK NeMo engine.
+
+        Args:
+            content: The AI output content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""

aip_agents/guardrails/engines/phrase_matcher.py

@@ -0,0 +1,113 @@
+"""PhraseMatcherEngine wrapper for GL SDK guardrails.
+
+This module wraps the GL SDK's PhraseMatcherEngine to provide a consistent
+interface for the aip-agents guardrails system.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from aip_agents.guardrails.engines.base import BaseGuardrailEngine
+from aip_agents.guardrails.schemas import (
+    BaseGuardrailEngineConfig,
+    GuardrailResult,
+)
+from aip_agents.guardrails.utils import convert_guardrail_mode_to_gl_sdk
+
+
+class PhraseMatcherEngine(BaseGuardrailEngine):
+    """Wrapper for GL SDK PhraseMatcherEngine with aip-agents interface.
+
+    This engine performs rule-based banned phrase detection using the
+    GL SDK's PhraseMatcherEngine. It checks for exact phrase matches
+    and blocks content containing banned phrases.
+
+    Note: Import of gllm_guardrail is deferred to __init__ to support
+    lazy loading when guardrails are optional dependency.
+    """
+
+    def __init__(
+        self,
+        config: BaseGuardrailEngineConfig | None = None,
+        banned_phrases: list[str] | None = None,
+    ) -> None:
+        """Initialize the PhraseMatcherEngine.
+
+        Args:
+            config: Engine configuration. Uses defaults if None provided.
+            banned_phrases: List of phrases that should trigger blocking.
+                          Defaults to empty list if None provided.
+
+        Raises:
+            ImportError: If gllm-guardrail is not installed.
+        """
+        super().__init__(config)
+
+        # Lazy import to support optional dependency and avoid import errors
+        # when gllm-guardrail is not installed
+        try:
+            from gllm_guardrail import PhraseMatcherEngine as GLPhraseMatcherEngine
+            from gllm_guardrail.engine.base_engine import BaseGuardrailEngineConfig as GLBaseGuardrailEngineConfig
+        except ImportError as e:
+            raise ImportError(
+                "gllm-guardrail is required for guardrails. Install with: pip install 'aip-agents[guardrails]'"
+            ) from e
+
+        # Convert our GuardrailMode to GL SDK's GuardrailMode
+        gl_mode = convert_guardrail_mode_to_gl_sdk(self.config.guardrail_mode)
+
+        # Create GL SDK config
+        gl_config = GLBaseGuardrailEngineConfig(guardrail_mode=gl_mode)
+
+        # Initialize the underlying GL SDK engine
+        self._engine = GLPhraseMatcherEngine(
+            config=gl_config,
+            banned_phrases=banned_phrases or [],
+        )
+
+    @property
+    def banned_phrases(self) -> list[str]:
+        """Get the list of banned phrases."""
+        return self._engine.banned_phrases
+
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content using wrapped GL SDK engine.
+
+        Args:
+            content: The user input content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+        gl_result = await self._engine.check_input(content)
+        return GuardrailResult(
+            is_safe=gl_result.is_safe,
+            reason=gl_result.reason,
+            filtered_content=gl_result.filtered_content,
+        )
+
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content using wrapped GL SDK engine.
+
+        Args:
+            content: The AI output content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+        gl_result = await self._engine.check_output(content)
+        return GuardrailResult(
+            is_safe=gl_result.is_safe,
+            reason=gl_result.reason,
+            filtered_content=gl_result.filtered_content,
+        )
+
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        return {
+            "type": "phrase_matcher",
+            "config": {
+                **self.config.model_dump(),
+                "banned_phrases": self.banned_phrases,
+            },
+        }

aip_agents/guardrails/engines/phrase_matcher.pyi

@@ -0,0 +1,48 @@
+from aip_agents.guardrails.engines.base import BaseGuardrailEngine as BaseGuardrailEngine
+from aip_agents.guardrails.schemas import BaseGuardrailEngineConfig as BaseGuardrailEngineConfig, GuardrailResult as GuardrailResult
+from aip_agents.guardrails.utils import convert_guardrail_mode_to_gl_sdk as convert_guardrail_mode_to_gl_sdk
+
+class PhraseMatcherEngine(BaseGuardrailEngine):
+    """Wrapper for GL SDK PhraseMatcherEngine with aip-agents interface.
+
+    This engine performs rule-based banned phrase detection using the
+    GL SDK's PhraseMatcherEngine. It checks for exact phrase matches
+    and blocks content containing banned phrases.
+
+    Note: Import of gllm_guardrail is deferred to __init__ to support
+    lazy loading when guardrails are optional dependency.
+    """
+    def __init__(self, config: BaseGuardrailEngineConfig | None = None, banned_phrases: list[str] | None = None) -> None:
+        """Initialize the PhraseMatcherEngine.
+
+        Args:
+            config: Engine configuration. Uses defaults if None provided.
+            banned_phrases: List of phrases that should trigger blocking.
+                          Defaults to empty list if None provided.
+
+        Raises:
+            ImportError: If gllm-guardrail is not installed.
+        """
+    @property
+    def banned_phrases(self) -> list[str]:
+        """Get the list of banned phrases."""
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content using wrapped GL SDK engine.
+
+        Args:
+            content: The user input content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content using wrapped GL SDK engine.
+
+        Args:
+            content: The AI output content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""

aip_agents/guardrails/exceptions.py

@@ -0,0 +1,39 @@
+"""Exceptions raised by the guardrails system.
+
+This module defines custom exceptions that are raised when guardrail
+violations occur or when guardrail operations fail.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from aip_agents.guardrails.schemas import GuardrailResult
+
+
+class GuardrailViolationError(Exception):
+    """Exception raised when unsafe content is detected by guardrails.
+
+    This exception is raised by GuardrailMiddleware when content violates
+    safety policies. It contains the GuardrailResult with details about
+    why the content was blocked.
+
+    Attributes:
+        result: The GuardrailResult containing safety check details
+        message: Human-readable error message
+    """
+
+    def __init__(self, result: GuardrailResult, message: str | None = None) -> None:
+        """Initialize the exception.
+
+        Args:
+            result: The GuardrailResult from the failed safety check
+            message: Optional custom error message
+        """
+        self.result = result
+        self.message = message or f"Content blocked by guardrails: {result.reason}"
+
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        """Return string representation of the exception."""
+        return self.message

aip_agents/guardrails/exceptions.pyi

@@ -0,0 +1,23 @@
+from _typeshed import Incomplete
+from aip_agents.guardrails.schemas import GuardrailResult as GuardrailResult
+
+class GuardrailViolationError(Exception):
+    """Exception raised when unsafe content is detected by guardrails.
+
+    This exception is raised by GuardrailMiddleware when content violates
+    safety policies. It contains the GuardrailResult with details about
+    why the content was blocked.
+
+    Attributes:
+        result: The GuardrailResult containing safety check details
+        message: Human-readable error message
+    """
+    result: Incomplete
+    message: Incomplete
+    def __init__(self, result: GuardrailResult, message: str | None = None) -> None:
+        """Initialize the exception.
+
+        Args:
+            result: The GuardrailResult from the failed safety check
+            message: Optional custom error message
+        """

aip_agents/guardrails/manager.py

@@ -0,0 +1,163 @@
+"""GuardrailManager for orchestrating multiple guardrail engines.
+
+This module provides the GuardrailManager class that coordinates multiple
+guardrail engines with fail-fast behavior.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from aip_agents.guardrails.schemas import GuardrailInput, GuardrailMode, GuardrailResult
+
+if TYPE_CHECKING:
+    from aip_agents.guardrails.engines.base import GuardrailEngine
+
+
+class GuardrailManager:
+    """Orchestrates multiple guardrail engines with fail-fast behavior.
+
+    The manager accepts one or more guardrail engines and runs them in sequence.
+    If any engine reports unsafe content, execution stops immediately (fail-fast)
+    and returns the violation result.
+
+    Attributes:
+        engines: List of guardrail engines to orchestrate
+    """
+
+    def __init__(
+        self,
+        engine: GuardrailEngine | list[GuardrailEngine] | None = None,
+        engines: list[GuardrailEngine] | None = None,
+    ) -> None:
+        """Initialize the GuardrailManager.
+
+        Args:
+            engine: Single guardrail engine to use
+            engines: List of guardrail engines to use
+
+        Raises:
+            ValueError: If both engine and engines are provided
+        """
+        self.enabled = True
+        if engine is not None and engines is not None:
+            raise ValueError("Cannot specify both 'engine' and 'engines'")
+
+        if engine is not None:
+            if isinstance(engine, list):
+                self.engines = engine
+            else:
+                self.engines = [engine]
+        elif engines is not None:
+            self.engines = engines
+        else:
+            self.engines = []
+
+    def model_dump(self) -> dict[str, Any]:
+        """Serialize manager configuration into a JSON-compatible dictionary."""
+        return {
+            "enabled": self.enabled,
+            "engines": [engine.model_dump() for engine in self.engines],
+        }
+
+    async def check_content(self, content: str | GuardrailInput) -> GuardrailResult:
+        """Check content against all registered engines.
+
+        Executes engines in order with fail-fast behavior. If any engine
+        reports unsafe content, returns immediately with that result.
+
+        Args:
+            content: Content to check. Can be a string (treated as input-only)
+                    or GuardrailInput with input/output fields.
+
+        Returns:
+            GuardrailResult indicating if content passed all checks
+        """
+        # Normalize input to GuardrailInput
+        guardrail_input = self._normalize_content(content)
+
+        # Execute engines in order (fail-fast on first unsafe result)
+        for engine in self.engines:
+            result = await self._check_engine(engine, guardrail_input)
+            if result is not None:
+                return result
+
+        # All engines passed
+        return GuardrailResult(is_safe=True, reason=None, filtered_content=None)
+
+    @staticmethod
+    def _normalize_content(content: str | GuardrailInput) -> GuardrailInput:
+        """Normalize content input to GuardrailInput.
+
+        Args:
+            content: Content to normalize
+
+        Returns:
+            GuardrailInput object
+        """
+        if isinstance(content, str):
+            return GuardrailInput(input=content, output=None)
+        return content
+
+    async def _check_engine(self, engine: GuardrailEngine, guardrail_input: GuardrailInput) -> GuardrailResult | None:
+        """Check content against a single engine.
+
+        Args:
+            engine: The guardrail engine to check against
+            guardrail_input: The content to check
+
+        Returns:
+            GuardrailResult if unsafe content detected, None if safe
+        """
+        engine_mode = engine.config.guardrail_mode
+
+        # Skip disabled engines
+        if engine_mode == GuardrailMode.DISABLED:
+            return None
+
+        if self._should_check_input(engine_mode, guardrail_input) and guardrail_input.input is not None:
+            result = await engine.check_input(guardrail_input.input)
+            if not result.is_safe:
+                return result
+
+        if self._should_check_output(engine_mode, guardrail_input) and guardrail_input.output is not None:
+            result = await engine.check_output(guardrail_input.output)
+            if not result.is_safe:
+                return result
+
+        return None
+
+    @staticmethod
+    def _should_check_input(engine_mode: GuardrailMode, guardrail_input: GuardrailInput) -> bool:
+        """Determine if input should be checked based on engine mode.
+
+        Args:
+            engine_mode: The guardrail mode of the engine
+            guardrail_input: The content to check
+
+        Returns:
+            True if input should be checked, False otherwise
+        """
+        return guardrail_input.input is not None and engine_mode in (
+            GuardrailMode.INPUT_ONLY,
+            GuardrailMode.INPUT_OUTPUT,
+        )
+
+    @staticmethod
+    def _should_check_output(engine_mode: GuardrailMode, guardrail_input: GuardrailInput) -> bool:
+        """Determine if output should be checked based on engine mode.
+
+        Args:
+            engine_mode: The guardrail mode of the engine
+            guardrail_input: The content to check
+
+        Returns:
+            True if output should be checked, False otherwise
+        """
+        return guardrail_input.output is not None and engine_mode in (
+            GuardrailMode.OUTPUT_ONLY,
+            GuardrailMode.INPUT_OUTPUT,
+        )