aip-agents-binary 0.5.24__py3-none-any.whl → 0.5.25b1__py3-none-any.whl

aip_agents/examples/tools/langchain_currency_exchange_tool.pyi

@@ -0,0 +1,20 @@
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+class CurrencyConfig(BaseModel):
+    """Tool configuration schema."""
+    tenant_id: str
+    auth_key: str
+
+class CurrencyInput(BaseModel):
+    """Input schema for currency exchange."""
+    amount: float
+    from_currency: str
+    to_currency: str
+
+class CurrencyExchangeTool(BaseTool):
+    """Simple currency exchange tool with SDK auto-injection configuration."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    tool_config_schema: type[BaseModel]

aip_agents/examples/tools/langchain_graph_artifact_tool.pyi

@@ -0,0 +1,25 @@
+from aip_agents.a2a.types import MimeType as MimeType
+from aip_agents.utils.artifact_helpers import create_artifact_command as create_artifact_command
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+PIL_AVAILABLE: bool
+
+class GraphCommandInput(BaseModel):
+    """Input schema for a tiny bar/line chart artifact tool.
+
+    Note: width/height are clamped to a small size to keep artifacts lightweight.
+    """
+    chart_type: str
+    labels: list[str]
+    values: list[float]
+    title: str
+    width: int
+    height: int
+    image_name: str
+
+class GraphArtifactCommandTool(BaseTool):
+    """Generate a very small PNG chart and return it as a Command artifact."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]

aip_agents/examples/tools/langchain_weather_tool.pyi

@@ -0,0 +1,19 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from pydantic import BaseModel
+
+logger: Incomplete
+
+class WeatherToolInputSchema(BaseModel):
+    """Schema for weather tool input."""
+    city: str
+
+def weather_tool(city: str) -> str:
+    """Gets the weather for a specified city.
+
+    Args:
+        city: The name of the city to get weather for.
+
+    Returns:
+        A string describing the weather conditions.
+    """

aip_agents/examples/tools/langgraph_streaming_tool.pyi

@@ -0,0 +1,43 @@
+from aip_agents.agent.langgraph_react_agent import LangGraphReactAgent as LangGraphReactAgent
+from aip_agents.examples.tools.langchain_weather_tool import weather_tool as weather_tool
+from aip_agents.examples.tools.time_tool import TimeTool as TimeTool
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+from typing import Any
+
+class StreamingToolConfig(BaseModel):
+    """Tool configuration schema for the LangGraph streaming tool."""
+    time_format: str
+
+class LangGraphStreamingToolInput(BaseModel):
+    """Input schema for the LangGraphStreamingTool."""
+    query: str
+
+class LangGraphStreamingTool(BaseTool):
+    """Tool that wraps a LangGraph agent with time and weather forecast capabilities."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    tool_config_schema: type[BaseModel]
+    def __init__(self, model: Any = None, **kwargs) -> None:
+        """Initialize the LangGraphStreamingTool.
+
+        Args:
+            model: The model to use for the agent.
+            **kwargs: Additional keyword arguments.
+        """
+    @property
+    def agent(self):
+        """Access the internal agent."""
+    async def arun_streaming(self, query: str = None, config: RunnableConfig = None, **kwargs):
+        """Execute the LangGraph agent asynchronously with A2A streaming output.
+
+        Args:
+            query: The query to execute.
+            config: Tool configuration containing user context and preferences.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            An async generator that yields streaming events.
+        """

aip_agents/examples/tools/mock_retrieval_tool.pyi

@@ -0,0 +1,13 @@
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+class MockRetrievalInput(BaseModel):
+    """Input schema for the MockRetrievalTool."""
+    query: str
+
+class MockRetrievalTool(BaseTool):
+    """Mock tool that returns hardcoded references for testing."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]
+    save_output_history: bool

aip_agents/examples/tools/pii_demo_tools.pyi

@@ -0,0 +1,54 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import LoggerManager as LoggerManager
+from pydantic import BaseModel
+
+logger: Incomplete
+
+class CustomerIdSchema(BaseModel):
+    """Schema for customer ID input."""
+    customer_id: str
+
+class EmployeeIdSchema(BaseModel):
+    """Schema for employee ID input."""
+    employee_id: str
+
+class UserIdSchema(BaseModel):
+    """Schema for user ID input."""
+    user_id: str
+
+def get_customer_info(customer_id: str) -> str:
+    """Gets customer information including email and phone number.
+
+    This tool demonstrates PII handling by returning sensitive customer data
+    that will be automatically anonymized by the PII handler.
+
+    Args:
+        customer_id: The ID of the customer to retrieve information for.
+
+    Returns:
+        A string containing customer information with PII.
+    """
+def get_employee_data(employee_id: str) -> str:
+    """Gets employee data including name, email, and salary information.
+
+    This tool demonstrates PII handling with employee-specific data that includes
+    sensitive information like salary and personal email addresses.
+
+    Args:
+        employee_id: The ID of the employee to retrieve data for.
+
+    Returns:
+        A string containing employee information with PII.
+    """
+def get_user_profile(user_id: str) -> str:
+    """Gets user profile information with personal details.
+
+    This tool demonstrates PII handling with user profile data that includes
+    personal information like email, phone, and date of birth.
+
+    Args:
+        user_id: The ID of the user to retrieve profile for.
+
+    Returns:
+        A string containing user profile information with PII.
+    """

aip_agents/examples/tools/random_chart_tool.pyi

@@ -0,0 +1,20 @@
+from aip_agents.a2a.types import MimeType as MimeType
+from aip_agents.utils.artifact_helpers import create_artifact_command as create_artifact_command
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+DEFAULT_RANDOM_CHART_TITLE: str
+PIL_AVAILABLE: bool
+
+class RandomChartInput(BaseModel):
+    """Input schema for random chart generation."""
+    title: str
+    num_bars: int
+    min_value: int
+    max_value: int
+
+class RandomChartTool(BaseTool):
+    """Generate random bar chart images without relying on upstream data."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]

aip_agents/examples/tools/serper_tool.pyi

@@ -0,0 +1,16 @@
+from _typeshed import Incomplete
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+logger: Incomplete
+
+class GoogleSerperInput(BaseModel):
+    """Input schema for the GoogleSerperTool."""
+    query: str
+
+class MockGoogleSerperTool(BaseTool):
+    """Mock Tool to simulate Google Serper API results for testing."""
+    name: str
+    description: str
+    save_output_history: bool
+    args_schema: type[BaseModel]

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__.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
+        """
+        ...
+
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations.
+
+        Args:
+            content: The AI output content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+        ...
+
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        ...
+
+
+class BaseGuardrailEngine(ABC):
+    """Abstract base class for guardrail engines.
+
+    Provides common functionality and ensures proper configuration handling.
+    Concrete engines should inherit from this class.
+    """
+
+    def __init__(self, config: BaseGuardrailEngineConfig | None = None) -> None:
+        """Initialize the engine with configuration.
+
+        Args:
+            config: Engine configuration. Uses defaults if None provided.
+        """
+        self.config = config or BaseGuardrailEngineConfig()
+
+    @abstractmethod
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content for safety violations."""
+        ...
+
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations."""
+        ...
+
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        ...

aip_agents/guardrails/engines/base.pyi

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