aip-agents-binary 0.5.25b8__py3-none-any.whl → 0.6.0__py3-none-any.whl

aip_agents/examples/tools/stock_tools.pyi

@@ -0,0 +1,36 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from pydantic import BaseModel
+from typing import Any
+
+logger: Incomplete
+
+class StockPriceInput(BaseModel):
+    """Input for the stock price tool."""
+    symbol: str
+
+def get_stock_price(symbol: str) -> dict[str, Any]:
+    """Get current stock price and performance data for a given symbol.
+
+    Args:
+        symbol (str): The stock symbol (e.g., AAPL, MSFT) to get the price for.
+
+    Returns:
+        dict[str, Any]: Dictionary containing stock price and performance data.
+    """
+
+class StockNewsInput(BaseModel):
+    """Input for the stock news tool."""
+    symbol: str
+    days: int
+
+def get_stock_news(symbol: str, days: int = 7) -> dict[str, Any]:
+    """Get recent news for a stock for a specified number of days.
+
+    Args:
+        symbol (str): The stock symbol (e.g., AAPL, MSFT) to get news for.
+        days (int, optional): Number of days of news to retrieve. Defaults to 7.
+
+    Returns:
+        dict[str, Any]: Dictionary containing stock news data.
+    """

aip_agents/examples/tools/table_generator_tool.pyi

@@ -0,0 +1,22 @@
+from aip_agents.a2a.types import MimeType as MimeType
+from aip_agents.utils.artifact_helpers import create_artifact_response as create_artifact_response
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+class TableGeneratorInput(BaseModel):
+    """Input schema for table generator tool."""
+    rows: int
+    columns: list[str]
+    table_name: str
+
+class TableGeneratorTool(BaseTool):
+    """Tool that generates sample data tables with artifact support.
+
+    This tool demonstrates the standardized artifact format by:
+    1. Generating sample data
+    2. Creating a markdown table for the agent's context
+    3. Creating a CSV file artifact for the user
+    """
+    name: str
+    description: str
+    args_schema: type[BaseModel]

aip_agents/examples/tools/time_tool.pyi

@@ -0,0 +1,15 @@
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+FORMAT_STRING: str
+
+class TimeToolInput(BaseModel):
+    """Input schema for the TimeTool."""
+    datetime_format: str
+
+class TimeTool(BaseTool):
+    """Tool to get the current time."""
+    name: str
+    description: str
+    save_output_history: bool
+    args_schema: type[BaseModel]

aip_agents/examples/tools/weather_forecast_tool.pyi

@@ -0,0 +1,14 @@
+from _typeshed import Incomplete
+
+DAILY_WEATHER: Incomplete
+DayOfWeek: Incomplete
+
+def get_weather_forecast(day: DayOfWeek) -> str:
+    """Get the weather forecast for a specific day of the week.
+
+    Args:
+        day: The day of the week (monday, tuesday, wednesday, etc.)
+
+    Returns:
+        str: A weather forecast message including conditions and temperature.
+    """

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__.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

@@ -39,7 +39,7 @@ class GuardrailEngine(Protocol):
         Returns:
             GuardrailResult indicating if content is safe
         """
-        ...
+        ...  # pragma: no cover
 
     @abstractmethod
     async def check_output(self, content: str) -> GuardrailResult:
@@ -51,12 +51,12 @@ class GuardrailEngine(Protocol):
         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):
@@ -77,14 +77,14 @@ class BaseGuardrailEngine(ABC):
     @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

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.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.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.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.pyi

@@ -0,0 +1,42 @@
+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

@@ -0,0 +1,87 @@
+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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,5 @@
+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']