churnkit 0.75.1a1__tar.gz → 0.75.1a3__tar.gz

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: churnkit
-Version: 0.75.1a1
+Version: 0.75.1a3
 Summary: Structured ML framework for customer churn prediction -- from exploration notebooks to production pipelines, locally or on Databricks.
 Project-URL: Homepage, https://github.com/aladjov/CR
 Project-URL: Documentation, https://github.com/aladjov/CR/wiki

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "churnkit"
-version = "0.75.1a1"
+version = "0.75.1a3"
 description = "Structured ML framework for customer churn prediction -- from exploration notebooks to production pipelines, locally or on Databricks."
 readme = "README.md"
 license = {text = "Apache-2.0"}

churnkit-0.75.1a3/scripts/release.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PYPROJECT="$REPO_ROOT/pyproject.toml"
+INIT_PY="$REPO_ROOT/src/customer_retention/__init__.py"
+
+usage() {
+    echo "Usage: $0 <version>"
+    echo "  e.g.  $0 0.75.1a2"
+    echo "        $0 v0.75.1a2   (leading 'v' is stripped for file versions)"
+    exit 1
+}
+
+[[ $# -ne 1 ]] && usage
+
+# Strip leading 'v' for the version string used in files
+VERSION="${1#v}"
+TAG="v${VERSION}"
+
+echo "==> Releasing ${TAG}  (file version: ${VERSION})"
+
+# --- 1. Update version in pyproject.toml and __init__.py ---------------
+sed -i '' "s/^version = \".*\"/version = \"${VERSION}\"/" "$PYPROJECT"
+sed -i '' "s/^__version__ = \".*\"/__version__ = \"${VERSION}\"/" "$INIT_PY"
+
+echo "    pyproject.toml  -> $(grep '^version' "$PYPROJECT")"
+echo "    __init__.py     -> $(grep '^__version__' "$INIT_PY")"
+
+# --- 2. Commit the version bump ----------------------------------------
+git -C "$REPO_ROOT" add "$PYPROJECT" "$INIT_PY"
+git -C "$REPO_ROOT" commit -m "Bump version to ${VERSION}"
+
+# --- 3. Tag the commit --------------------------------------------------
+git -C "$REPO_ROOT" tag -a "$TAG" -m "Release ${TAG}"
+echo "    Tagged: ${TAG}"
+
+# --- 4. Build -----------------------------------------------------------
+echo "==> Building sdist + wheel"
+rm -rf "$REPO_ROOT/dist"
+uvx --from build pyproject-build "$REPO_ROOT" --outdir "$REPO_ROOT/dist"
+
+# --- 5. Publish to PyPI -------------------------------------------------
+echo "==> Uploading to PyPI"
+uvx twine upload "$REPO_ROOT/dist/"*
+
+echo "==> Done. ${TAG} published to PyPI."

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/__init__.py

@@ -17,7 +17,7 @@ Main module categories:
                 llm_context, iteration)
 """
 
-__version__ = "0.75.1a1"
+__version__ = "0.75.1a3"
 
 # Environment utilities (always available)
 from .core.compat import (

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/analysis/notebook_progress.py

@@ -4,7 +4,7 @@ import threading
 from pathlib import Path
 from typing import Optional
 
-from customer_retention.analysis.notebook_html_exporter import export_notebook_html
+from customer_retention.core.compat import is_databricks
 from customer_retention.core.config.experiments import get_notebook_experiments_dir
 
 
@@ -25,7 +25,7 @@ def track_and_export_previous(current_notebook: str) -> None:
     previous = _read_last_notebook(progress_file)
     _write_current_notebook(progress_file, current_notebook)
 
-    if previous:
+    if previous and not is_databricks():
         _export_in_background(previous, docs_dir)
 
 
@@ -40,6 +40,8 @@ def _read_last_notebook(progress_file: Path) -> Optional[str]:
 
 def _export_notebook(notebook_name: str, docs_dir: Path) -> Optional[Path]:
     """Export *notebook_name* to HTML in *docs_dir*."""
+    from customer_retention.analysis.notebook_html_exporter import export_notebook_html
+
     return export_notebook_html(Path(notebook_name), docs_dir)
 
 

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/analysis/visualization/chart_builder.py

@@ -5,7 +5,7 @@ import numpy as np
 import plotly.express as px
 import plotly.graph_objects as go
 
-from customer_retention.core.compat import DataFrame, Series, ensure_pandas_series, to_pandas
+from customer_retention.core.compat import DataFrame, Series, ensure_pandas_series, safe_to_datetime, to_pandas
 
 from .number_formatter import NumberFormatter
 
@@ -532,9 +532,8 @@ class ChartBuilder:
         dates: Series,
         title: Optional[str] = None,
     ) -> go.Figure:
-        import pandas as pd
         dates = ensure_pandas_series(dates)
-        parsed = pd.to_datetime(dates, errors="coerce").dropna()
+        parsed = safe_to_datetime(dates, errors="coerce").dropna()
 
         if len(parsed) == 0:
             fig = go.Figure()
@@ -1029,7 +1028,7 @@ class ChartBuilder:
         """
         import pandas as pd
         dates = ensure_pandas_series(dates)
-        parsed = pd.to_datetime(dates, errors="coerce")
+        parsed = safe_to_datetime(dates, errors="coerce")
 
         if values is not None:
             values = ensure_pandas_series(values)
@@ -1078,7 +1077,7 @@ class ChartBuilder:
         """Create a month x day-of-week heatmap for pattern discovery."""
         import pandas as pd
         dates = ensure_pandas_series(dates)
-        parsed = pd.to_datetime(dates, errors="coerce").dropna()
+        parsed = safe_to_datetime(dates, errors="coerce").dropna()
 
         if values is not None:
             values = ensure_pandas_series(values)
@@ -1127,7 +1126,7 @@ class ChartBuilder:
         dates = ensure_pandas_series(dates)
         values = ensure_pandas_series(values)
 
-        df = pd.DataFrame({"date": pd.to_datetime(dates), "value": values}).dropna()
+        df = pd.DataFrame({"date": safe_to_datetime(dates), "value": values}).dropna()
         df = df.sort_values("date")
 
         df["rolling_mean"] = df["value"].rolling(window=window, center=True, min_periods=1).mean()
@@ -2222,7 +2221,7 @@ class ChartBuilder:
         import pandas as pd
         with warnings.catch_warnings():
             warnings.simplefilter("ignore")
-            dates = pd.to_datetime(series, errors='coerce').dropna()
+            dates = safe_to_datetime(pd.Series(series), errors='coerce').dropna()
         if len(dates) == 0:
             return
 

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/core/compat/__init__.py

@@ -147,6 +147,54 @@ def is_float_dtype(arr_or_dtype: Any) -> bool:
     return _pandas.api.types.is_float_dtype(arr_or_dtype)
 
 
+def _infer_epoch_unit(value: int) -> str:
+    """Infer the epoch unit from a representative integer timestamp value.
+
+    Spark LongType timestamps become int64 after ``to_pandas()``.  The bare
+    ``pd.to_datetime()`` call assumes nanoseconds for large integers, which
+    silently produces wrong dates when the source used seconds or milliseconds.
+    This helper picks the right ``unit`` based on magnitude.
+    """
+    abs_val = abs(int(value))
+    if abs_val > 1e17:
+        return "ns"
+    if abs_val > 1e14:
+        return "us"
+    if abs_val > 1e11:
+        return "ms"
+    return "s"
+
+
+def safe_to_datetime(series: Any, **kwargs: Any) -> _pandas.Series:
+    """Convert a Series to datetime, handling Spark LongType epoch integers.
+
+    Like ``pd.to_datetime`` but automatically detects integer epoch columns
+    and passes the correct ``unit`` parameter.  Any extra *kwargs* are
+    forwarded to ``pd.to_datetime``.
+    """
+    series = ensure_pandas_series(series)
+    if _pandas.api.types.is_datetime64_any_dtype(series):
+        return series
+    if _pandas.api.types.is_integer_dtype(series):
+        non_null = series.dropna()
+        if len(non_null) > 0:
+            unit = _infer_epoch_unit(non_null.iloc[0])
+            return _pandas.to_datetime(series, unit=unit, **kwargs)
+    return _pandas.to_datetime(series, **kwargs)
+
+
+def ensure_datetime_column(df: _pandas.DataFrame, column: str) -> _pandas.DataFrame:
+    """Ensure *column* in a **pandas** DataFrame is ``datetime64``.
+
+    Call this after ``to_pandas()`` to safely convert columns that may have
+    arrived as int64 epoch values from Spark.  Returns the DataFrame
+    (modified in-place).
+    """
+    if not _pandas.api.types.is_datetime64_any_dtype(df[column]):
+        df[column] = safe_to_datetime(df[column])
+    return df
+
+
 class PandasCompat:
     @staticmethod
     def value_counts_normalize(series: Any, normalize: bool = False) -> Any:
@@ -208,6 +256,8 @@ __all__ = [
     "is_notebook",
     "get_display_function",
     "get_dbutils",
+    "safe_to_datetime",
+    "ensure_datetime_column",
     "ops",
     "DataOps",
 ]

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/generators/notebook_generator/stages/s05_feature_engineering.py

@@ -55,7 +55,8 @@ else:
 else:
     print("Warning: No feature_timestamp column found. Using current date (may cause leakage).")
     if "signup_date" in df.columns:
-        df["tenure_days"] = (pd.Timestamp.now() - pd.to_datetime(df["signup_date"])).dt.days'''),
+        from customer_retention.core.compat import safe_to_datetime
+        df["tenure_days"] = (pd.Timestamp.now() - safe_to_datetime(df["signup_date"])).dt.days'''),
             self.cb.section("Validate Point-in-Time Correctness"),
             self.cb.code('''if "feature_timestamp" in df.columns:
     pit_report = PointInTimeJoiner.validate_temporal_integrity(df)

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/generators/pipeline_generator/renderer.py

@@ -290,6 +290,7 @@ from pathlib import Path
 {% if ops %}
 from customer_retention.transforms import {{ ops | sort | join(', ') }}
 {% endif %}
+from customer_retention.core.compat import ensure_datetime_column, safe_to_datetime
 from config import SOURCES, get_bronze_path{{ ', RAW_SOURCES' if config.lifecycle else '' }}
 
 SOURCE_NAME = "{{ source }}"
@@ -356,7 +357,7 @@ def _load_raw_events():
 {% if config.lifecycle.include_recency_bucket %}
 
 def add_recency_tenure(df: pd.DataFrame, raw_df: pd.DataFrame) -> pd.DataFrame:
-    raw_df[TIME_COLUMN] = pd.to_datetime(raw_df[TIME_COLUMN])
+    ensure_datetime_column(raw_df, TIME_COLUMN)
     reference_date = raw_df[TIME_COLUMN].max()
     entity_stats = raw_df.groupby(ENTITY_COLUMN)[TIME_COLUMN].agg(["min", "max"])
     entity_stats["days_since_last"] = (reference_date - entity_stats["max"]).dt.days
@@ -398,7 +399,7 @@ def add_lifecycle_quadrant(df: pd.DataFrame) -> pd.DataFrame:
 {% if config.lifecycle.include_cyclical_features %}
 
 def add_cyclical_features(df: pd.DataFrame, raw_df: pd.DataFrame) -> pd.DataFrame:
-    raw_df[TIME_COLUMN] = pd.to_datetime(raw_df[TIME_COLUMN])
+    ensure_datetime_column(raw_df, TIME_COLUMN)
     mean_dow = raw_df.groupby(ENTITY_COLUMN)[TIME_COLUMN].apply(lambda x: x.dt.dayofweek.mean())
     df = df.merge(mean_dow.rename("mean_dow"), left_on=ENTITY_COLUMN, right_index=True, how="left")
     df["dow_sin"] = np.sin(2 * np.pi * df["mean_dow"] / 7)
@@ -1447,6 +1448,7 @@ from pathlib import Path
 {% if ops %}
 from customer_retention.transforms import {{ ops | sort | join(', ') }}
 {% endif %}
+from customer_retention.core.compat import ensure_datetime_column, safe_to_datetime
 from config import PRODUCTION_DIR, RAW_SOURCES, TARGET_COLUMN
 
 SOURCE_NAME = "{{ source }}"
@@ -1502,7 +1504,7 @@ AGG_FUNCS = {{ config.aggregation.agg_funcs }}
 
 def apply_reshaping(df: pd.DataFrame) -> pd.DataFrame:
 {% if config.aggregation %}
-    df[TIME_COLUMN] = pd.to_datetime(df[TIME_COLUMN])
+    ensure_datetime_column(df, TIME_COLUMN)
     reference_date = df[TIME_COLUMN].max()
     result = df.groupby(ENTITY_COLUMN).agg("first")[[]]
     if TARGET_COLUMN in df.columns:
@@ -1535,7 +1537,7 @@ def _load_raw_events():
 {% if config.lifecycle.include_recency_bucket %}
 
 def add_recency_tenure(df: pd.DataFrame, raw_df: pd.DataFrame) -> pd.DataFrame:
-    raw_df[TIME_COLUMN] = pd.to_datetime(raw_df[TIME_COLUMN])
+    ensure_datetime_column(raw_df, TIME_COLUMN)
     reference_date = raw_df[TIME_COLUMN].max()
     entity_stats = raw_df.groupby(ENTITY_COLUMN)[TIME_COLUMN].agg(["min", "max"])
     entity_stats["days_since_last"] = (reference_date - entity_stats["max"]).dt.days
@@ -1577,7 +1579,7 @@ def add_lifecycle_quadrant(df: pd.DataFrame) -> pd.DataFrame:
 {% if config.lifecycle.include_cyclical_features %}
 
 def add_cyclical_features(df: pd.DataFrame, raw_df: pd.DataFrame) -> pd.DataFrame:
-    raw_df[TIME_COLUMN] = pd.to_datetime(raw_df[TIME_COLUMN])
+    ensure_datetime_column(raw_df, TIME_COLUMN)
     mean_dow = raw_df.groupby(ENTITY_COLUMN)[TIME_COLUMN].apply(lambda x: x.dt.dayofweek.mean())
     df = df.merge(mean_dow.rename("mean_dow"), left_on=ENTITY_COLUMN, right_index=True, how="left")
     df["dow_sin"] = np.sin(2 * np.pi * df["mean_dow"] / 7)

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/generators/spec_generator/mlflow_pipeline_generator.py

@@ -395,6 +395,7 @@ def log_data_quality_metrics(df: pd.DataFrame, prefix: str = "data"):
         code_lines = [
             "def engineer_features(df: pd.DataFrame) -> pd.DataFrame:",
             '    """Engineer features based on exploration findings."""',
+            "    from customer_retention.core.compat import safe_to_datetime",
             "    df = df.copy()",
             "    new_features = []",
             "",
@@ -411,7 +412,7 @@ def log_data_quality_metrics(df: pd.DataFrame, prefix: str = "data"):
             code_lines.extend([
                 f"    # Datetime features from {col_name}",
                 f"    if '{col_name}' in df.columns:",
-                f"        df['{col_name}'] = pd.to_datetime(df['{col_name}'], errors='coerce')",
+                f"        df['{col_name}'] = safe_to_datetime(df['{col_name}'], errors='coerce')",
                 "",
             ])
 

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/stages/features/temporal_features.py

@@ -10,7 +10,7 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import List, Optional, Union
 
-from customer_retention.core.compat import DataFrame, Series, Timedelta, Timestamp, pd
+from customer_retention.core.compat import DataFrame, Series, Timedelta, Timestamp, pd, safe_to_datetime, to_pandas
 
 
 class ReferenceDateSource(Enum):
@@ -122,19 +122,19 @@ class TemporalFeatureGenerator:
         if not self._is_fitted:
             raise ValueError("Generator not fitted. Call fit() first.")
 
-        result = df.copy()
+        result = to_pandas(df).copy()
         self.generated_features = []
         warnings_list = []
 
         # Get reference date(s) for this transform
         if self.reference_date_source in [ReferenceDateSource.COLUMN, ReferenceDateSource.FEATURE_TIMESTAMP]:
-            ref_dates = pd.to_datetime(df[self.reference_date_column], format='mixed')
+            ref_dates = safe_to_datetime(df[self.reference_date_column])
         else:
             ref_dates = self.reference_date
 
         # Tenure features
         if self.created_column and self.created_column in df.columns:
-            created = pd.to_datetime(df[self.created_column], format='mixed')
+            created = safe_to_datetime(df[self.created_column])
             tenure_days = self._compute_days_diff(ref_dates, created)
             result["tenure_days"] = tenure_days
             self.generated_features.append("tenure_days")
@@ -154,7 +154,7 @@ class TemporalFeatureGenerator:
 
         # Recency features
         if self.last_order_column and self.last_order_column in df.columns:
-            last_order = pd.to_datetime(df[self.last_order_column], format='mixed')
+            last_order = safe_to_datetime(df[self.last_order_column])
             days_since_last = self._compute_days_diff(ref_dates, last_order)
             result["days_since_last_order"] = days_since_last
             self.generated_features.append("days_since_last_order")
@@ -162,8 +162,8 @@ class TemporalFeatureGenerator:
         # Activation features
         if (self.first_order_column and self.first_order_column in df.columns and
                 self.created_column and self.created_column in df.columns):
-            created = pd.to_datetime(df[self.created_column], format='mixed')
-            first_order = pd.to_datetime(df[self.first_order_column], format='mixed')
+            created = safe_to_datetime(df[self.created_column])
+            first_order = safe_to_datetime(df[self.first_order_column])
             days_to_first = self._compute_days_diff(first_order, created)
             result["days_to_first_order"] = days_to_first
             self.generated_features.append("days_to_first_order")
@@ -171,8 +171,8 @@ class TemporalFeatureGenerator:
         # Active period
         if (self.first_order_column and self.first_order_column in df.columns and
                 self.last_order_column and self.last_order_column in df.columns):
-            first_order = pd.to_datetime(df[self.first_order_column], format='mixed')
-            last_order = pd.to_datetime(df[self.last_order_column], format='mixed')
+            first_order = safe_to_datetime(df[self.first_order_column])
+            last_order = safe_to_datetime(df[self.last_order_column])
             active_period = self._compute_days_diff(last_order, first_order)
             result["active_period_days"] = active_period
             self.generated_features.append("active_period_days")
@@ -210,21 +210,21 @@ class TemporalFeatureGenerator:
                 raise ValueError(
                     "date_column must be provided when source is MAX_DATE"
                 )
-            self.reference_date = pd.to_datetime(df[self.date_column], format='mixed').max()
+            self.reference_date = safe_to_datetime(df[self.date_column]).max()
 
         elif self.reference_date_source == ReferenceDateSource.COLUMN:
             if self.reference_date_column is None:
                 raise ValueError(
                     "reference_date_column must be provided when source is COLUMN"
                 )
-            self.reference_date = pd.to_datetime(df[self.reference_date_column], format='mixed')
+            self.reference_date = safe_to_datetime(df[self.reference_date_column])
 
         elif self.reference_date_source == ReferenceDateSource.FEATURE_TIMESTAMP:
             if "feature_timestamp" not in df.columns:
                 raise ValueError(
                     "feature_timestamp column required when source is FEATURE_TIMESTAMP"
                 )
-            self.reference_date = pd.to_datetime(df["feature_timestamp"], format='mixed')
+            self.reference_date = safe_to_datetime(df["feature_timestamp"])
             self.reference_date_column = "feature_timestamp"
 
     def _compute_days_diff(

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/stages/profiling/column_profiler.py

@@ -4,7 +4,7 @@ from typing import Optional
 
 import numpy as np
 
-from customer_retention.core.compat import Timestamp, is_bool_dtype, is_datetime64_any_dtype, pd
+from customer_retention.core.compat import Timestamp, is_bool_dtype, is_datetime64_any_dtype, pd, to_datetime
 from customer_retention.core.config.column_config import ColumnType
 
 from .profile_result import (
@@ -304,7 +304,7 @@ class DatetimeProfiler(ColumnProfiler):
                 pass
             else:
                 try:
-                    clean_series = pd.to_datetime(clean_series, errors='coerce', format='mixed')
+                    clean_series = to_datetime(clean_series, errors='coerce', format='mixed')
                 except Exception:
                     return {"datetime_metrics": None}
 

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/stages/profiling/pattern_analysis_config.py

@@ -4,7 +4,7 @@ from typing import Any, Dict, List, Optional, Tuple
 import numpy as np
 import pandas as pd
 
-from customer_retention.core.compat import DataFrame
+from customer_retention.core.compat import DataFrame, ensure_datetime_column, to_pandas
 
 
 @dataclass
@@ -216,12 +216,13 @@ class SparklineDataBuilder:
         self.freq = freq
 
     def build(self, df: DataFrame, columns: List[str]) -> Tuple[List[SparklineData], bool]:
-        import pandas as pd
+        df = to_pandas(df)
         has_target = self.target_column is not None and self.target_column in df.columns
         if has_target:
             validate_not_event_level(df, self.entity_column, self.target_column)
         df_work = self._prepare_working_df(df, has_target)
-        df_work['_period'] = pd.to_datetime(df_work[self.time_column]).dt.to_period(self.freq).dt.start_time
+        ensure_datetime_column(df_work, self.time_column)
+        df_work['_period'] = df_work[self.time_column].dt.to_period(self.freq).dt.start_time
         results = [self._build_sparkline_for_column(df_work, col, has_target)
                    for col in columns if col in df_work.columns]
         return results, has_target

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/stages/profiling/temporal_feature_analyzer.py

@@ -5,7 +5,7 @@ from typing import Any, Dict, List, Optional, Tuple
 import numpy as np
 from scipy import stats
 
-from customer_retention.core.compat import DataFrame, pd, qcut, to_datetime
+from customer_retention.core.compat import DataFrame, ensure_datetime_column, pd, qcut, to_pandas
 from customer_retention.core.utils import compute_effect_size
 
 
@@ -626,8 +626,8 @@ class TemporalFeatureAnalyzer:
         return next_priority
 
     def _prepare_dataframe(self, df: DataFrame) -> DataFrame:
-        df = df.copy()
-        df[self.time_column] = to_datetime(df[self.time_column])
+        df = to_pandas(df).copy()
+        ensure_datetime_column(df, self.time_column)
         return df
 
     def _validate_event_level_target_usage(self, df: DataFrame, target_column: Optional[str]) -> None:

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/stages/profiling/temporal_feature_engineer.py

@@ -25,7 +25,7 @@ from typing import Any, Dict, List, Optional
 
 import numpy as np
 
-from customer_retention.core.compat import pd
+from customer_retention.core.compat import Timedelta, pd, to_datetime, to_pandas
 
 
 class ReferenceMode(Enum):
@@ -179,8 +179,8 @@ class TemporalFeatureEngineer:
         Returns:
             TemporalFeatureResult with features DataFrame and metadata
         """
-        events_df = events_df.copy()
-        events_df[time_col] = pd.to_datetime(events_df[time_col])
+        events_df = to_pandas(events_df).copy()
+        events_df[time_col] = to_datetime(events_df[time_col])
 
         # Determine reference dates per entity
         ref_dates = self._get_reference_dates(
@@ -313,9 +313,9 @@ class TemporalFeatureEngineer:
             })
 
         if reference_dates is not None and reference_col is not None:
-            ref_df = reference_dates[[entity_col, reference_col]].copy()
+            ref_df = to_pandas(reference_dates)[[entity_col, reference_col]].copy()
             ref_df.columns = [entity_col, "reference_date"]
-            ref_df["reference_date"] = pd.to_datetime(ref_df["reference_date"])
+            ref_df["reference_date"] = to_datetime(ref_df["reference_date"])
             return ref_df
 
         # Default: Use last event date per entity
@@ -511,8 +511,8 @@ class TemporalFeatureEngineer:
             entity_df["last_event"].iloc[0]
 
             # Calculate split boundaries
-            split1 = first_event + pd.Timedelta(days=history_days * splits[0])
-            split2 = first_event + pd.Timedelta(days=history_days * (splits[0] + splits[1]))
+            split1 = first_event + Timedelta(days=history_days * splits[0])
+            split2 = first_event + Timedelta(days=history_days * (splits[0] + splits[1]))
 
             for col in value_cols:
                 beginning_val = entity_df[entity_df[time_col] < split1][col].sum()

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/stages/profiling/temporal_pattern_analyzer.py

@@ -5,7 +5,15 @@ from typing import Dict, List, Optional, Tuple
 import numpy as np
 from scipy import stats
 
-from customer_retention.core.compat import DataFrame, Timestamp, cut, pd, to_datetime
+from customer_retention.core.compat import (
+    DataFrame,
+    Timestamp,
+    cut,
+    ensure_datetime_column,
+    pd,
+    safe_to_datetime,
+    to_pandas,
+)
 from customer_retention.core.utils import compute_effect_size
 
 
@@ -177,6 +185,8 @@ def generate_trend_recommendations(trend: TrendResult, mean_value: float = 1.0)
 
 
 def analyze_cohort_distribution(first_events: DataFrame, time_column: str) -> CohortDistribution:
+    first_events = to_pandas(first_events)
+    ensure_datetime_column(first_events, time_column)
     years = first_events[time_column].dt.year
     year_counts = years.value_counts().sort_index().to_dict()
     total = len(first_events)
@@ -231,6 +241,8 @@ def compute_recency_buckets(
     df: DataFrame, entity_column: str, time_column: str, target_column: str,
     reference_date: Timestamp, bucket_edges: Optional[List[float]] = None
 ) -> List[RecencyBucketStats]:
+    df = to_pandas(df)
+    ensure_datetime_column(df, time_column)
     edges = bucket_edges or DEFAULT_BUCKET_EDGES
     labels = _generate_bucket_labels(edges)
     entity_last = df.groupby(entity_column)[time_column].max().reset_index()
@@ -296,6 +308,8 @@ def classify_distribution_pattern(buckets: List[RecencyBucketStats]) -> str:
 def _diagnose_anomaly_pattern(
     df: DataFrame, entity_column: str, time_column: str, target_column: str
 ) -> AnomalyDiagnostics:
+    df = to_pandas(df)
+    ensure_datetime_column(df, time_column)
     entity_target = df.groupby(entity_column)[target_column].first()
     target_1_pct = float(entity_target.mean() * 100)
     target_1_is_minority = target_1_pct < 50
@@ -431,8 +445,10 @@ def compare_recency_by_target(
     df: DataFrame, entity_column: str, time_column: str, target_column: str,
     reference_date: Optional[Timestamp] = None, cap_percentile: float = 0.99
 ) -> Optional[RecencyComparisonResult]:
+    df = to_pandas(df)
     if target_column not in df.columns:
         return None
+    ensure_datetime_column(df, time_column)
     ref_date = reference_date or df[time_column].max()
     entity_last = df.groupby(entity_column)[time_column].max().reset_index()
     entity_last["recency_days"] = (ref_date - entity_last[time_column]).dt.days
@@ -495,11 +511,11 @@ class TemporalPatternAnalyzer:
         if len(df) < 3:
             return self._unknown_trend()
 
-        df_clean = df[[self.time_column, value_column]].dropna()
+        df_clean = to_pandas(df)[[self.time_column, value_column]].dropna()
         if len(df_clean) < 3:
             return self._unknown_trend()
 
-        time_col = to_datetime(df_clean[self.time_column])
+        time_col = safe_to_datetime(df_clean[self.time_column])
         x = (time_col - time_col.min()).dt.total_seconds() / 86400
         y = df_clean[value_column].values
 
@@ -583,10 +599,11 @@ class TemporalPatternAnalyzer:
         if len(df) == 0:
             return pd.DataFrame()
 
-        df_copy = df.copy()
+        df_copy = to_pandas(df).copy()
+        ensure_datetime_column(df_copy, cohort_column)
         entity_first_event = df_copy.groupby(entity_column)[cohort_column].min()
         df_copy["_cohort"] = df_copy[entity_column].map(entity_first_event)
-        df_copy["_cohort"] = to_datetime(df_copy["_cohort"]).dt.to_period(period)
+        df_copy["_cohort"] = df_copy["_cohort"].dt.to_period(period)
 
         entity_cohorts = df_copy.groupby(entity_column)["_cohort"].first().reset_index()
         entity_cohorts.columns = [entity_column, "_cohort"]
@@ -611,11 +628,11 @@ class TemporalPatternAnalyzer:
         if len(df) == 0:
             return RecencyResult(avg_recency_days=0, median_recency_days=0, min_recency_days=0, max_recency_days=0)
 
+        df = to_pandas(df)
+        ensure_datetime_column(df, self.time_column)
         ref_date = reference_date or Timestamp.now()
-        to_datetime(df[self.time_column])
 
         entity_last = df.groupby(entity_column)[self.time_column].max()
-        entity_last = to_datetime(entity_last)
         recency_days = (ref_date - entity_last).dt.days
 
         target_correlation = None

{churnkit-0.75.1a1 → churnkit-0.75.1a3}/src/customer_retention/stages/profiling/temporal_quality_checks.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass, field
 from typing import Optional
 
-from customer_retention.core.compat import DataFrame, Timestamp, to_datetime
+from customer_retention.core.compat import DataFrame, Timestamp, ensure_datetime_column, safe_to_datetime, to_pandas
 from customer_retention.core.components.enums import Severity
 
 
@@ -38,6 +38,7 @@ class DuplicateEventCheck(TemporalQualityCheck):
         self.time_column = time_column
 
     def run(self, df: DataFrame) -> TemporalQualityResult:
+        df = to_pandas(df)
         if len(df) == 0:
             return self._pass_result("No data to check")
 
@@ -70,10 +71,12 @@ class TemporalGapCheck(TemporalQualityCheck):
         self.max_gap_multiple = max_gap_multiple
 
     def run(self, df: DataFrame) -> TemporalQualityResult:
+        df = to_pandas(df)
         if len(df) < 2:
             return self._pass_result("Insufficient data to check gaps")
 
-        time_col = to_datetime(df.sort_values(self.time_column)[self.time_column])
+        ensure_datetime_column(df, self.time_column)
+        time_col = df.sort_values(self.time_column)[self.time_column]
         diffs_days = time_col.diff().dropna().dt.total_seconds() / 86400
         expected_days = self.FREQ_TO_DAYS.get(self.expected_frequency, 1)
         threshold_days = expected_days * self.max_gap_multiple
@@ -107,10 +110,11 @@ class FutureDateCheck(TemporalQualityCheck):
         self.reference_date = reference_date or Timestamp.now()
 
     def run(self, df: DataFrame) -> TemporalQualityResult:
+        df = to_pandas(df)
         if len(df) == 0:
             return self._pass_result("No data to check")
 
-        time_col = to_datetime(df[self.time_column])
+        time_col = safe_to_datetime(df[self.time_column])
         future_mask = time_col > self.reference_date
         future_count = future_mask.sum()
 
@@ -137,10 +141,11 @@ class EventOrderCheck(TemporalQualityCheck):
         self.time_column = time_column
 
     def run(self, df: DataFrame) -> TemporalQualityResult:
+        df = to_pandas(df)
         if len(df) < 2:
             return self._pass_result("Insufficient data to check ordering")
 
-        df_check = df.assign(_parsed_time=to_datetime(df[self.time_column]))
+        df_check = df.assign(_parsed_time=safe_to_datetime(df[self.time_column]))
         collision_counts = df_check.groupby([self.entity_column, "_parsed_time"]).size()
         ambiguous = collision_counts[collision_counts > 1]
         ambiguous_count = ambiguous.sum() - len(ambiguous)