ai-parrot 0.17.2__cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

parrot/tools/ddgo.py

@@ -0,0 +1,370 @@
+"""
+DuckDuckGo Search Toolkit for AI-Parrot.
+
+This toolkit provides web search capabilities using the ddgs library directly,
+removing all Langchain dependencies and implementing proper backoff retry for rate limiting.
+"""
+import asyncio
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel, Field
+import backoff
+from ddgs import DDGS
+from ddgs.exceptions import (
+    DDGSException,
+    RatelimitException,
+    TimeoutException,
+)
+from navconfig.logging import logging
+from .toolkit import AbstractToolkit
+from .abstract import ToolResult
+
+
+
+# Pydantic schemas for tool arguments
+class WebSearchArgs(BaseModel):
+    """Arguments for web search."""
+    query: str = Field(description="Search query")
+    region: str = Field(default="us-en", description="Search region (e.g., us-en, uk-en, ru-ru)")
+    safesearch: str = Field(default="moderate", description="Safe search level: on, moderate, off")
+    timelimit: Optional[str] = Field(default=None, description="Time limit: d(day), w(week), m(month), y(year)")
+    max_results: int = Field(default=10, description="Maximum number of results to return")
+    page: int = Field(default=1, description="Page number for results")
+
+
+class NewsSearchArgs(BaseModel):
+    """Arguments for news search."""
+    query: str = Field(description="News search query")
+    region: str = Field(default="us-en", description="Search region")
+    safesearch: str = Field(default="moderate", description="Safe search level")
+    timelimit: Optional[str] = Field(default=None, description="Time limit for news")
+    max_results: int = Field(default=10, description="Maximum number of news results")
+
+
+class ImageSearchArgs(BaseModel):
+    """Arguments for image search."""
+    query: str = Field(description="Image search query")
+    region: str = Field(default="us-en", description="Search region")
+    safesearch: str = Field(default="moderate", description="Safe search level")
+    size: Optional[str] = Field(default=None, description="Image size filter: Small, Medium, Large, Wallpaper")
+    color: Optional[str] = Field(default=None, description="Color filter: color, Monochrome, Red, Orange, etc.")
+    type_image: Optional[str] = Field(default=None, description="Image type: photo, clipart, gif, transparent, line")
+    layout: Optional[str] = Field(default=None, description="Layout: Square, Tall, Wide")
+    license_image: Optional[str] = Field(default=None, description="License: any, Public, Share, ShareCommercially, Modify")
+    max_results: int = Field(default=10, description="Maximum number of image results")
+
+
+class VideoSearchArgs(BaseModel):
+    """Arguments for video search."""
+    query: str = Field(description="Video search query")
+    region: str = Field(default="us-en", description="Search region")
+    safesearch: str = Field(default="moderate", description="Safe search level")
+    timelimit: Optional[str] = Field(default=None, description="Time limit for videos")
+    resolution: Optional[str] = Field(default=None, description="Video resolution: high, standard")
+    duration: Optional[str] = Field(default=None, description="Video duration: short, medium, long")
+    license_videos: Optional[str] = Field(default=None, description="Video license filter")
+    max_results: int = Field(default=10, description="Maximum number of video results")
+
+
+class DuckDuckGoToolkit(AbstractToolkit):
+    """
+    DuckDuckGo Search Toolkit providing comprehensive search capabilities.
+
+    This toolkit uses the ddgs library directly for improved performance and reliability,
+    with built-in backoff retry mechanisms for handling rate limits.
+    """
+
+    def __init__(self, **kwargs):
+        """Initialize the DuckDuckGo toolkit."""
+        super().__init__(**kwargs)
+        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+
+        # Backoff configuration
+        self.max_retries = kwargs.get('max_retries', 3)
+        self.backoff_factor = kwargs.get('backoff_factor', 2.0)
+        self.max_wait_time = kwargs.get('max_wait_time', 60.0)
+
+    def _get_backoff_decorator(self):
+        """Get the backoff decorator for retry logic."""
+        return backoff.on_exception(
+            backoff.expo,
+            (RatelimitException, TimeoutException, DDGSException),
+            max_tries=self.max_retries,
+            factor=self.backoff_factor,
+            max_time=self.max_wait_time,
+            logger=self.logger
+        )
+
+    async def web_search(
+        self,
+        query: str,
+        region: str = "us-en",
+        safesearch: str = "moderate",
+        timelimit: Optional[str] = None,
+        max_results: int = 10,
+        page: int = 1
+    ) -> ToolResult:
+        """
+        Search the web using DuckDuckGo.
+
+        Args:
+            query: Search query
+            region: Search region (e.g., us-en, uk-en, ru-ru)
+            safesearch: Safe search level (on, moderate, off)
+            timelimit: Time limit (d, w, m, y)
+            max_results: Maximum number of results
+            page: Page number for results
+
+        Returns:
+            ToolResult containing search results
+        """
+        try:
+            # Create backoff-wrapped search function
+            @self._get_backoff_decorator()
+            def _search():
+                ddgs = DDGS()
+                return ddgs.text(
+                    query=query,
+                    region=region,
+                    safesearch=safesearch,
+                    timelimit=timelimit,
+                    max_results=max_results,
+                    page=page,
+                    backend="auto"
+                )
+
+            # Execute search in thread pool to avoid blocking
+            loop = asyncio.get_event_loop()
+            results = await loop.run_in_executor(None, _search)
+
+            return ToolResult(
+                status="success",
+                result={
+                    "query": query,
+                    "total_results": len(results),
+                    "results": results,
+                    "search_type": "web"
+                },
+                metadata={
+                    "region": region,
+                    "safesearch": safesearch,
+                    "timelimit": timelimit,
+                    "page": page
+                }
+            )
+
+        except Exception as e:
+            self.logger.error(f"Web search failed for query '{query}': {str(e)}")
+            return ToolResult(
+                status="error",
+                result=[],
+                error=f"Search failed: {str(e)}",
+                metadata={"query": query}
+            )
+
+    async def news_search(
+        self,
+        query: str,
+        region: str = "us-en",
+        safesearch: str = "moderate",
+        timelimit: Optional[str] = None,
+        max_results: int = 10
+    ) -> ToolResult:
+        """
+        Search for news using DuckDuckGo.
+
+        Args:
+            query: News search query
+            region: Search region
+            safesearch: Safe search level
+            timelimit: Time limit for news
+            max_results: Maximum number of results
+
+        Returns:
+            ToolResult containing news results
+        """
+        try:
+            @self._get_backoff_decorator()
+            def _search():
+                ddgs = DDGS()
+                return ddgs.news(
+                    query=query,
+                    region=region,
+                    safesearch=safesearch,
+                    timelimit=timelimit,
+                    max_results=max_results
+                )
+
+            loop = asyncio.get_event_loop()
+            results = await loop.run_in_executor(None, _search)
+
+            return ToolResult(
+                status="success",
+                result={
+                    "query": query,
+                    "total_results": len(results),
+                    "results": results,
+                    "search_type": "news"
+                },
+                metadata={
+                    "region": region,
+                    "safesearch": safesearch,
+                    "timelimit": timelimit
+                }
+            )
+
+        except Exception as e:
+            self.logger.error(f"News search failed for query '{query}': {str(e)}")
+            return ToolResult(
+                status="error",
+                result=[],
+                error=f"News search failed: {str(e)}",
+                metadata={"query": query}
+            )
+
+    async def image_search(
+        self,
+        query: str,
+        region: str = "us-en",
+        safesearch: str = "moderate",
+        size: Optional[str] = None,
+        color: Optional[str] = None,
+        type_image: Optional[str] = None,
+        layout: Optional[str] = None,
+        license_image: Optional[str] = None,
+        max_results: int = 10
+    ) -> ToolResult:
+        """
+        Search for images using DuckDuckGo.
+
+        Args:
+            query: Image search query
+            region: Search region
+            safesearch: Safe search level
+            size: Image size filter
+            color: Color filter
+            type_image: Image type filter
+            layout: Layout filter
+            license_image: License filter
+            max_results: Maximum number of results
+
+        Returns:
+            ToolResult containing image results
+        """
+        try:
+            @self._get_backoff_decorator()
+            def _search():
+                ddgs = DDGS()
+                return ddgs.images(
+                    query=query,
+                    region=region,
+                    safesearch=safesearch,
+                    size=size,
+                    color=color,
+                    type_image=type_image,
+                    layout=layout,
+                    license_image=license_image,
+                    max_results=max_results
+                )
+
+            loop = asyncio.get_event_loop()
+            results = await loop.run_in_executor(None, _search)
+
+            return ToolResult(
+                status="success",
+                result={
+                    "query": query,
+                    "total_results": len(results),
+                    "results": results,
+                    "search_type": "images"
+                },
+                metadata={
+                    "region": region,
+                    "safesearch": safesearch,
+                    "size": size,
+                    "color": color,
+                    "type_image": type_image,
+                    "layout": layout,
+                    "license_image": license_image
+                }
+            )
+
+        except Exception as e:
+            self.logger.error(f"Image search failed for query '{query}': {str(e)}")
+            return ToolResult(
+                status="error",
+                result=[],
+                error=f"Image search failed: {str(e)}",
+                metadata={"query": query}
+            )
+
+    async def video_search(
+        self,
+        query: str,
+        region: str = "us-en",
+        safesearch: str = "moderate",
+        timelimit: Optional[str] = None,
+        resolution: Optional[str] = None,
+        duration: Optional[str] = None,
+        license_videos: Optional[str] = None,
+        max_results: int = 10
+    ) -> ToolResult:
+        """
+        Search for videos using DuckDuckGo.
+
+        Args:
+            query: Video search query
+            region: Search region
+            safesearch: Safe search level
+            timelimit: Time limit for videos
+            resolution: Video resolution filter
+            duration: Video duration filter
+            license_videos: Video license filter
+            max_results: Maximum number of results
+
+        Returns:
+            ToolResult containing video results
+        """
+        try:
+            @self._get_backoff_decorator()
+            def _search():
+                ddgs = DDGS()
+                return ddgs.videos(
+                    query=query,
+                    region=region,
+                    safesearch=safesearch,
+                    timelimit=timelimit,
+                    resolution=resolution,
+                    duration=duration,
+                    license_videos=license_videos,
+                    max_results=max_results
+                )
+
+            loop = asyncio.get_event_loop()
+            results = await loop.run_in_executor(None, _search)
+
+            return ToolResult(
+                status="success",
+                result={
+                    "query": query,
+                    "total_results": len(results),
+                    "results": results,
+                    "search_type": "videos"
+                },
+                metadata={
+                    "region": region,
+                    "safesearch": safesearch,
+                    "timelimit": timelimit,
+                    "resolution": resolution,
+                    "duration": duration,
+                    "license_videos": license_videos
+                }
+            )
+
+        except Exception as e:
+            self.logger.error(f"Video search failed for query '{query}': {str(e)}")
+            return ToolResult(
+                status="error",
+                result=[],
+                error=f"Video search failed: {str(e)}",
+                metadata={"query": query}
+            )

parrot/tools/decorators.py

@@ -0,0 +1,271 @@
+from typing import Callable, Optional, Dict, Any, Type, Union, get_args, get_origin, get_type_hints
+from functools import wraps
+import inspect
+import re
+from enum import Enum
+from pydantic import BaseModel
+
+
+# Decorator for custom argument schemas
+def tool_schema(schema: Type[BaseModel], description: Optional[str] = None):
+    """
+    Decorator to specify a custom argument schema for a toolkit method.
+
+    Usage:
+        @tool_schema(MyCustomSchema)
+        async def my_tool(self, arg1: str, arg2: int) -> str:
+            '''My custom tool.'''
+            return result
+    """
+    def decorator(func):
+        # print(f"Decorating {func.__name__} with {schema}")
+        func._args_schema = schema
+        func._tool_description = description or func.__doc__ or f"Tool: {func.__name__}"
+        return func
+    return decorator
+
+
+def tool(
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    schema: Optional[Dict[str, Any]] = None,
+    auto_register: bool = False
+):
+    """
+    Decorator to mark a function as a tool with automatic schema generation.
+
+    Automatically extracts:
+    - Name from function name (or use custom name)
+    - Description from docstring (or use custom description)
+    - Input schema from type hints (or use custom schema)
+
+    Args:
+        name: Optional custom tool name (defaults to function name)
+        description: Optional custom description (defaults to docstring)
+        schema: Optional custom input schema (auto-generated from type hints if not provided)
+        auto_register: If True, automatically register with active client/bot
+
+    Usage:
+        @tool()
+        def get_weather(location: str) -> str:
+            '''Get weather for a location.'''
+            return f"Weather in {location}"
+
+        @tool(name="custom_name", description="Custom description")
+        def my_function(param: int) -> str:
+            return str(param)
+    """
+    def decorator(func: Callable) -> Callable:
+        # Extract metadata
+        tool_name = name or func.__name__
+        tool_description = description or _extract_description(func)
+
+        # Generate schema from type hints if not provided
+        if schema is None:
+            tool_schema = _generate_schema_from_function(func)
+        else:
+            tool_schema = schema
+
+        # Store metadata on the function
+        func._tool_metadata = {
+            'name': tool_name,
+            'description': tool_description,
+            'schema': tool_schema,
+            'function': func,
+            'auto_register': auto_register
+        }
+
+        # Mark as a tool
+        func._is_tool = True
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # Preserve metadata on wrapper
+        wrapper._tool_metadata = func._tool_metadata
+        wrapper._is_tool = True
+
+        return wrapper
+
+    return decorator
+
+def _extract_description(func: Callable) -> str:
+    """
+    Extract description from function docstring.
+    Takes the first line or paragraph of the docstring.
+    """
+    if not func.__doc__:
+        return f"Tool: {func.__name__}"
+
+    # Get first line or first paragraph
+    docstring = func.__doc__.strip()
+
+    # Split by newlines and get first non-empty line
+    lines = [line.strip() for line in docstring.split('\n')]
+    non_empty = [line for line in lines if line]
+
+    if non_empty:
+        return non_empty[0]
+
+    return f"Tool: {func.__name__}"
+
+
+def _generate_schema_from_function(func: Callable) -> Dict[str, Any]:
+    """
+    Generate JSON schema from function signature and type hints.
+
+    Args:
+        func: The function to generate schema for
+
+    Returns:
+        JSON schema dictionary
+    """
+    sig = inspect.signature(func)
+
+    # Get type hints
+    try:
+        type_hints = get_type_hints(func)
+    except Exception:
+        # If get_type_hints fails, fall back to annotations
+        type_hints = func.__annotations__ or {}
+
+    properties = {}
+    required = []
+
+    for param_name, param in sig.parameters.items():
+        # Skip self and cls
+        if param_name in ('self', 'cls'):
+            continue
+
+        # Get type hint (default to string if not specified)
+        param_type = type_hints.get(param_name, str)
+
+        # Convert Python types to JSON schema types
+        json_type = _python_type_to_json_type(param_type)
+
+        # Get description from docstring if available
+        param_description = _extract_param_description(func, param_name)
+
+        # Build property definition
+        if isinstance(json_type, dict):
+            # Complex type (List, Optional, Union, etc.)
+            prop_def = json_type.copy()
+            if param_description:
+                prop_def['description'] = param_description
+            else:
+                prop_def['description'] = f"The {param_name} parameter"
+        else:
+            # Simple type
+            prop_def = {
+                'type': json_type,
+                'description': param_description or f"The {param_name} parameter"
+            }
+
+        properties[param_name] = prop_def
+
+        # Check if parameter is required (no default value)
+        if param.default == inspect.Parameter.empty:
+            required.append(param_name)
+
+    return {
+        'type': 'object',
+        'properties': properties,
+        'required': required
+    }
+
+def _extract_param_description(func: Callable, param_name: str) -> Optional[str]:
+    """
+    Extract parameter description from docstring.
+    Looks for Google, NumPy, or Sphinx style docstrings.
+    """
+    if not func.__doc__:
+        return None
+
+    docstring = func.__doc__
+
+    # Google style: Args: section
+    google_pattern = rf'{param_name}\s*:\s*(.+?)(?:\n|$)'
+    match = re.search(google_pattern, docstring)
+    if match:
+        return match.group(1).strip()
+
+    # Sphinx style: :param name: description
+    sphinx_pattern = rf':param\s+{param_name}\s*:\s*(.+?)(?:\n|$)'
+    match = re.search(sphinx_pattern, docstring)
+    if match:
+        return match.group(1).strip()
+
+    return None
+
+
+def _python_type_to_json_type(python_type: Any) -> Union[str, Dict[str, Any]]:
+    """
+    Convert Python type hints to JSON schema types.
+
+    Handles:
+    - Basic types (str, int, float, bool)
+    - Optional types
+    - List types
+    - Dict types
+    - Union types
+    - Enum types
+    """
+    # Handle None type
+    if python_type is type(None):
+        return "null"
+
+    # Get origin for generic types (List, Dict, Optional, etc.)
+    origin = get_origin(python_type)
+
+    # Handle Optional[T] -> Union[T, None]
+    if origin is Union:
+        args = get_args(python_type)
+        # Check if it's Optional (Union with None)
+        if type(None) in args:
+            # It's Optional, get the non-None type
+            non_none_types = [t for t in args if t is not type(None)]
+            if len(non_none_types) == 1:
+                # Optional[T] - return the type with nullable
+                base_type = _python_type_to_json_type(non_none_types[0])
+                if isinstance(base_type, dict):
+                    return base_type
+                return {"type": [base_type, "null"]}
+        # Regular Union - return anyOf
+        return {
+            "anyOf": [_python_type_to_json_type(t) for t in args]
+        }
+
+    # Handle List[T]
+    if origin is list or python_type is list:
+        args = get_args(python_type)
+        if args:
+            item_type = _python_type_to_json_type(args[0])
+            return {
+                "type": "array",
+                "items": {"type": item_type} if isinstance(item_type, str) else item_type
+            }
+        return "array"
+
+    # Handle Dict[K, V]
+    if origin is dict or python_type is dict:
+        return "object"
+
+    # Handle Enum
+    if inspect.isclass(python_type) and issubclass(python_type, Enum):
+        return {
+            "type": "string",
+            "enum": [e.value for e in python_type]
+        }
+
+    # Basic types
+    type_mapping = {
+        str: "string",
+        int: "integer",
+        float: "number",
+        bool: "boolean",
+        list: "array",
+        dict: "object",
+    }
+
+    return type_mapping.get(python_type, "string")