churnkit 0.75.0a1__py3-none-any.whl

customer_retention/analysis/diagnostics/error_analyzer.py

@@ -0,0 +1,107 @@
+"""Prediction error analysis probes."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+import numpy as np
+
+from customer_retention.core.compat import DataFrame, Series
+
+
+@dataclass
+class ErrorPattern:
+    error_type: str
+    feature: str
+    pattern: str
+    count: int
+
+
+@dataclass
+class ErrorAnalysisResult:
+    total_errors: int
+    error_rate: float
+    fp_count: int
+    fn_count: int
+    false_positives: DataFrame
+    false_negatives: DataFrame
+    high_confidence_fp: DataFrame
+    high_confidence_fn: DataFrame
+    fp_confidence_dist: Dict[str, int] = field(default_factory=dict)
+    fn_confidence_dist: Dict[str, int] = field(default_factory=dict)
+    error_patterns: List[ErrorPattern] = field(default_factory=list)
+    hypotheses: List[str] = field(default_factory=list)
+
+
+class ErrorAnalyzer:
+    HIGH_CONFIDENCE_FP_THRESHOLD = 0.8
+    HIGH_CONFIDENCE_FN_THRESHOLD = 0.2
+
+    def analyze_errors(self, model, X: DataFrame, y: Series, threshold: float = 0.5) -> ErrorAnalysisResult:
+        y_pred = model.predict(X)
+        y_proba = model.predict_proba(X)[:, 1] if hasattr(model, "predict_proba") else y_pred.astype(float)
+        fp_mask = (y_pred == 1) & (y == 0)
+        fn_mask = (y_pred == 0) & (y == 1)
+        false_positives = X[fp_mask].copy()
+        false_negatives = X[fn_mask].copy()
+        false_positives["probability"] = y_proba[fp_mask]
+        false_negatives["probability"] = y_proba[fn_mask]
+        high_conf_fp = false_positives[false_positives["probability"] > self.HIGH_CONFIDENCE_FP_THRESHOLD]
+        high_conf_fn = false_negatives[false_negatives["probability"] < self.HIGH_CONFIDENCE_FN_THRESHOLD]
+        fp_confidence_dist = self._compute_confidence_dist(false_positives["probability"].values if len(false_positives) > 0 else np.array([]))
+        fn_confidence_dist = self._compute_confidence_dist(false_negatives["probability"].values if len(false_negatives) > 0 else np.array([]))
+        error_patterns = self._find_patterns(X, y, y_pred, fp_mask, fn_mask)
+        hypotheses = self._generate_hypotheses(false_positives, false_negatives, high_conf_fp, high_conf_fn)
+        total_errors = fp_mask.sum() + fn_mask.sum()
+        error_rate = total_errors / len(y) if len(y) > 0 else 0.0
+        return ErrorAnalysisResult(
+            total_errors=total_errors,
+            error_rate=error_rate,
+            fp_count=fp_mask.sum(),
+            fn_count=fn_mask.sum(),
+            false_positives=false_positives,
+            false_negatives=false_negatives,
+            high_confidence_fp=high_conf_fp,
+            high_confidence_fn=high_conf_fn,
+            fp_confidence_dist=fp_confidence_dist,
+            fn_confidence_dist=fn_confidence_dist,
+            error_patterns=error_patterns,
+            hypotheses=hypotheses,
+        )
+
+    def _compute_confidence_dist(self, proba: np.ndarray) -> Dict[str, int]:
+        if len(proba) == 0:
+            return {"low": 0, "medium": 0, "high": 0}
+        return {
+            "low": int((proba < 0.4).sum()),
+            "medium": int(((proba >= 0.4) & (proba < 0.7)).sum()),
+            "high": int((proba >= 0.7).sum()),
+        }
+
+    def _find_patterns(self, X: DataFrame, y: Series, y_pred, fp_mask, fn_mask) -> List[ErrorPattern]:
+        patterns = []
+        for col in X.columns:
+            if X[col].dtype in [np.float64, np.int64, np.float32, np.int32]:
+                fp_mean = X.loc[fp_mask, col].mean() if fp_mask.sum() > 0 else 0
+                correct_mean = X.loc[~fp_mask & ~fn_mask, col].mean()
+                if abs(fp_mean - correct_mean) > X[col].std() * 0.5:
+                    patterns.append(ErrorPattern(
+                        error_type="FP",
+                        feature=col,
+                        pattern=f"FPs have {'higher' if fp_mean > correct_mean else 'lower'} {col}",
+                        count=fp_mask.sum(),
+                    ))
+        return patterns
+
+    def _generate_hypotheses(self, fps, fns, high_fp, high_fn) -> List[str]:
+        hypotheses = []
+        if len(high_fp) > 0:
+            hypotheses.append(f"Model is overconfident on {len(high_fp)} false positives. Review these cases.")
+        if len(high_fn) > 0:
+            hypotheses.append(f"Model is overconfident on {len(high_fn)} false negatives. These are high-risk misses.")
+        if len(fps) > len(fns) * 2:
+            hypotheses.append("Model is biased toward positive predictions. Consider raising threshold.")
+        if len(fns) > len(fps) * 2:
+            hypotheses.append("Model is biased toward negative predictions. Consider lowering threshold.")
+        if not hypotheses:
+            hypotheses.append("Error distribution appears balanced. Focus on feature engineering to reduce errors.")
+        return hypotheses

customer_retention/analysis/diagnostics/leakage_detector.py

@@ -0,0 +1,394 @@
+"""Leakage detection probes for model validation."""
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Optional, Set, Tuple
+
+import numpy as np
+from sklearn.linear_model import LogisticRegression
+from sklearn.metrics import roc_auc_score
+from sklearn.model_selection import StratifiedKFold, cross_val_predict
+
+from customer_retention.core.compat import DataFrame, Series, pd
+from customer_retention.core.components.enums import Severity
+from customer_retention.core.utils.leakage import TEMPORAL_METADATA_COLUMNS, calculate_class_overlap
+
+
+@dataclass
+class LeakageCheck:
+    check_id: str
+    feature: str
+    severity: Severity
+    recommendation: str
+    correlation: float = 0.0
+    overlap_pct: float = 100.0
+    auc: float = 0.5
+
+
+@dataclass
+class LeakageResult:
+    passed: bool
+    checks: List[LeakageCheck] = field(default_factory=list)
+    critical_issues: List[LeakageCheck] = field(default_factory=list)
+    recommendations: List[str] = field(default_factory=list)
+
+
+class LeakageDetector:
+    TEMPORAL_PATTERNS = re.compile(r"(days|since|tenure|recency|last|ago|date|time)", re.IGNORECASE)
+    DOMAIN_TARGET_PATTERNS = re.compile(
+        r"(churn|reten|cancel|unsubscribe|attrit|lapse|defect|convert|active|inactive|"
+        r"leave|stay|renew|expir|terminat|close|deactivat)",
+        re.IGNORECASE,
+    )
+    CROSS_ENTITY_PATTERNS = re.compile(
+        r"(global|population|all_user|cross_entity|market_avg|cohort_avg|"
+        r"overall_mean|overall_std|benchmark|percentile_rank)",
+        re.IGNORECASE,
+    )
+    CORRELATION_CRITICAL, CORRELATION_HIGH, CORRELATION_MEDIUM = 0.90, 0.70, 0.50
+    SEPARATION_CRITICAL, SEPARATION_HIGH, SEPARATION_MEDIUM = 0.0, 1.0, 5.0
+    AUC_CRITICAL, AUC_HIGH = 0.90, 0.80
+    CV_FOLDS = 5
+    NUMERIC_DTYPES = (np.float64, np.int64, np.float32, np.int32)
+
+    def __init__(self, feature_timestamp_column: str = "feature_timestamp", label_timestamp_column: str = "label_timestamp"):
+        self.feature_timestamp_column = feature_timestamp_column
+        self.label_timestamp_column = label_timestamp_column
+        self._excluded_columns: Set[str] = set(TEMPORAL_METADATA_COLUMNS)
+
+    def _get_analyzable_columns(self, X: DataFrame) -> List[str]:
+        return [c for c in X.columns if c not in self._excluded_columns]
+
+    def _get_numeric_columns(self, X: DataFrame) -> List[str]:
+        return [c for c in self._get_analyzable_columns(X) if X[c].dtype in self.NUMERIC_DTYPES]
+
+    def _safe_correlation(self, X: DataFrame, col: str, y: Series) -> float:
+        corr = abs(X[col].corr(y))
+        return 0.0 if np.isnan(corr) else corr
+
+    def _build_result(self, checks: List[LeakageCheck]) -> LeakageResult:
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        return LeakageResult(passed=len(critical) == 0, checks=checks, critical_issues=critical)
+
+    def check_correlations(self, X: DataFrame, y: Series) -> LeakageResult:
+        checks = []
+        for col in self._get_numeric_columns(X):
+            corr = self._safe_correlation(X, col, y)
+            severity, check_id = self._classify_correlation(corr)
+            if severity != Severity.INFO:
+                checks.append(LeakageCheck(
+                    check_id=check_id, feature=col, severity=severity,
+                    recommendation=self._correlation_recommendation(col, corr), correlation=corr,
+                ))
+        return self._build_result(checks)
+
+    def _classify_correlation(self, corr: float) -> Tuple[Severity, str]:
+        if corr > self.CORRELATION_CRITICAL:
+            return Severity.CRITICAL, "LD001"
+        if corr > self.CORRELATION_HIGH:
+            return Severity.HIGH, "LD002"
+        if corr > self.CORRELATION_MEDIUM:
+            return Severity.MEDIUM, "LD003"
+        return Severity.INFO, "LD000"
+
+    def _correlation_recommendation(self, feature: str, corr: float) -> str:
+        if corr > self.CORRELATION_CRITICAL:
+            return f"REMOVE {feature}: correlation {corr:.2f} indicates likely data leakage"
+        if corr > self.CORRELATION_HIGH:
+            return f"INVESTIGATE {feature}: correlation {corr:.2f} is suspiciously high"
+        return f"MONITOR {feature}: elevated correlation {corr:.2f}"
+
+    def check_separation(self, X: DataFrame, y: Series) -> LeakageResult:
+        checks = []
+        for col in self._get_numeric_columns(X):
+            overlap_pct = calculate_class_overlap(X[col], y)
+            severity, check_id = self._classify_separation(overlap_pct)
+            checks.append(LeakageCheck(
+                check_id=check_id, feature=col, severity=severity,
+                recommendation=self._separation_recommendation(col, overlap_pct), overlap_pct=overlap_pct,
+            ))
+        return self._build_result(checks)
+
+    def _classify_separation(self, overlap_pct: float) -> Tuple[Severity, str]:
+        if overlap_pct <= self.SEPARATION_CRITICAL:
+            return Severity.CRITICAL, "LD010"
+        if overlap_pct < self.SEPARATION_HIGH:
+            return Severity.HIGH, "LD011"
+        if overlap_pct < self.SEPARATION_MEDIUM:
+            return Severity.MEDIUM, "LD012"
+        return Severity.INFO, "LD000"
+
+    def _separation_recommendation(self, feature: str, overlap_pct: float) -> str:
+        if overlap_pct <= self.SEPARATION_CRITICAL:
+            return f"REMOVE {feature}: perfect class separation indicates leakage"
+        if overlap_pct < self.SEPARATION_HIGH:
+            return f"REMOVE {feature}: near-perfect separation ({overlap_pct:.1f}% overlap)"
+        if overlap_pct < self.SEPARATION_MEDIUM:
+            return f"INVESTIGATE {feature}: high separation ({overlap_pct:.1f}% overlap)"
+        return f"OK: {feature} has normal class overlap"
+
+    def check_temporal_logic(self, X: DataFrame, y: Series) -> LeakageResult:
+        checks = []
+        for col in self._get_numeric_columns(X):
+            if not self.TEMPORAL_PATTERNS.search(col):
+                continue
+            corr = self._safe_correlation(X, col, y)
+            if corr > self.CORRELATION_HIGH:
+                checks.append(LeakageCheck(
+                    check_id="LD022", feature=col, severity=Severity.HIGH,
+                    recommendation=f"REVIEW temporal feature {col}: high correlation ({corr:.2f}) may indicate future data",
+                    correlation=corr,
+                ))
+            elif corr > self.CORRELATION_MEDIUM:
+                checks.append(LeakageCheck(
+                    check_id="LD022", feature=col, severity=Severity.MEDIUM,
+                    recommendation=f"CHECK temporal feature {col}: verify reference date logic", correlation=corr,
+                ))
+        return self._build_result(checks)
+
+    def check_single_feature_auc(self, X: DataFrame, y: Series) -> LeakageResult:
+        checks = []
+        for col in self._get_numeric_columns(X):
+            auc = self._compute_single_feature_auc(X[col], y)
+            is_temporal = bool(self.TEMPORAL_PATTERNS.search(col))
+            severity, check_id = self._classify_auc(auc, is_temporal=is_temporal)
+            if severity != Severity.INFO:
+                checks.append(LeakageCheck(
+                    check_id=check_id, feature=col, severity=severity,
+                    recommendation=self._auc_recommendation(col, auc, is_temporal=is_temporal), auc=auc,
+                ))
+        return self._build_result(checks)
+
+    def _compute_single_feature_auc(self, feature: Series, y: Series) -> float:
+        try:
+            X_single = feature.values.reshape(-1, 1)
+            mask = ~np.isnan(X_single.flatten())
+            X_clean, y_clean = X_single[mask], y.values[mask]
+            if len(np.unique(y_clean)) < 2 or min(np.bincount(y_clean.astype(int))) < self.CV_FOLDS:
+                return 0.5
+            model = LogisticRegression(max_iter=200, solver="lbfgs", random_state=42)
+            cv = StratifiedKFold(n_splits=self.CV_FOLDS, shuffle=True, random_state=42)
+            proba = cross_val_predict(model, X_clean, y_clean, cv=cv, method="predict_proba")
+            return roc_auc_score(y_clean, proba[:, 1])
+        except Exception:
+            return 0.5
+
+    def _classify_auc(self, auc: float, *, is_temporal: bool = False) -> Tuple[Severity, str]:
+        if is_temporal:
+            if auc > self.AUC_CRITICAL:
+                return Severity.HIGH, "LD031"
+            return Severity.INFO, "LD000"
+        if auc > self.AUC_CRITICAL:
+            return Severity.CRITICAL, "LD030"
+        if auc > self.AUC_HIGH:
+            return Severity.HIGH, "LD031"
+        return Severity.INFO, "LD000"
+
+    def _auc_recommendation(self, feature: str, auc: float, *, is_temporal: bool = False) -> str:
+        if auc > self.AUC_CRITICAL:
+            if is_temporal:
+                return f"REVIEW {feature}: temporal feature AUC {auc:.2f} is high but expected for recency/tenure features"
+            return f"REMOVE {feature}: single-feature AUC {auc:.2f} indicates leakage"
+        if auc > self.AUC_HIGH:
+            return f"INVESTIGATE {feature}: single-feature AUC {auc:.2f} is very high"
+        return f"OK: {feature} has normal predictive power"
+
+    def check_point_in_time(self, df: DataFrame) -> LeakageResult:
+        checks = []
+        feature_ts = self._parse_timestamp(df, self.feature_timestamp_column)
+        if feature_ts is None:
+            return self._build_result([])
+
+        self._check_label_timestamp_violation(df, feature_ts, checks)
+        self._check_datetime_column_violations(df, feature_ts, checks)
+        return self._build_result(checks)
+
+    def _parse_timestamp(self, df: DataFrame, col: str) -> Optional[Series]:
+        if col not in df.columns:
+            return None
+        try:
+            return pd.to_datetime(df[col], errors="coerce", format="mixed")
+        except Exception:
+            return None
+
+    def _check_label_timestamp_violation(self, df: DataFrame, feature_ts: Series, checks: List[LeakageCheck]) -> None:
+        label_ts = self._parse_timestamp(df, self.label_timestamp_column)
+        if label_ts is None:
+            return
+        violations = (feature_ts > label_ts).sum()
+        if violations > 0:
+            checks.append(LeakageCheck(
+                check_id="LD040", feature=self.feature_timestamp_column, severity=Severity.CRITICAL,
+                recommendation=f"FIX: {violations} rows have feature_timestamp > label_timestamp",
+            ))
+
+    def _check_datetime_column_violations(self, df: DataFrame, feature_ts: Series, checks: List[LeakageCheck]) -> None:
+        skip_cols = {self.feature_timestamp_column, self.label_timestamp_column}
+        for col in df.select_dtypes(include=["datetime64"]).columns:
+            if col in skip_cols:
+                continue
+            try:
+                col_ts = pd.to_datetime(df[col], errors="coerce", format="mixed")
+                violations = (col_ts > feature_ts).sum()
+                if violations > 0:
+                    pct = violations / len(df) * 100
+                    checks.append(LeakageCheck(
+                        check_id="LD041", feature=col,
+                        severity=Severity.CRITICAL if pct > 5 else Severity.HIGH,
+                        recommendation=f"INVESTIGATE {col}: {violations} rows ({pct:.1f}%) have values after feature_timestamp",
+                    ))
+            except Exception:
+                continue
+
+    def check_uniform_timestamps(self, df: DataFrame, timestamp_column: str = "event_timestamp") -> LeakageResult:
+        checks = []
+        if timestamp_column not in df.columns:
+            return self._build_result([])
+
+        try:
+            timestamps = pd.to_datetime(df[timestamp_column], errors="coerce").dropna()
+            if len(timestamps) < 2:
+                return self._build_result([])
+
+            if timestamps.nunique() == 1:
+                checks.append(LeakageCheck(
+                    check_id="LD050", feature=timestamp_column, severity=Severity.HIGH,
+                    recommendation=(
+                        f"INVESTIGATE {timestamp_column}: All {len(timestamps)} timestamps are identical. "
+                        "This suggests datetime.now() was used instead of actual aggregation reference dates."
+                    ),
+                ))
+            elif (timestamps.max() - timestamps.min()).total_seconds() < 60:
+                time_span = (timestamps.max() - timestamps.min()).total_seconds()
+                checks.append(LeakageCheck(
+                    check_id="LD050", feature=timestamp_column, severity=Severity.MEDIUM,
+                    recommendation=(
+                        f"REVIEW {timestamp_column}: Timestamps span only {time_span:.1f} seconds across "
+                        f"{len(timestamps)} records. Verify timestamps reflect actual observation dates."
+                    ),
+                ))
+        except Exception:
+            pass
+        return self._build_result(checks)
+
+    def check_target_in_features(self, X: DataFrame, y: Series, target_name: str = "target") -> LeakageResult:
+        checks = []
+        self._check_target_column_direct(X, target_name, checks)
+        self._check_target_derived_names(X, target_name, checks)
+        self._check_perfect_correlation(X, y, target_name, checks)
+        return self._build_result(checks)
+
+    def _check_target_column_direct(self, X: DataFrame, target_name: str, checks: List[LeakageCheck]) -> None:
+        if target_name in X.columns:
+            checks.append(LeakageCheck(
+                check_id="LD052", feature=target_name, severity=Severity.CRITICAL,
+                recommendation=f"REMOVE {target_name}: Target column found in feature matrix. Direct data leakage.",
+                correlation=1.0,
+            ))
+
+    def _check_target_derived_names(self, X: DataFrame, target_name: str, checks: List[LeakageCheck]) -> None:
+        patterns = [f"{target_name}_", f"_{target_name}"]
+        for col in X.columns:
+            col_lower = col.lower()
+            if any(p.lower() in col_lower for p in patterns):
+                checks.append(LeakageCheck(
+                    check_id="LD052", feature=col, severity=Severity.CRITICAL,
+                    recommendation=f"REMOVE {col}: Column name suggests derivation from target '{target_name}'.",
+                ))
+
+    def _check_perfect_correlation(self, X: DataFrame, y: Series, target_name: str, checks: List[LeakageCheck]) -> None:
+        already_flagged = {target_name} | {c.feature for c in checks}
+        for col in self._get_numeric_columns(X):
+            if col in already_flagged:
+                continue
+            try:
+                corr = abs(X[col].corr(y))
+                if not np.isnan(corr) and corr > 0.99:
+                    checks.append(LeakageCheck(
+                        check_id="LD052", feature=col, severity=Severity.CRITICAL,
+                        recommendation=f"REMOVE {col}: Perfect correlation ({corr:.4f}) indicates leakage.",
+                        correlation=corr,
+                    ))
+            except Exception:
+                pass
+
+    def check_cross_entity_leakage(self, X: DataFrame, y: Series, entity_column: str, timestamp_column: str) -> LeakageResult:
+        checks = []
+        for col in self._get_numeric_columns(X):
+            if not self.CROSS_ENTITY_PATTERNS.search(col):
+                continue
+            corr = self._safe_correlation(X, col, y)
+            severity = Severity.HIGH if corr > self.CORRELATION_MEDIUM else Severity.MEDIUM
+            checks.append(LeakageCheck(
+                check_id="LD060", feature=col, severity=severity,
+                recommendation=(
+                    f"REVIEW {col}: Cross-entity aggregation pattern detected. Correlation: {corr:.2f}. "
+                    "Verify this feature doesn't use future data from other entities."
+                ),
+                correlation=corr,
+            ))
+        return self._build_result(checks)
+
+    def check_temporal_split(self, train_timestamps: Series, test_timestamps: Series, timestamp_column: str = "timestamp") -> LeakageResult:
+        checks = []
+        try:
+            train_ts = pd.to_datetime(train_timestamps, errors="coerce").dropna()
+            test_ts = pd.to_datetime(test_timestamps, errors="coerce").dropna()
+            if len(train_ts) == 0 or len(test_ts) == 0:
+                return self._build_result([])
+
+            train_max, test_min = train_ts.max(), test_ts.min()
+            if train_max >= test_min:
+                overlap_count = (train_ts >= test_min).sum()
+                overlap_pct = overlap_count / len(train_ts) * 100
+                checks.append(LeakageCheck(
+                    check_id="LD061", feature=timestamp_column, severity=Severity.CRITICAL,
+                    recommendation=(
+                        f"FIX temporal split: Train max ({train_max}) >= Test min ({test_min}). "
+                        f"{overlap_count} train rows ({overlap_pct:.1f}%) overlap with test period."
+                    ),
+                ))
+        except Exception:
+            pass
+        return self._build_result(checks)
+
+    def check_domain_target_patterns(self, X: DataFrame, y: Series) -> LeakageResult:
+        checks = []
+        for col in self._get_numeric_columns(X):
+            if not self.DOMAIN_TARGET_PATTERNS.search(col):
+                continue
+            corr = self._safe_correlation(X, col, y)
+            severity, recommendation = self._classify_domain_pattern(col, corr)
+            checks.append(LeakageCheck(
+                check_id="LD053", feature=col, severity=severity,
+                recommendation=recommendation, correlation=corr,
+            ))
+        return self._build_result(checks)
+
+    def _classify_domain_pattern(self, col: str, corr: float) -> Tuple[Severity, str]:
+        if corr > self.CORRELATION_HIGH:
+            return Severity.CRITICAL, f"REMOVE {col}: Domain pattern with high correlation ({corr:.2f}) confirms likely leakage."
+        if corr > self.CORRELATION_MEDIUM:
+            return Severity.HIGH, f"INVESTIGATE {col}: Domain pattern with correlation ({corr:.2f}) warrants review."
+        return Severity.MEDIUM, f"REVIEW {col}: Contains churn/retention terminology. Low correlation ({corr:.2f}) suggests safe."
+
+    def run_all_checks(self, X: DataFrame, y: Series, include_pit: bool = True) -> LeakageResult:
+        all_checks = (
+            self.check_correlations(X, y).checks
+            + self.check_separation(X, y).checks
+            + self.check_temporal_logic(X, y).checks
+            + self.check_single_feature_auc(X, y).checks
+        )
+
+        if include_pit:
+            df_with_y = X.copy()
+            df_with_y["_target"] = y
+            all_checks.extend(self.check_point_in_time(df_with_y).checks)
+            all_checks.extend(self.check_uniform_timestamps(df_with_y, timestamp_column=self.feature_timestamp_column).checks)
+
+        all_checks.extend(self.check_target_in_features(X, y).checks)
+        all_checks.extend(self.check_domain_target_patterns(X, y).checks)
+
+        critical = [c for c in all_checks if c.severity == Severity.CRITICAL]
+        recommendations = list({c.recommendation for c in all_checks if c.severity in [Severity.CRITICAL, Severity.HIGH]})
+        return LeakageResult(passed=len(critical) == 0, checks=all_checks, critical_issues=critical, recommendations=recommendations)

customer_retention/analysis/diagnostics/noise_tester.py

@@ -0,0 +1,140 @@
+"""Noise robustness testing probes."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+import numpy as np
+from sklearn.metrics import roc_auc_score
+
+from customer_retention.core.compat import DataFrame, Series
+from customer_retention.core.components.enums import Severity
+
+
+@dataclass
+class NoiseCheck:
+    check_id: str
+    metric: str
+    severity: Severity
+    recommendation: str
+    value: float = 0.0
+
+
+@dataclass
+class NoiseResult:
+    passed: bool
+    checks: List[NoiseCheck] = field(default_factory=list)
+    degradation_curve: List[Dict[str, float]] = field(default_factory=list)
+    robustness_score: float = 1.0
+    feature_importance: Dict[str, float] = field(default_factory=dict)
+
+
+class NoiseTester:
+    NOISE_LEVELS = {"low": 0.01, "medium": 0.05, "high": 0.10, "extreme": 0.20}
+    DROPOUT_LEVELS = {"low": 0.05, "medium": 0.10, "high": 0.20, "extreme": 0.30}
+    DEGRADATION_LOW_THRESHOLD = 0.10
+    DEGRADATION_MEDIUM_THRESHOLD = 0.20
+
+    def test_gaussian_noise(self, model, X: DataFrame, y: Series) -> NoiseResult:
+        baseline_score = self._get_score(model, X, y)
+        degradation_curve = []
+        checks = []
+        for level_name, noise_factor in self.NOISE_LEVELS.items():
+            X_noisy = X.copy()
+            for col in X.columns:
+                if X[col].dtype in [np.float64, np.int64, np.float32, np.int32]:
+                    std = X[col].std()
+                    X_noisy[col] = X[col] + np.random.randn(len(X)) * std * noise_factor
+            noisy_score = self._get_score(model, X_noisy, y)
+            degradation = (baseline_score - noisy_score) / baseline_score if baseline_score > 0 else 0
+            degradation_curve.append({
+                "noise_level": level_name,
+                "noise_factor": noise_factor,
+                "score": noisy_score,
+                "degradation": degradation,
+            })
+            if level_name == "low" and degradation > self.DEGRADATION_LOW_THRESHOLD:
+                checks.append(NoiseCheck(
+                    check_id="NR001",
+                    metric="degradation_low_noise",
+                    severity=Severity.HIGH,
+                    recommendation=f"HIGH: Model fragile to low noise ({degradation:.1%} degradation). Consider regularization.",
+                    value=degradation,
+                ))
+            if level_name == "medium" and degradation > self.DEGRADATION_MEDIUM_THRESHOLD:
+                checks.append(NoiseCheck(
+                    check_id="NR002",
+                    metric="degradation_medium_noise",
+                    severity=Severity.MEDIUM,
+                    recommendation=f"MEDIUM: Model moderately fragile ({degradation:.1%} at medium noise).",
+                    value=degradation,
+                ))
+        robustness_score = self._compute_robustness(degradation_curve)
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        return NoiseResult(passed=len(critical) == 0, checks=checks, degradation_curve=degradation_curve, robustness_score=robustness_score)
+
+    def test_feature_dropout(self, model, X: DataFrame, y: Series) -> NoiseResult:
+        baseline_score = self._get_score(model, X, y)
+        degradation_curve = []
+        feature_importance = {}
+        for col in X.columns:
+            X_dropped = X.copy()
+            X_dropped[col] = 0
+            dropped_score = self._get_score(model, X_dropped, y)
+            importance = (baseline_score - dropped_score) / baseline_score if baseline_score > 0 else 0
+            feature_importance[col] = importance
+        checks = []
+        max_importance = max(feature_importance.values()) if feature_importance else 0
+        if max_importance > 0.5:
+            dominant_feature = max(feature_importance, key=feature_importance.get)
+            checks.append(NoiseCheck(
+                check_id="NR003",
+                metric="single_feature_dependency",
+                severity=Severity.HIGH,
+                recommendation=f"HIGH: Feature '{dominant_feature}' causes {max_importance:.1%} degradation when dropped. Model too dependent.",
+                value=max_importance,
+            ))
+        for level_name, dropout_rate in self.DROPOUT_LEVELS.items():
+            X_dropout = X.copy()
+            n_drop = int(len(X.columns) * dropout_rate)
+            cols_to_drop = np.random.choice(X.columns, min(n_drop, len(X.columns)), replace=False)
+            for col in cols_to_drop:
+                X_dropout[col] = 0
+            dropout_score = self._get_score(model, X_dropout, y)
+            degradation = (baseline_score - dropout_score) / baseline_score if baseline_score > 0 else 0
+            degradation_curve.append({
+                "dropout_level": level_name,
+                "dropout_rate": dropout_rate,
+                "score": dropout_score,
+                "degradation": degradation,
+            })
+        robustness_score = self._compute_robustness(degradation_curve)
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        return NoiseResult(passed=len(critical) == 0, checks=checks, degradation_curve=degradation_curve, robustness_score=robustness_score, feature_importance=feature_importance)
+
+    def _get_score(self, model, X: DataFrame, y: Series) -> float:
+        try:
+            y_proba = model.predict_proba(X)[:, 1]
+            return roc_auc_score(y, y_proba)
+        except Exception:
+            return 0.5
+
+    def _compute_robustness(self, degradation_curve: List[Dict]) -> float:
+        if not degradation_curve:
+            return 1.0
+        degradations = [d.get("degradation", 0) for d in degradation_curve]
+        return max(0, 1 - np.mean(degradations))
+
+    def run_all(self, model, X: DataFrame, y: Series) -> NoiseResult:
+        gaussian_result = self.test_gaussian_noise(model, X, y)
+        dropout_result = self.test_feature_dropout(model, X, y)
+        all_checks = gaussian_result.checks + dropout_result.checks
+        all_degradation = gaussian_result.degradation_curve + dropout_result.degradation_curve
+        avg_robustness = (gaussian_result.robustness_score + dropout_result.robustness_score) / 2
+        critical = [c for c in all_checks if c.severity == Severity.CRITICAL]
+        return NoiseResult(
+            passed=len(critical) == 0,
+            checks=all_checks,
+            degradation_curve=all_degradation,
+            robustness_score=avg_robustness,
+            feature_importance=dropout_result.feature_importance,
+        )