churnkit 0.75.0a1__py3-none-any.whl

customer_retention/analysis/recommendations/pipeline.py

@@ -0,0 +1,74 @@
+from typing import TYPE_CHECKING, Any, Dict, Iterator, List, Optional
+
+import pandas as pd
+
+from .base import BaseRecommendation, Platform
+
+if TYPE_CHECKING:
+    from customer_retention.analysis.auto_explorer.findings import ExplorationFindings
+    from customer_retention.stages.features.feature_definitions import FeatureCatalog
+
+
+class RecommendationPipeline:
+    def __init__(self, recommendations: List[BaseRecommendation] = None):
+        self.recommendations = recommendations or []
+        self._is_fitted = False
+
+    def add(self, recommendation: BaseRecommendation) -> "RecommendationPipeline":
+        self.recommendations.append(recommendation)
+        return self
+
+    def fit(self, df: pd.DataFrame) -> "RecommendationPipeline":
+        for rec in self.recommendations:
+            rec.fit(df)
+        self._is_fitted = True
+        return self
+
+    def transform(
+        self, df: pd.DataFrame, platform: Platform = Platform.LOCAL,
+        mlflow_adapter: Optional[Any] = None
+    ) -> pd.DataFrame:
+        for rec in self.recommendations:
+            result = rec.transform(df, platform, mlflow_adapter=mlflow_adapter)
+            df = result.data
+        return df
+
+    def fit_transform(
+        self, df: pd.DataFrame, platform: Platform = Platform.LOCAL,
+        mlflow_adapter: Optional[Any] = None
+    ) -> pd.DataFrame:
+        self.fit(df)
+        return self.transform(df, platform, mlflow_adapter=mlflow_adapter)
+
+    def generate_code(self, platform: Platform = Platform.LOCAL) -> str:
+        if not self.recommendations:
+            return ""
+        lines = []
+        for rec in self.recommendations:
+            lines.append(rec.generate_code(platform))
+            lines.append("")
+        return "\n".join(lines).strip()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "recommendations": [rec.to_dict() for rec in self.recommendations],
+            "is_fitted": self._is_fitted,
+        }
+
+    def to_feature_catalog(self) -> "FeatureCatalog":
+        from customer_retention.stages.features.feature_definitions import FeatureCatalog
+        catalog = FeatureCatalog()
+        for rec in self.recommendations:
+            catalog.add(rec.to_feature_definition())
+        return catalog
+
+    @classmethod
+    def from_findings(cls, findings: "ExplorationFindings") -> "RecommendationPipeline":
+        from .registry import RecommendationRegistry
+        return cls(RecommendationRegistry.from_findings(findings))
+
+    def __len__(self) -> int:
+        return len(self.recommendations)
+
+    def __iter__(self) -> Iterator[BaseRecommendation]:
+        return iter(self.recommendations)

customer_retention/analysis/recommendations/registry.py

@@ -0,0 +1,76 @@
+import re
+from typing import TYPE_CHECKING, List, Optional
+
+from .base import BaseRecommendation
+from .cleaning import ImputeRecommendation, OutlierCapRecommendation
+from .datetime import DaysSinceRecommendation, ExtractDayOfWeekRecommendation, ExtractMonthRecommendation
+from .encoding import LabelEncodeRecommendation, OneHotEncodeRecommendation
+from .transform import LogTransformRecommendation, MinMaxScaleRecommendation, StandardScaleRecommendation
+
+if TYPE_CHECKING:
+    from customer_retention.analysis.auto_explorer.findings import ColumnFinding, ExplorationFindings
+
+
+class RecommendationRegistry:
+    @classmethod
+    def create_cleaning(cls, rec_str: str, columns: List[str], finding: Optional["ColumnFinding"]) -> Optional[BaseRecommendation]:
+        if rec_str == "impute_median":
+            return ImputeRecommendation(columns, strategy="median", source_finding=finding)
+        if rec_str == "impute_mean":
+            return ImputeRecommendation(columns, strategy="mean", source_finding=finding)
+        if rec_str == "impute_mode":
+            return ImputeRecommendation(columns, strategy="mode", source_finding=finding)
+        if rec_str == "impute_zero":
+            return ImputeRecommendation(columns, strategy="constant", fill_value=0, source_finding=finding)
+        if match := re.match(r"cap_outliers_(\d+)", rec_str):
+            return OutlierCapRecommendation(columns, percentile=int(match.group(1)), source_finding=finding)
+        return None
+
+    @classmethod
+    def create_transform(cls, rec_str: str, columns: List[str], finding: Optional["ColumnFinding"]) -> Optional[BaseRecommendation]:
+        if rec_str == "standard_scale":
+            return StandardScaleRecommendation(columns, source_finding=finding)
+        if rec_str == "minmax_scale":
+            return MinMaxScaleRecommendation(columns, source_finding=finding)
+        if rec_str == "log_transform":
+            return LogTransformRecommendation(columns, source_finding=finding)
+        return None
+
+    @classmethod
+    def create_encoding(cls, rec_str: str, columns: List[str], finding: Optional["ColumnFinding"]) -> Optional[BaseRecommendation]:
+        if rec_str == "onehot_encode":
+            return OneHotEncodeRecommendation(columns, source_finding=finding)
+        if rec_str == "label_encode":
+            return LabelEncodeRecommendation(columns, source_finding=finding)
+        return None
+
+    @classmethod
+    def create_datetime(cls, rec_str: str, columns: List[str], finding: Optional["ColumnFinding"]) -> Optional[BaseRecommendation]:
+        if rec_str == "extract_month":
+            return ExtractMonthRecommendation(columns, source_finding=finding)
+        if rec_str == "extract_dayofweek":
+            return ExtractDayOfWeekRecommendation(columns, source_finding=finding)
+        if rec_str == "days_since":
+            return DaysSinceRecommendation(columns, source_finding=finding)
+        return None
+
+    @classmethod
+    def from_findings(cls, findings: "ExplorationFindings") -> List[BaseRecommendation]:
+        from customer_retention.core.config.column_config import ColumnType
+        recommendations = []
+        for col_name, col_finding in findings.columns.items():
+            if col_finding.inferred_type in (ColumnType.IDENTIFIER, ColumnType.TARGET):
+                continue
+            cleaning_recs = getattr(col_finding, "cleaning_recommendations", []) or []
+            for rec_str in cleaning_recs:
+                rec = cls.create_cleaning(rec_str, [col_name], col_finding)
+                if rec:
+                    recommendations.append(rec)
+            transform_recs = getattr(col_finding, "transformation_recommendations", []) or []
+            for rec_str in transform_recs:
+                rec = cls.create_transform(rec_str, [col_name], col_finding) or \
+                      cls.create_encoding(rec_str, [col_name], col_finding) or \
+                      cls.create_datetime(rec_str, [col_name], col_finding)
+                if rec:
+                    recommendations.append(rec)
+        return recommendations

customer_retention/analysis/recommendations/selection/__init__.py

@@ -0,0 +1,3 @@
+from .drop_column import DropColumnRecommendation
+
+__all__ = ["DropColumnRecommendation"]

customer_retention/analysis/recommendations/selection/drop_column.py

@@ -0,0 +1,56 @@
+from typing import Any, List, Optional
+
+import pandas as pd
+
+from ..base import BaseRecommendation, RecommendationResult
+
+
+class DropColumnRecommendation(BaseRecommendation):
+    def __init__(
+        self, columns: List[str], rationale: str = None, reason: str = "not_specified",
+        evidence: List[str] = None, priority: str = "medium", source_finding: Optional[Any] = None
+    ):
+        rationale = rationale or f"Drop columns: {', '.join(columns)}"
+        super().__init__(columns, rationale, evidence, priority, source_finding)
+        self.reason = reason
+        self._columns_to_drop: List[str] = []
+
+    @property
+    def category(self) -> str:
+        return "feature_selection"
+
+    @property
+    def recommendation_type(self) -> str:
+        return f"drop_{self.reason}"
+
+    def _fit_impl(self, df: pd.DataFrame) -> None:
+        self._columns_to_drop = [c for c in self.columns if c in df.columns]
+
+    def _transform_local(self, df: pd.DataFrame) -> RecommendationResult:
+        df = df.copy()
+        rows_before = len(df)
+        cols_to_drop = [c for c in self._columns_to_drop if c in df.columns]
+        if cols_to_drop:
+            df = df.drop(columns=cols_to_drop)
+        return RecommendationResult(
+            data=df, columns_affected=self._columns_to_drop, rows_before=rows_before,
+            rows_after=len(df), metadata={"dropped_columns": cols_to_drop}
+        )
+
+    def _transform_databricks(self, df: pd.DataFrame) -> RecommendationResult:
+        from customer_retention.core.compat import is_spark_available
+        if not is_spark_available():
+            return self._transform_local(df)
+        return self._transform_local(df)
+
+    def _generate_local_code(self) -> str:
+        cols_str = ", ".join(f"'{c}'" for c in self._columns_to_drop)
+        lines = [f"# Drop columns: {self.rationale}"]
+        lines.append(f"df = df.drop(columns=[{cols_str}])")
+        return "\n".join(lines)
+
+    def _generate_databricks_code(self) -> str:
+        cols_str = ", ".join(f"'{c}'" for c in self._columns_to_drop)
+        lines = [f"# Drop columns: {self.rationale}"]
+        lines.append(f"df = df.drop([{cols_str}])")
+        return "\n".join(lines)

customer_retention/analysis/recommendations/transform/__init__.py

@@ -0,0 +1,4 @@
+from .power import LogTransformRecommendation, SqrtTransformRecommendation
+from .scale import MinMaxScaleRecommendation, StandardScaleRecommendation
+
+__all__ = ["StandardScaleRecommendation", "MinMaxScaleRecommendation", "LogTransformRecommendation", "SqrtTransformRecommendation"]

customer_retention/analysis/recommendations/transform/power.py

@@ -0,0 +1,94 @@
+from typing import Any, List, Optional
+
+import numpy as np
+import pandas as pd
+
+from ..base import RecommendationResult, TransformRecommendation
+
+
+class LogTransformRecommendation(TransformRecommendation):
+    def __init__(
+        self, columns: List[str], rationale: str = None, evidence: List[str] = None,
+        priority: str = "medium", source_finding: Optional[Any] = None
+    ):
+        rationale = rationale or "Apply log1p transform to reduce skewness"
+        super().__init__(columns, rationale, evidence, priority, source_finding)
+
+    @property
+    def recommendation_type(self) -> str:
+        return "log_transform"
+
+    def _fit_impl(self, df: pd.DataFrame) -> None:
+        self._fit_params["columns"] = self.columns
+
+    def _transform_local(self, df: pd.DataFrame) -> RecommendationResult:
+        df = df.copy()
+        for col in self.columns:
+            if col in df.columns:
+                df[col] = np.log1p(df[col])
+        return RecommendationResult(
+            data=df, columns_affected=self.columns, rows_before=len(df),
+            rows_after=len(df), metadata={"transform": "log1p"}
+        )
+
+    def _transform_databricks(self, df: pd.DataFrame) -> RecommendationResult:
+        from customer_retention.core.compat import is_spark_available
+        if not is_spark_available():
+            return self._transform_local(df)
+        return self._transform_local(df)
+
+    def _generate_local_code(self) -> str:
+        lines = [f"# Transform: {self.rationale}", "import numpy as np"]
+        for col in self.columns:
+            lines.append(f"df['{col}'] = np.log1p(df['{col}'])")
+        return "\n".join(lines)
+
+    def _generate_databricks_code(self) -> str:
+        lines = [f"# Transform: {self.rationale}", "from pyspark.sql.functions import log1p, col"]
+        for col in self.columns:
+            lines.append(f"df = df.withColumn('{col}', log1p(col('{col}')))")
+        return "\n".join(lines)
+
+
+class SqrtTransformRecommendation(TransformRecommendation):
+    def __init__(
+        self, columns: List[str], rationale: str = None, evidence: List[str] = None,
+        priority: str = "medium", source_finding: Optional[Any] = None
+    ):
+        rationale = rationale or "Apply sqrt transform to reduce moderate skewness"
+        super().__init__(columns, rationale, evidence, priority, source_finding)
+
+    @property
+    def recommendation_type(self) -> str:
+        return "sqrt_transform"
+
+    def _fit_impl(self, df: pd.DataFrame) -> None:
+        self._fit_params["columns"] = self.columns
+
+    def _transform_local(self, df: pd.DataFrame) -> RecommendationResult:
+        df = df.copy()
+        for col in self.columns:
+            if col in df.columns:
+                df[col] = np.sqrt(df[col])
+        return RecommendationResult(
+            data=df, columns_affected=self.columns, rows_before=len(df),
+            rows_after=len(df), metadata={"transform": "sqrt"}
+        )
+
+    def _transform_databricks(self, df: pd.DataFrame) -> RecommendationResult:
+        from customer_retention.core.compat import is_spark_available
+        if not is_spark_available():
+            return self._transform_local(df)
+        return self._transform_local(df)
+
+    def _generate_local_code(self) -> str:
+        lines = [f"# Transform: {self.rationale}", "import numpy as np"]
+        for col in self.columns:
+            lines.append(f"df['{col}'] = np.sqrt(df['{col}'])")
+        return "\n".join(lines)
+
+    def _generate_databricks_code(self) -> str:
+        lines = [f"# Transform: {self.rationale}", "from pyspark.sql.functions import sqrt, col"]
+        for col in self.columns:
+            lines.append(f"df = df.withColumn('{col}', sqrt(col('{col}')))")
+        return "\n".join(lines)

customer_retention/analysis/recommendations/transform/scale.py

@@ -0,0 +1,112 @@
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+
+from ..base import RecommendationResult, TransformRecommendation
+
+
+class StandardScaleRecommendation(TransformRecommendation):
+    def __init__(
+        self, columns: List[str], rationale: str = None, evidence: List[str] = None,
+        priority: str = "medium", source_finding: Optional[Any] = None
+    ):
+        rationale = rationale or "Standardize features to zero mean and unit variance"
+        super().__init__(columns, rationale, evidence, priority, source_finding)
+        self._means: Dict[str, float] = {}
+        self._stds: Dict[str, float] = {}
+
+    @property
+    def recommendation_type(self) -> str:
+        return "standard_scale"
+
+    def _fit_impl(self, df: pd.DataFrame) -> None:
+        for col in self.columns:
+            if col in df.columns:
+                self._means[col] = float(df[col].mean())
+                self._stds[col] = float(df[col].std(ddof=0))
+        self._fit_params = {"means": self._means, "stds": self._stds}
+
+    def _transform_local(self, df: pd.DataFrame) -> RecommendationResult:
+        df = df.copy()
+        for col in self.columns:
+            if col in df.columns and col in self._means:
+                std = self._stds[col] if self._stds[col] != 0 else 1.0
+                df[col] = (df[col] - self._means[col]) / std
+        return RecommendationResult(
+            data=df, columns_affected=self.columns, rows_before=len(df),
+            rows_after=len(df), metadata={"means": self._means, "stds": self._stds}
+        )
+
+    def _transform_databricks(self, df: pd.DataFrame) -> RecommendationResult:
+        from customer_retention.core.compat import is_spark_available
+        if not is_spark_available():
+            return self._transform_local(df)
+        return self._transform_local(df)
+
+    def _generate_local_code(self) -> str:
+        return f"""# Scale: {self.rationale}
+from sklearn.preprocessing import StandardScaler
+scaler = StandardScaler()
+df[{self.columns}] = scaler.fit_transform(df[{self.columns}])"""
+
+    def _generate_databricks_code(self) -> str:
+        return f"""# Scale: {self.rationale}
+from pyspark.ml.feature import StandardScaler, VectorAssembler
+assembler = VectorAssembler(inputCols={self.columns}, outputCol="features")
+scaler = StandardScaler(inputCol="features", outputCol="scaled", withStd=True, withMean=True)
+df = scaler.fit(assembler.transform(df)).transform(assembler.transform(df))"""
+
+
+class MinMaxScaleRecommendation(TransformRecommendation):
+    def __init__(
+        self, columns: List[str], rationale: str = None, feature_range: Tuple[float, float] = (0, 1),
+        evidence: List[str] = None, priority: str = "medium", source_finding: Optional[Any] = None
+    ):
+        rationale = rationale or f"Scale features to range {feature_range}"
+        super().__init__(columns, rationale, evidence, priority, source_finding)
+        self.feature_range = feature_range
+        self._mins: Dict[str, float] = {}
+        self._maxs: Dict[str, float] = {}
+
+    @property
+    def recommendation_type(self) -> str:
+        return "minmax_scale"
+
+    def _fit_impl(self, df: pd.DataFrame) -> None:
+        for col in self.columns:
+            if col in df.columns:
+                self._mins[col] = float(df[col].min())
+                self._maxs[col] = float(df[col].max())
+        self._fit_params = {"mins": self._mins, "maxs": self._maxs, "feature_range": self.feature_range}
+
+    def _transform_local(self, df: pd.DataFrame) -> RecommendationResult:
+        df = df.copy()
+        min_val, max_val = self.feature_range
+        for col in self.columns:
+            if col in df.columns and col in self._mins:
+                col_min, col_max = self._mins[col], self._maxs[col]
+                scale = (max_val - min_val) / (col_max - col_min) if col_max != col_min else 1.0
+                df[col] = (df[col] - col_min) * scale + min_val
+        return RecommendationResult(
+            data=df, columns_affected=self.columns, rows_before=len(df),
+            rows_after=len(df), metadata={"mins": self._mins, "maxs": self._maxs}
+        )
+
+    def _transform_databricks(self, df: pd.DataFrame) -> RecommendationResult:
+        from customer_retention.core.compat import is_spark_available
+        if not is_spark_available():
+            return self._transform_local(df)
+        return self._transform_local(df)
+
+    def _generate_local_code(self) -> str:
+        return f"""# Scale: {self.rationale}
+from sklearn.preprocessing import MinMaxScaler
+scaler = MinMaxScaler(feature_range={self.feature_range})
+df[{self.columns}] = scaler.fit_transform(df[{self.columns}])"""
+
+    def _generate_databricks_code(self) -> str:
+        return f"""# Scale: {self.rationale}
+from pyspark.ml.feature import MinMaxScaler, VectorAssembler
+assembler = VectorAssembler(inputCols={self.columns}, outputCol="features")
+scaler = MinMaxScaler(inputCol="features", outputCol="scaled", min={self.feature_range[0]}, max={self.feature_range[1]})
+df = scaler.fit(assembler.transform(df)).transform(assembler.transform(df))"""

customer_retention/analysis/visualization/__init__.py

@@ -0,0 +1,15 @@
+from . import console
+from .chart_builder import ChartBuilder
+from .display import DisplayManager, detect_environment, display_figure, display_summary, display_table
+from .number_formatter import NumberFormatter
+
+__all__ = [
+    "ChartBuilder",
+    "DisplayManager",
+    "NumberFormatter",
+    "detect_environment",
+    "display_figure",
+    "display_summary",
+    "display_table",
+    "console",
+]