churnkit 0.75.0a1__py3-none-any.whl

customer_retention/stages/ingestion/source_registry.py

@@ -0,0 +1,130 @@
+import json
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel
+
+from customer_retention.core.config.source_config import DataSourceConfig
+
+from .load_result import LoadResult
+
+
+class LoadHistoryEntry(BaseModel):
+    timestamp: str
+    row_count: int
+    duration_seconds: float
+    success: bool
+    warnings: list[str] = []
+    errors: list[str] = []
+
+
+class SourceRegistration(BaseModel):
+    source_config: DataSourceConfig
+    registered_at: str
+    registered_by: str
+    last_loaded_at: Optional[str] = None
+    last_row_count: Optional[int] = None
+    last_load_duration: Optional[float] = None
+    load_history: list[LoadHistoryEntry] = []
+
+    def update_from_load(self, load_result: LoadResult) -> None:
+        entry = LoadHistoryEntry(
+            timestamp=datetime.now().isoformat(),
+            row_count=load_result.row_count,
+            duration_seconds=load_result.duration_seconds,
+            success=load_result.success,
+            warnings=load_result.warnings,
+            errors=load_result.errors
+        )
+
+        self.load_history.append(entry)
+        if len(self.load_history) > 100:
+            self.load_history = self.load_history[-100:]
+
+        self.last_loaded_at = entry.timestamp
+        self.last_row_count = load_result.row_count
+        self.last_load_duration = load_result.duration_seconds
+
+
+class DataSourceRegistry:
+    def __init__(self):
+        self._sources: dict[str, SourceRegistration] = {}
+
+    def register(self, config: DataSourceConfig, registered_by: str = "system",
+                overwrite: bool = False) -> None:
+        if config.name in self._sources and not overwrite:
+            raise ValueError(f"Source '{config.name}' already registered. Use overwrite=True to replace.")
+
+        self._sources[config.name] = SourceRegistration(
+            source_config=config,
+            registered_at=datetime.now().isoformat(),
+            registered_by=registered_by
+        )
+
+    def get(self, name: str) -> Optional[SourceRegistration]:
+        return self._sources.get(name)
+
+    def list_sources(self) -> list[str]:
+        return list(self._sources.keys())
+
+    def record_load(self, source_name: str, load_result: LoadResult) -> None:
+        registration = self.get(source_name)
+        if not registration:
+            raise ValueError(f"Source '{source_name}' not found in registry")
+        registration.update_from_load(load_result)
+
+    def get_load_stats(self, source_name: str) -> dict:
+        registration = self.get(source_name)
+        if not registration:
+            raise ValueError(f"Source '{source_name}' not found in registry")
+
+        total_loads = len(registration.load_history)
+        successful_loads = sum(1 for entry in registration.load_history if entry.success)
+        failed_loads = total_loads - successful_loads
+
+        return {
+            "source_name": source_name,
+            "total_loads": total_loads,
+            "successful_loads": successful_loads,
+            "failed_loads": failed_loads,
+            "last_loaded_at": registration.last_loaded_at,
+            "last_row_count": registration.last_row_count,
+            "last_load_duration": registration.last_load_duration
+        }
+
+    def save_to_file(self, path: str) -> None:
+        data = {name: reg.model_dump() for name, reg in self._sources.items()}
+        with open(path, 'w') as f:
+            json.dump(data, f, indent=2)
+
+    def load_from_file(self, path: str) -> None:
+        with open(path, 'r') as f:
+            data = json.load(f)
+        self._sources = {
+            name: SourceRegistration(**reg_data)
+            for name, reg_data in data.items()
+        }
+
+    def validate_source(self, config: DataSourceConfig) -> list[str]:
+        errors = []
+
+        if not config.name:
+            errors.append("Source name is required")
+        if not config.primary_key:
+            errors.append("Primary key is required")
+
+        duplicate_columns = self.find_duplicate_column_names(config)
+        if duplicate_columns:
+            errors.append(f"Duplicate column names found: {', '.join(duplicate_columns)}")
+
+        return errors
+
+    def find_duplicate_column_names(self, config: DataSourceConfig) -> list[str]:
+        column_names = [c.name for c in config.columns]
+        seen = set()
+        duplicates = set()
+        for name in column_names:
+            if name in seen:
+                duplicates.add(name)
+            seen.add(name)
+        return list(duplicates)

customer_retention/stages/modeling/__init__.py

@@ -0,0 +1,31 @@
+from .baseline_trainer import BaselineTrainer, ModelType, TrainedModel, TrainingConfig
+from .cross_validator import CrossValidator, CVResult, CVStrategy
+from .data_splitter import DataSplitter, SplitConfig, SplitResult, SplitStrategy
+from .feature_scaler import FeatureScaler, ScalerType, ScalingResult
+from .hyperparameter_tuner import HyperparameterTuner, SearchStrategy, TuningResult
+from .imbalance_handler import (
+    ClassWeightMethod,
+    ImbalanceHandler,
+    ImbalanceRecommendation,
+    ImbalanceRecommender,
+    ImbalanceResult,
+    ImbalanceStrategy,
+)
+from .mlflow_logger import ExperimentConfig, MLflowLogger
+from .model_comparator import ComparisonResult, ModelComparator, ModelMetrics
+from .model_evaluator import EvaluationResult, ModelEvaluator
+from .threshold_optimizer import OptimizationObjective, ThresholdOptimizer, ThresholdResult
+
+__all__ = [
+    "DataSplitter", "SplitStrategy", "SplitResult", "SplitConfig",
+    "ImbalanceHandler", "ImbalanceStrategy", "ClassWeightMethod", "ImbalanceResult",
+    "ImbalanceRecommender", "ImbalanceRecommendation",
+    "BaselineTrainer", "ModelType", "TrainingConfig", "TrainedModel",
+    "ModelEvaluator", "EvaluationResult",
+    "CrossValidator", "CVStrategy", "CVResult",
+    "HyperparameterTuner", "SearchStrategy", "TuningResult",
+    "ThresholdOptimizer", "OptimizationObjective", "ThresholdResult",
+    "ModelComparator", "ComparisonResult", "ModelMetrics",
+    "FeatureScaler", "ScalerType", "ScalingResult",
+    "MLflowLogger", "ExperimentConfig",
+]

customer_retention/stages/modeling/baseline_trainer.py

@@ -0,0 +1,139 @@
+"""Baseline model training for customer retention prediction."""
+
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from customer_retention.core.compat import DataFrame, Series
+from customer_retention.core.components.enums import ModelType
+
+
+@dataclass
+class TrainingConfig:
+    random_state: int = 42
+    verbose: bool = False
+    n_jobs: int = -1
+
+
+@dataclass
+class TrainedModel:
+    model: Any
+    model_type: ModelType
+    hyperparameters: Dict[str, Any]
+    training_time: float
+    feature_names: List[str]
+    class_weight: Optional[Any] = None
+
+
+class BaselineTrainer:
+    DEFAULT_PARAMS = {
+        ModelType.LOGISTIC_REGRESSION: {
+            "C": 1.0,
+            "solver": "lbfgs",
+            "max_iter": 1000,
+        },
+        ModelType.RANDOM_FOREST: {
+            "n_estimators": 100,
+            "max_depth": 10,
+            "min_samples_split": 5,
+            "min_samples_leaf": 2,
+            "n_jobs": -1,
+        },
+        ModelType.XGBOOST: {
+            "n_estimators": 100,
+            "max_depth": 6,
+            "learning_rate": 0.1,
+            "subsample": 0.8,
+            "colsample_bytree": 0.8,
+            "eval_metric": "logloss",
+        },
+        ModelType.LIGHTGBM: {
+            "n_estimators": 100,
+            "max_depth": 6,
+            "learning_rate": 0.1,
+            "num_leaves": 31,
+        },
+    }
+
+    def __init__(
+        self,
+        model_type: ModelType,
+        model_params: Optional[Dict[str, Any]] = None,
+        class_weight: Optional[Any] = None,
+        random_state: int = 42,
+        verbose: bool = False,
+    ):
+        self.model_type = model_type
+        self.model_params = model_params or {}
+        self.class_weight = class_weight
+        self.random_state = random_state
+        self.verbose = verbose
+
+    def fit(
+        self,
+        X: DataFrame,
+        y: Series,
+        X_val: Optional[DataFrame] = None,
+        y_val: Optional[Series] = None,
+    ) -> TrainedModel:
+        start_time = time.time()
+        params = self._build_params()
+        model = self._create_model(params)
+
+        if self.model_type == ModelType.XGBOOST and X_val is not None:
+            early_stopping = params.pop("early_stopping_rounds", None)
+            if early_stopping:
+                model.set_params(early_stopping_rounds=early_stopping)
+                model.fit(X, y, eval_set=[(X_val, y_val)], verbose=self.verbose)
+            else:
+                model.fit(X, y)
+        else:
+            model.fit(X, y)
+
+        training_time = time.time() - start_time
+
+        return TrainedModel(
+            model=model,
+            model_type=self.model_type,
+            hyperparameters=self._get_final_params(model),
+            training_time=training_time,
+            feature_names=list(X.columns),
+            class_weight=self.class_weight,
+        )
+
+    def _build_params(self) -> Dict[str, Any]:
+        defaults = self.DEFAULT_PARAMS.get(self.model_type, {}).copy()
+        defaults.update(self.model_params)
+        defaults["random_state"] = self.random_state
+        return defaults
+
+    def _create_model(self, params: Dict[str, Any]):
+        if self.model_type == ModelType.LOGISTIC_REGRESSION:
+            from sklearn.linear_model import LogisticRegression
+            if self.class_weight:
+                params["class_weight"] = self.class_weight
+            return LogisticRegression(**params)
+
+        if self.model_type == ModelType.RANDOM_FOREST:
+            from sklearn.ensemble import RandomForestClassifier
+            if self.class_weight:
+                params["class_weight"] = self.class_weight
+            return RandomForestClassifier(**params)
+
+        if self.model_type == ModelType.XGBOOST:
+            from xgboost import XGBClassifier
+            params.pop("class_weight", None)
+            return XGBClassifier(**params, verbosity=0 if not self.verbose else 1)
+
+        if self.model_type == ModelType.LIGHTGBM:
+            from lightgbm import LGBMClassifier
+            if self.class_weight:
+                params["class_weight"] = self.class_weight
+            return LGBMClassifier(**params, verbosity=-1 if not self.verbose else 1)
+
+        raise ValueError(f"Unsupported model type: {self.model_type}")
+
+    def _get_final_params(self, model) -> Dict[str, Any]:
+        if hasattr(model, "get_params"):
+            return model.get_params()
+        return self.model_params

customer_retention/stages/modeling/cross_validator.py

@@ -0,0 +1,125 @@
+"""Cross-validation strategies for model evaluation."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+from sklearn.model_selection import GroupKFold, RepeatedStratifiedKFold, StratifiedKFold, cross_val_score
+
+from customer_retention.core.compat import DataFrame, Series
+
+
+class CVStrategy(Enum):
+    STRATIFIED_KFOLD = "stratified_kfold"
+    REPEATED_STRATIFIED = "repeated_stratified"
+    TIME_SERIES = "time_series"
+    GROUP_KFOLD = "group_kfold"
+
+
+@dataclass
+class CVResult:
+    cv_scores: np.ndarray
+    cv_mean: float
+    cv_std: float
+    fold_details: List[Dict[str, Any]]
+    scoring: str
+    is_stable: bool
+
+
+class CrossValidator:
+    def __init__(
+        self,
+        strategy: CVStrategy = CVStrategy.STRATIFIED_KFOLD,
+        n_splits: int = 5,
+        n_repeats: int = 1,
+        shuffle: bool = True,
+        random_state: int = 42,
+        scoring: str = "average_precision",
+        stability_threshold: float = 0.10,
+    ):
+        self.strategy = strategy
+        self.n_splits = n_splits
+        self.n_repeats = n_repeats
+        self.shuffle = shuffle
+        self.random_state = random_state
+        self.scoring = scoring
+        self.stability_threshold = stability_threshold
+
+    def run(
+        self,
+        model,
+        X: DataFrame,
+        y: Series,
+        groups: Optional[Series] = None,
+    ) -> CVResult:
+        cv_splitter = self._create_cv_splitter(groups)
+        fold_details = []
+
+        if self.strategy == CVStrategy.GROUP_KFOLD:
+            scores = cross_val_score(model, X, y, cv=cv_splitter, scoring=self.scoring, groups=groups)
+            fold_details = self._collect_fold_details_with_groups(X, y, groups, cv_splitter)
+        else:
+            scores = cross_val_score(model, X, y, cv=cv_splitter, scoring=self.scoring)
+            fold_details = self._collect_fold_details(X, y, cv_splitter)
+
+        cv_mean = np.mean(scores)
+        cv_std = np.std(scores)
+        is_stable = bool(cv_std <= self.stability_threshold)
+
+        return CVResult(
+            cv_scores=scores,
+            cv_mean=cv_mean,
+            cv_std=cv_std,
+            fold_details=fold_details,
+            scoring=self.scoring,
+            is_stable=is_stable,
+        )
+
+    def _create_cv_splitter(self, groups: Optional[Series] = None):
+        if self.strategy == CVStrategy.STRATIFIED_KFOLD:
+            return StratifiedKFold(n_splits=self.n_splits, shuffle=self.shuffle, random_state=self.random_state)
+
+        if self.strategy == CVStrategy.REPEATED_STRATIFIED:
+            return RepeatedStratifiedKFold(n_splits=self.n_splits, n_repeats=self.n_repeats, random_state=self.random_state)
+
+        if self.strategy == CVStrategy.GROUP_KFOLD:
+            return GroupKFold(n_splits=self.n_splits)
+
+        if self.strategy == CVStrategy.TIME_SERIES:
+            from sklearn.model_selection import TimeSeriesSplit
+            return TimeSeriesSplit(n_splits=self.n_splits)
+
+        return StratifiedKFold(n_splits=self.n_splits, shuffle=self.shuffle, random_state=self.random_state)
+
+    def _collect_fold_details(self, X: DataFrame, y: Series, cv_splitter) -> List[Dict[str, Any]]:
+        fold_details = []
+        for fold_idx, (train_idx, test_idx) in enumerate(cv_splitter.split(X, y)):
+            y_train = y.iloc[train_idx]
+            fold_details.append({
+                "fold": fold_idx + 1,
+                "train_size": len(train_idx),
+                "test_size": len(test_idx),
+                "train_class_ratio": y_train.mean(),
+                "score": None,
+            })
+        return fold_details
+
+    def _collect_fold_details_with_groups(
+        self,
+        X: DataFrame,
+        y: Series,
+        groups: Series,
+        cv_splitter,
+    ) -> List[Dict[str, Any]]:
+        fold_details = []
+        for fold_idx, (train_idx, test_idx) in enumerate(cv_splitter.split(X, y, groups)):
+            y_train = y.iloc[train_idx]
+            fold_details.append({
+                "fold": fold_idx + 1,
+                "train_size": len(train_idx),
+                "test_size": len(test_idx),
+                "train_class_ratio": y_train.mean(),
+                "score": None,
+            })
+        return fold_details

customer_retention/stages/modeling/data_splitter.py

@@ -0,0 +1,205 @@
+import warnings
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from sklearn.model_selection import GroupShuffleSplit, train_test_split
+
+from customer_retention.core.compat import DataFrame, Series
+
+if TYPE_CHECKING:
+    from customer_retention.analysis.auto_explorer.findings import FeatureAvailabilityMetadata
+
+
+class SplitStrategy(Enum):
+    RANDOM_STRATIFIED = "random_stratified"
+    TEMPORAL = "temporal"
+    GROUP = "group"
+    CUSTOM = "custom"
+
+
+@dataclass
+class SplitConfig:
+    test_size: float = 0.11
+    validation_size: float = 0.10
+    stratify: bool = True
+    random_state: int = 42
+    temporal_column: Optional[str] = None
+    group_column: Optional[str] = None
+
+
+@dataclass
+class SplitResult:
+    X_train: DataFrame
+    X_test: DataFrame
+    y_train: Series
+    y_test: Series
+    X_val: Optional[DataFrame] = None
+    y_val: Optional[Series] = None
+    split_info: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SplitWarning:
+    column: str
+    issue: str
+    severity: str
+    recommendation: str
+
+    def to_dict(self) -> Dict[str, str]:
+        return {"column": self.column, "issue": self.issue, "severity": self.severity, "recommendation": self.recommendation}
+
+
+class DataSplitter:
+    def __init__(self, target_column: str, strategy: SplitStrategy = SplitStrategy.RANDOM_STRATIFIED, test_size: float = 0.11, validation_size: float = 0.10, stratify: bool = True, random_state: int = 42, temporal_column: Optional[str] = None, group_column: Optional[str] = None, exclude_columns: Optional[List[str]] = None, include_validation: bool = False):
+        self.target_column = target_column
+        self.strategy = strategy
+        self.test_size = test_size
+        self.validation_size = validation_size
+        self.stratify = stratify
+        self.random_state = random_state
+        self.temporal_column = temporal_column
+        self.group_column = group_column
+        self.exclude_columns = exclude_columns or []
+        self.include_validation = include_validation
+
+    def split(self, df: DataFrame, feature_availability: Optional["FeatureAvailabilityMetadata"] = None) -> SplitResult:
+        self._validate_minority_samples(df)
+        availability_warnings = self.validate_feature_availability(df, feature_availability)
+
+        if self.strategy == SplitStrategy.TEMPORAL:
+            result = self._temporal_split(df)
+        elif self.strategy == SplitStrategy.GROUP:
+            result = self._group_split(df)
+        else:
+            result = self._stratified_split(df)
+
+        if availability_warnings:
+            result.split_info["availability_warnings"] = [w.to_dict() for w in availability_warnings]
+        return result
+
+    def validate_feature_availability(self, df: DataFrame, availability: Optional["FeatureAvailabilityMetadata"]) -> List[SplitWarning]:
+        if availability is None:
+            return []
+        if self.strategy != SplitStrategy.TEMPORAL:
+            return []
+        warnings_list: List[SplitWarning] = []
+        for col in availability.new_tracking:
+            if col in df.columns:
+                feat_info = availability.features.get(col)
+                first_date = feat_info.first_valid_date if feat_info else "unknown"
+                warnings_list.append(SplitWarning(
+                    column=col, issue="new_tracking", severity="warning",
+                    recommendation=f"Feature '{col}' only available from {first_date}. Training data before this date will have missing values.",
+                ))
+        for col in availability.retired_tracking:
+            if col in df.columns:
+                feat_info = availability.features.get(col)
+                last_date = feat_info.last_valid_date if feat_info else "unknown"
+                warnings_list.append(SplitWarning(
+                    column=col, issue="retired", severity="warning",
+                    recommendation=f"Feature '{col}' retired at {last_date}. Test data after this date will have missing values.",
+                ))
+        for col in availability.partial_window:
+            if col in df.columns:
+                feat_info = availability.features.get(col)
+                first_date = feat_info.first_valid_date if feat_info else "unknown"
+                last_date = feat_info.last_valid_date if feat_info else "unknown"
+                warnings_list.append(SplitWarning(
+                    column=col, issue="partial_window", severity="warning",
+                    recommendation=f"Feature '{col}' only available {first_date} to {last_date}. Both train and test may have gaps.",
+                ))
+        return warnings_list
+
+    def _stratified_split(self, df: DataFrame) -> SplitResult:
+        X, y = self._prepare_features_target(df)
+        stratify_col = y if self.stratify else None
+
+        X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=self.test_size, random_state=self.random_state, stratify=stratify_col)
+
+        X_val, y_val = None, None
+        if self.include_validation:
+            val_ratio = self.validation_size / (1 - self.test_size)
+            stratify_train = y_train if self.stratify else None
+            X_train, X_val, y_train, y_val = train_test_split(X_train, y_train, test_size=val_ratio, random_state=self.random_state, stratify=stratify_train)
+
+        return SplitResult(
+            X_train=X_train, X_test=X_test, y_train=y_train, y_test=y_test,
+            X_val=X_val, y_val=y_val,
+            split_info=self._build_split_info(X_train, X_test, X_val)
+        )
+
+    def _temporal_split(self, df: DataFrame) -> SplitResult:
+        df_sorted = df.sort_values(self.temporal_column).reset_index(drop=True)
+        split_idx = int(len(df_sorted) * (1 - self.test_size))
+
+        train_df = df_sorted.iloc[:split_idx]
+        test_df = df_sorted.iloc[split_idx:]
+
+        X_train, y_train = self._prepare_features_target(train_df)
+        X_test, y_test = self._prepare_features_target(test_df)
+
+        X_val, y_val = None, None
+        if self.include_validation:
+            val_split = int(len(X_train) * (1 - self.validation_size / (1 - self.test_size)))
+            X_val, y_val = X_train.iloc[val_split:], y_train.iloc[val_split:]
+            X_train, y_train = X_train.iloc[:val_split], y_train.iloc[:val_split]
+
+        return SplitResult(
+            X_train=X_train, X_test=X_test, y_train=y_train, y_test=y_test,
+            X_val=X_val, y_val=y_val,
+            split_info=self._build_split_info(X_train, X_test, X_val)
+        )
+
+    def _group_split(self, df: DataFrame) -> SplitResult:
+        X, y = self._prepare_features_target(df)
+        groups = df[self.group_column]
+
+        gss = GroupShuffleSplit(n_splits=1, test_size=self.test_size, random_state=self.random_state)
+        train_idx, test_idx = next(gss.split(X, y, groups))
+
+        X_train, X_test = X.iloc[train_idx], X.iloc[test_idx]
+        y_train, y_test = y.iloc[train_idx], y.iloc[test_idx]
+
+        X_val, y_val = None, None
+        if self.include_validation:
+            val_ratio = self.validation_size / (1 - self.test_size)
+            train_groups = groups.iloc[train_idx]
+            gss_val = GroupShuffleSplit(n_splits=1, test_size=val_ratio, random_state=self.random_state)
+            train_idx2, val_idx2 = next(gss_val.split(X_train, y_train, train_groups))
+            X_val, y_val = X_train.iloc[val_idx2], y_train.iloc[val_idx2]
+            X_train, y_train = X_train.iloc[train_idx2], y_train.iloc[train_idx2]
+
+        return SplitResult(
+            X_train=X_train, X_test=X_test, y_train=y_train, y_test=y_test,
+            X_val=X_val, y_val=y_val,
+            split_info=self._build_split_info(X_train, X_test, X_val)
+        )
+
+    def _prepare_features_target(self, df: DataFrame) -> tuple[DataFrame, Series]:
+        exclude = [self.target_column] + self.exclude_columns
+        feature_cols = [c for c in df.columns if c not in exclude]
+        return df[feature_cols], df[self.target_column]
+
+    def _validate_minority_samples(self, df: DataFrame):
+        class_counts = df[self.target_column].value_counts()
+        minority_count = class_counts.min()
+        expected_minority_test = minority_count * self.test_size
+
+        if expected_minority_test < 50:
+            warnings.warn(
+                f"Insufficient minority samples: expected ~{expected_minority_test:.0f} in test set. "
+                "Consider using a smaller test_size or collecting more data.",
+                UserWarning
+            )
+
+    def _build_split_info(self, X_train, X_test, X_val) -> Dict[str, Any]:
+        info = {
+            "train_size": len(X_train),
+            "test_size": len(X_test),
+            "strategy": self.strategy.value,
+            "random_state": self.random_state,
+        }
+        if X_val is not None:
+            info["validation_size"] = len(X_val)
+        return info