aip-agents-binary 0.5.21__py3-none-macosx_13_0_arm64.whl → 0.6.8__py3-none-macosx_13_0_arm64.whl

aip_agents/agent/langgraph_react_agent.pyi

@@ -2,14 +2,16 @@ from _typeshed import Incomplete
 from aip_agents.agent.base_langgraph_agent import BaseLangGraphAgent as BaseLangGraphAgent
 from aip_agents.agent.hitl.langgraph_hitl_mixin import LangGraphHitLMixin as LangGraphHitLMixin
 from aip_agents.agent.hitl.manager import TOOL_EXECUTION_BLOCKING_DECISIONS as TOOL_EXECUTION_BLOCKING_DECISIONS
+from aip_agents.guardrails.manager import GuardrailManager as GuardrailManager
 from aip_agents.middleware.base import AgentMiddleware as AgentMiddleware, ModelRequest as ModelRequest
 from aip_agents.middleware.manager import MiddlewareManager as MiddlewareManager
 from aip_agents.middleware.todolist import TodoList as TodoList, TodoListMiddleware as TodoListMiddleware
+from aip_agents.ptc import PTCSandboxConfig as PTCSandboxConfig
 from aip_agents.schema.a2a import A2AStreamEventType as A2AStreamEventType
 from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, HitlMetadata as HitlMetadata
 from aip_agents.schema.langgraph import ToolCallResult as ToolCallResult, ToolStorageParams as ToolStorageParams
 from aip_agents.schema.step_limit import MaxStepsExceededError as MaxStepsExceededError, StepLimitConfig as StepLimitConfig
-from aip_agents.tools.memory_search_tool import MEMORY_SEARCH_TOOL_NAME as MEMORY_SEARCH_TOOL_NAME
+from aip_agents.tools.memory_search_tool import MEMORY_DELETE_TOOL_NAME as MEMORY_DELETE_TOOL_NAME, MEMORY_SEARCH_TOOL_NAME as MEMORY_SEARCH_TOOL_NAME
 from aip_agents.tools.tool_config_injector import TOOL_CONFIGS_KEY as TOOL_CONFIGS_KEY
 from aip_agents.utils import add_references_chunks as add_references_chunks
 from aip_agents.utils.langgraph import convert_langchain_messages_to_gllm_messages as convert_langchain_messages_to_gllm_messages, convert_lm_output_to_langchain_message as convert_lm_output_to_langchain_message
@@ -85,7 +87,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
     """
     tool_output_manager: Incomplete
     step_limit_config: Incomplete
-    def __init__(self, name: str, instruction: str = ..., model: BaseChatModel | str | Any | None = None, tools: Sequence[BaseTool] | None = None, agents: Sequence[Any] | None = None, description: str | None = None, thread_id_key: str = 'thread_id', event_emitter: EventEmitter | None = None, tool_output_manager: ToolOutputManager | None = None, planning: bool = False, middlewares: Sequence[AgentMiddleware] | None = None, step_limit_config: StepLimitConfig | None = None, **kwargs: Any) -> None:
+    def __init__(self, name: str, instruction: str = ..., model: BaseChatModel | str | Any | None = None, tools: Sequence[BaseTool] | None = None, agents: Sequence[Any] | None = None, description: str | None = None, thread_id_key: str = 'thread_id', event_emitter: EventEmitter | None = None, tool_output_manager: ToolOutputManager | None = None, planning: bool = False, middlewares: Sequence[AgentMiddleware] | None = None, guardrail: GuardrailManager | None = None, step_limit_config: StepLimitConfig | None = None, ptc_config: PTCSandboxConfig | None = None, **kwargs: Any) -> None:
         """Initialize the LangGraph ReAct Agent.
 
         Args:
@@ -104,10 +106,19 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             planning: Enable planning capabilities with TodoListMiddleware. Defaults to False.
             middlewares: Optional sequence of custom middleware to COMPOSE (not override) with built-in middleware.
                         Execution order: [TodoListMiddleware (if planning=True),
+                                         GuardrailMiddleware (if guardrail provided),
                                          ...custom middlewares in order provided]
                         All middleware hooks execute - this extends capabilities, never replaces them.
+            guardrail: Optional GuardrailManager for content filtering and safety checks.
+                     When provided, automatically wraps in GuardrailMiddleware for transparent
+                     input/output filtering during agent execution.
             enable_pii: Optional toggle to enable PII handling for tool inputs and outputs.
             step_limit_config: Optional configuration for step limits and delegation depth.
+            ptc_config: Optional configuration for PTC sandbox execution. See PTCSandboxConfig
+                for available options including enabled flag, sandbox timeout, and template settings.
+                PTC is enabled when ptc_config is not None and ptc_config.enabled is True.
+                When enabled, prompt guidance is automatically injected into the agent's instruction.
+                PTC runs in a sandbox only; there is no in-process trusted PTC path.
             **kwargs: Additional keyword arguments passed to BaseLangGraphAgent.
         """
     def define_graph(self, graph_builder: StateGraph) -> CompiledStateGraph:
@@ -119,6 +130,39 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         Returns:
             Compiled LangGraph ready for execution.
         """
+    def add_mcp_server(self, mcp_config: dict[str, dict[str, Any]]) -> None:
+        """Add MCP servers and refresh PTC tool state if needed."""
+    def enable_ptc(self, config: PTCSandboxConfig | None = None) -> None:
+        '''Enable Programmatic Tool Calling (PTC) for this agent.
+
+        PTC allows the LLM to execute Python code that calls MCP tools
+        programmatically inside a sandboxed environment. This is useful for
+        chaining multiple tool calls with local data processing.
+
+        The execute_ptc_code tool is automatically added to the agent\'s tools
+        after MCP servers are configured. If no MCP servers are configured,
+        the tool sync is deferred until servers are added.
+
+        Args:
+            config: Optional configuration for PTC sandbox execution.
+                See PTCSandboxConfig for options like enabled flag and sandbox_timeout.
+                If None is passed, a default config with enabled=True will be created.
+
+        Example:
+            agent.enable_ptc(PTCSandboxConfig(enabled=True))
+            agent.add_mcp_server({"yfinance": {...}})
+            # execute_ptc_code tool is now available
+
+        Note:
+            PTC can also be enabled via the constructor by passing
+            ptc_config=PTCSandboxConfig(enabled=True, ...).
+        '''
+    async def cleanup(self) -> None:
+        """Cleanup agent resources including PTC sandbox.
+
+        Extends base cleanup to also cleanup the PTC sandbox runtime if
+        execute_ptc_code tool was created.
+        """
 
 class LangGraphAgent(LangGraphReactAgent):
     """Alias for LangGraphReactAgent."""

aip_agents/examples/{hello_world_langgraph_bosa_twitter.py → hello_world_langgraph_gl_connector_twitter.py}

@@ -1,4 +1,4 @@
-"""Minimal LangGraph agent with bosa support example demonstrating asynchronous run.
+"""Minimal LangGraph agent with GL Connectors support example demonstrating asynchronous run.
 
 Authors:
     Saul Sayers (saul.sayers@gdplabs.id)
@@ -6,22 +6,25 @@ Authors:
 
 import asyncio
 
+from dotenv import load_dotenv
 from langchain_openai import ChatOpenAI
 
 from aip_agents.agent import LangGraphAgent
-from aip_agents.tools import BOSA_AUTOMATED_TOOLS
+from aip_agents.tools import GL_CONNECTORS_AUTOMATED_TOOLS
 
+load_dotenv(override=True)
 
-async def langgraph_bosa_example():
+
+async def langgraph_gl_connector_example():
     """Demonstrates the LangGraphAgent's arun method."""
     model = ChatOpenAI(model="gpt-4.1", temperature=0)
-    agent_name = "BOSAConnectorTwitterAgent"
+    agent_name = "GLConnectorTwitterAgent"
 
     langgraph_agent = LangGraphAgent(
         name=agent_name,
-        instruction="You are a helpful assistant that use BOSA connector to connect with Twitter API.",
+        instruction="You are a helpful assistant that uses GL Connectors to connect with the Twitter API.",
         model=model,
-        tools=BOSA_AUTOMATED_TOOLS["twitter"],
+        tools=GL_CONNECTORS_AUTOMATED_TOOLS["twitter"],
     )
 
     query = "Get 3 tweets about the latest Air India Incident"
@@ -38,4 +41,4 @@ async def langgraph_bosa_example():
 
 
 if __name__ == "__main__":
-    asyncio.run(langgraph_bosa_example())
+    asyncio.run(langgraph_gl_connector_example())

aip_agents/examples/hello_world_langgraph_gl_connector_twitter.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangGraphAgent as LangGraphAgent
+from aip_agents.tools import GL_CONNECTORS_AUTOMATED_TOOLS as GL_CONNECTORS_AUTOMATED_TOOLS
+
+async def langgraph_gl_connector_example() -> None:
+    """Demonstrates the LangGraphAgent's arun method."""

aip_agents/examples/hello_world_ptc.py

@@ -0,0 +1,49 @@
+"""Minimal PTC hello world example.
+
+Required environment variables:
+- OPENAI_API_KEY
+- E2B_API_KEY
+"""
+
+import asyncio
+
+from aip_agents.agent import LangGraphReactAgent
+from aip_agents.ptc import PromptConfig, PTCSandboxConfig
+
+
+async def main() -> None:
+    """Run a hello-world PTC flow."""
+    instruction = (
+        "You are a helpful assistant with access to execute_ptc_code. "
+        "Use execute_ptc_code to run Python and print output. "
+        "The tool returns JSON with ok/stdout/stderr/exit_code."
+    )
+
+    agent = LangGraphReactAgent(
+        name="ptc_hello_world",
+        instruction=instruction,
+        model="openai/gpt-5.2",
+        ptc_config=PTCSandboxConfig(enabled=True, sandbox_timeout=180.0, prompt=PromptConfig(mode="index")),
+    )
+    agent.add_mcp_server(
+        {
+            "deepwiki": {
+                "transport": "streamable-http",
+                "url": "https://mcp.deepwiki.com/mcp",
+                "headers": {},
+                "timeout": 60.0,
+            }
+        }
+    )
+
+    try:
+        response = await agent.arun(
+            query="Use execute_ptc_code to print 'Hello, world!' and count the number of words in the output of deepwiki.read_wiki_structure('anthropics/claude-code')."
+        )
+        print("execute_ptc_code output:", response["output"])
+    finally:
+        await agent.cleanup()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_ptc.pyi

@@ -0,0 +1,5 @@
+from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
+from aip_agents.ptc import PTCSandboxConfig as PTCSandboxConfig, PromptConfig as PromptConfig
+
+async def main() -> None:
+    """Run a hello-world PTC flow."""

aip_agents/examples/hello_world_ptc_custom_tools.py

@@ -0,0 +1,83 @@
+"""Minimal PTC hello world example with custom tools.
+
+Author: Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+
+Required environment variables:
+- OPENAI_API_KEY
+- E2B_API_KEY
+"""
+
+import asyncio
+import json
+from pathlib import Path
+
+from langchain_openai import ChatOpenAI
+
+from aip_agents.agent import LangGraphReactAgent
+from aip_agents.examples.tools.multiply_tool import MultiplyTool
+from aip_agents.ptc import PromptConfig, PTCCustomToolConfig, PTCSandboxConfig, file_tool, package_tool
+from aip_agents.tools.time_tool import TimeTool
+
+
+async def main() -> None:
+    """Run a hello-world PTC flow with custom tools."""
+    repo_root = Path.cwd()
+    multiply_tool_path = repo_root / "aip_agents/examples/tools/multiply_tool.py"
+
+    instruction = (
+        "You are a helpful assistant with access to execute_ptc_code. "
+        "Use execute_ptc_code to run Python and print output. "
+        "Custom tools are available under tools.custom (import with "
+        "'from tools.custom import <tool_name>')."
+    )
+
+    agent = LangGraphReactAgent(
+        name="ptc_custom_tools_hello_world",
+        instruction=instruction,
+        model=ChatOpenAI(model="gpt-5.2"),
+        tools=[TimeTool(), MultiplyTool()],
+        tool_configs={"multiply": {"offset": 20}},
+        ptc_config=PTCSandboxConfig(
+            enabled=True,
+            sandbox_timeout=180.0,
+            prompt=PromptConfig(mode="auto"),
+            custom_tools=PTCCustomToolConfig(
+                enabled=True,
+                bundle_roots=[str(repo_root)],
+                requirements=[],
+                tools=[
+                    package_tool(
+                        "time_tool",
+                        import_path="aip_agents.tools.time_tool",
+                        class_name="TimeTool",
+                    ),
+                    file_tool(
+                        "multiply",
+                        file_path=str(multiply_tool_path),
+                        class_name="MultiplyTool",
+                    ),
+                ],
+            ),
+        ),
+    )
+
+    try:
+        # Pass tool config at runtime via metadata
+        # The multiply tool will use offset=10, so multiply(a=6, b=7) returns 6*7+10=52
+        print("execute_ptc_code output: ", end="")
+        last_chunk = None
+        async for chunk in agent.arun_sse_stream(
+            query=("Use execute_ptc_code to import from tools.custom. Print time_tool() and multiply(a=6, b=7)."),
+            metadata={"tool_configs": {"multiply": {"offset": 10}}},
+        ):
+            last_chunk = chunk
+            print(json.dumps(chunk))
+            print("-" * 20)
+    finally:
+        await agent.cleanup()
+
+    print("execute_ptc_code output: ", last_chunk["content"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

aip_agents/examples/hello_world_ptc_custom_tools.pyi

@@ -0,0 +1,7 @@
+from aip_agents.agent import LangGraphReactAgent as LangGraphReactAgent
+from aip_agents.examples.tools.multiply_tool import MultiplyTool as MultiplyTool
+from aip_agents.ptc import PTCCustomToolConfig as PTCCustomToolConfig, PTCSandboxConfig as PTCSandboxConfig, PromptConfig as PromptConfig, file_tool as file_tool, package_tool as package_tool
+from aip_agents.tools.time_tool import TimeTool as TimeTool
+
+async def main() -> None:
+    """Run a hello-world PTC flow with custom tools."""

aip_agents/examples/hello_world_sentry.py

@@ -1,4 +1,4 @@
-"""This is a simple FastAPI app to test Sentry with Open Telemetry from BOSA SDK.
+"""This is a simple FastAPI app to test Sentry with Open Telemetry from GL Connectors SDK.
 
 To run this example, make sure to set the following environment variables:
     SENTRY_DSN
@@ -63,7 +63,7 @@ def create_app() -> FastAPI:
         FastAPI: The configured FastAPI application.
     """
     app = FastAPI(
-        title="Bosa SDK - Sentry with Open Telemetry",
+        title="GL Connectors SDK - Sentry with Open Telemetry",
         description="This is a simple FastAPI app to test Sentry with Open Telemetry.",
         version="0.0.1",
         docs_url=None,

aip_agents/examples/hello_world_tool_output_client.py

@@ -39,6 +39,15 @@ async def main():
             print(chunk["content"], end="", flush=True)
         if chunk.get("metadata"):
             print(f"\nMetadata: {chunk['metadata']}", end="\n\n", flush=True)
+        tool_info = chunk.get("metadata", {}).get("tool_info") if isinstance(chunk.get("metadata"), dict) else None
+        if isinstance(tool_info, dict):
+            for tool_call in tool_info.get("tool_calls", []):
+                if tool_call.get("name") == "data_visualizer":
+                    data_source = tool_call.get("args", {}).get("data_source")
+                    if not (isinstance(data_source, str) and data_source.startswith("$tool_output.")):
+                        raise RuntimeError(
+                            "Tool output sharing failed: expected data_source to reference $tool_output.<call_id>."
+                        )
     print("\n")
 
 

aip_agents/examples/tools/multiply_tool.py

@@ -0,0 +1,43 @@
+"""Tool to multiply two integers.
+
+Author: Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class MultiplyToolInput(BaseModel):
+    """Input schema for the MultiplyTool."""
+
+    a: int = Field(..., description="First factor.")
+    b: int = Field(..., description="Second factor.")
+
+
+class MultiplyToolConfig(BaseModel):
+    """Configuration for MultiplyTool."""
+
+    offset: int = Field(default=0, description="Offset to add to the result.")
+
+
+class MultiplyTool(BaseTool):
+    """Tool to multiply two integers."""
+
+    name: str = "multiply"
+    description: str = "Multiply two integers."
+    args_schema: type[BaseModel] = MultiplyToolInput
+    tool_config_schema: type[BaseModel] = MultiplyToolConfig
+
+    def _run(self, a: int, b: int) -> int:
+        """Return the product of two integers."""
+        offset = 0
+        if hasattr(self, "get_tool_config"):
+            config = self.get_tool_config()
+            if config:
+                offset = getattr(config, "offset", 0)
+
+        return a * b + offset
+
+    async def _arun(self, a: int, b: int) -> int:
+        """Return the product of two integers asynchronously."""
+        return self._run(a=a, b=b)

aip_agents/examples/tools/multiply_tool.pyi

@@ -0,0 +1,18 @@
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+class MultiplyToolInput(BaseModel):
+    """Input schema for the MultiplyTool."""
+    a: int
+    b: int
+
+class MultiplyToolConfig(BaseModel):
+    """Configuration for MultiplyTool."""
+    offset: int
+
+class MultiplyTool(BaseTool):
+    """Tool to multiply two integers."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    tool_config_schema: type[BaseModel]

aip_agents/guardrails/__init__.py

@@ -0,0 +1,83 @@
+# flake8: noqa: F401
+"""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
+to work with optional dependencies.
+
+Example:
+    Basic usage with a phrase matcher engine:
+
+    .. code-block:: python
+
+        from aip_agents.guardrails import GuardrailManager, GuardrailMiddleware
+        from aip_agents.guardrails.engines import PhraseMatcherEngine
+        from aip_agents.guardrails.schemas import GuardrailMode
+
+        # Create a guardrail engine
+        engine = PhraseMatcherEngine(
+            banned_phrases=["spam", "inappropriate"]
+        )
+
+        # Create a manager
+        manager = GuardrailManager(engines=[engine])
+
+        # Create middleware for agent integration
+        middleware = GuardrailMiddleware(guardrail_manager=manager)
+
+        # Use with agent (components are lazy-loaded)
+        from aip_agents.agent import LangGraphReactAgent
+        agent = LangGraphReactAgent(
+            name="my_agent",
+            guardrail=manager,
+            # ... other agent config
+        )
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aip_agents.guardrails.exceptions import GuardrailViolationError
+    from aip_agents.guardrails.manager import GuardrailManager
+    from aip_agents.guardrails.middleware import GuardrailMiddleware
+    from aip_agents.guardrails.schemas import (
+        BaseGuardrailEngineConfig,
+        GuardrailInput,
+        GuardrailMode,
+        GuardrailResult,
+    )
+
+
+_IMPORT_MAP = {
+    "GuardrailViolationError": "aip_agents.guardrails.exceptions",
+    "GuardrailManager": "aip_agents.guardrails.manager",
+    "GuardrailMiddleware": "aip_agents.guardrails.middleware",
+    "BaseGuardrailEngineConfig": "aip_agents.guardrails.schemas",
+    "GuardrailMode": "aip_agents.guardrails.schemas",
+    "GuardrailInput": "aip_agents.guardrails.schemas",
+    "GuardrailResult": "aip_agents.guardrails.schemas",
+}
+
+_cache: dict[str, Any] = {}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import components on first access."""
+    if name in _cache:
+        return _cache[name]
+
+    if name in _IMPORT_MAP:
+        try:
+            module = __import__(_IMPORT_MAP[name], fromlist=[name])
+            _cache[name] = getattr(module, name)
+            return _cache[name]
+        except ImportError as e:
+            raise ImportError(f"Failed to import {name}. Optional dependencies may be missing: {e}") from e
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = list(_IMPORT_MAP.keys())

aip_agents/guardrails/__init__.pyi

@@ -0,0 +1,6 @@
+from aip_agents.guardrails.exceptions import GuardrailViolationError as GuardrailViolationError
+from aip_agents.guardrails.manager import GuardrailManager as GuardrailManager
+from aip_agents.guardrails.middleware import GuardrailMiddleware as GuardrailMiddleware
+from aip_agents.guardrails.schemas import BaseGuardrailEngineConfig as BaseGuardrailEngineConfig, GuardrailInput as GuardrailInput, GuardrailMode as GuardrailMode, GuardrailResult as GuardrailResult
+
+__all__ = ['GuardrailViolationError', 'GuardrailManager', 'GuardrailMiddleware', 'BaseGuardrailEngineConfig', 'GuardrailMode', 'GuardrailInput', 'GuardrailResult']

aip_agents/guardrails/engines/__init__.py

@@ -0,0 +1,69 @@
+# flake8: noqa: F401
+"""Guardrail engines package with lazy loading support.
+
+This package provides guardrail engines that wrap GL SDK implementations.
+Engines are loaded lazily to support optional dependencies.
+
+Example:
+    Import and use guardrail engines:
+
+    .. code-block:: python
+
+        # Lazy import - works even if gllm-guardrail is not installed
+        from aip_agents.guardrails.engines import PhraseMatcherEngine, NemoGuardrailEngine
+
+        # Create a phrase matcher engine
+        phrase_engine = PhraseMatcherEngine(
+            banned_phrases=["spam", "inappropriate"]
+        )
+
+        # Create a NeMo guardrail engine (requires gllm-guardrail)
+        nemo_engine = NemoGuardrailEngine(
+            # NeMo-specific configuration
+        )
+
+        # Use with GuardrailManager
+        from aip_agents.guardrails import GuardrailManager
+        manager = GuardrailManager(engines=[phrase_engine, nemo_engine])
+
+Note:
+    All engines support lazy loading. If `gllm-guardrail` is not installed,
+    importing these engines will raise an ImportError only when actually
+    instantiated, not at import time.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+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
+
+
+_IMPORT_MAP = {
+    "NemoGuardrailEngine": "aip_agents.guardrails.engines.nemo",
+    "PhraseMatcherEngine": "aip_agents.guardrails.engines.phrase_matcher",
+}
+
+_cache: dict[str, Any] = {}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import engines on first access."""
+    if name in _cache:
+        return _cache[name]
+
+    if name in _IMPORT_MAP:
+        try:
+            module = __import__(_IMPORT_MAP[name], fromlist=[name])
+            _cache[name] = getattr(module, name)
+            return _cache[name]
+        except ImportError as e:
+            raise ImportError(f"Failed to import {name}. Optional dependencies may be missing: {e}") from e
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = list(_IMPORT_MAP.keys())

aip_agents/guardrails/engines/__init__.pyi

@@ -0,0 +1,4 @@
+from aip_agents.guardrails.engines.nemo import NemoGuardrailEngine as NemoGuardrailEngine
+from aip_agents.guardrails.engines.phrase_matcher import PhraseMatcherEngine as PhraseMatcherEngine
+
+__all__ = ['NemoGuardrailEngine', 'PhraseMatcherEngine']

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
+        """
+        ...  # pragma: no cover
+
+    @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
+        """
+        ...  # pragma: no cover
+
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        ...  # pragma: no cover
+
+
+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."""
+        ...  # pragma: no cover
+
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations."""
+        ...  # pragma: no cover
+
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        ...  # pragma: no cover