aip-agents-binary 0.5.25b1__py3-none-macosx_13_0_arm64.whl

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']

aip_agents/tools/web_search/serper_tool.py

@@ -0,0 +1,187 @@
+"""Tool to search Google Serper API.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+import json
+from json import dumps
+from typing import Any
+
+from gllm_core.schema import Chunk
+from langchain_community.utilities.google_serper import GoogleSerperAPIWrapper
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class GoogleSerperInput(BaseModel):
+    """Input schema for the GoogleSerperTool."""
+
+    query: str = Field(..., description="Search query", min_length=1)
+
+
+class GoogleSerperTool(BaseTool):
+    """Tool to search Google Serper API."""
+
+    name: str = "google_serper"
+    description: str = """
+    Useful for searching the web using the Google Serper API.
+    Input should be a search query.
+    """
+    save_output_history: bool = Field(default=True)
+    args_schema: type[BaseModel] = GoogleSerperInput
+    api_wrapper: GoogleSerperAPIWrapper = Field(default_factory=GoogleSerperAPIWrapper, exclude=True)
+
+    def _run(
+        self,
+        query: str,
+    ) -> str:
+        """Executes a query using the API wrapper and returns the result as a JSON string.
+
+        Args:
+            query (str): The query string to be executed.
+            run_manager (Optional[CallbackManagerForToolRun], optional): An optional callback manager for the tool run.
+                Defaults to None.
+
+        Returns:
+            str: The result of the query execution, serialized as a JSON string.
+        """
+        result = self.api_wrapper.results(query)
+        return dumps(result)
+
+    def _format_agent_reference(self, tool_output: str) -> list[Chunk]:
+        """Format tool output into agent references.
+
+        Args:
+            tool_output (str): The output from the tool, which is expected to be a JSON string.
+
+        Returns:
+            list[Chunk]: Formatted tool output as agent references
+        """
+        # Parse the tool output if it's a string
+        parsed_output = self._parse_tool_output(tool_output)
+        if not parsed_output:
+            return []
+
+        formatted_chunks = []
+        file_id_counter = 0
+
+        for section_name, section_data in parsed_output.items():
+            # Process only list-type sections
+            if not isinstance(section_data, list):
+                continue
+
+            # Process each item in the section
+            results = self._process_section_items(section_name, section_data, file_id_counter)
+            formatted_chunks.extend(results["chunks"])
+            file_id_counter = results["counter"]
+
+        return formatted_chunks
+
+    def _parse_tool_output(self, tool_output: str) -> dict[str, Any]:
+        """Parses the tool output to ensure it is in dictionary format.
+
+        This method attempts to convert string outputs to JSON dictionaries and handles
+        potential JSON parsing errors gracefully.
+
+        Args:
+            tool_output (str): The output from a tool, which is expected to be a JSON string.
+
+        Returns:
+            dict[str, Any]: The parsed output as a dictionary. Returns an empty
+            dictionary if parsing fails.
+        """
+        if isinstance(tool_output, str):
+            try:
+                return json.loads(tool_output)
+            except json.JSONDecodeError:
+                logger.warning("Error: Unable to parse tool_output as JSON when formatting agent references.")
+                return {}
+        return tool_output
+
+    def _process_section_items(self, section_name: str, section_data: list[dict], start_counter: int) -> dict[str, Any]:
+        """Process items from a specific section of search results and create chunks.
+
+        Args:
+            section_name (str): Name of the section being processed (e.g., 'organic', 'news').
+            section_data (list): List of items to process from the section.
+            start_counter (int): Initial counter value for chunk numbering.
+
+        Returns:
+            dict[str, Any]: Dictionary containing:
+                - chunks (list): List of processed chunks extracted from the section items.
+                - counter (int): Updated counter after processing all items.
+
+        Raises:
+            Exception: Logs errors that occur during processing of individual items.
+        """
+        chunks = []
+        counter = start_counter
+
+        for item in section_data:
+            if not isinstance(item, dict):
+                continue
+
+            try:
+                chunk = self._create_chunk_from_item(section_name, item, counter)
+                if chunk:
+                    chunks.append(chunk)
+                    counter += 1
+            except Exception as e:
+                logger.warning(f"Error processing {section_name} result: {e}")
+
+        return {"chunks": chunks, "counter": counter}
+
+    def _create_chunk_from_item(self, section_name: str, item: dict[str, Any], file_id: int) -> Chunk | None:
+        """Creates a Chunk object from a search result item.
+
+        This method extracts content and metadata from a search result item and creates
+        a Chunk object. It prioritizes snippet over title for content and includes various
+        metadata fields.
+
+        Args:
+            section_name (str): The name of the section this item belongs to.
+            item (dict[str, Any]): The search result item containing information like
+                snippet, title, and link.
+            file_id (int): The ID of the file associated with this chunk.
+
+        Returns:
+            Optional[Chunk]: A Chunk object containing the extracted content and metadata,
+                or None if the item lacks essential information (link or content).
+        """
+        # First check if link exists
+        link = item.get("link")
+        if not link:
+            logger.warning(f"Skipping item {file_id} from {section_name} result: Missing link")
+            return None
+
+        # Then extract and check content
+        content = ""
+        if "snippet" in item:
+            content = item["snippet"]
+        elif "title" in item:
+            content = item["title"]
+
+        if not content:
+            logger.warning(f"Skipping item {file_id} from {section_name} result: Missing content")
+            return None
+
+        metadata = {
+            "source": item.get("title", "Untitled Source"),
+            "section_type": section_name,
+            "source_type": "website",
+            "title": item.get("title", "Untitled"),
+            "link": link,
+            "file_id": str(file_id),
+            "url": link,
+            "start_index": 0,
+            "end_index": 0,
+        }
+
+        return Chunk(content=content, metadata=metadata)

aip_agents/tools/web_search/serper_tool.pyi

@@ -0,0 +1,19 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from langchain_community.utilities.google_serper import GoogleSerperAPIWrapper
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+logger: Incomplete
+
+class GoogleSerperInput(BaseModel):
+    """Input schema for the GoogleSerperTool."""
+    query: str
+
+class GoogleSerperTool(BaseTool):
+    """Tool to search Google Serper API."""
+    name: str
+    description: str
+    save_output_history: bool
+    args_schema: type[BaseModel]
+    api_wrapper: GoogleSerperAPIWrapper