churnkit 0.75.0a1__py3-none-any.whl

customer_retention/analysis/business/risk_profile.py

@@ -0,0 +1,199 @@
+"""Customer risk profiling."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, List, Optional
+
+import numpy as np
+import shap
+
+from customer_retention.core.compat import DataFrame, Series
+from customer_retention.core.components.enums import RiskSegment
+
+
+class Urgency(Enum):
+    IMMEDIATE = "Immediate"
+    THIS_WEEK = "This Week"
+    THIS_MONTH = "This Month"
+    MONITOR = "Monitor"
+
+
+@dataclass
+class RiskFactor:
+    factor_name: str
+    current_value: str
+    comparison: str
+    impact: str
+    actionable: bool
+    suggested_action: str = ""
+
+
+@dataclass
+class Intervention:
+    intervention_type: str
+    description: str
+    estimated_cost: float
+    estimated_success_rate: float
+    expected_roi: float
+    priority: int
+    reasoning: str
+    channel: str
+    timing: str
+
+
+@dataclass
+class CustomerRiskProfile:
+    customer_id: Optional[str]
+    churn_probability: float
+    risk_segment: RiskSegment
+    confidence: str
+    risk_factors: List[RiskFactor]
+    recommended_interventions: List[Intervention]
+    expected_ltv_if_retained: float
+    expected_ltv_if_churned: float
+    intervention_roi_estimate: float
+    urgency: Urgency
+    days_until_likely_churn: Optional[int] = None
+
+
+class RiskProfiler:
+    SEGMENT_THRESHOLDS = [(0.80, RiskSegment.CRITICAL), (0.60, RiskSegment.HIGH),
+                         (0.40, RiskSegment.MEDIUM), (0.20, RiskSegment.LOW)]
+    INTERVENTION_CATALOG = [
+        {"name": "email_campaign", "cost": 2, "success_rate": 0.10, "channel": "email",
+         "segments": [RiskSegment.LOW, RiskSegment.MEDIUM]},
+        {"name": "phone_call", "cost": 15, "success_rate": 0.25, "channel": "phone",
+         "segments": [RiskSegment.MEDIUM, RiskSegment.HIGH]},
+        {"name": "discount_offer", "cost": 25, "success_rate": 0.35, "channel": "email",
+         "segments": [RiskSegment.HIGH, RiskSegment.CRITICAL]},
+        {"name": "account_manager", "cost": 150, "success_rate": 0.60, "channel": "personal",
+         "segments": [RiskSegment.CRITICAL]},
+    ]
+
+    def __init__(self, model: Any, background_data: DataFrame,
+                 actionable_features: Optional[List[str]] = None,
+                 avg_customer_ltv: float = 500, max_samples: int = 100):
+        self.model = model
+        self.background_data = background_data.head(max_samples)
+        self.actionable_features = actionable_features or []
+        self.avg_ltv = avg_customer_ltv
+        self.feature_names = list(background_data.columns)
+        self._explainer = self._create_explainer()
+
+    def _create_explainer(self) -> shap.Explainer:
+        model_type = type(self.model).__name__
+        if model_type in ["RandomForestClassifier", "GradientBoostingClassifier"]:
+            return shap.TreeExplainer(self.model)
+        return shap.KernelExplainer(self.model.predict_proba, self.background_data)
+
+    def generate_profile(self, instance: Series,
+                         customer_id: Optional[str] = None) -> CustomerRiskProfile:
+        instance_df = instance.to_frame().T
+        churn_prob = float(self.model.predict_proba(instance_df)[0, 1])
+        segment = self._assign_segment(churn_prob)
+        confidence = self._assess_confidence(churn_prob)
+        risk_factors = self._extract_risk_factors(instance)
+        interventions = self._match_interventions(segment, churn_prob)
+        ltv_retained = self.avg_ltv
+        ltv_churned = self.avg_ltv * 0.1
+        best_intervention = interventions[0] if interventions else None
+        roi = best_intervention.expected_roi if best_intervention else 0
+        urgency = self._assign_urgency(segment)
+        return CustomerRiskProfile(
+            customer_id=customer_id,
+            churn_probability=churn_prob,
+            risk_segment=segment,
+            confidence=confidence,
+            risk_factors=risk_factors,
+            recommended_interventions=interventions,
+            expected_ltv_if_retained=ltv_retained,
+            expected_ltv_if_churned=ltv_churned,
+            intervention_roi_estimate=roi,
+            urgency=urgency
+        )
+
+    def _assign_segment(self, probability: float) -> RiskSegment:
+        for threshold, segment in self.SEGMENT_THRESHOLDS:
+            if probability >= threshold:
+                return segment
+        return RiskSegment.VERY_LOW
+
+    def _assess_confidence(self, probability: float) -> str:
+        if probability < 0.2 or probability > 0.8:
+            return "High"
+        if 0.4 < probability < 0.6:
+            return "Low"
+        return "Medium"
+
+    def _extract_risk_factors(self, instance: Series) -> List[RiskFactor]:
+        instance_df = instance.to_frame().T
+        shap_values = self._extract_shap_values(instance_df)
+        sorted_indices = np.argsort(np.abs(shap_values))[::-1]
+        factors = []
+        for idx in sorted_indices[:5]:
+            feature = self.feature_names[idx]
+            value = instance[feature]
+            impact_pct = abs(shap_values[idx]) * 100
+            direction = "increases" if shap_values[idx] > 0 else "decreases"
+            factors.append(RiskFactor(
+                factor_name=feature,
+                current_value=f"{value:.2f}" if isinstance(value, float) else str(value),
+                comparison=f"vs avg {self.background_data[feature].mean():.2f}",
+                impact=f"{direction} risk by {impact_pct:.1f}%",
+                actionable=feature in self.actionable_features,
+                suggested_action=f"Improve {feature}" if feature in self.actionable_features else ""
+            ))
+        return factors
+
+    def _extract_shap_values(self, X: DataFrame) -> np.ndarray:
+        shap_values = self._explainer.shap_values(X)
+        if hasattr(shap_values, 'values'):
+            shap_values = shap_values.values
+        if isinstance(shap_values, list):
+            shap_values = shap_values[1]
+        if len(shap_values.shape) == 3:
+            shap_values = shap_values[:, :, 1]
+        return shap_values.flatten()
+
+    def _match_interventions(self, segment: RiskSegment, churn_prob: float) -> List[Intervention]:
+        applicable = [i for i in self.INTERVENTION_CATALOG if segment in i["segments"]]
+        interventions = []
+        for item in applicable:
+            expected_saves = churn_prob * item["success_rate"]
+            revenue_saved = expected_saves * self.avg_ltv
+            roi = (revenue_saved - item["cost"]) / item["cost"] if item["cost"] > 0 else 0
+            interventions.append(Intervention(
+                intervention_type=item["name"],
+                description=f"{item['name'].replace('_', ' ').title()} via {item['channel']}",
+                estimated_cost=item["cost"],
+                estimated_success_rate=item["success_rate"],
+                expected_roi=roi,
+                priority=self._get_priority(segment),
+                reasoning=f"Recommended for {segment.value} risk customers",
+                channel=item["channel"],
+                timing="Within 24 hours" if segment == RiskSegment.CRITICAL else "Within 1 week"
+            ))
+        return sorted(interventions, key=lambda x: x.expected_roi, reverse=True)
+
+    def _get_priority(self, segment: RiskSegment) -> int:
+        priorities = {RiskSegment.CRITICAL: 1, RiskSegment.HIGH: 2,
+                      RiskSegment.MEDIUM: 3, RiskSegment.LOW: 4, RiskSegment.VERY_LOW: 5}
+        return priorities.get(segment, 5)
+
+    def _assign_urgency(self, segment: RiskSegment) -> Urgency:
+        urgency_map = {
+            RiskSegment.CRITICAL: Urgency.IMMEDIATE,
+            RiskSegment.HIGH: Urgency.THIS_WEEK,
+            RiskSegment.MEDIUM: Urgency.THIS_MONTH,
+            RiskSegment.LOW: Urgency.MONITOR,
+            RiskSegment.VERY_LOW: Urgency.MONITOR
+        }
+        return urgency_map.get(segment, Urgency.MONITOR)
+
+    def generate_batch(self, X: DataFrame, customer_ids: Optional[List[str]] = None,
+                       sort_by_risk: bool = False) -> List[CustomerRiskProfile]:
+        customer_ids = customer_ids or [None] * len(X)
+        profiles = [self.generate_profile(X.iloc[i], customer_ids[i]) for i in range(len(X))]
+        if sort_by_risk:
+            profiles.sort(key=lambda p: p.churn_probability, reverse=True)
+        return profiles

customer_retention/analysis/business/roi_analyzer.py

@@ -0,0 +1,139 @@
+"""ROI analysis for retention interventions."""
+
+from dataclasses import dataclass
+from typing import Dict, List
+
+
+@dataclass
+class InterventionROI:
+    intervention: str
+    targeted_customers: int
+    actual_churners: float
+    customers_saved: float
+    total_cost: float
+    revenue_saved: float
+    net_benefit: float
+    roi_pct: float
+
+
+@dataclass
+class OptimizationResult:
+    allocations: Dict[str, Dict[str, any]]
+    total_cost: float
+    total_saves: float
+    total_revenue: float
+    overall_roi: float
+
+
+@dataclass
+class ROIResult:
+    intervention_rois: List[InterventionROI]
+    best_intervention: str
+    best_roi: float
+
+
+class ROIAnalyzer:
+    def __init__(self, avg_ltv: float, intervention_costs: Dict[str, float],
+                 success_rates: Dict[str, float]):
+        self.avg_ltv = avg_ltv
+        self.intervention_costs = intervention_costs
+        self.success_rates = success_rates
+
+    def calculate_roi(self, intervention: str, targeted_customers: int,
+                      actual_churn_rate: float) -> InterventionROI:
+        cost = self.intervention_costs.get(intervention, 0)
+        success_rate = self.success_rates.get(intervention, 0)
+        actual_churners = targeted_customers * actual_churn_rate
+        customers_saved = actual_churners * success_rate
+        revenue_saved = customers_saved * self.avg_ltv
+        total_cost = targeted_customers * cost
+        net_benefit = revenue_saved - total_cost
+        roi_pct = (net_benefit / total_cost * 100) if total_cost > 0 else 0
+        return InterventionROI(
+            intervention=intervention,
+            targeted_customers=targeted_customers,
+            actual_churners=actual_churners,
+            customers_saved=customers_saved,
+            total_cost=total_cost,
+            revenue_saved=revenue_saved,
+            net_benefit=net_benefit,
+            roi_pct=roi_pct
+        )
+
+    def analyze_all_interventions(self, targeted_customers: int,
+                                  actual_churn_rate: float) -> List[InterventionROI]:
+        results = [self.calculate_roi(intervention, targeted_customers, actual_churn_rate)
+                   for intervention in self.intervention_costs.keys()]
+        return sorted(results, key=lambda r: r.roi_pct, reverse=True)
+
+    def compare_interventions(self, targeted_customers: int,
+                              actual_churn_rate: float) -> List[InterventionROI]:
+        return self.analyze_all_interventions(targeted_customers, actual_churn_rate)
+
+    def analyze_by_segment(self, segment_data: Dict[str, Dict]) -> Dict[str, List[InterventionROI]]:
+        results = {}
+        for segment, data in segment_data.items():
+            customers = data["customers"]
+            churn_rate = data["churn_rate"]
+            results[segment] = self.analyze_all_interventions(customers, churn_rate)
+        return results
+
+    def optimize_budget(self, segment_data: Dict[str, Dict], total_budget: float,
+                        objective: str = "maximize_roi") -> OptimizationResult:
+        all_options = []
+        for segment, data in segment_data.items():
+            customers = data["customers"]
+            churn_rate = data["churn_rate"]
+            for intervention in self.intervention_costs.keys():
+                cost_per = self.intervention_costs[intervention]
+                success_rate = self.success_rates[intervention]
+                all_options.append({
+                    "segment": segment,
+                    "intervention": intervention,
+                    "customers": customers,
+                    "churn_rate": churn_rate,
+                    "cost_per": cost_per,
+                    "success_rate": success_rate,
+                    "total_cost": customers * cost_per,
+                    "expected_saves": customers * churn_rate * success_rate,
+                    "expected_revenue": customers * churn_rate * success_rate * self.avg_ltv
+                })
+        for opt in all_options:
+            if opt["total_cost"] > 0:
+                opt["roi"] = (opt["expected_revenue"] - opt["total_cost"]) / opt["total_cost"]
+            else:
+                opt["roi"] = 0
+        if objective == "maximize_roi":
+            all_options.sort(key=lambda x: x["roi"], reverse=True)
+        else:
+            all_options.sort(key=lambda x: x["expected_saves"], reverse=True)
+        allocations = {}
+        remaining_budget = total_budget
+        total_saves = 0
+        total_revenue = 0
+        total_cost = 0
+        for opt in all_options:
+            if opt["total_cost"] <= remaining_budget and opt["segment"] not in allocations:
+                allocations[opt["segment"]] = {
+                    "intervention": opt["intervention"],
+                    "customers": opt["customers"],
+                    "cost": opt["total_cost"],
+                    "expected_saves": opt["expected_saves"],
+                    "expected_revenue": opt["expected_revenue"]
+                }
+                remaining_budget -= opt["total_cost"]
+                total_saves += opt["expected_saves"]
+                total_revenue += opt["expected_revenue"]
+                total_cost += opt["total_cost"]
+        overall_roi = (total_revenue - total_cost) / total_cost if total_cost > 0 else 0
+        return OptimizationResult(
+            allocations=allocations,
+            total_cost=total_cost,
+            total_saves=total_saves,
+            total_revenue=total_revenue,
+            overall_roi=overall_roi
+        )
+
+    def run_scenarios(self, intervention: str, targeted_customers: int,
+                      churn_rates: List[float]) -> List[InterventionROI]:
+        return [self.calculate_roi(intervention, targeted_customers, rate) for rate in churn_rates]

customer_retention/analysis/diagnostics/__init__.py

@@ -0,0 +1,20 @@
+from customer_retention.core.components.enums import Severity
+
+from .calibration_analyzer import CalibrationAnalyzer, CalibrationCheck, CalibrationResult
+from .cv_analyzer import CVAnalysisResult, CVAnalyzer, CVCheck
+from .error_analyzer import ErrorAnalysisResult, ErrorAnalyzer, ErrorPattern
+from .leakage_detector import LeakageCheck, LeakageDetector, LeakageResult
+from .noise_tester import NoiseResult, NoiseTester
+from .overfitting_analyzer import OverfittingAnalyzer, OverfittingCheck, OverfittingResult
+from .segment_analyzer import SegmentCheck, SegmentPerformanceAnalyzer, SegmentResult
+
+__all__ = [
+    "Severity",
+    "LeakageDetector", "LeakageResult", "LeakageCheck",
+    "OverfittingAnalyzer", "OverfittingResult", "OverfittingCheck",
+    "CVAnalyzer", "CVAnalysisResult", "CVCheck",
+    "SegmentPerformanceAnalyzer", "SegmentResult", "SegmentCheck",
+    "CalibrationAnalyzer", "CalibrationResult", "CalibrationCheck",
+    "ErrorAnalyzer", "ErrorAnalysisResult", "ErrorPattern",
+    "NoiseTester", "NoiseResult",
+]

customer_retention/analysis/diagnostics/calibration_analyzer.py

@@ -0,0 +1,133 @@
+"""Calibration analysis probes for model validation."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+import numpy as np
+
+from customer_retention.core.components.enums import Severity
+
+
+@dataclass
+class CalibrationCheck:
+    check_id: str
+    metric: str
+    severity: Severity
+    recommendation: str
+    value: float = 0.0
+
+
+@dataclass
+class CalibrationResult:
+    passed: bool
+    checks: List[CalibrationCheck] = field(default_factory=list)
+    brier_score: float = 0.0
+    ece: float = 0.0
+    mce: float = 0.0
+    reliability_data: List[Dict[str, float]] = field(default_factory=list)
+    recommendation: str = ""
+
+
+class CalibrationAnalyzer:
+    BRIER_HIGH = 0.20
+    BRIER_MEDIUM = 0.15
+    ECE_HIGH = 0.10
+    MCE_HIGH = 0.30
+    N_BINS = 10
+
+    def analyze_brier(self, y_true: np.ndarray, y_proba: np.ndarray) -> CalibrationResult:
+        brier = np.mean((y_proba - y_true) ** 2)
+        checks = []
+        severity, check_id = self._classify_brier(brier)
+        if severity != Severity.INFO:
+            checks.append(CalibrationCheck(
+                check_id=check_id,
+                metric="brier_score",
+                severity=severity,
+                recommendation=self._brier_recommendation(brier),
+                value=brier,
+            ))
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        return CalibrationResult(passed=len(critical) == 0, checks=checks, brier_score=brier)
+
+    def _classify_brier(self, brier: float) -> tuple:
+        if brier > self.BRIER_HIGH:
+            return Severity.HIGH, "CA001"
+        if brier > self.BRIER_MEDIUM:
+            return Severity.MEDIUM, "CA002"
+        return Severity.INFO, "CA000"
+
+    def _brier_recommendation(self, brier: float) -> str:
+        if brier > self.BRIER_HIGH:
+            return f"HIGH: Brier score {brier:.3f} is poor. Apply calibration (Platt scaling or isotonic)."
+        if brier > self.BRIER_MEDIUM:
+            return f"MEDIUM: Brier score {brier:.3f} is moderate. Consider calibration."
+        return f"OK: Brier score {brier:.3f} is acceptable."
+
+    def analyze_calibration(self, y_true: np.ndarray, y_proba: np.ndarray) -> CalibrationResult:
+        brier = np.mean((y_proba - y_true) ** 2)
+        reliability_data, ece, mce = self._compute_reliability(y_true, y_proba)
+        checks = []
+        brier_severity, brier_id = self._classify_brier(brier)
+        if brier_severity != Severity.INFO:
+            checks.append(CalibrationCheck(
+                check_id=brier_id, metric="brier_score", severity=brier_severity,
+                recommendation=self._brier_recommendation(brier), value=brier,
+            ))
+        if ece > self.ECE_HIGH:
+            checks.append(CalibrationCheck(
+                check_id="CA003", metric="ece", severity=Severity.MEDIUM,
+                recommendation=f"MEDIUM: ECE {ece:.3f} is high. Calibration recommended.", value=ece,
+            ))
+        if mce > self.MCE_HIGH:
+            checks.append(CalibrationCheck(
+                check_id="CA004", metric="mce", severity=Severity.HIGH,
+                recommendation=f"HIGH: MCE {mce:.3f} is extreme. Some probability bins are very miscalibrated.", value=mce,
+            ))
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        recommendation = self._global_recommendation(reliability_data, brier, ece)
+        return CalibrationResult(
+            passed=len(critical) == 0,
+            checks=checks,
+            brier_score=brier,
+            ece=ece,
+            mce=mce,
+            reliability_data=reliability_data,
+            recommendation=recommendation,
+        )
+
+    def _compute_reliability(self, y_true: np.ndarray, y_proba: np.ndarray) -> tuple:
+        bin_edges = np.linspace(0, 1, self.N_BINS + 1)
+        reliability_data = []
+        ece_sum = 0.0
+        mce = 0.0
+        for i in range(self.N_BINS):
+            mask = (y_proba >= bin_edges[i]) & (y_proba < bin_edges[i + 1])
+            if i == self.N_BINS - 1:
+                mask = (y_proba >= bin_edges[i]) & (y_proba <= bin_edges[i + 1])
+            if mask.sum() > 0:
+                predicted = y_proba[mask].mean()
+                actual = y_true[mask].mean()
+                bin_size = mask.sum()
+                reliability_data.append({
+                    "bin": i,
+                    "predicted_prob": float(predicted),
+                    "actual_prob": float(actual),
+                    "count": int(bin_size),
+                })
+                error = abs(predicted - actual)
+                ece_sum += error * bin_size
+                mce = max(mce, error)
+        ece = ece_sum / len(y_true) if len(y_true) > 0 else 0.0
+        return reliability_data, ece, mce
+
+    def _global_recommendation(self, reliability_data: List[Dict], brier: float, ece: float) -> str:
+        if brier < 0.10 and ece < 0.05:
+            return "Well calibrated. No action needed."
+        above_diagonal = sum(1 for b in reliability_data if b["predicted_prob"] > b["actual_prob"] + 0.05)
+        below_diagonal = sum(1 for b in reliability_data if b["predicted_prob"] < b["actual_prob"] - 0.05)
+        if above_diagonal > below_diagonal:
+            return "Overconfident predictions. Apply Platt scaling."
+        if below_diagonal > above_diagonal:
+            return "Underconfident predictions. Consider isotonic regression."
+        return "Apply CalibratedClassifierCV for general calibration improvement."

customer_retention/analysis/diagnostics/cv_analyzer.py

@@ -0,0 +1,144 @@
+"""Cross-validation stability analysis probes."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+import numpy as np
+
+from customer_retention.core.components.enums import Severity
+
+
+@dataclass
+class CVCheck:
+    check_id: str
+    metric: str
+    severity: Severity
+    recommendation: str
+    value: float = 0.0
+
+
+@dataclass
+class CVAnalysisResult:
+    passed: bool
+    checks: List[CVCheck] = field(default_factory=list)
+    cv_mean: float = 0.0
+    cv_std: float = 0.0
+    fold_analysis: List[Dict[str, float]] = field(default_factory=list)
+    best_worst_gap: float = 0.0
+    outlier_folds: List[int] = field(default_factory=list)
+    recommendations: List[str] = field(default_factory=list)
+
+
+class CVAnalyzer:
+    STD_CRITICAL = 0.15
+    STD_HIGH = 0.10
+    STD_MEDIUM = 0.05
+    CV_TEST_HIGH = 0.10
+    CV_TEST_MEDIUM = -0.10
+
+    def analyze_variance(self, cv_scores: List[float]) -> CVAnalysisResult:
+        cv_mean = np.mean(cv_scores)
+        cv_std = np.std(cv_scores)
+        checks = []
+        severity, check_id = self._classify_variance(cv_std)
+        checks.append(CVCheck(
+            check_id=check_id,
+            metric="cv_std",
+            severity=severity,
+            recommendation=self._variance_recommendation(cv_std),
+            value=cv_std,
+        ))
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        return CVAnalysisResult(passed=len(critical) == 0, checks=checks, cv_mean=cv_mean, cv_std=cv_std)
+
+    def _classify_variance(self, cv_std: float) -> tuple:
+        if cv_std > self.STD_CRITICAL:
+            return Severity.CRITICAL, "CV001"
+        if cv_std > self.STD_HIGH:
+            return Severity.HIGH, "CV002"
+        if cv_std > self.STD_MEDIUM:
+            return Severity.MEDIUM, "CV003"
+        return Severity.INFO, "CV004"
+
+    def _variance_recommendation(self, cv_std: float) -> str:
+        if cv_std > self.STD_CRITICAL:
+            return f"CRITICAL: CV std {cv_std:.3f} is very high. Model is unstable. Use more data or robust methods."
+        if cv_std > self.STD_HIGH:
+            return f"HIGH: CV std {cv_std:.3f} is high. Consider ensemble methods or robust scaling."
+        if cv_std > self.STD_MEDIUM:
+            return f"MEDIUM: CV std {cv_std:.3f} is moderate. Monitor closely."
+        return f"OK: CV std {cv_std:.3f} indicates stable model."
+
+    def analyze_folds(self, cv_scores: List[float]) -> CVAnalysisResult:
+        cv_mean = np.mean(cv_scores)
+        cv_std = np.std(cv_scores)
+        fold_analysis = [{"fold": i, "score": score, "deviation": score - cv_mean} for i, score in enumerate(cv_scores)]
+        best_worst_gap = max(cv_scores) - min(cv_scores)
+        outlier_folds = [i for i, score in enumerate(cv_scores) if abs(score - cv_mean) > 2 * cv_std]
+        checks = []
+        if outlier_folds:
+            checks.append(CVCheck(
+                check_id="CV005",
+                metric="outlier_folds",
+                severity=Severity.HIGH,
+                recommendation=f"HIGH: Folds {outlier_folds} are outliers (>2 std from mean). Investigate data heterogeneity.",
+                value=len(outlier_folds),
+            ))
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        return CVAnalysisResult(
+            passed=len(critical) == 0,
+            checks=checks,
+            cv_mean=cv_mean,
+            cv_std=cv_std,
+            fold_analysis=fold_analysis,
+            best_worst_gap=best_worst_gap,
+            outlier_folds=outlier_folds,
+        )
+
+    def compare_cv_test(self, cv_mean: float, test_score: float) -> CVAnalysisResult:
+        gap = cv_mean - test_score
+        checks = []
+        severity, check_id = self._classify_cv_test_gap(gap)
+        checks.append(CVCheck(
+            check_id=check_id,
+            metric="cv_test_gap",
+            severity=severity,
+            recommendation=self._cv_test_recommendation(gap, cv_mean, test_score),
+            value=gap,
+        ))
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        return CVAnalysisResult(passed=len(critical) == 0, checks=checks, cv_mean=cv_mean)
+
+    def _classify_cv_test_gap(self, gap: float) -> tuple:
+        if gap > self.CV_TEST_HIGH:
+            return Severity.HIGH, "CV010"
+        if gap < self.CV_TEST_MEDIUM:
+            return Severity.MEDIUM, "CV011"
+        return Severity.INFO, "CV012"
+
+    def _cv_test_recommendation(self, gap: float, cv_mean: float, test_score: float) -> str:
+        if gap > self.CV_TEST_HIGH:
+            return f"HIGH: CV mean {cv_mean:.3f} >> test {test_score:.3f}. CV may be overly optimistic."
+        if gap < self.CV_TEST_MEDIUM:
+            return f"MEDIUM: CV mean {cv_mean:.3f} << test {test_score:.3f}. CV may be pessimistic."
+        return f"OK: CV mean {cv_mean:.3f} ≈ test {test_score:.3f}. Good estimate."
+
+    def run_all(self, cv_scores: List[float], test_score: Optional[float] = None) -> CVAnalysisResult:
+        variance_result = self.analyze_variance(cv_scores)
+        fold_result = self.analyze_folds(cv_scores)
+        all_checks = variance_result.checks + fold_result.checks
+        if test_score is not None:
+            cv_test_result = self.compare_cv_test(variance_result.cv_mean, test_score)
+            all_checks += cv_test_result.checks
+        critical = [c for c in all_checks if c.severity == Severity.CRITICAL]
+        recommendations = [c.recommendation for c in all_checks if c.severity in [Severity.CRITICAL, Severity.HIGH]]
+        return CVAnalysisResult(
+            passed=len(critical) == 0,
+            checks=all_checks,
+            cv_mean=variance_result.cv_mean,
+            cv_std=variance_result.cv_std,
+            fold_analysis=fold_result.fold_analysis,
+            best_worst_gap=fold_result.best_worst_gap,
+            outlier_folds=fold_result.outlier_folds,
+            recommendations=recommendations,
+        )