churnkit 0.75.0a1__py3-none-any.whl

customer_retention/stages/features/interaction_features.py

@@ -0,0 +1,160 @@
+"""
+Interaction feature generation for customer retention analysis.
+
+This module provides feature combinations and ratio calculations
+from existing features.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+import numpy as np
+
+from customer_retention.core.compat import DataFrame, Series
+
+
+@dataclass
+class InteractionFeatureResult:
+    """Result of interaction feature generation."""
+    df: DataFrame
+    generated_features: List[str]
+    skipped_combinations: List[str] = field(default_factory=list)
+
+
+class InteractionFeatureGenerator:
+    """
+    Generates interaction features from combinations of existing features.
+
+    Interaction features are derived by combining two or more features
+    using mathematical operations (multiply, divide, add, subtract).
+
+    Parameters
+    ----------
+    combinations : List[Tuple[str, str, str, str]], optional
+        List of feature combinations to create.
+        Each tuple contains (col1, col2, output_name, operation).
+        Supported operations: "multiply", "divide", "add", "subtract"
+    ratios : List[Tuple[str, str, str]], optional
+        List of ratio features to create.
+        Each tuple contains (numerator, denominator, output_name).
+
+    Attributes
+    ----------
+    generated_features : List[str]
+        Names of features generated during last transform.
+    """
+
+    def __init__(
+        self,
+        combinations: Optional[List[Tuple[str, str, str, str]]] = None,
+        ratios: Optional[List[Tuple[str, str, str]]] = None,
+    ):
+        self.combinations = combinations or []
+        self.ratios = ratios or []
+        self.generated_features: List[str] = []
+        self._is_fitted = False
+
+    def fit(self, df: DataFrame) -> "InteractionFeatureGenerator":
+        """
+        Fit the generator (validates columns exist).
+
+        Parameters
+        ----------
+        df : DataFrame
+            Input DataFrame.
+
+        Returns
+        -------
+        self
+        """
+        self._is_fitted = True
+        return self
+
+    def transform(self, df: DataFrame) -> DataFrame:
+        """
+        Generate interaction features for the input DataFrame.
+
+        Parameters
+        ----------
+        df : DataFrame
+            Input DataFrame.
+
+        Returns
+        -------
+        DataFrame
+            DataFrame with interaction features added.
+        """
+        if not self._is_fitted:
+            raise ValueError("Generator not fitted. Call fit() first.")
+
+        result = df.copy()
+        self.generated_features = []
+
+        # Process combinations
+        for combo in self.combinations:
+            col1, col2, output_name, operation = combo
+            if col1 in df.columns and col2 in df.columns:
+                result[output_name] = self._apply_operation(
+                    df[col1], df[col2], operation
+                )
+                self.generated_features.append(output_name)
+
+        # Process ratios
+        for ratio in self.ratios:
+            numerator, denominator, output_name = ratio
+            if numerator in df.columns and denominator in df.columns:
+                result[output_name] = self._safe_divide(
+                    df[numerator], df[denominator]
+                )
+                self.generated_features.append(output_name)
+
+        return result
+
+    def fit_transform(self, df: DataFrame) -> DataFrame:
+        """
+        Fit and transform in one step.
+
+        Parameters
+        ----------
+        df : DataFrame
+            Input DataFrame.
+
+        Returns
+        -------
+        DataFrame
+            DataFrame with interaction features added.
+        """
+        self.fit(df)
+        return self.transform(df)
+
+    def _apply_operation(
+        self,
+        col1: Series,
+        col2: Series,
+        operation: str
+    ) -> Series:
+        """Apply the specified operation to two columns."""
+        if operation == "multiply":
+            return col1 * col2
+        elif operation == "divide":
+            return self._safe_divide(col1, col2)
+        elif operation == "add":
+            return col1 + col2
+        elif operation == "subtract":
+            return col1 - col2
+        else:
+            raise ValueError(f"Unknown operation: {operation}")
+
+    def _safe_divide(
+        self,
+        numerator: Series,
+        denominator: Series
+    ) -> Series:
+        """
+        Safely divide two series, handling division by zero.
+
+        Returns NaN where denominator is zero or null.
+        """
+        # Replace zeros with NaN to avoid inf
+        safe_denominator = denominator.replace(0, np.nan)
+        return numerator / safe_denominator

customer_retention/stages/features/temporal_features.py

@@ -0,0 +1,243 @@
+"""
+Temporal feature generation for customer retention analysis.
+
+This module provides temporal feature calculations such as tenure,
+recency, activation time, and active period.
+"""
+
+import warnings
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional, Union
+
+from customer_retention.core.compat import DataFrame, Series, Timedelta, Timestamp, pd
+
+
+class ReferenceDateSource(Enum):
+    """Source for the reference date used in temporal calculations."""
+    CONFIG = "config"
+    MAX_DATE = "max_date"
+    COLUMN = "column"
+    FEATURE_TIMESTAMP = "feature_timestamp"
+
+
+@dataclass
+class TemporalFeatureResult:
+    """Result of temporal feature generation."""
+    df: DataFrame
+    reference_date: Union[Timestamp, Series]
+    generated_features: List[str]
+    warnings: List[str] = field(default_factory=list)
+
+
+class TemporalFeatureGenerator:
+    """
+    Generates temporal features from datetime columns.
+
+    Temporal features are calculated relative to a reference date, which can
+    be specified explicitly, derived from the data, or per-row from a column.
+
+    Parameters
+    ----------
+    reference_date : Timestamp, optional
+        Explicit reference date for calculations. Used when reference_date_source
+        is CONFIG.
+    reference_date_source : ReferenceDateSource, default CONFIG
+        How to determine the reference date:
+        - CONFIG: Use the explicit reference_date parameter
+        - MAX_DATE: Use the maximum date in date_column
+        - COLUMN: Use per-row dates from reference_date_column
+    reference_date_column : str, optional
+        Column name for per-row reference dates. Required when source is COLUMN.
+    date_column : str, optional
+        Column used to determine max date when source is MAX_DATE.
+    created_column : str, default "created"
+        Column containing customer account creation date.
+    first_order_column : str, optional
+        Column containing date of first order.
+    last_order_column : str, optional
+        Column containing date of last order.
+
+    Attributes
+    ----------
+    reference_date : Timestamp or Series
+        The reference date(s) used for calculations after fitting.
+    generated_features : List[str]
+        Names of features generated during last transform.
+    """
+
+    def __init__(
+        self,
+        reference_date: Optional[Timestamp] = None,
+        reference_date_source: ReferenceDateSource = ReferenceDateSource.CONFIG,
+        reference_date_column: Optional[str] = None,
+        date_column: Optional[str] = None,
+        created_column: str = "created",
+        first_order_column: Optional[str] = None,
+        last_order_column: Optional[str] = None,
+    ):
+        self._reference_date_param = reference_date
+        self.reference_date_source = reference_date_source
+        self.reference_date_column = reference_date_column
+        self.date_column = date_column
+        self.created_column = created_column
+        self.first_order_column = first_order_column
+        self.last_order_column = last_order_column
+
+        self.reference_date: Optional[Union[Timestamp, Series]] = None
+        self.generated_features: List[str] = []
+        self._is_fitted = False
+
+    def fit(self, df: DataFrame) -> "TemporalFeatureGenerator":
+        """
+        Fit the generator by determining the reference date.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            Input DataFrame containing datetime columns.
+
+        Returns
+        -------
+        self
+        """
+        self._determine_reference_date(df)
+        self._is_fitted = True
+        return self
+
+    def transform(self, df: DataFrame) -> DataFrame:
+        """
+        Generate temporal features for the input DataFrame.
+
+        Parameters
+        ----------
+        df : DataFrame
+            Input DataFrame containing datetime columns.
+
+        Returns
+        -------
+        DataFrame
+            DataFrame with temporal features added.
+        """
+        if not self._is_fitted:
+            raise ValueError("Generator not fitted. Call fit() first.")
+
+        result = df.copy()
+        self.generated_features = []
+        warnings_list = []
+
+        # Get reference date(s) for this transform
+        if self.reference_date_source in [ReferenceDateSource.COLUMN, ReferenceDateSource.FEATURE_TIMESTAMP]:
+            ref_dates = pd.to_datetime(df[self.reference_date_column], format='mixed')
+        else:
+            ref_dates = self.reference_date
+
+        # Tenure features
+        if self.created_column and self.created_column in df.columns:
+            created = pd.to_datetime(df[self.created_column], format='mixed')
+            tenure_days = self._compute_days_diff(ref_dates, created)
+            result["tenure_days"] = tenure_days
+            self.generated_features.append("tenure_days")
+
+            # Check for negative values
+            if (tenure_days < 0).any():
+                warnings.warn(
+                    "negative tenure_days detected. Reference date may be before "
+                    "some created dates.",
+                    UserWarning
+                )
+                warnings_list.append("negative_tenure_days")
+
+            # Account age in months
+            result["account_age_months"] = tenure_days / 30.44
+            self.generated_features.append("account_age_months")
+
+        # Recency features
+        if self.last_order_column and self.last_order_column in df.columns:
+            last_order = pd.to_datetime(df[self.last_order_column], format='mixed')
+            days_since_last = self._compute_days_diff(ref_dates, last_order)
+            result["days_since_last_order"] = days_since_last
+            self.generated_features.append("days_since_last_order")
+
+        # Activation features
+        if (self.first_order_column and self.first_order_column in df.columns and
+                self.created_column and self.created_column in df.columns):
+            created = pd.to_datetime(df[self.created_column], format='mixed')
+            first_order = pd.to_datetime(df[self.first_order_column], format='mixed')
+            days_to_first = self._compute_days_diff(first_order, created)
+            result["days_to_first_order"] = days_to_first
+            self.generated_features.append("days_to_first_order")
+
+        # Active period
+        if (self.first_order_column and self.first_order_column in df.columns and
+                self.last_order_column and self.last_order_column in df.columns):
+            first_order = pd.to_datetime(df[self.first_order_column], format='mixed')
+            last_order = pd.to_datetime(df[self.last_order_column], format='mixed')
+            active_period = self._compute_days_diff(last_order, first_order)
+            result["active_period_days"] = active_period
+            self.generated_features.append("active_period_days")
+
+        return result
+
+    def fit_transform(self, df: DataFrame) -> DataFrame:
+        """
+        Fit and transform in one step.
+
+        Parameters
+        ----------
+        df : DataFrame
+            Input DataFrame containing datetime columns.
+
+        Returns
+        -------
+        DataFrame
+            DataFrame with temporal features added.
+        """
+        self.fit(df)
+        return self.transform(df)
+
+    def _determine_reference_date(self, df: DataFrame) -> None:
+        """Determine the reference date based on configuration."""
+        if self.reference_date_source == ReferenceDateSource.CONFIG:
+            if self._reference_date_param is None:
+                raise ValueError(
+                    "reference_date must be provided when source is CONFIG"
+                )
+            self.reference_date = self._reference_date_param
+
+        elif self.reference_date_source == ReferenceDateSource.MAX_DATE:
+            if self.date_column is None:
+                raise ValueError(
+                    "date_column must be provided when source is MAX_DATE"
+                )
+            self.reference_date = pd.to_datetime(df[self.date_column], format='mixed').max()
+
+        elif self.reference_date_source == ReferenceDateSource.COLUMN:
+            if self.reference_date_column is None:
+                raise ValueError(
+                    "reference_date_column must be provided when source is COLUMN"
+                )
+            self.reference_date = pd.to_datetime(df[self.reference_date_column], format='mixed')
+
+        elif self.reference_date_source == ReferenceDateSource.FEATURE_TIMESTAMP:
+            if "feature_timestamp" not in df.columns:
+                raise ValueError(
+                    "feature_timestamp column required when source is FEATURE_TIMESTAMP"
+                )
+            self.reference_date = pd.to_datetime(df["feature_timestamp"], format='mixed')
+            self.reference_date_column = "feature_timestamp"
+
+    def _compute_days_diff(
+        self,
+        later: Union[Timestamp, Series],
+        earlier: Union[Timestamp, Series]
+    ) -> Series:
+        """
+        Compute the difference in days between two dates.
+
+        Handles both scalar and Series inputs, preserving NaN values.
+        """
+        diff = later - earlier
+        if isinstance(diff, Timedelta):
+            return pd.Series([diff.days])
+        return diff.dt.days

customer_retention/stages/ingestion/__init__.py

@@ -0,0 +1,9 @@
+from .load_result import LoadResult
+from .loaders import CSVLoader, DataLoader, DeltaLoader, LoaderFactory, ParquetLoader
+from .source_registry import DataSourceRegistry
+
+__all__ = [
+    "LoadResult",
+    "DataLoader", "CSVLoader", "ParquetLoader", "DeltaLoader", "LoaderFactory",
+    "DataSourceRegistry"
+]

customer_retention/stages/ingestion/load_result.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel
+
+
+class LoadResult(BaseModel):
+    success: bool
+    row_count: int
+    column_count: int
+    duration_seconds: float
+    source_name: str
+    warnings: list[str] = []
+    errors: list[str] = []
+    schema_info: dict[str, str] = {}
+
+    def has_warnings(self) -> bool:
+        return len(self.warnings) > 0
+
+    def has_errors(self) -> bool:
+        return len(self.errors) > 0
+
+    def add_warning(self, message: str) -> None:
+        self.warnings.append(message)
+
+    def add_error(self, message: str) -> None:
+        self.errors.append(message)
+
+    def get_summary(self) -> str:
+        status = "SUCCESS" if self.success else "FAILED"
+        return (
+            f"{status}: {self.source_name} - "
+            f"{self.row_count} rows, {self.column_count} columns "
+            f"({self.duration_seconds:.2f}s)"
+        )

customer_retention/stages/ingestion/loaders.py

@@ -0,0 +1,195 @@
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+from customer_retention.core.compat import DataFrame, pd
+from customer_retention.core.config.source_config import DataSourceConfig, FileFormat, SourceType
+
+from .load_result import LoadResult
+
+
+class DataLoader(ABC):
+    @abstractmethod
+    def load(self, config: DataSourceConfig, spark_session: Optional[Any] = None,
+             sample_size: Optional[int] = None) -> tuple[DataFrame, LoadResult]:
+        pass
+
+    @abstractmethod
+    def validate_source(self, config: DataSourceConfig) -> list[str]:
+        pass
+
+    def create_load_result(self, config: DataSourceConfig, df: DataFrame,
+                          duration: float, success: bool = True) -> LoadResult:
+        return LoadResult(
+            success=success,
+            row_count=len(df),
+            column_count=len(df.columns),
+            duration_seconds=duration,
+            source_name=config.name,
+            schema_info={col: str(dtype) for col, dtype in df.dtypes.items()}
+        )
+
+    def apply_sample(self, df: DataFrame, sample_size: Optional[int]) -> DataFrame:
+        return df.head(sample_size) if sample_size else df
+
+
+class CSVLoader(DataLoader):
+    def validate_source(self, config: DataSourceConfig) -> list[str]:
+        errors = []
+        if not config.path:
+            errors.append("CSV source requires path")
+        if config.file_format != FileFormat.CSV:
+            errors.append(f"CSVLoader requires CSV format, got {config.file_format}")
+        return errors
+
+    def load(self, config: DataSourceConfig, spark_session: Optional[Any] = None,
+             sample_size: Optional[int] = None) -> tuple[DataFrame, LoadResult]:
+        start_time = time.time()
+        result = LoadResult(success=False, row_count=0, column_count=0,
+                           duration_seconds=0, source_name=config.name)
+
+        try:
+            validation_errors = self.validate_source(config)
+            if validation_errors:
+                result.errors.extend(validation_errors)
+                result.duration_seconds = time.time() - start_time
+                return pd.DataFrame(), result
+
+            read_kwargs = self.build_read_kwargs(config, sample_size)
+            df = pd.read_csv(config.path, **read_kwargs)
+
+            if sample_size and len(df) > sample_size:
+                df = df.head(sample_size)
+
+            duration = time.time() - start_time
+            result = self.create_load_result(config, df, duration)
+            return df, result
+
+        except Exception as e:
+            result.add_error(f"Failed to load CSV: {str(e)}")
+            result.duration_seconds = time.time() - start_time
+            return pd.DataFrame(), result
+
+    def build_read_kwargs(self, config: DataSourceConfig, sample_size: Optional[int]) -> dict:
+        kwargs = {
+            "delimiter": config.delimiter,
+            "header": 0 if config.header else None,
+            "quotechar": config.quote_char,
+            "encoding": config.encoding
+        }
+        if sample_size:
+            kwargs["nrows"] = sample_size
+        return kwargs
+
+
+class ParquetLoader(DataLoader):
+    def validate_source(self, config: DataSourceConfig) -> list[str]:
+        errors = []
+        if not config.path:
+            errors.append("Parquet source requires path")
+        if config.file_format != FileFormat.PARQUET:
+            errors.append(f"ParquetLoader requires PARQUET format, got {config.file_format}")
+        return errors
+
+    def load(self, config: DataSourceConfig, spark_session: Optional[Any] = None,
+             sample_size: Optional[int] = None) -> tuple[DataFrame, LoadResult]:
+        start_time = time.time()
+        result = LoadResult(success=False, row_count=0, column_count=0,
+                           duration_seconds=0, source_name=config.name)
+
+        try:
+            validation_errors = self.validate_source(config)
+            if validation_errors:
+                result.errors.extend(validation_errors)
+                result.duration_seconds = time.time() - start_time
+                return pd.DataFrame(), result
+
+            df = pd.read_parquet(config.path)
+            df = self.apply_sample(df, sample_size)
+
+            duration = time.time() - start_time
+            result = self.create_load_result(config, df, duration)
+            return df, result
+
+        except Exception as e:
+            result.add_error(f"Failed to load Parquet: {str(e)}")
+            result.duration_seconds = time.time() - start_time
+            return pd.DataFrame(), result
+
+
+class DeltaLoader(DataLoader):
+    def validate_source(self, config: DataSourceConfig) -> list[str]:
+        errors = []
+        if config.source_type == SourceType.BATCH_FILE and not config.path:
+            errors.append("Delta file source requires path")
+        if config.source_type == SourceType.BATCH_TABLE and not config.table:
+            errors.append("Delta table source requires table name")
+        if config.file_format != FileFormat.DELTA:
+            errors.append(f"DeltaLoader requires DELTA format, got {config.file_format}")
+        return errors
+
+    def load(self, config: DataSourceConfig, spark_session: Optional[Any] = None,
+             sample_size: Optional[int] = None) -> tuple[DataFrame, LoadResult]:
+        start_time = time.time()
+        result = LoadResult(success=False, row_count=0, column_count=0,
+                           duration_seconds=0, source_name=config.name)
+
+        try:
+            validation_errors = self.validate_source(config)
+            if validation_errors:
+                result.errors.extend(validation_errors)
+                result.duration_seconds = time.time() - start_time
+                return pd.DataFrame(), result
+
+            if not spark_session:
+                result.add_error("Delta loader requires Spark session")
+                result.duration_seconds = time.time() - start_time
+                return pd.DataFrame(), result
+
+            spark_df = self.load_spark_dataframe(config, spark_session, sample_size)
+            df = spark_df.toPandas()
+
+            duration = time.time() - start_time
+            result = self.create_load_result(config, df, duration)
+            return df, result
+
+        except Exception as e:
+            result.add_error(f"Failed to load Delta: {str(e)}")
+            result.duration_seconds = time.time() - start_time
+            return pd.DataFrame(), result
+
+    def load_spark_dataframe(self, config: DataSourceConfig, spark_session: Any,
+                            sample_size: Optional[int]) -> Any:
+        if config.source_type == SourceType.BATCH_FILE:
+            spark_df = spark_session.read.format("delta").load(config.path)
+        else:
+            table_name = config.get_full_table_name()
+            spark_df = spark_session.read.table(table_name)
+
+        if sample_size:
+            spark_df = spark_df.limit(sample_size)
+
+        return spark_df
+
+
+class LoaderFactory:
+    _loaders = {
+        FileFormat.CSV: CSVLoader,
+        FileFormat.PARQUET: ParquetLoader,
+        FileFormat.DELTA: DeltaLoader
+    }
+
+    @classmethod
+    def get_loader(cls, config: DataSourceConfig) -> DataLoader:
+        if not config.file_format:
+            raise ValueError(f"file_format required to determine loader for {config.name}")
+
+        loader_class = cls._loaders.get(config.file_format)
+        if not loader_class:
+            raise ValueError(f"No loader available for format: {config.file_format}")
+
+        return loader_class()
+
+    @classmethod
+    def register_loader(cls, file_format: FileFormat, loader_class: type[DataLoader]) -> None:
+        cls._loaders[file_format] = loader_class