churnkit 0.75.0a1__py3-none-any.whl

customer_retention/stages/profiling/type_detector.py

@@ -0,0 +1,382 @@
+from typing import Optional
+
+from customer_retention.core.compat import DataFrame, is_datetime64_any_dtype, is_numeric_dtype, is_string_dtype, pd
+from customer_retention.core.config.column_config import ColumnType, DatasetGranularity
+
+from .profile_result import GranularityResult, TypeConfidence, TypeInference
+
+
+class TypeDetector:
+    IDENTIFIER_PATTERNS = ["id", "key", "code", "uuid", "guid"]
+    TARGET_PATTERNS_PRIMARY = ["churned", "retained", "churn", "retention", "attrition"]
+    TARGET_PATTERNS_SECONDARY = [
+        "unsubscribe", "unsubscribed", "terminate", "terminated", "cancel", "cancelled",
+        "close", "closed", "discontinue", "discontinued", "exit", "exited", "leave", "left",
+    ]
+    TARGET_PATTERNS_GENERIC = ["target", "label", "outcome", "class", "flag"]
+    CYCLICAL_DAY_PATTERNS = ["mon", "tue", "wed", "thu", "fri", "sat", "sun", "monday", "tuesday", "wednesday"]
+    CYCLICAL_MONTH_PATTERNS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"]
+
+    def __init__(self):
+        self.evidence = []
+
+    def detect_type(self, series: pd.Series, column_name: str) -> TypeInference:
+        self.evidence = []
+
+        if self.is_identifier(series, column_name):
+            return TypeInference(
+                inferred_type=ColumnType.IDENTIFIER,
+                confidence=TypeConfidence.HIGH,
+                evidence=self.evidence.copy()
+            )
+
+        if self.is_target(series, column_name):
+            return TypeInference(
+                inferred_type=ColumnType.TARGET,
+                confidence=TypeConfidence.HIGH,
+                evidence=self.evidence.copy()
+            )
+
+        if self.is_binary(series):
+            return TypeInference(
+                inferred_type=ColumnType.BINARY,
+                confidence=TypeConfidence.HIGH,
+                evidence=self.evidence.copy()
+            )
+
+        if self.is_datetime(series):
+            return TypeInference(
+                inferred_type=ColumnType.DATETIME,
+                confidence=TypeConfidence.HIGH,
+                evidence=self.evidence.copy()
+            )
+
+        if is_numeric_dtype(series):
+            return self.detect_numeric_type(series)
+
+        if is_string_dtype(series) or series.dtype == object:
+            return self.detect_categorical_type(series)
+
+        return TypeInference(
+            inferred_type=ColumnType.UNKNOWN,
+            confidence=TypeConfidence.LOW,
+            evidence=["Could not determine type"]
+        )
+
+    def is_identifier(self, series: pd.Series, column_name: str) -> bool:
+        column_lower = column_name.lower()
+        if any(pattern in column_lower for pattern in self.IDENTIFIER_PATTERNS):
+            self.evidence.append("Column name contains identifier pattern")
+            return True
+
+        if len(series) == 0:
+            return False
+
+        if is_datetime64_any_dtype(series):
+            return False
+
+        if is_numeric_dtype(series):
+            return False
+
+        distinct_count = series.nunique()
+        distinct_ratio = distinct_count / len(series)
+
+        if distinct_ratio == 1.0 and distinct_count <= 100:
+            if series.dtype == object:
+                sample = series.dropna().head(100)
+                if len(sample) > 0:
+                    parseable_count = 0
+                    for value in sample:
+                        try:
+                            pd.to_datetime(value, format='mixed')
+                            parseable_count += 1
+                        except (ValueError, TypeError):
+                            pass
+
+                    if parseable_count / len(sample) > 0.8:
+                        return False
+
+            self.evidence.append("All values are unique (100%)")
+            return True
+
+        return False
+
+    def is_target(self, series: pd.Series, column_name: str) -> bool:
+        column_lower = column_name.lower()
+        distinct_count = series.nunique()
+        if distinct_count > 10:
+            return False
+
+        for pattern in self.TARGET_PATTERNS_PRIMARY:
+            if pattern in column_lower:
+                self.evidence.append(f"Column name contains primary target pattern '{pattern}' with {distinct_count} classes")
+                return True
+
+        for pattern in self.TARGET_PATTERNS_SECONDARY:
+            if pattern in column_lower:
+                self.evidence.append(f"Column name contains secondary target pattern '{pattern}' with {distinct_count} classes")
+                return True
+
+        for pattern in self.TARGET_PATTERNS_GENERIC:
+            if pattern in column_lower:
+                self.evidence.append(f"Column name contains generic target pattern '{pattern}' with {distinct_count} classes")
+                return True
+
+        return False
+
+    def is_binary(self, series: pd.Series) -> bool:
+        distinct_count = series.nunique()
+        if distinct_count != 2:
+            return False
+
+        unique_values = set(series.dropna().unique())
+
+        binary_sets = [
+            {0, 1}, {0.0, 1.0},
+            {True, False},
+            {"0", "1"},
+            {"yes", "no"}, {"Yes", "No"}, {"YES", "NO"},
+            {"true", "false"}, {"True", "False"}, {"TRUE", "FALSE"},
+            {"y", "n"}, {"Y", "N"}
+        ]
+
+        for binary_set in binary_sets:
+            if unique_values == binary_set or unique_values.issubset(binary_set):
+                self.evidence.append(f"Exactly 2 unique values: {unique_values}")
+                return True
+
+        if distinct_count == 2:
+            self.evidence.append(f"Exactly 2 unique values (non-standard): {unique_values}")
+            return True
+
+        return False
+
+    def is_datetime(self, series: pd.Series) -> bool:
+        if is_datetime64_any_dtype(series):
+            self.evidence.append("Column is datetime dtype")
+            return True
+
+        if series.dtype == object:
+            sample = series.dropna().head(100)
+            if len(sample) == 0:
+                return False
+
+            parseable_count = 0
+            for value in sample:
+                try:
+                    pd.to_datetime(value, format='mixed')
+                    parseable_count += 1
+                except (ValueError, TypeError):
+                    pass
+
+            if parseable_count / len(sample) > 0.8:
+                self.evidence.append(f"{parseable_count}/{len(sample)} values parseable as datetime")
+                return True
+
+        return False
+
+    def detect_numeric_type(self, series: pd.Series) -> TypeInference:
+        distinct_count = series.nunique()
+
+        if distinct_count <= 20:
+            self.evidence.append(f"Numeric with {distinct_count} unique values (≤20)")
+            return TypeInference(
+                inferred_type=ColumnType.NUMERIC_DISCRETE,
+                confidence=TypeConfidence.MEDIUM,
+                evidence=self.evidence.copy(),
+                alternatives=[ColumnType.NUMERIC_CONTINUOUS]
+            )
+
+        self.evidence.append(f"Numeric with {distinct_count} unique values (>20)")
+        return TypeInference(
+            inferred_type=ColumnType.NUMERIC_CONTINUOUS,
+            confidence=TypeConfidence.HIGH,
+            evidence=self.evidence.copy()
+        )
+
+    def detect_categorical_type(self, series: pd.Series) -> TypeInference:
+        if len(series) == 0 or series.dropna().empty:
+            return TypeInference(
+                inferred_type=ColumnType.UNKNOWN,
+                confidence=TypeConfidence.LOW,
+                evidence=["Empty or all-null series"]
+            )
+
+        distinct_count = series.nunique()
+
+        if self.is_cyclical_pattern(series):
+            return TypeInference(
+                inferred_type=ColumnType.CATEGORICAL_CYCLICAL,
+                confidence=TypeConfidence.MEDIUM,
+                evidence=self.evidence.copy()
+            )
+
+        if distinct_count <= 10:
+            self.evidence.append(f"String with {distinct_count} unique values (≤10)")
+            return TypeInference(
+                inferred_type=ColumnType.CATEGORICAL_NOMINAL,
+                confidence=TypeConfidence.HIGH,
+                evidence=self.evidence.copy()
+            )
+
+        if distinct_count <= 100:
+            self.evidence.append(f"String with {distinct_count} unique values (≤100)")
+            return TypeInference(
+                inferred_type=ColumnType.CATEGORICAL_NOMINAL,
+                confidence=TypeConfidence.MEDIUM,
+                evidence=self.evidence.copy()
+            )
+
+        self.evidence.append(f"String with {distinct_count} unique values (>100)")
+        return TypeInference(
+            inferred_type=ColumnType.TEXT,
+            confidence=TypeConfidence.MEDIUM,
+            evidence=self.evidence.copy(),
+            alternatives=[ColumnType.CATEGORICAL_NOMINAL]
+        )
+
+    def is_cyclical_pattern(self, series: pd.Series) -> bool:
+        sample_values = [str(v).lower() for v in series.dropna().unique()[:20]]
+
+        if len(sample_values) == 0:
+            return False
+
+        day_matches = sum(1 for v in sample_values if any(day in v for day in self.CYCLICAL_DAY_PATTERNS))
+        if day_matches >= min(3, len(sample_values)):
+            self.evidence.append("Contains day name patterns (cyclical)")
+            return True
+
+        month_matches = sum(1 for v in sample_values if any(month in v for month in self.CYCLICAL_MONTH_PATTERNS))
+        if month_matches >= min(3, len(sample_values)):
+            self.evidence.append("Contains month name patterns (cyclical)")
+            return True
+
+        return False
+
+    def detect_granularity(self, df: DataFrame) -> GranularityResult:
+        """Detect whether dataset is entity-level or event-level (time series)."""
+        evidence = []
+
+        if df is None or len(df) == 0 or len(df.columns) == 0:
+            return GranularityResult(
+                granularity=DatasetGranularity.UNKNOWN,
+                evidence=["Empty or invalid DataFrame"]
+            )
+
+        entity_column = self._detect_entity_column(df)
+        time_column = self._detect_time_column(df)
+
+        if entity_column is None:
+            evidence.append("No clear entity/ID column detected")
+            return GranularityResult(
+                granularity=DatasetGranularity.UNKNOWN,
+                evidence=evidence
+            )
+
+        unique_entities = df[entity_column].nunique()
+        total_rows = len(df)
+        avg_events = total_rows / unique_entities if unique_entities > 0 else 0
+
+        if unique_entities == total_rows:
+            evidence.append(f"Each {entity_column} appears exactly once")
+            return GranularityResult(
+                granularity=DatasetGranularity.ENTITY_LEVEL,
+                entity_column=entity_column,
+                time_column=time_column,
+                unique_entities=unique_entities,
+                total_rows=total_rows,
+                avg_events_per_entity=1.0,
+                evidence=evidence
+            )
+
+        if avg_events > 1.5 and time_column is not None:
+            evidence.append(f"Multiple rows per {entity_column} (avg {avg_events:.1f})")
+            evidence.append(f"Temporal column detected: {time_column}")
+            return GranularityResult(
+                granularity=DatasetGranularity.EVENT_LEVEL,
+                entity_column=entity_column,
+                time_column=time_column,
+                unique_entities=unique_entities,
+                total_rows=total_rows,
+                avg_events_per_entity=round(avg_events, 2),
+                evidence=evidence
+            )
+
+        if avg_events > 1.5:
+            evidence.append(f"Multiple rows per {entity_column} but no datetime column")
+            return GranularityResult(
+                granularity=DatasetGranularity.EVENT_LEVEL,
+                entity_column=entity_column,
+                time_column=None,
+                unique_entities=unique_entities,
+                total_rows=total_rows,
+                avg_events_per_entity=round(avg_events, 2),
+                evidence=evidence
+            )
+
+        evidence.append("Could not determine granularity with confidence")
+        return GranularityResult(
+            granularity=DatasetGranularity.UNKNOWN,
+            entity_column=entity_column,
+            time_column=time_column,
+            evidence=evidence
+        )
+
+    def _detect_entity_column(self, df: DataFrame) -> Optional[str]:
+        """Find the most likely entity/ID column."""
+        candidates = []
+
+        for col in df.columns:
+            col_lower = col.lower()
+
+            if any(pattern in col_lower for pattern in self.IDENTIFIER_PATTERNS):
+                unique_ratio = df[col].nunique() / len(df)
+                if 0.01 < unique_ratio < 1.0:
+                    candidates.append((col, unique_ratio, "name_match"))
+                elif unique_ratio == 1.0:
+                    candidates.append((col, unique_ratio, "unique_id"))
+
+        if not candidates:
+            for col in df.columns:
+                if df[col].dtype == object or str(df[col].dtype).startswith("str"):
+                    unique_ratio = df[col].nunique() / len(df)
+                    if 0.01 < unique_ratio < 0.5:
+                        candidates.append((col, unique_ratio, "string_repeating"))
+
+        if not candidates:
+            return None
+
+        for col, ratio, match_type in candidates:
+            if match_type == "name_match" and ratio < 1.0:
+                return col
+
+        for col, ratio, match_type in candidates:
+            if match_type == "unique_id":
+                return col
+
+        return candidates[0][0] if candidates else None
+
+    def _detect_time_column(self, df: DataFrame) -> Optional[str]:
+        """Find the most likely datetime/timestamp column."""
+        for col in df.columns:
+            if is_datetime64_any_dtype(df[col]):
+                return col
+
+        datetime_patterns = ["date", "time", "timestamp", "created", "updated", "sent", "event"]
+        for col in df.columns:
+            col_lower = col.lower()
+            if any(pattern in col_lower for pattern in datetime_patterns):
+                if df[col].dtype == object:
+                    sample = df[col].dropna().head(20)
+                    if len(sample) > 0:
+                        parseable = 0
+                        for val in sample:
+                            try:
+                                pd.to_datetime(val, format='mixed')
+                                parseable += 1
+                            except (ValueError, TypeError):
+                                pass
+                        if parseable / len(sample) > 0.8:
+                            return col
+
+        return None

customer_retention/stages/profiling/window_recommendation.py

@@ -0,0 +1,288 @@
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+import pandas as pd
+
+from .temporal_pattern_analyzer import SeasonalityPeriod
+from .time_series_profiler import ActivitySegmentResult, LifecycleQuadrantResult
+
+WINDOW_DAYS_MAP: Dict[str, Optional[float]] = {
+    "24h": 1.0, "7d": 7.0, "14d": 14.0, "30d": 30.0,
+    "90d": 90.0, "180d": 180.0, "365d": 365.0, "all_time": None,
+}
+
+SEASONALITY_WINDOW_MAP: Dict[int, str] = {
+    1: "24h", 7: "7d", 14: "14d", 30: "30d", 90: "90d", 365: "365d",
+}
+
+TIMING_TOLERANCE = 0.5
+
+
+@dataclass
+class TemporalHeterogeneityResult:
+    eta_squared_intensity: float
+    eta_squared_event_count: float
+    heterogeneity_level: str
+    segmentation_advisory: str
+    advisory_rationale: List[str]
+    coverage_table: pd.DataFrame
+
+
+@dataclass
+class WindowUnionResult:
+    windows: List[str]
+    explanation: pd.DataFrame
+    heterogeneity: TemporalHeterogeneityResult
+    coverage_threshold: float
+    feature_count_estimate: int
+
+
+class WindowRecommendationCollector:
+    ALL_CANDIDATE_WINDOWS = ["24h", "7d", "14d", "30d", "90d", "180d", "365d", "all_time"]
+
+    def __init__(self, coverage_threshold: float = 0.10, always_include: Optional[List[str]] = None):
+        self._coverage_threshold = coverage_threshold
+        self._always_include = always_include if always_include is not None else ["all_time"]
+        self._segment_lifecycles: Optional[pd.DataFrame] = None
+        self._quadrant_lifecycles: Optional[pd.DataFrame] = None
+        self._seasonality_periods: List[SeasonalityPeriod] = []
+        self._inter_event_median: Optional[float] = None
+        self._inter_event_mean: Optional[float] = None
+
+    def add_segment_context(self, result: ActivitySegmentResult) -> None:
+        self._segment_lifecycles = result.lifecycles
+
+    def add_quadrant_context(self, result: LifecycleQuadrantResult) -> None:
+        self._quadrant_lifecycles = result.lifecycles
+
+    def add_seasonality_context(self, periods: List[SeasonalityPeriod]) -> None:
+        self._seasonality_periods = periods
+
+    def add_inter_event_context(self, median_days: float, mean_days: float) -> None:
+        self._inter_event_median = median_days
+        self._inter_event_mean = mean_days
+
+    def compute_union(
+        self, lifecycles: pd.DataFrame, time_span_days: int,
+        min_coverage_ratio: float = 2.0,
+        value_columns: int = 0, agg_funcs: int = 4,
+    ) -> WindowUnionResult:
+        rows = self._compute_coverage_rows(lifecycles, time_span_days, min_coverage_ratio)
+        self._annotate_context(rows, lifecycles)
+        selected = [r["window"] for r in rows if r["included"]]
+        explanation = pd.DataFrame(rows)
+        heterogeneity = self._compute_heterogeneity(lifecycles, selected)
+        feature_count = value_columns * agg_funcs * len(selected) + len(selected) if value_columns > 0 else len(selected)
+        return WindowUnionResult(
+            windows=selected, explanation=explanation,
+            heterogeneity=heterogeneity, coverage_threshold=self._coverage_threshold,
+            feature_count_estimate=feature_count,
+        )
+
+    def _compute_coverage_rows(
+        self, lifecycles: pd.DataFrame, time_span_days: int, min_coverage_ratio: float,
+    ) -> List[Dict]:
+        duration = lifecycles["duration_days"].astype(float)
+        event_count = lifecycles["event_count"].astype(float)
+        n = len(lifecycles)
+        rows = []
+        for window in self.ALL_CANDIDATE_WINDOWS:
+            window_days = WINDOW_DAYS_MAP[window]
+            if window_days is None:
+                rows.append(self._all_time_row(n))
+                continue
+            has_span = duration >= window_days
+            expected_events = event_count * (window_days / duration.clip(lower=1))
+            has_density = expected_events >= 2
+            beneficial = has_span & has_density
+            coverage_pct = beneficial.mean()
+            meaningful_pct = has_density[has_span].mean() if has_span.any() else 0.0
+            beneficial_count = int(beneficial.sum())
+            hard_excluded = time_span_days < window_days * min_coverage_ratio
+            included, exclusion_reason = self._determine_inclusion(
+                window, coverage_pct, hard_excluded,
+            )
+            rows.append({
+                "window": window, "window_days": window_days,
+                "coverage_pct": round(coverage_pct, 4),
+                "meaningful_pct": round(meaningful_pct, 4),
+                "beneficial_entities": beneficial_count,
+                "primary_segments": [], "included": included,
+                "exclusion_reason": exclusion_reason, "note": "",
+            })
+        return rows
+
+    def _all_time_row(self, n: int) -> Dict:
+        return {
+            "window": "all_time", "window_days": None,
+            "coverage_pct": 1.0, "meaningful_pct": 1.0,
+            "beneficial_entities": n, "primary_segments": [],
+            "included": True, "exclusion_reason": "", "note": "",
+        }
+
+    def _determine_inclusion(self, window: str, coverage_pct: float, hard_excluded: bool) -> Tuple[bool, str]:
+        if hard_excluded:
+            if window in self._always_include:
+                return True, ""
+            return False, f"Excluded: span < {WINDOW_DAYS_MAP[window] * 2:.0f}d required"
+        if window in self._always_include:
+            return True, ""
+        if coverage_pct >= self._coverage_threshold:
+            return True, ""
+        return False, f"Coverage {coverage_pct:.1%} < threshold {self._coverage_threshold:.1%}"
+
+    def _annotate_context(self, rows: List[Dict], lifecycles: pd.DataFrame) -> None:
+        self._annotate_segments(rows, lifecycles)
+        self._annotate_seasonality(rows)
+        self._annotate_timing(rows)
+
+    def _annotate_segments(self, rows: List[Dict], lifecycles: pd.DataFrame) -> None:
+        context_lc = self._segment_lifecycles if self._segment_lifecycles is not None else self._quadrant_lifecycles
+        if context_lc is None:
+            return
+        group_col = "activity_segment" if "activity_segment" in (context_lc.columns if self._segment_lifecycles is not None else []) else None
+        if group_col is None and self._quadrant_lifecycles is not None and "lifecycle_quadrant" in self._quadrant_lifecycles.columns:
+            group_col = "lifecycle_quadrant"
+            context_lc = self._quadrant_lifecycles
+        if group_col is None:
+            return
+        duration = context_lc["duration_days"].astype(float)
+        event_count = context_lc["event_count"].astype(float)
+        groups = context_lc[group_col]
+        for row in rows:
+            window_days = row["window_days"]
+            if window_days is None:
+                row["primary_segments"] = sorted(groups.unique().tolist())
+                continue
+            has_span = duration >= window_days
+            expected_events = event_count * (window_days / duration.clip(lower=1))
+            beneficial = has_span & (expected_events >= 2)
+            if not beneficial.any():
+                continue
+            group_coverage = groups[beneficial].value_counts(normalize=True)
+            top = group_coverage[group_coverage >= 0.15].index.tolist()
+            row["primary_segments"] = sorted(top[:3])
+
+    def _annotate_seasonality(self, rows: List[Dict]) -> None:
+        if not self._seasonality_periods:
+            return
+        detected_windows = set()
+        for sp in self._seasonality_periods:
+            if sp.period in SEASONALITY_WINDOW_MAP:
+                detected_windows.add(SEASONALITY_WINDOW_MAP[sp.period])
+        for row in rows:
+            if row["window"] in detected_windows:
+                period_name = next(
+                    (sp.period_name or f"{sp.period}d" for sp in self._seasonality_periods
+                     if SEASONALITY_WINDOW_MAP.get(sp.period) == row["window"]), ""
+                )
+                row["note"] = f"Seasonality detected ({period_name})"
+
+    def _annotate_timing(self, rows: List[Dict]) -> None:
+        if self._inter_event_median is None:
+            return
+        for row in rows:
+            window_days = row["window_days"]
+            if window_days is None:
+                continue
+            ratio = self._inter_event_median / window_days if window_days > 0 else 0
+            if TIMING_TOLERANCE <= ratio <= (1.0 / TIMING_TOLERANCE):
+                existing = row["note"]
+                timing_note = "Timing-aligned (median inter-event)"
+                row["note"] = f"{existing}; {timing_note}" if existing else timing_note
+
+    def _compute_heterogeneity(self, lifecycles: pd.DataFrame, selected_windows: List[str]) -> TemporalHeterogeneityResult:
+        eta_intensity, eta_event = self._compute_eta_squared(lifecycles)
+        level = self._classify_heterogeneity(max(eta_intensity, eta_event))
+        cold_start_frac = self._cold_start_fraction(lifecycles)
+        advisory, rationale = self._build_advisory(level, cold_start_frac, selected_windows, lifecycles)
+        coverage_table = self._build_coverage_table(lifecycles, selected_windows)
+        return TemporalHeterogeneityResult(
+            eta_squared_intensity=eta_intensity,
+            eta_squared_event_count=eta_event,
+            heterogeneity_level=level,
+            segmentation_advisory=advisory,
+            advisory_rationale=rationale,
+            coverage_table=coverage_table,
+        )
+
+    def _compute_eta_squared(self, lifecycles: pd.DataFrame) -> Tuple[float, float]:
+        group_col = "lifecycle_quadrant" if "lifecycle_quadrant" in lifecycles.columns else None
+        if group_col is None:
+            return 0.0, 0.0
+        groups = lifecycles[group_col]
+        if groups.nunique() < 2:
+            return 0.0, 0.0
+        eta_intensity = self._eta_squared_for_variable(lifecycles, "intensity", groups)
+        eta_event = self._eta_squared_for_variable(lifecycles, "event_count", groups)
+        return eta_intensity, eta_event
+
+    def _eta_squared_for_variable(self, df: pd.DataFrame, var: str, groups: pd.Series) -> float:
+        if var not in df.columns:
+            return 0.0
+        values = df[var].astype(float)
+        grand_mean = values.mean()
+        ss_total = ((values - grand_mean) ** 2).sum()
+        if ss_total == 0:
+            return 0.0
+        ss_between = 0.0
+        for _, group_vals in values.groupby(groups):
+            n_k = len(group_vals)
+            mean_k = group_vals.mean()
+            ss_between += n_k * (mean_k - grand_mean) ** 2
+        return float(ss_between / ss_total)
+
+    def _classify_heterogeneity(self, eta_max: float) -> str:
+        if eta_max < 0.06:
+            return "low"
+        if eta_max < 0.14:
+            return "moderate"
+        return "high"
+
+    def _cold_start_fraction(self, lifecycles: pd.DataFrame) -> float:
+        cold_labels = {"One-shot", "One-time"}
+        cold_count = 0
+        for col in ("lifecycle_quadrant", "activity_segment"):
+            if col in lifecycles.columns:
+                cold_count = max(cold_count, lifecycles[col].isin(cold_labels).sum())
+        return cold_count / len(lifecycles) if len(lifecycles) > 0 else 0.0
+
+    def _build_advisory(
+        self, level: str, cold_start_frac: float, selected_windows: List[str], lifecycles: pd.DataFrame,
+    ) -> Tuple[str, List[str]]:
+        rationale: List[str] = []
+        if level == "low":
+            rationale.append("Low temporal diversity across quadrants")
+            rationale.append("Union strategy loses minimal signal")
+            return "single_model", rationale
+        if level == "high" and cold_start_frac > 0.30:
+            rationale.append("High temporal diversity across quadrants")
+            rationale.append(f"Large cold-start population ({cold_start_frac:.0%} One-time/One-shot)")
+            rationale.append("Consider separate handling for entities with vs without history")
+            return "consider_separate_models", rationale
+        rationale.append(f"{level.capitalize()} temporal diversity across quadrants")
+        rationale.append("Union windows still pragmatic for feature engineering")
+        rationale.append("Model may benefit from knowing entity's engagement pattern")
+        return "consider_segment_feature", rationale
+
+    def _build_coverage_table(self, lifecycles: pd.DataFrame, selected_windows: List[str]) -> pd.DataFrame:
+        duration = lifecycles["duration_days"].astype(float)
+        event_count = lifecycles["event_count"].astype(float)
+        rows = []
+        for window in selected_windows:
+            window_days = WINDOW_DAYS_MAP.get(window)
+            if window_days is None:
+                rows.append({"window": "all_time", "coverage_pct": 1.0, "meaningful_pct": 1.0, "zero_risk_pct": 0.0})
+                continue
+            has_span = duration >= window_days
+            coverage = has_span.mean()
+            expected_events = event_count * (window_days / duration.clip(lower=1))
+            meaningful = (has_span & (expected_events >= 2)).mean()
+            zero_risk = 1.0 - meaningful
+            rows.append({
+                "window": window,
+                "coverage_pct": round(float(coverage), 4),
+                "meaningful_pct": round(float(meaningful), 4),
+                "zero_risk_pct": round(float(zero_risk), 4),
+            })
+        return pd.DataFrame(rows)