"""
Interface for data processing services.

Defines the contract for data processing operations including CBF mapping,
dataset loading, and data transformation for both generated and ad-hoc uploads.
"""

from abc import ABC, abstractmethod
from typing import List, Tuple
from pathlib import Path
import polars as pl
from ..models import ProcessingResult, CBFProcessingConfig


class DataProcessingServiceInterface(ABC):
    """
    Interface for data processing operations.
    
    Handles data transformation, CBF mapping, and validation for both
    generated datasets and ad-hoc CSV uploads.
    """
    
    @abstractmethod
    def process_generated_dataset(self, df: pl.DataFrame) -> ProcessingResult:
        """
        Process generated dataset with CBF mapping.
        
        Generated datasets from the pipeline are already properly formatted
        and validated, so they only need CBF mapping and API formatting.
        
        Args:
            df: Generated dataset DataFrame
            
        Returns:
            ProcessingResult with processed data and metadata
        """
        pass
    
    @abstractmethod
    def process_adhoc_dataset(
        self,
        df: pl.DataFrame,
        user_mapping: List[Tuple[str, str]]
    ) -> ProcessingResult:
        """
        Process ad-hoc dataset with sanitization and user mapping.
        
        Ad-hoc datasets require sanitization to clean dirty user data
        before CBF mapping and validation.
        
        Args:
            df: Raw ad-hoc dataset DataFrame
            user_mapping: List of (source_column, target_column) tuples
            
        Returns:
            ProcessingResult with processed and sanitized data
        """
        pass
    
    @abstractmethod
    def load_dataset_from_s3(
        self,
        dataset_name: str,
        provider: str, 
        month: str,
        stage: str
    ) -> pl.DataFrame:
        """
        Load dataset chunk from S3.
        
        Args:
            dataset_name: Name of the dataset
            provider: Provider name (AWS, Azure, GCP)
            month: Month in YYYY-MM format
            stage: Processing stage (usage, metadata, etc.)
            
        Returns:
            DataFrame loaded from S3
        """
        pass
    
    @abstractmethod
    def load_adhoc_dataset_from_csv(self, csv_path: Path) -> pl.DataFrame:
        """
        Load ad-hoc dataset from CSV file.
        
        Args:
            csv_path: Path to CSV file
            
        Returns:
            DataFrame loaded from CSV
        """
        pass
    
    @abstractmethod
    def load_user_mapping(self, mapping_path: Path) -> List[Tuple[str, str]]:
        """
        Load user-defined column mapping from file.
        
        Args:
            mapping_path: Path to mapping file
            
        Returns:
            List of (source_column, target_column) tuples
        """
        pass
    
    @abstractmethod
    def validate_source_columns(
        self,
        df: pl.DataFrame,
        cbf_config: CBFProcessingConfig
    ) -> List[str]:
        """
        Validate that source DataFrame has required columns.
        
        Args:
            df: Source DataFrame to validate
            cbf_config: CBF processing configuration
            
        Returns:
            List of missing required columns
        """
        pass
    
    @abstractmethod
    def get_required_source_columns(self, cbf_config: CBFProcessingConfig) -> List[str]:
        """
        Get the source columns required for CBF mapping.
        
        Args:
            cbf_config: CBF processing configuration
            
        Returns:
            List of required source column names
        """
        pass