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

aip_agents/tools/memory_search/schema.py

@@ -0,0 +1,81 @@
+"""Pydantic schemas shared by memory search tools.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MemoryConfig(BaseModel):
+    """Tool configuration schema for memory operations."""
+
+    user_id: str = Field(description="User identifier for memory scoping")
+
+
+class LongTermMemorySearchInput(BaseModel):
+    """Input schema for unified long-term memory retrieval."""
+
+    query: str | None = Field(
+        None,
+        description="Optional semantic query for searching memories. If provided, performs semantic search. "
+        "If omitted, performs pure date-based recall using time filters.",
+    )
+    start_date: str | None = Field(
+        None,
+        description="Explicit start date in YYYY-MM-DD format. Used with end_date for precise date ranges. "
+        "If omitted, recall is unbounded at the start.",
+    )
+    end_date: str | None = Field(
+        None,
+        description="Explicit end date in YYYY-MM-DD format. Used with start_date for precise date ranges. "
+        "If omitted, recall is unbounded at the end.",
+    )
+    limit: int | None = Field(
+        None,
+        description="Maximum number of memories to retrieve. If not specified, uses default. "
+        "Values below 5 are automatically increased to ensure adequate context.",
+    )
+    categories: list[str] | None = Field(
+        None,
+        description="Optional categories to filter by (uses 'in' operator).",
+    )
+    metadata: dict[str, Any] | None = Field(
+        None,
+        description="Optional metadata dict to filter by (exact key-value match).",
+    )
+
+
+class LongTermMemoryDeleteInput(BaseModel):
+    """Input schema for unified long-term memory deletion."""
+
+    query: str | None = Field(
+        None,
+        description="Semantic query describing memories to delete. If provided, delete_by_user_query is used.",
+    )
+    memory_ids: list[str] | None = Field(
+        None,
+        description="Optional list of memory IDs to delete directly.",
+    )
+    delete_all: bool | None = Field(
+        None,
+        description="When True and no query/IDs are provided, delete all memories for the user scope.",
+    )
+    top_k: int | None = Field(
+        None,
+        description="Optional maximum number of memories to delete by query.",
+    )
+    threshold: float | None = Field(
+        None,
+        description="Optional semantic threshold for delete_by_user_query.",
+    )
+    categories: list[str] | None = Field(
+        None,
+        description="Optional categories to filter by (uses 'in' operator).",
+    )
+    metadata: dict[str, Any] | None = Field(
+        None,
+        description="Optional metadata dict to filter by (exact key-value match).",
+    )

aip_agents/tools/memory_search/schema.pyi

@@ -0,0 +1,25 @@
+from pydantic import BaseModel
+from typing import Any
+
+class MemoryConfig(BaseModel):
+    """Tool configuration schema for memory operations."""
+    user_id: str
+
+class LongTermMemorySearchInput(BaseModel):
+    """Input schema for unified long-term memory retrieval."""
+    query: str | None
+    start_date: str | None
+    end_date: str | None
+    limit: int | None
+    categories: list[str] | None
+    metadata: dict[str, Any] | None
+
+class LongTermMemoryDeleteInput(BaseModel):
+    """Input schema for unified long-term memory deletion."""
+    query: str | None
+    memory_ids: list[str] | None
+    delete_all: bool | None
+    top_k: int | None
+    threshold: float | None
+    categories: list[str] | None
+    metadata: dict[str, Any] | None

aip_agents/tools/memory_search_tool.py

@@ -0,0 +1,34 @@
+"""Backward-compatible shim for the memory search tool module.
+
+The actual implementations now live under ``aip_agents.tools.memory_search``.
+Importing from this module continues to work for existing callers.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from aip_agents.tools.memory_search import (
+    MEMORY_DELETE_TOOL_NAME,
+    MEMORY_SEARCH_TOOL_NAME,
+    LongTermMemoryDeleteInput,
+    LongTermMemorySearchInput,
+    LongTermMemorySearchTool,
+    Mem0DeleteInput,
+    Mem0DeleteTool,
+    Mem0SearchInput,
+    Mem0SearchTool,
+    MemoryConfig,
+)
+
+__all__ = [
+    "MemoryConfig",
+    "LongTermMemoryDeleteInput",
+    "LongTermMemorySearchInput",
+    "LongTermMemorySearchTool",
+    "Mem0DeleteInput",
+    "Mem0DeleteTool",
+    "Mem0SearchInput",
+    "Mem0SearchTool",
+    "MEMORY_DELETE_TOOL_NAME",
+    "MEMORY_SEARCH_TOOL_NAME",
+]

aip_agents/tools/memory_search_tool.pyi

@@ -0,0 +1,3 @@
+from aip_agents.tools.memory_search import LongTermMemoryDeleteInput as LongTermMemoryDeleteInput, LongTermMemorySearchInput as LongTermMemorySearchInput, LongTermMemorySearchTool as LongTermMemorySearchTool, MEMORY_DELETE_TOOL_NAME as MEMORY_DELETE_TOOL_NAME, MEMORY_SEARCH_TOOL_NAME as MEMORY_SEARCH_TOOL_NAME, Mem0DeleteInput as Mem0DeleteInput, Mem0DeleteTool as Mem0DeleteTool, Mem0SearchInput as Mem0SearchInput, Mem0SearchTool as Mem0SearchTool, MemoryConfig as MemoryConfig
+
+__all__ = ['MemoryConfig', 'LongTermMemoryDeleteInput', 'LongTermMemorySearchInput', 'LongTermMemorySearchTool', 'Mem0DeleteInput', 'Mem0DeleteTool', 'Mem0SearchInput', 'Mem0SearchTool', 'MEMORY_DELETE_TOOL_NAME', 'MEMORY_SEARCH_TOOL_NAME']

aip_agents/tools/time_tool.py

@@ -0,0 +1,117 @@
+"""Tool to get the current time.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+import re
+from datetime import datetime, timedelta, timezone, tzinfo
+
+from dateutil import tz
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+FORMAT_STRING = "%m/%d/%y %H:%M:%S"
+DEFAULT_TIMEZONE = "UTC+7"
+
+
+class TimeToolInput(BaseModel):
+    """Input schema for the TimeTool."""
+
+    datetime_format: str = Field(
+        default=FORMAT_STRING,
+        description="""
+        Optional datetime format string. Default: '%m/%d/%y %H:%M:%S'
+
+        Common format codes:
+        %Y: Year with century (2024)
+        %m: Month as number (01-12)
+        %d: Day of month (01-31)
+        %A: Full weekday name (Wednesday)
+        %a: Short weekday name (Wed)
+        %H: Hour (00-23)
+        %M: Minute (00-59)
+        %S: Second (00-59)
+        %Z: Timezone name
+        %j: Day of year (001-366)
+        %W: Week number (00-53, Monday first)
+        %U: Week number (00-53, Sunday first)
+        %c: Locale's date and time
+        %x: Locale's date
+        %X: Locale's time
+        """,
+    )
+    timezone: str | None = Field(
+        default=DEFAULT_TIMEZONE,
+        description="""
+        Optional timezone identifier. Supports IANA names (e.g., 'Asia/Jakarta')
+        or offsets (e.g., 'UTC+7', 'UTC-04:30'). Default: 'UTC+7' (Asia/Jakarta).
+        Highly recommended to be filled when getting the current time to ensure
+        the time is in the correct timezone.
+        """,
+    )
+
+
+def _parse_timezone(timezone_value: str | None) -> tzinfo | None:
+    """Return a tzinfo instance for a given timezone string.
+
+    Args:
+        timezone_value: Timezone string (e.g., "UTC+7", "UTC-5:30") or None.
+
+    Returns:
+        tzinfo instance or None if invalid/None input.
+    """
+    if timezone_value is None:
+        return None
+
+    tz_string = timezone_value.strip()
+    if not tz_string:
+        return None
+
+    offset_match = re.fullmatch(r"UTC([+-])(\d{1,2})(?::?(\d{2}))?$", tz_string.upper())
+    if offset_match:
+        sign, hours_str, minutes_str = offset_match.groups()
+        hours = int(hours_str)
+        minutes = int(minutes_str) if minutes_str else 0
+        MAX_HOURS_OFFSET = 12
+        MINUTES_OFFSETS = [0, 30, 45]
+        if hours > MAX_HOURS_OFFSET or minutes not in MINUTES_OFFSETS:
+            raise ValueError(f"Invalid timezone offset: {timezone_value}")
+        delta = timedelta(hours=hours, minutes=minutes)
+        if sign == "-":
+            delta = -delta
+        return timezone(delta)
+
+    tzinfo = tz.gettz(tz_string)
+    if tzinfo is not None:
+        return tzinfo
+
+    raise ValueError(f"Unknown timezone: {timezone_value}")
+
+
+class TimeTool(BaseTool):
+    """Tool to get the current time."""
+
+    name: str = "time_tool"
+    description: str = """
+    Useful for getting the current time in a specified format and timezone.
+    Default format: '%m/%d/%y %H:%M:%S' (e.g., '05/15/24 17:30:00')
+
+    Supports timezone specification to get the current time in any timezone.
+    It is highly recommended to specify a timezone to ensure accurate results.
+    """
+    args_schema: type[BaseModel] = TimeToolInput
+
+    def _run(self, datetime_format: str = FORMAT_STRING, timezone: str | None = DEFAULT_TIMEZONE) -> str:
+        """Get current time formatted according to the specified format and timezone.
+
+        Args:
+            datetime_format: Format string for datetime (default: ISO format).
+            timezone: Timezone string (default: UTC).
+
+        Returns:
+            Formatted datetime string.
+        """
+        tzinfo = _parse_timezone(timezone)
+        current_time = datetime.now(tz=tzinfo)
+        return current_time.strftime(datetime_format)

aip_agents/tools/time_tool.pyi

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

aip_agents/tools/tool_config_injector.py

@@ -0,0 +1,300 @@
+"""Tool Configuration Injector for existing LangChain tools.
+
+This module provides utilities to inject Pydantic-based configuration into existing
+LangChain tools without requiring inheritance or modification of the tool classes.
+
+The SDK automatically injects configuration capabilities into tools that have a
+tool_config_schema attribute, providing:
+- Agent-level default configurations
+- Runtime configuration overrides via RunnableConfig metadata
+- Type-safe validation using Pydantic models
+- Support for optional fields with proper default handling
+
+Configuration Extraction Examples:
+
+    Nested format:
+        metadata = {"tool_configs": {"tool_name": {"api_key": "secret", "timeout": 30}}}
+
+    Flattened format (only works if ALL required fields are present):
+        metadata = {"api_key": "secret", "timeout": 30}  # Optional fields can be omitted
+
+    Required vs Optional fields:
+        class ToolConfig(BaseModel):
+            api_key: str              # Required - must be provided
+            timeout: int = 30         # Optional - will use default if not provided
+            retries: Optional[int] = None  # Optional - can be None
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from typing import Any, TypeVar
+
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+ConfigSchema = TypeVar("ConfigSchema", bound=BaseModel)
+
+# Public API exports
+__all__ = [
+    "inject_config_methods_into_tool",
+    "CONFIG_SCHEMA_ATTR",
+    "CONFIG_ATTR",
+    "TOOL_CONFIG_SCHEMA_ATTR",
+    "TOOL_CONFIGS_KEY",
+]
+
+# Constants for configuration attribute names and keys
+CONFIG_SCHEMA_ATTR: str = "_config_schema"
+CONFIG_ATTR: str = "_config"
+TOOL_CONFIG_SCHEMA_ATTR: str = "tool_config_schema"
+TOOL_CONFIGS_KEY: str = "tool_configs"
+
+
+def _get_config_field_names(schema: type[BaseModel]) -> list[str]:
+    """Get field names from a Pydantic model schema.
+
+    Args:
+        schema: The Pydantic model schema to get field names from.
+
+    Returns:
+        A list of field names.
+    """
+    if hasattr(schema, "model_fields"):
+        return list(schema.model_fields.keys())
+    elif hasattr(schema, "__fields__"):
+        return list(schema.__fields__.keys())
+    else:
+        return []
+
+
+def _get_required_field_names(schema: type[BaseModel]) -> set[str]:
+    """Get required field names from a Pydantic model schema.
+
+    Args:
+        schema: The Pydantic model schema to get required field names from.
+
+    Returns:
+        A set of required field names.
+    """
+    # Pydantic V2
+    if hasattr(schema, "model_fields"):
+        return {name for name, field_info in schema.model_fields.items() if field_info.is_required()}
+
+    # Pydantic V1 (fallback)
+    elif hasattr(schema, "__fields__"):
+        return {name for name, field in schema.__fields__.items() if field.required}
+
+    return set()
+
+
+def _extract_nested_config(tool: BaseTool, metadata: dict[str, Any]) -> ConfigSchema | None:
+    """Extract tool config from nested tool_configs structure.
+
+    Args:
+        tool: The tool instance to extract configuration from.
+        metadata: The metadata to use.
+
+    Returns:
+        The nested configuration.
+    """
+    tool_configs = metadata.get(TOOL_CONFIGS_KEY, {})
+    if not isinstance(tool_configs, dict) or tool.name not in tool_configs:
+        return None
+
+    tool_config_data = tool_configs[tool.name]
+    try:
+        config_schema = getattr(tool, CONFIG_SCHEMA_ATTR)
+        if isinstance(tool_config_data, dict):
+            return config_schema(**tool_config_data)
+        elif isinstance(tool_config_data, config_schema):
+            return tool_config_data
+    except Exception as e:
+        logger.debug(f"Failed to validate nested config for tool '{tool.name}': {e}")
+
+    return None
+
+
+def _extract_flattened_config(tool: BaseTool, metadata: dict[str, Any]) -> ConfigSchema | None:
+    """Extract tool config from flattened metadata keys.
+
+    This function builds a configuration from metadata keys that match the tool's
+    config schema field names. Only required fields must be present; optional fields
+    with defaults will be handled by Pydantic during instantiation.
+
+    Behavior:
+    - Returns None silently if metadata is empty (likely using agent defaults)
+    - Logs debug message if metadata exists but contains no matching config fields
+    - Logs warning if some required fields are missing from provided config fields
+
+    Args:
+        tool: The tool instance to extract configuration from.
+        metadata: The metadata to use.
+
+    Returns:
+        The flattened configuration if all required fields are present, None otherwise.
+    """
+    config_schema = getattr(tool, CONFIG_SCHEMA_ATTR)
+    config_fields = _get_config_field_names(config_schema)
+    required_fields = _get_required_field_names(config_schema)
+
+    if not config_fields:
+        return None
+
+    # Extract all available config fields from metadata
+    flattened_config = {}
+    for field_name in config_fields:
+        if field_name in metadata:
+            flattened_config[field_name] = metadata[field_name]
+
+    # Only proceed if we have at least some configuration fields
+    if not flattened_config:
+        if metadata:
+            logger.debug(
+                f"No valid config fields found in flattened metadata for tool '{tool.name}'. "
+                f"Available metadata keys: {list(metadata.keys())}, "
+                f"Expected config fields: {config_fields}"
+            )
+        return None
+
+    # Check if all required fields are present
+    provided_fields = set(flattened_config.keys())
+    missing_required_fields = required_fields - provided_fields
+
+    if missing_required_fields:
+        logger.warning(f"Missing required fields for flattened config in tool '{tool.name}': {missing_required_fields}")
+        return None
+
+    try:
+        return config_schema(**flattened_config)
+    except Exception as e:
+        logger.debug(f"Failed to validate flattened config for tool '{tool.name}': {e}")
+
+    return None
+
+
+def _extract_runtime_config(tool: BaseTool, config: RunnableConfig | None) -> ConfigSchema | None:
+    """Extract runtime configuration from RunnableConfig metadata.
+
+    Args:
+        tool: The tool instance to extract configuration from.
+        config: The configuration to use.
+
+    Returns:
+        The runtime configuration.
+    """
+    if not config or not hasattr(tool, CONFIG_SCHEMA_ATTR):
+        return None
+
+    metadata = config.get("metadata", {})
+    if not isinstance(metadata, dict):
+        return None
+
+    # Try nested structure first
+    nested_config = _extract_nested_config(tool, metadata)
+    if nested_config is not None:
+        return nested_config
+
+    # Try flattened structure
+    return _extract_flattened_config(tool, metadata)
+
+
+def _create_tool_config_methods(tool: BaseTool) -> dict[str, Any]:
+    """Create the configuration management methods for a tool.
+
+    Args:
+        tool: The tool instance to create methods for.
+
+    Returns:
+        Dictionary of method names to method functions.
+    """
+
+    def set_tool_config(config: ConfigSchema | dict[str, Any] | None) -> None:
+        """Set the tool's agent-level default configuration with validation.
+
+        Args:
+            config: The configuration to set.
+
+        Raises:
+            ValueError: If the config is not an instance of the tool's config schema or a dictionary.
+        """
+        if config is None:
+            object.__setattr__(tool, CONFIG_ATTR, None)
+            return
+
+        config_schema = getattr(tool, CONFIG_SCHEMA_ATTR)
+        if isinstance(config, dict):
+            object.__setattr__(tool, CONFIG_ATTR, config_schema(**config))
+        elif isinstance(config, config_schema):
+            object.__setattr__(tool, CONFIG_ATTR, config)
+        else:
+            config_schema_name = getattr(config_schema, "__name__", repr(config_schema))
+            raise ValueError(f"Config must be an instance of {config_schema_name} or dict, got {type(config).__name__}")
+
+    def get_default_config() -> ConfigSchema | None:
+        """Get the agent-level default configuration.
+
+        Returns:
+            The agent-level default configuration.
+        """
+        return getattr(tool, CONFIG_ATTR)
+
+    def has_tool_config() -> bool:
+        """Check if the tool has an agent-level default configuration set.
+
+        Returns:
+            True if the tool has an agent-level default configuration set, False otherwise.
+        """
+        return getattr(tool, CONFIG_ATTR) is not None
+
+    def get_tool_config(config: RunnableConfig | None = None) -> ConfigSchema | None:
+        """Get the effective tool configuration.
+
+        This function extracts the tool configuration from the runnable configuration.
+        If the tool configuration is not found in the runnable configuration, it will
+        return the agent-level default configuration.
+
+        Args:
+            config: The runnable configuration to use from LangGraph.
+
+        Returns:
+            The effective tool configuration.
+        """
+        runtime_config = _extract_runtime_config(tool, config)
+        return runtime_config if runtime_config is not None else getattr(tool, CONFIG_ATTR)
+
+    return {
+        "set_tool_config": set_tool_config,
+        "get_default_config": get_default_config,
+        "has_tool_config": has_tool_config,
+        "get_tool_config": get_tool_config,
+    }
+
+
+def inject_config_methods_into_tool(tool: BaseTool, config_schema: type[ConfigSchema]) -> None:
+    """Inject configuration methods into a tool.
+
+    This function is used by the SDK to automatically inject configuration capabilities
+    into tools that have a tool_config_schema attribute. It can also be used directly
+    by developers who want to add configuration support to their tools.
+
+    Args:
+        tool: The tool to inject configuration capabilities into.
+        config_schema: Pydantic model class for configuration validation.
+
+    Raises:
+        ValueError: If tool is not a BaseTool instance or config_schema is not a Pydantic BaseModel subclass.
+    """
+    # Add configuration attributes
+    object.__setattr__(tool, CONFIG_SCHEMA_ATTR, config_schema)
+    object.__setattr__(tool, CONFIG_ATTR, None)
+
+    # Create and inject methods
+    methods = _create_tool_config_methods(tool)
+    for method_name, method_func in methods.items():
+        object.__setattr__(tool, method_name, method_func)

aip_agents/tools/tool_config_injector.pyi

@@ -0,0 +1,26 @@
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+from typing import TypeVar
+
+__all__ = ['inject_config_methods_into_tool', 'CONFIG_SCHEMA_ATTR', 'CONFIG_ATTR', 'TOOL_CONFIG_SCHEMA_ATTR', 'TOOL_CONFIGS_KEY']
+
+ConfigSchema = TypeVar('ConfigSchema', bound=BaseModel)
+CONFIG_SCHEMA_ATTR: str
+CONFIG_ATTR: str
+TOOL_CONFIG_SCHEMA_ATTR: str
+TOOL_CONFIGS_KEY: str
+
+def inject_config_methods_into_tool(tool: BaseTool, config_schema: type[ConfigSchema]) -> None:
+    """Inject configuration methods into a tool.
+
+    This function is used by the SDK to automatically inject configuration capabilities
+    into tools that have a tool_config_schema attribute. It can also be used directly
+    by developers who want to add configuration support to their tools.
+
+    Args:
+        tool: The tool to inject configuration capabilities into.
+        config_schema: Pydantic model class for configuration validation.
+
+    Raises:
+        ValueError: If tool is not a BaseTool instance or config_schema is not a Pydantic BaseModel subclass.
+    """

aip_agents/tools/web_search/__init__.py

@@ -0,0 +1,15 @@
+"""Web Search Tools for AI Agents.
+
+This package provides web search capabilities for AI agents through integration
+with Google Serper API and Tavily Search API.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+    Saul Sayers (saul.sayers@gdplabs.id)
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+from aip_agents.tools.web_search.serper_tool import GoogleSerperTool
+
+__all__ = ["GoogleSerperTool"]

aip_agents/tools/web_search/__init__.pyi

@@ -0,0 +1,3 @@
+from aip_agents.tools.web_search.serper_tool import GoogleSerperTool as GoogleSerperTool
+
+__all__ = ['GoogleSerperTool']