aip-agents-binary 0.6.3__py3-none-any.whl → 0.6.5__py3-none-any.whl

aip_agents/guardrails/__init__.pyi

@@ -1,6 +0,0 @@
-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__.pyi

@@ -1,4 +0,0 @@
-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.pyi

@@ -1,61 +0,0 @@
-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.pyi

@@ -1,46 +0,0 @@
-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.pyi

@@ -1,48 +0,0 @@
-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.pyi

@@ -1,23 +0,0 @@
-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.pyi

@@ -1,42 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.guardrails.engines.base import GuardrailEngine as GuardrailEngine
-from aip_agents.guardrails.schemas import GuardrailInput as GuardrailInput, GuardrailMode as GuardrailMode, GuardrailResult as GuardrailResult
-from typing import Any
-
-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
-    """
-    enabled: bool
-    engines: Incomplete
-    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
-        """
-    def model_dump(self) -> dict[str, Any]:
-        """Serialize manager configuration into a JSON-compatible dictionary."""
-    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
-        """

aip_agents/guardrails/middleware.pyi

@@ -1,87 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.guardrails.exceptions import GuardrailViolationError as GuardrailViolationError
-from aip_agents.guardrails.manager import GuardrailManager as GuardrailManager
-from aip_agents.guardrails.schemas import GuardrailInput as GuardrailInput
-from aip_agents.middleware.base import AgentMiddleware as AgentMiddleware, ModelRequest as ModelRequest
-from typing import Any
-
-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
-    """
-    guardrail_manager: Incomplete
-    def __init__(self, guardrail_manager: GuardrailManager) -> None:
-        """Initialize the GuardrailMiddleware.
-
-        Args:
-            guardrail_manager: GuardrailManager instance to use for checking
-        """
-    @property
-    def tools(self) -> list:
-        """Guardrails are passive filters and don't contribute tools."""
-    @property
-    def system_prompt_additions(self) -> str | None:
-        """Guardrails are passive filters and don't modify system prompts."""
-    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
-        """
-    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
-        """
-    def modify_model_request(self, request: ModelRequest, state: dict[str, Any]) -> ModelRequest:
-        """Guardrails don't modify model requests."""
-    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
-        """
-    def after_model(self, state: dict[str, Any]) -> dict[str, Any]:
-        """Check AI output after model invocation (synchronous wrapper)."""

aip_agents/guardrails/schemas.pyi

@@ -1,43 +0,0 @@
-from _typeshed import Incomplete
-from enum import StrEnum
-from pydantic import BaseModel
-
-class GuardrailMode(StrEnum):
-    """Modes determining what content an engine checks."""
-    INPUT_ONLY: str
-    OUTPUT_ONLY: str
-    INPUT_OUTPUT: str
-    DISABLED: str
-
-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: Incomplete
-    input: str | None
-    output: str | 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: Incomplete
-    is_safe: bool
-    reason: str | None
-    filtered_content: str | None
-
-class BaseGuardrailEngineConfig(BaseModel):
-    """Base configuration for guardrail engines.
-
-    Attributes:
-        guardrail_mode: What content this engine should check
-    """
-    model_config: Incomplete
-    guardrail_mode: GuardrailMode

aip_agents/guardrails/utils.pyi

@@ -1,19 +0,0 @@
-from aip_agents.guardrails.schemas import GuardrailMode as GuardrailMode
-from typing import Any
-
-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
-    """

aip_agents/mcp/client/__init__.pyi

@@ -1,5 +0,0 @@
-from aip_agents.mcp.client.base_mcp_client import BaseMCPClient as BaseMCPClient
-from aip_agents.mcp.client.google_adk.client import GoogleADKMCPClient as GoogleADKMCPClient
-from aip_agents.mcp.client.langchain.client import LangchainMCPClient as LangchainMCPClient
-
-__all__ = ['GoogleADKMCPClient', 'LangchainMCPClient', 'BaseMCPClient']

aip_agents/mcp/client/base_mcp_client.pyi

@@ -1,148 +0,0 @@
-from _typeshed import Incomplete
-from abc import ABC, abstractmethod
-from aip_agents.mcp.client.persistent_session import PersistentMCPSession as PersistentMCPSession
-from aip_agents.mcp.client.session_pool import MCPSessionPool as MCPSessionPool
-from aip_agents.utils.logger import get_logger as get_logger
-from gllm_tools.mcp.client.client import MCPClient
-from gllm_tools.mcp.client.config import MCPConfiguration as MCPConfiguration
-from mcp.types import CallToolResult, Tool as Tool
-from typing import Any
-
-logger: Incomplete
-
-class BaseMCPClient(MCPClient, ABC):
-    """Base MCP Client with persistent session management for aip-agents.
-
-    This class provides:
-    - Persistent session management across tool calls
-    - One-time tool registration and caching
-    - Automatic connection health monitoring and reconnection
-    - Centralized cleanup of all MCP resources
-    - Generic tool discovery from all configured MCP servers
-
-    Subclasses should implement SDK-specific tool conversion in _process_tool() method.
-    """
-    session_pool: Incomplete
-    def __init__(self, servers: dict[str, MCPConfiguration]) -> None:
-        """Initialize the base MCP client with session pool.
-
-        Args:
-            servers (dict[str, MCPConfiguration]): Dictionary of MCP server configurations by server name
-        """
-    async def initialize(self) -> None:
-        """Initialize all MCP sessions and cache tools once.
-
-        This method is idempotent and only performs initialization if not already done.
-        It establishes persistent connections to all configured MCP servers and caches
-        available tools for efficient access.
-
-        Raises:
-            Exception: If any session initialization fails
-        """
-    @abstractmethod
-    async def get_tools(self, server: str | None = None) -> list[Any]:
-        """Get framework-specific tools from MCP servers.
-
-        This method must be implemented by subclasses to provide framework-specific
-        tool conversion (e.g., StructuredTool for LangChain, FunctionTool for Google ADK).
-
-        Args:
-            server (str | None): Optional server name to filter tools from a specific server.
-                    If None, returns tools from all configured servers.
-
-        Returns:
-            list[Any]: List of framework-specific tool objects.
-        """
-    async def get_raw_mcp_tools(self, server: str | None = None) -> list[Tool]:
-        """Get raw MCP tools - for subclasses to perform framework-specific conversions.
-
-        This method provides access to the cached raw MCP Tool objects.
-        Subclasses use this to convert to framework-specific tools.
-
-        Args:
-            server (str | None): Optional server name to filter tools from a specific server.
-                    If None, returns tools from all configured servers.
-
-        Returns:
-            list[Tool]: List of raw MCP Tool objects. Empty list if not initialized or no tools available.
-        """
-    def get_tools_count(self, server: str | None = None) -> int:
-        """Get count of raw MCP tools without expensive copying.
-
-        This is an efficient way to get tool counts for logging/metrics
-        without the overhead of copying tool lists.
-
-        Args:
-            server (str | None): Optional server name to filter tools from a specific server.
-                    If None, returns count from all configured servers.
-
-        Returns:
-            int: Count of raw MCP tools available.
-        """
-    async def get_session(self, server_name: str) -> PersistentMCPSession:
-        """Get a persistent session for a specific server.
-
-        Args:
-            server_name (str): The name of the MCP server
-
-        Returns:
-            PersistentMCPSession: Persistent MCP session for the specified server
-
-        Raises:
-            KeyError: If the server is not configured or no active session exists
-        """
-    async def call_tool(self, server_name: str, tool_name: str, arguments: dict[str, Any]) -> CallToolResult:
-        """Execute a tool on a specific MCP server using persistent session.
-
-        Args:
-            server_name (str): The MCP server to execute the tool on
-            tool_name (str): The name of the tool to execute
-            arguments (dict[str, Any]): Arguments for the tool execution
-
-        Returns:
-            CallToolResult: The result of the tool execution
-
-        Raises:
-            KeyError: If the server doesn't exist
-            Exception: If tool execution fails
-        """
-    async def read_resource(self, server_name: str, resource_uri: str):
-        """Read an MCP resource from a specific server using persistent session.
-
-        Args:
-            server_name (str): The MCP server to read the resource from
-            resource_uri (str): The URI of the resource to read
-
-        Returns:
-            Any: The resource content
-
-        Raises:
-            KeyError: If the server doesn't exist
-            Exception: If resource reading fails
-        """
-    async def cleanup(self) -> None:
-        """Clean up all MCP resources and close sessions.
-
-        This method properly closes all persistent sessions and cleans up resources.
-        It can be called multiple times safely.
-        """
-    @property
-    def is_initialized(self) -> bool:
-        """Check if the client is fully initialized.
-
-        Returns:
-            bool: True if sessions are initialized and tools are cached, False otherwise
-        """
-    @property
-    def active_sessions(self) -> dict[str, PersistentMCPSession]:
-        """Get all active persistent sessions.
-
-        Returns:
-            dict[str, PersistentMCPSession]: Dictionary of active sessions by server name
-        """
-    def get_session_count(self) -> int:
-        """Get the number of active MCP sessions.
-
-        Returns:
-            Number of active persistent sessions
-        """

aip_agents/mcp/client/connection_manager.pyi

@@ -1,51 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.mcp.client.transports import TransportType as TransportType, create_transport as create_transport
-from aip_agents.utils.logger import get_logger as get_logger
-from gllm_tools.mcp.client.config import MCPConfiguration
-from typing import Any
-
-logger: Incomplete
-
-class MCPConnectionManager:
-    """Manages MCP connection lifecycle following mcp-use patterns.
-
-    This connection manager handles the transport connection lifecycle in a background
-    task to avoid cancel scope issues during cleanup. It supports automatic transport
-    negotiation (HTTP -> SSE fallback) and graceful shutdown. Invalid explicit transports
-    are normalized via aliases (e.g., 'streamable_http' -> 'http') or fall back to
-    auto-detection with a warning.
-    """
-    TRANSPORT_ALIASES: Incomplete
-    server_name: Incomplete
-    config: Incomplete
-    transport_type: Incomplete
-    max_retries: Incomplete
-    initial_retry_delay: Incomplete
-    def __init__(self, server_name: str, config: MCPConfiguration) -> None:
-        """Initialize connection manager.
-
-        Args:
-            server_name (str): Name of the MCP server
-            config (MCPConfiguration): MCP server configuration
-        """
-    async def start(self) -> tuple[Any, Any]:
-        """Start connection in background task.
-
-        For HTTP/SSE transports, establishes connection directly to avoid anyio context issues.
-        For stdio transport, uses background task to manage subprocess lifecycle.
-
-        Returns:
-            tuple[Any, Any]: Tuple of (read_stream, write_stream) for ClientSession
-
-        Raises:
-            Exception: If connection establishment fails
-        """
-    async def stop(self) -> None:
-        """Stop connection gracefully."""
-    @property
-    def is_connected(self) -> bool:
-        """Check if connection is active.
-
-        Returns:
-            bool: True if connected, False otherwise
-        """

aip_agents/mcp/client/google_adk/__init__.pyi

@@ -1,3 +0,0 @@
-from aip_agents.mcp.client.google_adk.client import GoogleADKMCPClient as GoogleADKMCPClient
-
-__all__ = ['GoogleADKMCPClient']