Search Tools

def perform_web_search(self, query: str, max_results: Optional[int] = None) -> str:
    """
    Perform a web search using SearxNG.

    Args:
        query: Search query string
        max_results: Maximum number of results (overrides default)

    Returns:
        JSON string containing search results

    Raises:
        SearxngSearchError: If search fails
    """
    return self._search(query, category="general", max_results=max_results)

def perform_news_search(self, query: str, max_results: Optional[int] = None) -> str:
    """
    Perform a news search using SearxNG.

    Args:
        query: Search query string
        max_results: Maximum number of results (overrides default)

    Returns:
        JSON string containing news search results

    Raises:
        SearxngSearchError: If search fails
    """
    return self._search(query, category="news", max_results=max_results)

def perform_image_search(self, query: str, max_results: Optional[int] = None) -> str:
    """
    Perform an image search using SearxNG.

    Args:
        query: Search query string
        max_results: Maximum number of results (overrides default)

    Returns:
        JSON string containing image search results

    Raises:
        SearxngSearchError: If search fails
    """
    return self._search(query, category="images", max_results=max_results)

def perform_video_search(self, query: str, max_results: Optional[int] = None) -> str:
    """
    Perform a video search using SearxNG.

    Args:
        query: Search query string
        max_results: Maximum number of results (overrides default)

    Returns:
        JSON string containing video search results

    Raises:
        SearxngSearchError: If search fails
    """
    return self._search(query, category="videos", max_results=max_results)

def perform_category_search(
    self, query: str, category: str, max_results: Optional[int] = None
) -> str:
    """
    Perform a search in a specific category using SearxNG.

    Args:
        query: Search query string
        category: Search category (general, news, images, videos, etc.)
        max_results: Maximum number of results (overrides default)

    Returns:
        JSON string containing search results

    Raises:
        SearxngSearchError: If search fails or category is invalid
    """
    if category not in self.SUPPORTED_CATEGORIES:
        available_categories = ", ".join(self.SUPPORTED_CATEGORIES.keys())
        raise SearxngSearchError(
            f"Unsupported category '{category}'. Available categories: {available_categories}"
        )

    return self._search(query, category=category, max_results=max_results)

    @staticmethod
    def get_llm_usage_instructions() -> str:
        """
        Returns a set of detailed instructions for LLMs on how to use each tool in EnhancedSearxngTools.
        Each instruction includes the method name, description, parameters, types, and example values.
        """
        instructions = """
<internet_search_tools_instructions>
*** Web Search Tools Instructions using SearxNG ***

These tools enable you to perform various web searches and manage the results. They provide accurate, real-time information with improved file handling capabilities.

**General Instructions:**
- All methods return a dictionary with 'results' (list) and 'status' (str) keys.
- Each result is a dictionary containing relevant data based on the search type.
- The 'file_type' field will be present if supported file types are detected in URLs.
- If errors occur, an error message will be returned under the 'error' key.

### Functions Tools

1. **perform_web_search**: Perform a web search.
   - Parameters:
     - `query` (str): Search term or phrase, e.g., "climate change impacts".
     - `max_results` (int, optional): Maximum results to return (default: 5, range: 1-30).
   - *Example:* `perform_web_search("python best practices", max_results=7)`

2. **perform_news_search**: Perform a news search.
   - Parameters:
     - `query` (str): Search term or phrase, e.g., "AI in healthcare".
     - `max_results` (int, optional): Maximum results to return (default: 5, range: 1-30).
   - *Example:* `perform_news_search("space exploration", max_results=5)`

3. **perform_image_search**: Perform an image search.
   - Parameters:
     - `query` (str): Search term or phrase, e.g., "coffee shop interior".
     - `max_results` (int, optional): Maximum results to return (default: 5, range: 1-30).
   - *Example:* `perform_image_search("dog breeds")`

4. **perform_video_search**: Perform a video search.
   - Parameters:
     - `query` (str): Search term or phrase, e.g., "language learning".
     - `max_results` (int, optional): Maximum results to return (default: 5, range: 1-30).
   - *Example:* `perform_video_search("language learning", max_results=8)`

5. **perform_category_search**: Search within a specific category.
   - Parameters:
     - `query` (str): Search term or phrase, e.g., "quantum computing advancements".
     - `category` (str): One of: general, news, images, videos, music, files, science, social, or it.
     - `max_results` (int, optional): Maximum results to return (default: 5, range: 1-30).
   - *Example:* `perform_category_search("cybersecurity trends", category="it")`

**File Processing Features:**
- Automatically detects PDF, TXT, and Markdown files in search results.
- Extracts readable content from PDFs using MarkItDown.
- Preserves formatting when downloading Markdown files.
- Handles TXT file downloads with proper encoding detection.

**Configuration Options:**
- Max file download size (default: 50MB)
- Download timeout protection
- Enable/disable URL content fetching and file downloads

**Additional Notes:**
- Ensure the category parameter in `perform_category_search` matches one of the accepted values.
- File processing is automatically applied when supported file types are detected in URLs.

**Error Handling:**
If any errors occur during execution (e.g., invalid parameters, connectivity issues), appropriate error messages will be returned under the 'error' key to guide troubleshooting.

</internet_search_tools_instructions>
"""
        return instructions