aip-agents-binary 0.0.0__py3-none-any.whl

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,
+        )

aip_agents/guardrails/middleware.py

@@ -0,0 +1,199 @@
+"""GuardrailMiddleware for integrating guardrails into agent execution.
+
+This module provides GuardrailMiddleware that hooks into the agent execution
+flow to automatically check content before and after model invocations.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from langchain_core.messages import AIMessage, HumanMessage
+
+from aip_agents.guardrails.exceptions import GuardrailViolationError
+from aip_agents.guardrails.schemas import GuardrailInput
+from aip_agents.middleware.base import AgentMiddleware, ModelRequest
+
+if TYPE_CHECKING:
+    from aip_agents.guardrails.manager import GuardrailManager
+
+
+class GuardrailMiddleware(AgentMiddleware):
+    """Middleware that integrates guardrails into agent execution.
+
+    This middleware wraps a GuardrailManager and automatically checks content
+    at appropriate points during agent execution:
+
+    - Before model invocation: checks user input from messages
+    - After model invocation: checks AI output from messages
+
+    If unsafe content is detected, raises GuardrailViolationError to stop execution.
+
+    Attributes:
+        guardrail_manager: The GuardrailManager to use for content checking
+    """
+
+    def __init__(self, guardrail_manager: GuardrailManager) -> None:
+        """Initialize the GuardrailMiddleware.
+
+        Args:
+            guardrail_manager: GuardrailManager instance to use for checking
+        """
+        self.guardrail_manager = guardrail_manager
+
+    @property
+    def tools(self) -> list:
+        """Guardrails are passive filters and don't contribute tools."""
+        return []
+
+    @property
+    def system_prompt_additions(self) -> str | None:
+        """Guardrails are passive filters and don't modify system prompts."""
+        return None
+
+    async def abefore_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronously check user input before model invocation.
+
+        Extracts the last user message from state and checks it with guardrails.
+        If unsafe, raises GuardrailViolationError to stop execution.
+
+        Args:
+            state: Current agent state containing messages and context
+
+        Returns:
+            Empty dict (no state modifications needed)
+
+        Raises:
+            GuardrailViolationError: If user input violates safety policies
+        """
+        # Extract last user message from state
+        messages = state.get("messages", [])
+        user_input = self._extract_last_user_message(messages)
+
+        if user_input is not None:
+            # Check input content
+            result = await self.guardrail_manager.check_content(user_input)
+
+            if not result.is_safe:
+                raise GuardrailViolationError(result)
+
+        return {}
+
+    def before_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Check user input before model invocation (synchronous wrapper).
+
+        Note:
+            This is a synchronous wrapper for the async `abefore_model()` method.
+            LangGraph agents primarily use `abefore_model()` in async contexts.
+            This method should rarely be called directly. If called from an async
+            context with a running event loop, it will attempt to handle it,
+            but `abefore_model()` should be preferred.
+
+        Args:
+            state: Current agent state containing messages and context
+
+        Returns:
+            Empty dict (no state modifications needed)
+
+        Raises:
+            GuardrailViolationError: If user input violates safety policies
+        """
+        import asyncio
+
+        user_input = self._extract_last_user_message(state.get("messages", []))
+        if user_input is None:
+            return {}
+
+        # Check if we're in an async context with a running loop
+        try:
+            loop = asyncio.get_running_loop()
+            if loop.is_running():
+                # We're in an async context with a running loop
+                # Use nest_asyncio to allow nested event loops
+                # This enables calling asyncio.run() from within a running loop
+                import nest_asyncio
+
+                nest_asyncio.apply()
+                result = asyncio.run(self.guardrail_manager.check_content(user_input))
+            else:
+                # Loop exists but not running - safe to use asyncio.run()
+                result = asyncio.run(self.guardrail_manager.check_content(user_input))
+        except RuntimeError:
+            # No running loop - safe to use asyncio.run()
+            result = asyncio.run(self.guardrail_manager.check_content(user_input))
+
+        if not result.is_safe:
+            raise GuardrailViolationError(result)
+
+        return {}
+
+    def modify_model_request(self, request: ModelRequest, state: dict[str, Any]) -> ModelRequest:
+        """Guardrails don't modify model requests."""
+        return request
+
+    async def aafter_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronously check AI output after model invocation.
+
+        Extracts the last AI message from state and checks it with guardrails.
+        If unsafe, raises GuardrailViolationError to stop execution.
+
+        Args:
+            state: Current agent state after model invocation
+
+        Returns:
+            Empty dict (no state modifications needed)
+
+        Raises:
+            GuardrailViolationError: If AI output violates safety policies
+        """
+        # Extract last AI message from state
+        messages = state.get("messages", [])
+        ai_output = self._extract_last_ai_message(messages)
+
+        if ai_output is not None:
+            # Check output content
+            result = await self.guardrail_manager.check_content(GuardrailInput(input=None, output=ai_output))
+
+            if not result.is_safe:
+                raise GuardrailViolationError(result)
+
+        return {}
+
+    def after_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Check AI output after model invocation (synchronous wrapper)."""
+        return {}
+
+    def _extract_last_user_message(self, messages: list) -> str | None:
+        """Extract the last user message from a list of messages.
+
+        Searches backwards through messages to find the most recent HumanMessage.
+
+        Args:
+            messages: List of message objects
+
+        Returns:
+            Content of the last user message, or None if not found
+        """
+        for message in reversed(messages):
+            if isinstance(message, HumanMessage) and message.content:
+                return str(message.content)
+        return None
+
+    def _extract_last_ai_message(self, messages: list) -> str | None:
+        """Extract the last AI message from a list of messages.
+
+        Searches backwards through messages to find the most recent AIMessage.
+
+        Args:
+            messages: List of message objects
+
+        Returns:
+            Content of the last AI message, or None if not found
+        """
+        for message in reversed(messages):
+            if isinstance(message, AIMessage) and message.content:
+                return str(message.content)
+        return None

aip_agents/guardrails/schemas.py

@@ -0,0 +1,63 @@
+"""Schemas for guardrail input, output, and configuration.
+
+This module defines the data structures used throughout the guardrails system,
+including input/output schemas and configuration objects.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class GuardrailMode(StrEnum):
+    """Modes determining what content an engine checks."""
+
+    INPUT_ONLY = "input_only"
+    OUTPUT_ONLY = "output_only"
+    INPUT_OUTPUT = "input_output"
+    DISABLED = "disabled"
+
+
+class GuardrailInput(BaseModel):
+    """Input schema for guardrail checks.
+
+    Attributes:
+        input: User input content to check (queries, prompts, context)
+        output: AI output content to check (responses, generated text)
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    input: str | None = None
+    output: str | None = None
+
+
+class GuardrailResult(BaseModel):
+    """Result schema returned by guardrail engines and managers.
+
+    Attributes:
+        is_safe: Whether the content passed all checks
+        reason: Explanation when content is blocked (None if safe)
+        filtered_content: Cleaned/sanitized content if engine provides it
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    is_safe: bool
+    reason: str | None = None
+    filtered_content: str | None = None
+
+
+class BaseGuardrailEngineConfig(BaseModel):
+    """Base configuration for guardrail engines.
+
+    Attributes:
+        guardrail_mode: What content this engine should check
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    guardrail_mode: GuardrailMode = GuardrailMode.INPUT_OUTPUT

aip_agents/guardrails/utils.py

@@ -0,0 +1,45 @@
+"""Utility functions for guardrail mode conversion.
+
+This module provides utilities for converting between aip-agents GuardrailMode
+and gllm-guardrail GuardrailMode enums.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from typing import Any
+
+from aip_agents.guardrails.schemas import GuardrailMode
+
+
+def convert_guardrail_mode_to_gl_sdk(mode: GuardrailMode) -> Any:
+    """Convert aip-agents GuardrailMode to gllm-guardrail GuardrailMode.
+
+    This function performs lazy import of gllm-guardrail to support optional
+    dependencies. The conversion is necessary because we maintain our own
+    GuardrailMode enum for API consistency while wrapping the external library.
+
+    Args:
+        mode: The aip-agents GuardrailMode to convert
+
+    Returns:
+        The corresponding gllm-guardrail GuardrailMode enum value
+
+    Raises:
+        ImportError: If gllm-guardrail is not installed
+    """
+    try:
+        from gllm_guardrail.constants import GuardrailMode as GLGuardrailMode  # pragma: no cover
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            "gllm-guardrail is required for guardrails. Install with: pip install 'aip-agents[guardrails]'"
+        ) from e  # pragma: no cover
+
+    mode_mapping = {
+        GuardrailMode.INPUT_ONLY: GLGuardrailMode.INPUT_ONLY,
+        GuardrailMode.OUTPUT_ONLY: GLGuardrailMode.OUTPUT_ONLY,
+        GuardrailMode.INPUT_OUTPUT: GLGuardrailMode.BOTH,
+        GuardrailMode.DISABLED: GLGuardrailMode.DISABLED,
+    }
+
+    return mode_mapping[mode]

aip_agents/integration/__init__.py

@@ -0,0 +1,43 @@
+"""Public cross-package integration facade for `glaip-sdk` consumers.
+
+Only the `aip_agents.integration` namespace is part of the boundary contract for
+cross-package local-runtime integrations. Deep module paths remain implementation
+details and non-contract surfaces, even when the facade re-exports types sourced
+from those modules.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from aip_agents.integration import agent, guardrails, hitl, ptc, skills, storage
+from aip_agents.integration.version import (
+    AUTO_MODE_FALLBACK_ENABLED,
+    CONTRACT_EXPORTS,
+    CONTRACT_MODULES,
+    CONTRACT_NAMESPACE,
+    IMPORT_MODE_ENV_VAR,
+    INTEGRATION_FACADE_MODULES,
+    INTEGRATION_MODE_STRICT,
+    NON_CONTRACT_SURFACE_PATTERNS,
+    integration_contract_version,
+)
+
+__all__ = [
+    "AUTO_MODE_FALLBACK_ENABLED",
+    "agent",
+    "guardrails",
+    "hitl",
+    "ptc",
+    "skills",
+    "storage",
+    "CONTRACT_EXPORTS",
+    "CONTRACT_MODULES",
+    "CONTRACT_NAMESPACE",
+    "INTEGRATION_FACADE_MODULES",
+    "INTEGRATION_MODE_STRICT",
+    "IMPORT_MODE_ENV_VAR",
+    "NON_CONTRACT_SURFACE_PATTERNS",
+    "integration_contract_version",
+]

aip_agents/integration/agent.py

@@ -0,0 +1,58 @@
+"""Public agent runtime contracts for cross-package integrations.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from aip_agents.agent import AgentInterface, LangGraphReactAgent
+
+
+class AgentRunProtocol(Protocol):
+    """Minimal async agent execution contract used by integration callers."""
+
+    async def arun(self, *args: Any, **kwargs: Any) -> Any:
+        """Run the agent and return the final result."""
+        raise NotImplementedError  # pragma: no cover
+
+    async def arun_stream(self, *args: Any, **kwargs: Any) -> Any:
+        """Run the agent and stream incremental results."""
+        raise NotImplementedError  # pragma: no cover
+
+    async def arun_sse_stream(self, *args: Any, **kwargs: Any) -> Any:
+        """Run the agent and stream SSE-compatible incremental results."""
+        raise NotImplementedError  # pragma: no cover
+
+
+_IMPORT_MAP = {
+    "AgentInterface": "aip_agents.agent",
+    "LangGraphReactAgent": "aip_agents.agent",
+}
+
+__all__ = [
+    "AgentInterface",
+    "AgentRunProtocol",
+    "LangGraphReactAgent",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load public agent contracts."""
+    module_name = _IMPORT_MAP.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module = importlib.import_module(module_name)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return module attributes for dir()."""
+    return sorted(__all__)

aip_agents/integration/guardrails.py

@@ -0,0 +1,52 @@
+"""Public guardrail contracts for cross-package integrations.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib
+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
+
+
+_GUARDRAILS_MODULE = "aip_agents.guardrails"
+_GUARDRAILS_NEMO_MODULE = "aip_agents.guardrails.engines.nemo"
+_GUARDRAILS_PHRASE_MATCHER_MODULE = "aip_agents.guardrails.engines.phrase_matcher"
+
+_IMPORT_MAP = {
+    "GuardrailManager": _GUARDRAILS_MODULE,
+    "GuardrailMode": _GUARDRAILS_MODULE,
+    "NemoGuardrailEngine": _GUARDRAILS_NEMO_MODULE,
+    "PhraseMatcherEngine": _GUARDRAILS_PHRASE_MATCHER_MODULE,
+}
+
+__all__ = [
+    "GuardrailManager",
+    "GuardrailMode",
+    "NemoGuardrailEngine",
+    "PhraseMatcherEngine",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load public guardrail contracts."""
+    module_name = _IMPORT_MAP.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module = importlib.import_module(module_name)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return module attributes for dir()."""
+    return sorted(__all__)

aip_agents/integration/hitl.py

@@ -0,0 +1,71 @@
+"""Public HITL contracts for cross-package integrations.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from aip_agents.agent.hitl.manager import ApprovalManager
+    from aip_agents.agent.hitl.prompt import BasePromptHandler
+    from aip_agents.schema.hitl import ApprovalDecision, ApprovalDecisionType, ApprovalRequest
+
+
+class PromptHandlerProtocol(Protocol):
+    """Minimal HITL prompt contract used by SDK-side prompt handlers."""
+
+    def attach_manager(self, manager: ApprovalManager) -> None:
+        """Attach the approval manager coordinating the prompt handler."""
+        raise NotImplementedError  # pragma: no cover
+
+    async def prompt_for_decision(
+        self,
+        request: ApprovalRequest,
+        timeout_seconds: int,
+        context_keys: list[str] | None = None,
+    ) -> ApprovalDecision:
+        """Return an approval decision for a pending HITL request."""
+        raise NotImplementedError  # pragma: no cover
+
+
+_SCHEMA_HITL_MODULE = "aip_agents.schema.hitl"
+_HITL_MANAGER_MODULE = "aip_agents.agent.hitl.manager"
+_HITL_PROMPT_MODULE = "aip_agents.agent.hitl.prompt"
+
+_IMPORT_MAP = {
+    "ApprovalDecision": _SCHEMA_HITL_MODULE,
+    "ApprovalDecisionType": _SCHEMA_HITL_MODULE,
+    "ApprovalManager": _HITL_MANAGER_MODULE,
+    "ApprovalRequest": _SCHEMA_HITL_MODULE,
+    "BasePromptHandler": _HITL_PROMPT_MODULE,
+}
+
+__all__ = [
+    "ApprovalDecision",
+    "ApprovalDecisionType",
+    "ApprovalManager",
+    "ApprovalRequest",
+    "BasePromptHandler",
+    "PromptHandlerProtocol",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load public HITL contracts."""
+    module_name = _IMPORT_MAP.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module = importlib.import_module(module_name)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Return module attributes for dir()."""
+    return sorted(__all__)