"""
Base handler interface for search APIs.
All specific API handlers should inherit from this base class.
"""

from abc import ABC, abstractmethod
from typing import Dict, List, Any, Optional


class BaseSearchHandler(ABC):
    """Base class for all search API handlers."""

    @abstractmethod
    def search(self, query: str, num_results: int = 10, **kwargs) -> List[Dict[str, Any]]:
        """
        Execute a search query and return results.

        Args:
            query: The search query to execute
            num_results: Number of results to return
            **kwargs: Additional search parameters specific to the API

        Returns:
            List of search results, each as a dictionary with at least:
                - title: Title of the result
                - url: URL of the result
                - snippet: Text snippet or description
                - source: Source of the result (e.g., "google", "scholar")
        """
        pass

    @abstractmethod
    def get_name(self) -> str:
        """
        Get the name of the search handler.

        Returns:
            Name of the search handler (e.g., "google", "scholar")
        """
        pass

    @abstractmethod
    def is_available(self) -> bool:
        """
        Check if the search API is available and properly configured.

        Returns:
            True if the API is available, False otherwise
        """
        pass

    @abstractmethod
    def get_rate_limit_info(self) -> Dict[str, Any]:
        """
        Get information about the API's rate limits.

        Returns:
            Dictionary with rate limit information:
                - requests_per_minute: Maximum requests per minute
                - requests_per_day: Maximum requests per day
                - current_usage: Current usage statistics if available
        """
        pass