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:
        """Return precise, structured instructions for LLM tool calling."""
        instructions = """
<internet_search_tools_instructions>
Web search via SearxNG (ranked results; optional limited content fetch)

GOAL
- Search the web via SearxNG and return ranked results as JSON.

OUTPUT
- Always returns a JSON string encoding a list of results.
- Each result includes: title, url, summary, category.
- Optional fields by category:
  - images: thumbnail/img_src/width/height
  - videos: thumbnail/duration/publishedDate
  - news: publishedDate/source
  - files: file_type/content_type
  - content: only if enable_content_fetching=True

TOOLS
- perform_web_search(query, max_results=None)
- perform_news_search(query, max_results=None)
- perform_image_search(query, max_results=None)
- perform_video_search(query, max_results=None)
- perform_category_search(query, category, max_results=None)
  categories: general|news|images|videos|music|files|science|social

LIMITS / CONTEXT-SIZE RULES (IMPORTANT)
- query is trimmed and truncated to 500 chars.
- Keep max_results small (5–10) unless the user asks; internal clamping applies.
- Content fetching is OFF by default and expensive/large:
  - enabled only for general/news/files
  - fetches at most the first 3 results
- Do NOT paste large raw page/PDF content into the final answer; summarize.

ERRORS
- SearxngSearchError: invalid category / request failures
- SearxngContentError, FileDownloadError: content fetching or file processing

</internet_search_tools_instructions>
"""
        return instructions