churnkit 0.75.0a1__py3-none-any.whl

customer_retention/analysis/diagnostics/overfitting_analyzer.py

@@ -0,0 +1,190 @@
+"""Overfitting analysis probes for model validation."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+from sklearn.model_selection import learning_curve
+
+from customer_retention.core.compat import DataFrame, Series
+from customer_retention.core.components.enums import Severity
+
+
+@dataclass
+class OverfittingCheck:
+    check_id: str
+    metric: str
+    severity: Severity
+    recommendation: str
+    train_value: float = 0.0
+    test_value: float = 0.0
+    gap: float = 0.0
+
+
+@dataclass
+class OverfittingResult:
+    passed: bool
+    checks: List[OverfittingCheck] = field(default_factory=list)
+    recommendations: List[str] = field(default_factory=list)
+    learning_curve: List[Dict[str, float]] = field(default_factory=list)
+    diagnosis: Optional[str] = None
+    sample_to_feature_ratio: float = 0.0
+
+
+class OverfittingAnalyzer:
+    GAP_CRITICAL = 0.15
+    GAP_HIGH = 0.10
+    GAP_MEDIUM = 0.05
+    RATIO_CRITICAL = 10
+    RATIO_HIGH = 50
+    DEPTH_HIGH = 15
+    ESTIMATORS_HIGH = 500
+
+    def analyze_train_test_gap(self, train_metrics: Dict[str, float], test_metrics: Dict[str, float]) -> OverfittingResult:
+        checks = []
+        for metric in train_metrics:
+            if metric in test_metrics:
+                train_val = train_metrics[metric]
+                test_val = test_metrics[metric]
+                gap = train_val - test_val
+                severity, check_id = self._classify_gap(gap)
+                checks.append(OverfittingCheck(
+                    check_id=check_id,
+                    metric=metric,
+                    severity=severity,
+                    recommendation=self._gap_recommendation(metric, gap),
+                    train_value=train_val,
+                    test_value=test_val,
+                    gap=gap,
+                ))
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        recommendations = [c.recommendation for c in checks if c.severity in [Severity.CRITICAL, Severity.HIGH]]
+        return OverfittingResult(passed=len(critical) == 0, checks=checks, recommendations=recommendations)
+
+    def _classify_gap(self, gap: float) -> tuple:
+        if gap > self.GAP_CRITICAL:
+            return Severity.CRITICAL, "OF001"
+        if gap > self.GAP_HIGH:
+            return Severity.HIGH, "OF002"
+        if gap > self.GAP_MEDIUM:
+            return Severity.MEDIUM, "OF003"
+        return Severity.INFO, "OF004"
+
+    def _gap_recommendation(self, metric: str, gap: float) -> str:
+        if gap > self.GAP_CRITICAL:
+            return f"CRITICAL: {metric} gap {gap:.1%} indicates severe overfitting. Reduce model complexity, add regularization."
+        if gap > self.GAP_HIGH:
+            return f"HIGH: {metric} gap {gap:.1%} indicates moderate overfitting. Consider feature selection or regularization."
+        if gap > self.GAP_MEDIUM:
+            return f"MEDIUM: {metric} gap {gap:.1%} shows mild overfitting. Monitor closely."
+        return f"OK: {metric} gap {gap:.1%} shows good generalization."
+
+    def analyze_learning_curve(self, model, X: DataFrame, y: Series, cv: int = 5) -> OverfittingResult:
+        try:
+            train_sizes = np.linspace(0.2, 1.0, 5)
+            train_sizes_abs, train_scores, val_scores = learning_curve(
+                model, X, y, train_sizes=train_sizes, cv=cv, scoring="roc_auc", random_state=42
+            )
+            curve_data = []
+            for i, size in enumerate(train_sizes_abs):
+                curve_data.append({
+                    "train_size": int(size),
+                    "train_score": float(np.mean(train_scores[i])),
+                    "val_score": float(np.mean(val_scores[i])),
+                })
+            diagnosis = self._diagnose_learning_curve(curve_data)
+            return OverfittingResult(passed=True, learning_curve=curve_data, diagnosis=diagnosis)
+        except Exception:
+            return OverfittingResult(passed=True, learning_curve=[], diagnosis="Unable to generate learning curve")
+
+    def _diagnose_learning_curve(self, curve_data: List[Dict[str, float]]) -> str:
+        if not curve_data:
+            return "Insufficient data for diagnosis"
+        last = curve_data[-1]
+        first = curve_data[0]
+        train_score = last["train_score"]
+        val_score = last["val_score"]
+        gap = train_score - val_score
+        val_improvement = last["val_score"] - first["val_score"]
+        if gap < 0.05 and val_score > 0.7:
+            return "Good fit: Both curves converged at high performance"
+        if gap > 0.15:
+            return "Overfitting: High train score but low validation. Reduce complexity."
+        if val_score < 0.6 and train_score < 0.7:
+            return "Underfitting: Both scores low. Increase model complexity or add features."
+        if val_improvement > 0.05:
+            return "More data may help: Validation still improving with more samples."
+        return "Validation plateau: More data unlikely to help significantly."
+
+    def analyze_complexity(self, X: DataFrame, y: Series) -> OverfittingResult:
+        n_samples, n_features = X.shape
+        ratio = n_samples / max(n_features, 1)
+        checks = []
+        severity, check_id = self._classify_ratio(ratio)
+        if severity != Severity.INFO:
+            checks.append(OverfittingCheck(
+                check_id=check_id,
+                metric="sample_to_feature_ratio",
+                severity=severity,
+                recommendation=self._ratio_recommendation(ratio, n_samples, n_features),
+                train_value=ratio,
+            ))
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        recommendations = [c.recommendation for c in checks if c.severity in [Severity.CRITICAL, Severity.HIGH]]
+        return OverfittingResult(passed=len(critical) == 0, checks=checks, recommendations=recommendations, sample_to_feature_ratio=ratio)
+
+    def _classify_ratio(self, ratio: float) -> tuple:
+        if ratio < self.RATIO_CRITICAL:
+            return Severity.CRITICAL, "OF010"
+        if ratio < self.RATIO_HIGH:
+            return Severity.HIGH, "OF011"
+        return Severity.INFO, "OF000"
+
+    def _ratio_recommendation(self, ratio: float, n_samples: int, n_features: int) -> str:
+        if ratio < self.RATIO_CRITICAL:
+            suggested_features = n_samples // 10
+            return f"CRITICAL: Ratio {ratio:.1f}:1 is too low. Reduce to {suggested_features} features or get more data."
+        if ratio < self.RATIO_HIGH:
+            return f"HIGH: Ratio {ratio:.1f}:1 is concerning. Use L1 regularization and monitor closely."
+        return f"OK: Ratio {ratio:.1f}:1 is adequate."
+
+    def analyze_model_complexity(self, model_params: Dict[str, Any]) -> OverfittingResult:
+        checks = []
+        if "max_depth" in model_params and model_params["max_depth"]:
+            depth = model_params["max_depth"]
+            if depth > self.DEPTH_HIGH:
+                checks.append(OverfittingCheck(
+                    check_id="OF012",
+                    metric="max_depth",
+                    severity=Severity.HIGH,
+                    recommendation=f"HIGH: max_depth={depth} may cause overfitting. Consider depth <= 10.",
+                    train_value=depth,
+                ))
+        if "n_estimators" in model_params:
+            n_est = model_params["n_estimators"]
+            if n_est > self.ESTIMATORS_HIGH and "regularization" not in model_params:
+                checks.append(OverfittingCheck(
+                    check_id="OF013",
+                    metric="n_estimators",
+                    severity=Severity.MEDIUM,
+                    recommendation=f"MEDIUM: n_estimators={n_est} without regularization may cause overfitting.",
+                    train_value=n_est,
+                ))
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        return OverfittingResult(passed=len(critical) == 0, checks=checks)
+
+    def run_all(self, model, X: DataFrame, y: Series, train_metrics: Dict[str, float], test_metrics: Dict[str, float]) -> OverfittingResult:
+        gap_result = self.analyze_train_test_gap(train_metrics, test_metrics)
+        complexity_result = self.analyze_complexity(X, y)
+        learning_result = self.analyze_learning_curve(model, X, y)
+        all_checks = gap_result.checks + complexity_result.checks
+        all_recommendations = gap_result.recommendations + complexity_result.recommendations
+        critical = [c for c in all_checks if c.severity == Severity.CRITICAL]
+        return OverfittingResult(
+            passed=len(critical) == 0,
+            checks=all_checks,
+            recommendations=list(set(all_recommendations)),
+            learning_curve=learning_result.learning_curve,
+            diagnosis=learning_result.diagnosis,
+            sample_to_feature_ratio=complexity_result.sample_to_feature_ratio,
+        )

customer_retention/analysis/diagnostics/segment_analyzer.py

@@ -0,0 +1,122 @@
+"""Segment performance analysis probes."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+import numpy as np
+from sklearn.metrics import average_precision_score, precision_score, recall_score, roc_auc_score
+
+from customer_retention.core.compat import DataFrame, Series, pd
+from customer_retention.core.components.enums import Severity
+
+
+@dataclass
+class SegmentCheck:
+    check_id: str
+    segment: str
+    severity: Severity
+    recommendation: str
+    metric: str = ""
+    value: float = 0.0
+
+
+@dataclass
+class SegmentResult:
+    passed: bool
+    checks: List[SegmentCheck] = field(default_factory=list)
+    segment_metrics: Dict[str, Dict[str, float]] = field(default_factory=dict)
+    recommendations: List[str] = field(default_factory=list)
+    recommendation: str = ""
+
+
+class SegmentPerformanceAnalyzer:
+    UNDERPERFORMANCE_THRESHOLD = 0.20
+    LOW_RECALL_THRESHOLD = 0.20
+    SMALL_SEGMENT_THRESHOLD = 0.05
+
+    def define_segments(self, X: DataFrame, segment_column: str, segment_type: str = "quantile") -> Series:
+        if segment_column not in X.columns:
+            return pd.Series(["all"] * len(X))
+        values = X[segment_column]
+        if segment_type == "tenure":
+            return pd.cut(values, bins=[0, 90, 365, np.inf], labels=["new", "established", "mature"])
+        if segment_type == "quantile":
+            return pd.qcut(values, q=3, labels=["low", "medium", "high"], duplicates="drop")
+        return Series(["all"] * len(X))
+
+    def analyze_performance(self, model, X: DataFrame, y: Series, segments: Series) -> SegmentResult:
+        checks = []
+        segment_metrics = {}
+        global_metrics = self._compute_metrics(model, X, y)
+        unique_segments = segments.unique()
+        for seg in unique_segments:
+            mask = segments == seg
+            if mask.sum() < 10:
+                continue
+            X_seg = X[mask]
+            y_seg = y[mask]
+            seg_size_pct = mask.sum() / len(y)
+            metrics = self._compute_metrics(model, X_seg, y_seg)
+            segment_metrics[str(seg)] = metrics
+            if seg_size_pct < self.SMALL_SEGMENT_THRESHOLD:
+                checks.append(SegmentCheck(
+                    check_id="SG003",
+                    segment=str(seg),
+                    severity=Severity.MEDIUM,
+                    recommendation=f"MEDIUM: Segment '{seg}' is small ({seg_size_pct:.1%}). Results may be unreliable.",
+                    metric="size",
+                    value=seg_size_pct,
+                ))
+            if "pr_auc" in metrics and "pr_auc" in global_metrics:
+                gap = global_metrics["pr_auc"] - metrics["pr_auc"]
+                if gap > self.UNDERPERFORMANCE_THRESHOLD:
+                    checks.append(SegmentCheck(
+                        check_id="SG001",
+                        segment=str(seg),
+                        severity=Severity.HIGH,
+                        recommendation=f"HIGH: Segment '{seg}' underperforms by {gap:.1%}. Consider segment-specific model.",
+                        metric="pr_auc",
+                        value=metrics["pr_auc"],
+                    ))
+            if "recall" in metrics and metrics["recall"] < self.LOW_RECALL_THRESHOLD:
+                checks.append(SegmentCheck(
+                    check_id="SG002",
+                    segment=str(seg),
+                    severity=Severity.HIGH,
+                    recommendation=f"HIGH: Segment '{seg}' has low recall ({metrics['recall']:.1%}). Adjust threshold or add features.",
+                    metric="recall",
+                    value=metrics["recall"],
+                ))
+        critical = [c for c in checks if c.severity == Severity.CRITICAL]
+        recommendations = [c.recommendation for c in checks if c.severity in [Severity.CRITICAL, Severity.HIGH]]
+        recommendation = self._global_recommendation(checks, unique_segments)
+        return SegmentResult(
+            passed=len(critical) == 0,
+            checks=checks,
+            segment_metrics=segment_metrics,
+            recommendations=recommendations,
+            recommendation=recommendation,
+        )
+
+    def _compute_metrics(self, model, X: DataFrame, y: Series) -> Dict[str, float]:
+        try:
+            y_pred = model.predict(X)
+            y_proba = model.predict_proba(X)[:, 1] if hasattr(model, "predict_proba") else y_pred
+            return {
+                "precision": precision_score(y, y_pred, zero_division=0),
+                "recall": recall_score(y, y_pred, zero_division=0),
+                "roc_auc": roc_auc_score(y, y_proba) if len(np.unique(y)) > 1 else 0.5,
+                "pr_auc": average_precision_score(y, y_proba) if len(np.unique(y)) > 1 else 0.5,
+                "churn_rate": y.mean(),
+                "sample_size": len(y),
+            }
+        except Exception:
+            return {}
+
+    def _global_recommendation(self, checks: List[SegmentCheck], segments) -> str:
+        high_issues = [c for c in checks if c.severity == Severity.HIGH]
+        if not high_issues:
+            return "No significant segment gaps. Continue with global model."
+        if len(high_issues) == 1:
+            return "One segment underperforms. Consider adding segment as feature."
+        return "Multiple segments underperform. Consider segment-specific models."

customer_retention/analysis/discovery/__init__.py

@@ -0,0 +1,8 @@
+from .config_generator import ConfigGenerator
+from .discovery_flow import discover_and_configure
+from .type_inferencer import ColumnInference, InferenceConfidence, InferenceResult, TypeInferencer
+
+__all__ = [
+    "TypeInferencer", "InferenceResult", "ColumnInference", "InferenceConfidence",
+    "ConfigGenerator", "discover_and_configure"
+]

customer_retention/analysis/discovery/config_generator.py

@@ -0,0 +1,49 @@
+import json
+from typing import Optional
+
+from customer_retention.core.config.column_config import ColumnConfig
+from customer_retention.core.config.pipeline_config import (
+    BronzeConfig,
+    GoldConfig,
+    ModelingConfig,
+    PipelineConfig,
+    SilverConfig,
+)
+from customer_retention.core.config.source_config import DataSourceConfig, FileFormat, SourceType
+
+from .type_inferencer import InferenceResult
+
+
+class ConfigGenerator:
+    def from_inference(self, result: InferenceResult, project_name: str = "customer_retention",
+                       source_path: Optional[str] = None) -> PipelineConfig:
+        column_configs = []
+        for col, inf in result.inferences.items():
+            cc = ColumnConfig(name=col, column_type=inf.inferred_type)
+            column_configs.append(cc)
+        primary_key = result.identifier_columns[0] if result.identifier_columns else "id"
+        data_source = DataSourceConfig(
+            name="main_source",
+            source_type=SourceType.BATCH_FILE,
+            primary_key=primary_key,
+            path=source_path or "./data.csv",
+            file_format=FileFormat.CSV,
+            columns=column_configs
+        )
+        target_col = result.target_column or "target"
+        modeling = ModelingConfig(target_column=target_col)
+        bronze = BronzeConfig(dedup_keys=[primary_key])
+        silver = SilverConfig(entity_key=primary_key)
+        return PipelineConfig(
+            project_name=project_name,
+            data_sources=[data_source],
+            bronze=bronze,
+            silver=silver,
+            gold=GoldConfig(),
+            modeling=modeling
+        )
+
+    def save(self, config: PipelineConfig, path: str) -> None:
+        data = config.model_dump() if hasattr(config, "model_dump") else config.dict()
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2, default=str)

customer_retention/analysis/discovery/discovery_flow.py

@@ -0,0 +1,19 @@
+from typing import Optional, Union
+
+import pandas as pd
+
+from customer_retention.core.config.pipeline_config import PipelineConfig
+
+from .config_generator import ConfigGenerator
+from .type_inferencer import TypeInferencer
+
+
+def discover_and_configure(source: Union[str, pd.DataFrame], project_name: str = "customer_retention",
+                           target_hint: Optional[str] = None) -> PipelineConfig:
+    inferencer = TypeInferencer()
+    result = inferencer.infer(source)
+    if target_hint:
+        result.target_column = target_hint
+    generator = ConfigGenerator()
+    config = generator.from_inference(result, project_name=project_name)
+    return config

customer_retention/analysis/discovery/type_inferencer.py

@@ -0,0 +1,147 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Union
+
+import pandas as pd
+
+from customer_retention.core.compat import ops
+from customer_retention.core.config.column_config import ColumnType
+
+
+class InferenceConfidence(str, Enum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class ColumnInference:
+    column_name: str
+    inferred_type: ColumnType
+    confidence: InferenceConfidence
+    evidence: List[str]
+    alternatives: List[ColumnType] = field(default_factory=list)
+    suggested_encoding: Optional[str] = None
+    suggested_scaling: Optional[str] = None
+    suggested_missing_strategy: Optional[str] = None
+
+
+@dataclass
+class InferenceResult:
+    inferences: Dict[str, ColumnInference]
+    target_column: Optional[str] = None
+    identifier_columns: List[str] = field(default_factory=list)
+    datetime_columns: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+
+class TypeInferencer:
+    TARGET_PATTERNS = ["target", "label", "churn", "retained", "outcome", "class", "y"]
+    ID_PATTERNS = ["id", "key", "code", "identifier", "index"]
+
+    def __init__(self):
+        self.evidence: List[str] = []
+
+    def infer(self, source: Union[str, pd.DataFrame]) -> InferenceResult:
+        if isinstance(source, str):
+            df = ops.read_csv(source)
+        else:
+            df = source
+        inferences = {}
+        target_column = None
+        identifier_columns = []
+        datetime_columns = []
+        for col in df.columns:
+            inference = self._infer_column(df[col], col)
+            inferences[col] = inference
+            if inference.inferred_type == ColumnType.TARGET:
+                target_column = col
+            elif inference.inferred_type == ColumnType.IDENTIFIER:
+                identifier_columns.append(col)
+            elif inference.inferred_type == ColumnType.DATETIME:
+                datetime_columns.append(col)
+        return InferenceResult(
+            inferences=inferences,
+            target_column=target_column,
+            identifier_columns=identifier_columns,
+            datetime_columns=datetime_columns
+        )
+
+    def _infer_column(self, series: pd.Series, column_name: str) -> ColumnInference:
+        evidence = []
+        col_lower = column_name.lower()
+        if self._is_identifier(series, col_lower, evidence):
+            return ColumnInference(column_name, ColumnType.IDENTIFIER, InferenceConfidence.HIGH, evidence)
+        if self._is_target(series, col_lower, evidence):
+            return ColumnInference(column_name, ColumnType.TARGET, InferenceConfidence.HIGH, evidence)
+        if self._is_datetime(series, evidence):
+            return ColumnInference(column_name, ColumnType.DATETIME, InferenceConfidence.HIGH, evidence)
+        if self._is_binary(series, evidence):
+            return ColumnInference(column_name, ColumnType.BINARY, InferenceConfidence.HIGH, evidence)
+        if pd.api.types.is_numeric_dtype(series):
+            return self._infer_numeric(series, column_name, evidence)
+        return self._infer_categorical(series, column_name, evidence)
+
+    def _is_identifier(self, series: pd.Series, col_lower: str, evidence: List[str]) -> bool:
+        if any(p in col_lower for p in self.ID_PATTERNS):
+            if series.nunique() == len(series):
+                evidence.append("unique values, id pattern in name")
+                return True
+        if series.nunique() == len(series) and pd.api.types.is_integer_dtype(series):
+            evidence.append("unique integer values")
+            return True
+        return False
+
+    def _is_target(self, series: pd.Series, col_lower: str, evidence: List[str]) -> bool:
+        if any(p in col_lower for p in self.TARGET_PATTERNS):
+            if series.nunique() <= 10:
+                evidence.append(f"target pattern in name, {series.nunique()} distinct values")
+                return True
+        return False
+
+    def _is_datetime(self, series: pd.Series, evidence: List[str]) -> bool:
+        if pd.api.types.is_datetime64_any_dtype(series):
+            evidence.append("datetime dtype")
+            return True
+        if series.dtype == object:
+            try:
+                pd.to_datetime(series.dropna().head(100), format='mixed')
+                evidence.append("parseable as datetime")
+                return True
+            except (ValueError, TypeError):
+                pass
+        return False
+
+    def _is_binary(self, series: pd.Series, evidence: List[str]) -> bool:
+        unique = series.dropna().unique()
+        if len(unique) == 2:
+            evidence.append("exactly 2 unique values")
+            return True
+        return False
+
+    def _infer_numeric(self, series: pd.Series, column_name: str, evidence: List[str]) -> ColumnInference:
+        nunique = series.nunique()
+        if nunique <= 20:
+            evidence.append(f"numeric with {nunique} unique values (discrete)")
+            return ColumnInference(column_name, ColumnType.NUMERIC_DISCRETE, InferenceConfidence.HIGH, evidence,
+                                   suggested_encoding="ordinal", suggested_missing_strategy="median")
+        evidence.append(f"numeric with {nunique} unique values (continuous)")
+        return ColumnInference(column_name, ColumnType.NUMERIC_CONTINUOUS, InferenceConfidence.HIGH, evidence,
+                               suggested_scaling="standard", suggested_missing_strategy="median")
+
+    def _infer_categorical(self, series: pd.Series, column_name: str, evidence: List[str]) -> ColumnInference:
+        nunique = series.nunique()
+        if nunique <= 10:
+            evidence.append(f"categorical with {nunique} categories (low cardinality)")
+            return ColumnInference(column_name, ColumnType.CATEGORICAL_NOMINAL, InferenceConfidence.HIGH, evidence,
+                                   suggested_encoding="onehot", suggested_missing_strategy="mode")
+        evidence.append(f"categorical with {nunique} categories (high cardinality)")
+        return ColumnInference(column_name, ColumnType.CATEGORICAL_NOMINAL, InferenceConfidence.MEDIUM, evidence,
+                               suggested_encoding="target", suggested_missing_strategy="mode")
+
+    def show_report(self, result: InferenceResult) -> None:
+        print(f"Target column: {result.target_column}")
+        print(f"Identifier columns: {result.identifier_columns}")
+        print(f"Datetime columns: {result.datetime_columns}")
+        for col, inf in result.inferences.items():
+            print(f"  {col}: {inf.inferred_type.value} ({inf.confidence.value}) - {', '.join(inf.evidence)}")

customer_retention/analysis/interpretability/__init__.py

@@ -0,0 +1,13 @@
+from .cohort_analyzer import CohortAnalysisResult, CohortAnalyzer, CohortComparison, CohortInsight
+from .counterfactual import Counterfactual, CounterfactualChange, CounterfactualGenerator
+from .individual_explainer import Confidence, IndividualExplainer, IndividualExplanation, RiskContribution
+from .pdp_generator import InteractionResult, PDPGenerator, PDPResult
+from .shap_explainer import FeatureImportance, GlobalExplanation, ShapExplainer
+
+__all__ = [
+    "ShapExplainer", "GlobalExplanation", "FeatureImportance",
+    "PDPGenerator", "PDPResult", "InteractionResult",
+    "CohortAnalyzer", "CohortInsight", "CohortComparison", "CohortAnalysisResult",
+    "IndividualExplainer", "IndividualExplanation", "RiskContribution", "Confidence",
+    "CounterfactualGenerator", "Counterfactual", "CounterfactualChange",
+]