churnkit 0.75.0a1__py3-none-any.whl

customer_retention/analysis/business/fairness_analyzer.py

@@ -0,0 +1,166 @@
+"""Fairness analysis for model predictions."""
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from customer_retention.core.compat import Series, pd
+
+
+@dataclass
+class GroupMetrics:
+    group_name: str
+    size: int
+    positive_rate: float
+    true_positive_rate: Optional[float] = None
+    false_positive_rate: Optional[float] = None
+    accuracy: Optional[float] = None
+
+
+@dataclass
+class FairnessMetric:
+    name: str
+    values: Dict[str, float]
+    ratio: float
+    passed: bool
+    threshold: float
+
+
+@dataclass
+class FairnessResult:
+    passed: bool
+    metrics: List[FairnessMetric]
+    group_metrics: Dict[str, GroupMetrics]
+    recommendations: List[str]
+
+
+class FairnessAnalyzer:
+    def __init__(self, threshold: float = 0.8):
+        self.threshold = threshold
+
+    def analyze(self, y_true: Series, y_pred: Series,
+                protected: Series) -> FairnessResult:
+        groups = protected.unique()
+        group_metrics = {}
+        metrics = []
+        for group in groups:
+            mask = protected == group
+            y_t = y_true[mask]
+            y_p = y_pred[mask]
+            positive_rate = y_p.mean()
+            accuracy = (y_t == y_p).mean()
+            tp = ((y_t == 1) & (y_p == 1)).sum()
+            fn = ((y_t == 1) & (y_p == 0)).sum()
+            fp = ((y_t == 0) & (y_p == 1)).sum()
+            tn = ((y_t == 0) & (y_p == 0)).sum()
+            tpr = tp / (tp + fn) if (tp + fn) > 0 else 0
+            fpr = fp / (fp + tn) if (fp + tn) > 0 else 0
+            group_metrics[group] = GroupMetrics(
+                group_name=group,
+                size=int(mask.sum()),
+                positive_rate=float(positive_rate),
+                true_positive_rate=float(tpr),
+                false_positive_rate=float(fpr),
+                accuracy=float(accuracy)
+            )
+        positive_rates = {g: m.positive_rate for g, m in group_metrics.items()}
+        if positive_rates:
+            min_rate = min(positive_rates.values())
+            max_rate = max(positive_rates.values())
+            dp_ratio = min_rate / max_rate if max_rate > 0 else 1.0
+            metrics.append(FairnessMetric(
+                name="demographic_parity",
+                values=positive_rates,
+                ratio=dp_ratio,
+                passed=dp_ratio >= self.threshold,
+                threshold=self.threshold
+            ))
+            metrics.append(FairnessMetric(
+                name="disparate_impact",
+                values=positive_rates,
+                ratio=dp_ratio,
+                passed=dp_ratio >= self.threshold,
+                threshold=self.threshold
+            ))
+        tprs = {g: m.true_positive_rate for g, m in group_metrics.items()}
+        fprs = {g: m.false_positive_rate for g, m in group_metrics.items()}
+        if tprs:
+            min_tpr = min(tprs.values())
+            max_tpr = max(tprs.values())
+            tpr_ratio = min_tpr / max_tpr if max_tpr > 0 else 1.0
+            min_fpr = min(fprs.values())
+            max_fpr = max(fprs.values())
+            fpr_ratio = min_fpr / max_fpr if max_fpr > 0 else 1.0
+            eo_ratio = min(tpr_ratio, fpr_ratio)
+            metrics.append(FairnessMetric(
+                name="equalized_odds",
+                values={"tpr_ratio": tpr_ratio, "fpr_ratio": fpr_ratio},
+                ratio=eo_ratio,
+                passed=eo_ratio >= self.threshold,
+                threshold=self.threshold
+            ))
+        overall_passed = all(m.passed for m in metrics)
+        recommendations = self._generate_recommendations(metrics, group_metrics)
+        return FairnessResult(
+            passed=overall_passed,
+            metrics=metrics,
+            group_metrics=group_metrics,
+            recommendations=recommendations
+        )
+
+    def _generate_recommendations(self, metrics: List[FairnessMetric],
+                                  group_metrics: Dict[str, GroupMetrics]) -> List[str]:
+        recommendations = []
+        for metric in metrics:
+            if not metric.passed:
+                recommendations.append(
+                    f"Metric '{metric.name}' failed with ratio {metric.ratio:.2f} "
+                    f"(threshold: {metric.threshold}). Consider rebalancing training data."
+                )
+        accuracies = {g: m.accuracy for g, m in group_metrics.items()}
+        if accuracies:
+            max_acc = max(accuracies.values())
+            min_acc = min(accuracies.values())
+            if max_acc - min_acc > 0.1:
+                worst_group = min(accuracies, key=accuracies.get)
+                recommendations.append(
+                    f"Accuracy differs significantly across groups. "
+                    f"Consider additional features for {worst_group}."
+                )
+        if not recommendations:
+            recommendations.append("No significant bias detected. Model passes fairness checks.")
+        return recommendations
+
+    def analyze_calibration(self, y_true: Series, y_proba: Series,
+                            protected: Series) -> FairnessResult:
+        groups = protected.unique()
+        group_metrics = {}
+        for group in groups:
+            mask = protected == group
+            y_t = y_true[mask]
+            y_p = y_proba[mask]
+            bins = pd.cut(y_p, bins=10, labels=False)
+            calibration_error = 0
+            for b in range(10):
+                bin_mask = bins == b
+                if bin_mask.sum() > 0:
+                    predicted_prob = y_p[bin_mask].mean()
+                    actual_prob = y_t[bin_mask].mean()
+                    calibration_error += abs(predicted_prob - actual_prob) * bin_mask.sum()
+            calibration_error /= len(y_t) if len(y_t) > 0 else 1
+            group_metrics[group] = GroupMetrics(
+                group_name=group,
+                size=int(mask.sum()),
+                positive_rate=float(y_t.mean()),
+                accuracy=1 - calibration_error
+            )
+        return FairnessResult(
+            passed=True,
+            metrics=[],
+            group_metrics=group_metrics,
+            recommendations=[]
+        )
+
+    def analyze_multiple(self, y_true: Series, y_pred: Series,
+                        protected_attributes: Dict[str, Series]) -> Dict[str, FairnessResult]:
+        return {name: self.analyze(y_true, y_pred, protected)
+                for name, protected in protected_attributes.items()}

customer_retention/analysis/business/intervention_matcher.py

@@ -0,0 +1,121 @@
+"""Intervention matching and recommendation."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from customer_retention.core.components.enums import RiskSegment
+
+
+@dataclass
+class Intervention:
+    name: str
+    cost: float
+    success_rate: float
+    channel: str
+    min_ltv: float = 0
+    applicable_segments: List[RiskSegment] = field(default_factory=list)
+    timing: str = "Within 1 week"
+
+
+@dataclass
+class InterventionRecommendation:
+    intervention: Optional[Intervention]
+    reasoning: str
+    expected_roi: Optional[float] = None
+    timing: str = "Within 1 week"
+    priority: int = 5
+
+
+class InterventionCatalog:
+    def __init__(self, interventions: List[Intervention]):
+        self.interventions = interventions
+        self._by_name = {i.name: i for i in interventions}
+
+    def get(self, name: str) -> Optional[Intervention]:
+        return self._by_name.get(name)
+
+    def filter_by_segment(self, segment: RiskSegment) -> List[Intervention]:
+        return [i for i in self.interventions if segment in i.applicable_segments]
+
+    def filter_by_ltv(self, min_ltv: float) -> List[Intervention]:
+        return [i for i in self.interventions if i.min_ltv <= min_ltv]
+
+
+class InterventionMatcher:
+    PRIORITY_MAP = {RiskSegment.CRITICAL: 1, RiskSegment.HIGH: 2,
+                    RiskSegment.MEDIUM: 3, RiskSegment.LOW: 4, RiskSegment.VERY_LOW: 5}
+    TIMING_MAP = {
+        RiskSegment.CRITICAL: "Within 24 hours",
+        RiskSegment.HIGH: "Within 3 days",
+        RiskSegment.MEDIUM: "Within 1 week",
+        RiskSegment.LOW: "Within 2 weeks",
+        RiskSegment.VERY_LOW: "Standard schedule"
+    }
+
+    def __init__(self, catalog: InterventionCatalog, avg_ltv: float = 500):
+        self.catalog = catalog
+        self.avg_ltv = avg_ltv
+
+    def match(self, risk_segment: RiskSegment, customer_ltv: float,
+              churn_probability: float = 0.5) -> InterventionRecommendation:
+        if risk_segment == RiskSegment.VERY_LOW:
+            return InterventionRecommendation(
+                intervention=Intervention(name="none", cost=0, success_rate=0, channel="none"),
+                reasoning="Customer is low risk, no intervention needed",
+                expected_roi=0,
+                timing=self.TIMING_MAP[risk_segment],
+                priority=self.PRIORITY_MAP[risk_segment]
+            )
+        applicable = self.catalog.filter_by_segment(risk_segment)
+        affordable = [i for i in applicable if i.min_ltv <= customer_ltv]
+        if not affordable:
+            affordable = [i for i in applicable if i.cost <= customer_ltv * 0.1]
+        if not affordable and applicable:
+            affordable = [min(applicable, key=lambda x: x.min_ltv)]
+        if not affordable:
+            return InterventionRecommendation(
+                intervention=None,
+                reasoning="No suitable intervention found",
+                timing=self.TIMING_MAP.get(risk_segment, "Within 1 week"),
+                priority=self.PRIORITY_MAP.get(risk_segment, 5)
+            )
+        best = max(affordable, key=lambda i: self._calculate_roi(i, churn_probability, customer_ltv))
+        roi = self._calculate_roi(best, churn_probability, customer_ltv)
+        return InterventionRecommendation(
+            intervention=best,
+            reasoning=f"Best ROI option for {risk_segment.value} risk with LTV ${customer_ltv:.0f}",
+            expected_roi=roi,
+            timing=self.TIMING_MAP.get(risk_segment, "Within 1 week"),
+            priority=self.PRIORITY_MAP.get(risk_segment, 5)
+        )
+
+    def _calculate_roi(self, intervention: Intervention, churn_prob: float, ltv: float) -> float:
+        expected_saves = churn_prob * intervention.success_rate
+        revenue_saved = expected_saves * ltv
+        if intervention.cost == 0:
+            return float("inf") if revenue_saved > 0 else 0
+        return (revenue_saved - intervention.cost) / intervention.cost
+
+    def match_multiple(self, risk_segment: RiskSegment, customer_ltv: float,
+                       churn_probability: float = 0.5, n: int = 3) -> List[InterventionRecommendation]:
+        applicable = self.catalog.filter_by_segment(risk_segment)
+        affordable = [i for i in applicable if i.min_ltv <= customer_ltv]
+        recommendations = []
+        for intervention in affordable:
+            roi = self._calculate_roi(intervention, churn_probability, customer_ltv)
+            recommendations.append(InterventionRecommendation(
+                intervention=intervention,
+                reasoning=f"Option: {intervention.name} via {intervention.channel}",
+                expected_roi=roi,
+                timing=self.TIMING_MAP.get(risk_segment, "Within 1 week"),
+                priority=self.PRIORITY_MAP.get(risk_segment, 5)
+            ))
+        recommendations.sort(key=lambda r: r.expected_roi or 0, reverse=True)
+        return recommendations[:n]
+
+    def match_batch(self, customers: List[Dict]) -> List[InterventionRecommendation]:
+        return [self.match(
+            risk_segment=c["risk_segment"],
+            customer_ltv=c.get("customer_ltv", self.avg_ltv),
+            churn_probability=c.get("churn_probability", 0.5)
+        ) for c in customers]

customer_retention/analysis/business/report_generator.py

@@ -0,0 +1,222 @@
+"""Business report generation."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from customer_retention.core.compat import DataFrame, Series, pd
+
+
+@dataclass
+class ExecutiveDashboard:
+    total_customers: int
+    churn_rate: float
+    revenue_at_risk: float
+    risk_distribution: Dict[str, int]
+    expected_saves: Optional[int] = None
+    expected_roi: Optional[float] = None
+    trend: Optional[Dict[str, float]] = None
+    top_actions: List[str] = field(default_factory=list)
+
+
+@dataclass
+class CampaignList:
+    customers: List[Dict]
+    total_count: int
+    segment_breakdown: Dict[str, int]
+
+    def to_dict_list(self) -> List[Dict]:
+        return self.customers
+
+    def to_dataframe(self) -> DataFrame:
+        return pd.DataFrame(self.customers)
+
+
+@dataclass
+class CustomerServiceReport:
+    customer_id: str
+    risk_segment: str
+    churn_probability: float
+    risk_factors: List[Dict]
+    talking_points: List[str]
+    offer_eligibility: List[str]
+    intervention_history: List[Dict] = field(default_factory=list)
+
+
+@dataclass
+class ProductInsights:
+    top_churn_drivers: List[Dict[str, Any]]
+    segment_risk_profiles: Dict[str, Dict]
+    product_gaps: List[str]
+    competitive_indicators: List[str]
+    improvement_recommendations: List[str]
+
+
+@dataclass
+class GovernanceReport:
+    model_performance: Dict[str, float]
+    data_quality_summary: Dict[str, float]
+    drift_status: Optional[Dict[str, bool]] = None
+    fairness_summary: Optional[Dict[str, float]] = None
+    retraining_recommendation: str = "No retraining needed"
+
+
+class ReportGenerator:
+    def generate_executive_dashboard(self, customer_data: DataFrame,
+                                     model_metrics: Dict[str, float],
+                                     intervention_data: Optional[Dict] = None) -> ExecutiveDashboard:
+        total = len(customer_data)
+        churn_rate = customer_data["churn_probability"].mean()
+        if "ltv" in customer_data.columns:
+            revenue_at_risk = (customer_data["churn_probability"] * customer_data["ltv"]).sum()
+        else:
+            revenue_at_risk = churn_rate * total * 500
+        if "risk_segment" in customer_data.columns:
+            risk_dist = customer_data["risk_segment"].value_counts().to_dict()
+        else:
+            risk_dist = {"Unknown": total}
+        expected_saves = intervention_data.get("expected_saves") if intervention_data else None
+        expected_roi = intervention_data.get("expected_roi") if intervention_data else None
+        top_actions = self._generate_top_actions(customer_data, risk_dist)
+        return ExecutiveDashboard(
+            total_customers=total,
+            churn_rate=churn_rate,
+            revenue_at_risk=revenue_at_risk,
+            risk_distribution=risk_dist,
+            expected_saves=expected_saves,
+            expected_roi=expected_roi,
+            top_actions=top_actions
+        )
+
+    def _generate_top_actions(self, data: DataFrame, risk_dist: Dict) -> List[str]:
+        actions = []
+        critical = risk_dist.get("Critical", 0)
+        high = risk_dist.get("High", 0)
+        if critical > 0:
+            actions.append(f"Prioritize outreach to {critical} critical-risk customers")
+        if high > 0:
+            actions.append(f"Schedule engagement campaigns for {high} high-risk customers")
+        actions.append("Review top churn drivers for product improvements")
+        return actions[:5]
+
+    def generate_campaign_list(self, customer_data: DataFrame,
+                               risk_segments: List[str]) -> CampaignList:
+        filtered = customer_data[customer_data["risk_segment"].isin(risk_segments)]
+        customers = []
+        for _, row in filtered.iterrows():
+            customers.append({
+                "customer_id": row.get("customer_id", ""),
+                "risk_segment": row["risk_segment"],
+                "churn_probability": row["churn_probability"],
+                "ltv": row.get("ltv", 500),
+                "recommended_intervention": self._get_intervention(row["risk_segment"])
+            })
+        segment_breakdown = filtered["risk_segment"].value_counts().to_dict()
+        return CampaignList(
+            customers=customers,
+            total_count=len(customers),
+            segment_breakdown=segment_breakdown
+        )
+
+    def _get_intervention(self, segment: str) -> str:
+        interventions = {
+            "Critical": "Account manager call",
+            "High": "Phone call + discount",
+            "Medium": "Personalized email",
+            "Low": "Standard nurturing"
+        }
+        return interventions.get(segment, "Standard communication")
+
+    def generate_customer_service_report(self, customer_id: str,
+                                         customer_data: Series,
+                                         risk_factors: List[Dict]) -> CustomerServiceReport:
+        risk_segment = customer_data.get("risk_segment", "Unknown")
+        churn_prob = customer_data.get("churn_probability", 0.5)
+        talking_points = self._generate_talking_points(risk_factors, risk_segment)
+        offer_eligibility = self._determine_offers(risk_segment, customer_data.get("ltv", 500))
+        return CustomerServiceReport(
+            customer_id=customer_id,
+            risk_segment=risk_segment,
+            churn_probability=churn_prob,
+            risk_factors=risk_factors,
+            talking_points=talking_points,
+            offer_eligibility=offer_eligibility
+        )
+
+    def _generate_talking_points(self, risk_factors: List[Dict], segment: str) -> List[str]:
+        points = [f"Customer is in {segment} risk category"]
+        for factor in risk_factors[:3]:
+            name = factor.get("name", "Unknown factor")
+            points.append(f"Address concern about {name}")
+        points.append("Express appreciation for their business")
+        return points
+
+    def _determine_offers(self, segment: str, ltv: float) -> List[str]:
+        offers = ["Standard loyalty points"]
+        if segment in ["Critical", "High"]:
+            offers.append("10% discount on next order")
+            if ltv > 500:
+                offers.append("Free premium upgrade for 1 month")
+        if segment == "Critical":
+            offers.append("Dedicated account manager")
+        return offers
+
+    def generate_product_insights(self, customer_data: DataFrame,
+                                  feature_importance: Dict[str, float]) -> ProductInsights:
+        sorted_features = sorted(feature_importance.items(), key=lambda x: x[1], reverse=True)
+        top_drivers = [{"feature": f, "importance": i} for f, i in sorted_features[:5]]
+        segment_profiles = {}
+        if "risk_segment" in customer_data.columns:
+            for segment in customer_data["risk_segment"].unique():
+                seg_data = customer_data[customer_data["risk_segment"] == segment]
+                segment_profiles[segment] = {
+                    "count": len(seg_data),
+                    "avg_churn_prob": seg_data["churn_probability"].mean()
+                }
+        gaps = self._identify_product_gaps(feature_importance)
+        indicators = self._identify_competitive_indicators(feature_importance)
+        recommendations = self._generate_improvement_recommendations(top_drivers)
+        return ProductInsights(
+            top_churn_drivers=top_drivers,
+            segment_risk_profiles=segment_profiles,
+            product_gaps=gaps,
+            competitive_indicators=indicators,
+            improvement_recommendations=recommendations
+        )
+
+    def _identify_product_gaps(self, importance: Dict[str, float]) -> List[str]:
+        gaps = []
+        if importance.get("engagement", 0) > 0.15:
+            gaps.append("Low engagement indicates need for better onboarding")
+        if importance.get("recency", 0) > 0.15:
+            gaps.append("High recency impact suggests need for re-engagement features")
+        if not gaps:
+            gaps.append("No critical product gaps identified")
+        return gaps
+
+    def _identify_competitive_indicators(self, importance: Dict[str, float]) -> List[str]:
+        return ["Monitor competitor pricing", "Track feature parity"]
+
+    def _generate_improvement_recommendations(self, drivers: List[Dict]) -> List[str]:
+        recommendations = []
+        for driver in drivers[:3]:
+            feature = driver["feature"]
+            recommendations.append(f"Improve {feature} experience to reduce churn")
+        return recommendations
+
+    def generate_governance_report(self, model_metrics: Dict[str, float],
+                                   data_quality_summary: Dict[str, float],
+                                   drift_status: Optional[Dict] = None,
+                                   fairness_summary: Optional[Dict] = None) -> GovernanceReport:
+        retraining_rec = "No retraining needed"
+        if drift_status:
+            if drift_status.get("feature_drift", False) or drift_status.get("target_drift", False):
+                retraining_rec = "Retraining recommended due to detected drift"
+        if model_metrics.get("pr_auc", 1) < 0.6:
+            retraining_rec = "Retraining recommended due to performance degradation"
+        return GovernanceReport(
+            model_performance=model_metrics,
+            data_quality_summary=data_quality_summary,
+            drift_status=drift_status,
+            fairness_summary=fairness_summary,
+            retraining_recommendation=retraining_rec
+        )