"""
Core interfaces for MusicBrainz Data Cleaner.
Defines the common protocol that all data access implementations must follow.
"""

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


class MusicBrainzDataProvider(ABC):
    """
    Abstract base class defining the interface for MusicBrainz data access.
    Both database and API implementations must implement these methods.
    """
    
    @abstractmethod
    def test_connection(self) -> bool:
        """Test connection to the data source."""
        pass
    
    @abstractmethod
    def fuzzy_search_artist(self, artist_name: str) -> Optional[Tuple[str, str, float]]:
        """
        Fuzzy search for artist by name.
        Returns (artist_name, mbid, similarity_score) or None.
        """
        pass
    
    @abstractmethod
    def fuzzy_search_recording(self, title: str, artist_mbid: Optional[str] = None) -> Optional[Tuple[str, str, float]]:
        """
        Fuzzy search for recording by title and optionally artist.
        Returns (recording_name, mbid, similarity_score) or None.
        """
        pass
    
    @abstractmethod
    def get_artist_info(self, mbid: str) -> Optional[Dict[str, Any]]:
        """Get detailed artist information by MBID."""
        pass
    
    @abstractmethod
    def get_recording_info(self, mbid: str) -> Optional[Dict[str, Any]]:
        """Get detailed recording information by MBID."""
        pass


class SongProcessorInterface(ABC):
    """
    Abstract base class defining the interface for song processing.
    This ensures consistent behavior across different implementations.
    """
    
    @abstractmethod
    def clean_song(self, song: Dict[str, Any]) -> Tuple[Dict[str, Any], bool]:
        """
        Clean a single song.
        Returns (cleaned_song, success_status)
        """
        pass 