churnkit 0.75.0a1__py3-none-any.whl

customer_retention/stages/modeling/feature_scaler.py

@@ -0,0 +1,99 @@
+"""Feature scaling for model training."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from sklearn.preprocessing import MinMaxScaler, RobustScaler, StandardScaler
+
+from customer_retention.core.compat import DataFrame
+
+
+class ScalerType(Enum):
+    STANDARD = "standard"
+    ROBUST = "robust"
+    MINMAX = "minmax"
+    NONE = "none"
+
+
+@dataclass
+class ScalingResult:
+    scaler: Optional[Any]
+    X_train_scaled: DataFrame
+    X_test_scaled: DataFrame
+    scaling_params: Dict[str, Any]
+
+
+class FeatureScaler:
+    def __init__(
+        self,
+        scaler_type: ScalerType = ScalerType.ROBUST,
+        fit_on_train_only: bool = True,
+        save_scaler: bool = True,
+    ):
+        self.scaler_type = scaler_type
+        self.fit_on_train_only = fit_on_train_only
+        self.save_scaler = save_scaler
+        self._scaler = None
+        self._feature_names = None
+
+    def fit_transform(
+        self,
+        X_train: DataFrame,
+        X_test: DataFrame,
+    ) -> ScalingResult:
+        self._feature_names = list(X_train.columns)
+
+        if self.scaler_type == ScalerType.NONE:
+            return ScalingResult(
+                scaler=None,
+                X_train_scaled=X_train,
+                X_test_scaled=X_test,
+                scaling_params={},
+            )
+
+        self._scaler = self._create_scaler()
+        X_train_scaled = self._scaler.fit_transform(X_train)
+        X_test_scaled = self._scaler.transform(X_test)
+
+        scaling_params = self._extract_params()
+
+        return ScalingResult(
+            scaler=self._scaler if self.save_scaler else None,
+            X_train_scaled=DataFrame(X_train_scaled, columns=self._feature_names, index=X_train.index),
+            X_test_scaled=DataFrame(X_test_scaled, columns=self._feature_names, index=X_test.index),
+            scaling_params=scaling_params,
+        )
+
+    def transform(self, X: DataFrame) -> DataFrame:
+        if self._scaler is None:
+            return X
+        X_scaled = self._scaler.transform(X)
+        return DataFrame(X_scaled, columns=self._feature_names, index=X.index)
+
+    def _create_scaler(self):
+        if self.scaler_type == ScalerType.STANDARD:
+            return StandardScaler()
+        if self.scaler_type == ScalerType.ROBUST:
+            return RobustScaler()
+        if self.scaler_type == ScalerType.MINMAX:
+            return MinMaxScaler()
+        return None
+
+    def _extract_params(self) -> Dict[str, Any]:
+        if self._scaler is None:
+            return {}
+
+        params = {}
+        if hasattr(self._scaler, "mean_"):
+            params["mean"] = self._scaler.mean_.tolist()
+        if hasattr(self._scaler, "scale_"):
+            params["scale"] = self._scaler.scale_.tolist()
+        if hasattr(self._scaler, "center_"):
+            params["center"] = self._scaler.center_.tolist()
+        if hasattr(self._scaler, "data_min_"):
+            params["data_min"] = self._scaler.data_min_.tolist()
+        if hasattr(self._scaler, "data_max_"):
+            params["data_max"] = self._scaler.data_max_.tolist()
+
+        return params

customer_retention/stages/modeling/hyperparameter_tuner.py

@@ -0,0 +1,107 @@
+"""Hyperparameter tuning strategies for model optimization."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from sklearn.model_selection import GridSearchCV, RandomizedSearchCV
+
+from customer_retention.core.compat import DataFrame, Series
+
+
+class SearchStrategy(Enum):
+    RANDOM_SEARCH = "random_search"
+    GRID_SEARCH = "grid_search"
+    BAYESIAN = "bayesian"
+    HALVING = "halving"
+
+
+@dataclass
+class TuningResult:
+    best_params: Dict[str, Any]
+    best_score: float
+    best_model: Any
+    cv_results: List[Dict[str, Any]]
+    scoring: str
+
+
+class HyperparameterTuner:
+    def __init__(
+        self,
+        strategy: SearchStrategy = SearchStrategy.RANDOM_SEARCH,
+        param_space: Optional[Dict[str, Any]] = None,
+        n_iter: int = 50,
+        cv: int = 5,
+        scoring: str = "average_precision",
+        n_jobs: int = -1,
+        verbose: int = 0,
+        random_state: int = 42,
+    ):
+        self.strategy = strategy
+        self.param_space = param_space or {}
+        self.n_iter = n_iter
+        self.cv = cv
+        self.scoring = scoring
+        self.n_jobs = n_jobs
+        self.verbose = verbose
+        self.random_state = random_state
+
+    def tune(self, model, X: DataFrame, y: Series) -> TuningResult:
+        search = self._create_search(model)
+        search.fit(X, y)
+
+        cv_results = self._extract_cv_results(search)
+
+        return TuningResult(
+            best_params=search.best_params_,
+            best_score=search.best_score_,
+            best_model=search.best_estimator_,
+            cv_results=cv_results,
+            scoring=self.scoring,
+        )
+
+    def _create_search(self, model):
+        if self.strategy == SearchStrategy.GRID_SEARCH:
+            return GridSearchCV(
+                model,
+                param_grid=self.param_space,
+                cv=self.cv,
+                scoring=self.scoring,
+                n_jobs=self.n_jobs,
+                verbose=self.verbose,
+            )
+
+        if self.strategy == SearchStrategy.HALVING:
+            from sklearn.model_selection import HalvingRandomSearchCV
+            return HalvingRandomSearchCV(
+                model,
+                param_distributions=self.param_space,
+                cv=self.cv,
+                scoring=self.scoring,
+                n_jobs=self.n_jobs,
+                verbose=self.verbose,
+                random_state=self.random_state,
+            )
+
+        return RandomizedSearchCV(
+            model,
+            param_distributions=self.param_space,
+            n_iter=self.n_iter,
+            cv=self.cv,
+            scoring=self.scoring,
+            n_jobs=self.n_jobs,
+            verbose=self.verbose,
+            random_state=self.random_state,
+        )
+
+    def _extract_cv_results(self, search) -> List[Dict[str, Any]]:
+        results = []
+        for i in range(len(search.cv_results_["mean_test_score"])):
+            result = {
+                "params": search.cv_results_["params"][i],
+                "mean_score": search.cv_results_["mean_test_score"][i],
+                "std_score": search.cv_results_["std_test_score"][i],
+                "rank": search.cv_results_["rank_test_score"][i],
+            }
+            results.append(result)
+        return results

customer_retention/stages/modeling/imbalance_handler.py

@@ -0,0 +1,282 @@
+"""Class imbalance handling strategies for model training."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, Optional, Union
+
+import numpy as np
+
+from customer_retention.core.compat import DataFrame, Series
+
+
+class ImbalanceStrategy(Enum):
+    CLASS_WEIGHT = "class_weight"
+    SMOTE = "smote"
+    RANDOM_OVERSAMPLE = "random_oversample"
+    RANDOM_UNDERSAMPLE = "random_undersample"
+    SMOTEENN = "smoteenn"
+    ADASYN = "adasyn"
+    NONE = "none"
+
+
+class ClassWeightMethod(Enum):
+    BALANCED = "balanced"
+    CUSTOM = "custom"
+    INVERSE = "inverse"
+
+
+@dataclass
+class ImbalanceResult:
+    X_resampled: Optional[DataFrame]
+    y_resampled: Optional[Series]
+    strategy_used: ImbalanceStrategy
+    original_class_counts: Dict[int, int]
+    resampled_class_counts: Optional[Dict[int, int]] = None
+    class_weights: Optional[Dict[int, float]] = None
+    imbalance_ratio: Optional[float] = None
+
+
+class ImbalanceHandler:
+    def __init__(
+        self,
+        strategy: ImbalanceStrategy = ImbalanceStrategy.CLASS_WEIGHT,
+        weight_method: ClassWeightMethod = ClassWeightMethod.BALANCED,
+        custom_weights: Optional[Dict[int, float]] = None,
+        sampling_strategy: Union[str, float] = "auto",
+        random_state: int = 42,
+    ):
+        self.strategy = strategy
+        self.weight_method = weight_method
+        self.custom_weights = custom_weights
+        self.sampling_strategy = sampling_strategy
+        self.random_state = random_state
+        self._class_weights = None
+
+    def fit(self, X: DataFrame, y: Series) -> ImbalanceResult:
+        original_counts = y.value_counts().to_dict()
+        imbalance_ratio = max(original_counts.values()) / min(original_counts.values())
+
+        class_weights = None
+        if self.strategy == ImbalanceStrategy.CLASS_WEIGHT:
+            class_weights = self._compute_class_weights(y)
+
+        return ImbalanceResult(
+            X_resampled=None,
+            y_resampled=None,
+            strategy_used=self.strategy,
+            original_class_counts=original_counts,
+            resampled_class_counts=None,
+            class_weights=class_weights,
+            imbalance_ratio=imbalance_ratio,
+        )
+
+    def fit_transform(self, X: DataFrame, y: Series) -> ImbalanceResult:
+        original_counts = y.value_counts().to_dict()
+        imbalance_ratio = max(original_counts.values()) / min(original_counts.values())
+
+        if self.strategy == ImbalanceStrategy.NONE:
+            return ImbalanceResult(
+                X_resampled=X,
+                y_resampled=y,
+                strategy_used=self.strategy,
+                original_class_counts=original_counts,
+                resampled_class_counts=original_counts,
+                imbalance_ratio=imbalance_ratio,
+            )
+
+        if self.strategy == ImbalanceStrategy.CLASS_WEIGHT:
+            return ImbalanceResult(
+                X_resampled=X,
+                y_resampled=y,
+                strategy_used=self.strategy,
+                original_class_counts=original_counts,
+                resampled_class_counts=original_counts,
+                class_weights=self._compute_class_weights(y),
+                imbalance_ratio=imbalance_ratio,
+            )
+
+        X_res, y_res = self._resample(X, y)
+        resampled_counts = Series(y_res).value_counts().to_dict()
+
+        return ImbalanceResult(
+            X_resampled=DataFrame(X_res, columns=X.columns),
+            y_resampled=Series(y_res),
+            strategy_used=self.strategy,
+            original_class_counts=original_counts,
+            resampled_class_counts=resampled_counts,
+            imbalance_ratio=imbalance_ratio,
+        )
+
+    def _compute_class_weights(self, y: Series) -> Dict[int, float]:
+        if self.weight_method == ClassWeightMethod.CUSTOM:
+            return self.custom_weights
+
+        classes = np.unique(y)
+        n_samples = len(y)
+        n_classes = len(classes)
+
+        if self.weight_method == ClassWeightMethod.BALANCED:
+            weights = {}
+            for cls in classes:
+                n_cls = (y == cls).sum()
+                weights[cls] = n_samples / (n_classes * n_cls)
+            return weights
+
+        if self.weight_method == ClassWeightMethod.INVERSE:
+            weights = {}
+            for cls in classes:
+                proportion = (y == cls).sum() / n_samples
+                weights[cls] = 1.0 / proportion
+            return weights
+
+        return {cls: 1.0 for cls in classes}
+
+    def _resample(self, X: DataFrame, y: Series) -> tuple:
+        if self.strategy == ImbalanceStrategy.SMOTE:
+            from imblearn.over_sampling import SMOTE
+            sampler = SMOTE(sampling_strategy=self.sampling_strategy, random_state=self.random_state)
+            return sampler.fit_resample(X, y)
+
+        if self.strategy == ImbalanceStrategy.RANDOM_OVERSAMPLE:
+            from imblearn.over_sampling import RandomOverSampler
+            sampler = RandomOverSampler(sampling_strategy=self.sampling_strategy, random_state=self.random_state)
+            return sampler.fit_resample(X, y)
+
+        if self.strategy == ImbalanceStrategy.RANDOM_UNDERSAMPLE:
+            from imblearn.under_sampling import RandomUnderSampler
+            sampler = RandomUnderSampler(sampling_strategy=self.sampling_strategy, random_state=self.random_state)
+            return sampler.fit_resample(X, y)
+
+        if self.strategy == ImbalanceStrategy.SMOTEENN:
+            from imblearn.combine import SMOTEENN
+            sampler = SMOTEENN(sampling_strategy=self.sampling_strategy, random_state=self.random_state)
+            return sampler.fit_resample(X, y)
+
+        if self.strategy == ImbalanceStrategy.ADASYN:
+            from imblearn.over_sampling import ADASYN
+            sampler = ADASYN(sampling_strategy=self.sampling_strategy, random_state=self.random_state)
+            return sampler.fit_resample(X, y)
+
+        return X.values, y.values
+
+
+@dataclass
+class ImbalanceRecommendation:
+    """Recommendation for handling class imbalance."""
+    severity: str  # "low", "moderate", "high", "severe"
+    ratio: float
+    strategies: list
+    primary_strategy: ImbalanceStrategy
+    explanation: str
+
+    def print_recommendation(self):
+        icons = {"low": "🟢", "moderate": "🟡", "high": "🟠", "severe": "🔴"}
+        print(f"\n{icons.get(self.severity, '⚪')} Class Imbalance: {self.severity.upper()} ({self.ratio:.1f}:1)")
+        print(f"\n{self.explanation}")
+        print("\nRecommended strategies (in order of preference):")
+        for i, (strategy, desc) in enumerate(self.strategies, 1):
+            marker = "→" if strategy == self.primary_strategy else " "
+            print(f"  {marker} {i}. {strategy.value}: {desc}")
+
+
+class ImbalanceRecommender:
+    """Recommends imbalance handling strategies based on data characteristics."""
+
+    THRESHOLDS = {"low": 3, "moderate": 10, "high": 20, "severe": float("inf")}
+
+    STRATEGY_DESCRIPTIONS = {
+        ImbalanceStrategy.CLASS_WEIGHT: "Adjust loss function weights (no data modification)",
+        ImbalanceStrategy.SMOTE: "Generate synthetic minority samples using k-NN interpolation",
+        ImbalanceStrategy.RANDOM_UNDERSAMPLE: "Randomly remove majority samples",
+        ImbalanceStrategy.RANDOM_OVERSAMPLE: "Duplicate minority samples (risk of overfitting)",
+        ImbalanceStrategy.SMOTEENN: "SMOTE + ENN cleaning (removes noisy samples)",
+        ImbalanceStrategy.ADASYN: "Adaptive synthetic sampling (focuses on harder examples)",
+    }
+
+    def recommend(self, y: Series, n_samples: Optional[int] = None) -> ImbalanceRecommendation:
+        """Recommend imbalance handling strategy based on class distribution."""
+        counts = y.value_counts().to_dict()
+        ratio = max(counts.values()) / min(counts.values())
+        n_minority = min(counts.values())
+        n_total = n_samples or len(y)
+
+        severity = self._get_severity(ratio)
+        strategies, primary, explanation = self._get_strategies(severity, ratio, n_minority, n_total)
+
+        return ImbalanceRecommendation(
+            severity=severity, ratio=ratio, strategies=strategies,
+            primary_strategy=primary, explanation=explanation
+        )
+
+    def _get_severity(self, ratio: float) -> str:
+        if ratio < self.THRESHOLDS["low"]:
+            return "low"
+        elif ratio < self.THRESHOLDS["moderate"]:
+            return "moderate"
+        elif ratio < self.THRESHOLDS["high"]:
+            return "high"
+        return "severe"
+
+    def _get_strategies(self, severity: str, ratio: float, n_minority: int, n_total: int):
+        strategies = []
+        primary = ImbalanceStrategy.CLASS_WEIGHT
+        explanation = ""
+
+        if severity == "low":
+            explanation = f"Ratio {ratio:.1f}:1 is manageable. Class weights are usually sufficient."
+            strategies = [
+                (ImbalanceStrategy.CLASS_WEIGHT, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.CLASS_WEIGHT]),
+            ]
+            primary = ImbalanceStrategy.CLASS_WEIGHT
+
+        elif severity == "moderate":
+            explanation = f"Ratio {ratio:.1f}:1 may affect model performance. Consider resampling if class weights aren't enough."
+            strategies = [
+                (ImbalanceStrategy.CLASS_WEIGHT, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.CLASS_WEIGHT]),
+                (ImbalanceStrategy.SMOTE, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.SMOTE]),
+            ]
+            primary = ImbalanceStrategy.CLASS_WEIGHT
+
+        elif severity == "high":
+            explanation = f"Ratio {ratio:.1f}:1 is significant. SMOTE recommended to create synthetic minority samples."
+            if n_minority < 6:
+                explanation += f"\n⚠️ Only {n_minority} minority samples - SMOTE needs k=5 neighbors minimum."
+                strategies = [
+                    (ImbalanceStrategy.RANDOM_OVERSAMPLE, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.RANDOM_OVERSAMPLE]),
+                    (ImbalanceStrategy.CLASS_WEIGHT, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.CLASS_WEIGHT]),
+                ]
+                primary = ImbalanceStrategy.RANDOM_OVERSAMPLE
+            else:
+                strategies = [
+                    (ImbalanceStrategy.SMOTE, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.SMOTE]),
+                    (ImbalanceStrategy.SMOTEENN, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.SMOTEENN]),
+                    (ImbalanceStrategy.CLASS_WEIGHT, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.CLASS_WEIGHT]),
+                ]
+                primary = ImbalanceStrategy.SMOTE
+
+        else:  # severe
+            explanation = f"Ratio {ratio:.1f}:1 is severe. Combination of techniques recommended."
+            if n_total > 100000:
+                explanation += f"\nDataset is large ({n_total:,} rows) - undersampling majority is viable."
+                strategies = [
+                    (ImbalanceStrategy.RANDOM_UNDERSAMPLE, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.RANDOM_UNDERSAMPLE]),
+                    (ImbalanceStrategy.SMOTE, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.SMOTE]),
+                    (ImbalanceStrategy.SMOTEENN, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.SMOTEENN]),
+                ]
+                primary = ImbalanceStrategy.RANDOM_UNDERSAMPLE
+            elif n_minority < 6:
+                explanation += f"\n⚠️ Only {n_minority} minority samples - limited options."
+                strategies = [
+                    (ImbalanceStrategy.RANDOM_OVERSAMPLE, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.RANDOM_OVERSAMPLE]),
+                    (ImbalanceStrategy.CLASS_WEIGHT, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.CLASS_WEIGHT]),
+                ]
+                primary = ImbalanceStrategy.RANDOM_OVERSAMPLE
+            else:
+                strategies = [
+                    (ImbalanceStrategy.SMOTE, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.SMOTE]),
+                    (ImbalanceStrategy.ADASYN, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.ADASYN]),
+                    (ImbalanceStrategy.SMOTEENN, self.STRATEGY_DESCRIPTIONS[ImbalanceStrategy.SMOTEENN]),
+                ]
+                primary = ImbalanceStrategy.SMOTE
+
+        return strategies, primary, explanation

customer_retention/stages/modeling/mlflow_logger.py

@@ -0,0 +1,95 @@
+"""MLflow integration for experiment tracking."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+try:
+    import mlflow
+    import mlflow.sklearn
+    MLFLOW_AVAILABLE = True
+except ImportError:
+    MLFLOW_AVAILABLE = False
+
+
+@dataclass
+class ExperimentConfig:
+    experiment_name: str
+    run_name: Optional[str] = None
+    tracking_uri: Optional[str] = None
+    artifact_location: Optional[str] = None
+
+
+class MLflowLogger:
+    def __init__(
+        self,
+        experiment_name: str,
+        run_name: Optional[str] = None,
+        tracking_uri: Optional[str] = None,
+    ):
+        self.experiment_name = experiment_name
+        self.run_name = run_name
+        self.tracking_uri = tracking_uri
+        self._run = None
+
+    def __enter__(self):
+        self.start_run()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.end_run()
+        return False
+
+    def start_run(self, run_name: Optional[str] = None):
+        if not MLFLOW_AVAILABLE:
+            return
+
+        if self.tracking_uri:
+            mlflow.set_tracking_uri(self.tracking_uri)
+
+        experiment = mlflow.get_experiment_by_name(self.experiment_name)
+        if experiment is None:
+            experiment_id = mlflow.create_experiment(self.experiment_name)
+        else:
+            experiment_id = experiment.experiment_id
+
+        self._run = mlflow.start_run(
+            experiment_id=experiment_id,
+            run_name=run_name or self.run_name,
+        )
+
+    def end_run(self):
+        if MLFLOW_AVAILABLE:
+            mlflow.end_run()
+        self._run = None
+
+    def log_params(self, params: Dict[str, Any]):
+        if MLFLOW_AVAILABLE:
+            mlflow.log_params(params)
+
+    def log_metrics(self, metrics: Dict[str, float]):
+        if MLFLOW_AVAILABLE:
+            mlflow.log_metrics(metrics)
+
+    def log_artifact(self, local_path: str, artifact_path: Optional[str] = None):
+        if MLFLOW_AVAILABLE:
+            mlflow.log_artifact(local_path, artifact_path)
+
+    def set_tags(self, tags: Dict[str, str]):
+        if MLFLOW_AVAILABLE:
+            mlflow.set_tags(tags)
+
+    def log_dict(self, dictionary: Dict[str, Any], artifact_file: str):
+        if MLFLOW_AVAILABLE:
+            mlflow.log_dict(dictionary, artifact_file)
+
+    def log_model(self, model, artifact_path: str, registered_model_name: Optional[str] = None):
+        if MLFLOW_AVAILABLE:
+            mlflow.sklearn.log_model(
+                model,
+                artifact_path,
+                registered_model_name=registered_model_name,
+            )
+
+    def log_figure(self, figure, artifact_file: str):
+        if MLFLOW_AVAILABLE:
+            mlflow.log_figure(figure, artifact_file)