churnkit 0.75.1a1__tar.gz → 0.76.0a1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: churnkit
-Version: 0.75.1a1
+Version: 0.76.0a1
 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
@@ -164,12 +164,14 @@ It serves two audiences:
 
 ## Quick Start
 
-### 1. Install
+### 1. Install (local)
 
 ```bash
 pip install "churnkit[ml]"
 ```
 
+For **Databricks**, see the [Databricks Installation](https://github.com/aladjov/CR/wiki/Databricks-Installation) guide.
+
 ### 2. Bootstrap notebooks into your project
 
 ```bash
@@ -200,6 +202,7 @@ Detailed documentation lives in the [Wiki](https://github.com/aladjov/CR/wiki):
 | Topic | Wiki Page |
 |-------|-----------|
 | Installation options & environment setup | [Getting Started](https://github.com/aladjov/CR/wiki/Getting-Started) |
+| Databricks install & `databricks_init()` setup | [Databricks Installation](https://github.com/aladjov/CR/wiki/Databricks-Installation) |
 | Medallion architecture & system design | [Architecture](https://github.com/aladjov/CR/wiki/Architecture) |
 | Notebook workflow & iteration tracking | [Exploration Loop](https://github.com/aladjov/CR/wiki/Exploration-Loop) |
 | Leakage-safe temporal data preparation | [Temporal Framework](https://github.com/aladjov/CR/wiki/Temporal-Framework) |

{churnkit-0.75.1a1 → churnkit-0.76.0a1}/README.md

@@ -34,12 +34,14 @@ It serves two audiences:
 
 ## Quick Start
 
-### 1. Install
+### 1. Install (local)
 
 ```bash
 pip install "churnkit[ml]"
 ```
 
+For **Databricks**, see the [Databricks Installation](https://github.com/aladjov/CR/wiki/Databricks-Installation) guide.
+
 ### 2. Bootstrap notebooks into your project
 
 ```bash
@@ -70,6 +72,7 @@ Detailed documentation lives in the [Wiki](https://github.com/aladjov/CR/wiki):
 | Topic | Wiki Page |
 |-------|-----------|
 | Installation options & environment setup | [Getting Started](https://github.com/aladjov/CR/wiki/Getting-Started) |
+| Databricks install & `databricks_init()` setup | [Databricks Installation](https://github.com/aladjov/CR/wiki/Databricks-Installation) |
 | Medallion architecture & system design | [Architecture](https://github.com/aladjov/CR/wiki/Architecture) |
 | Notebook workflow & iteration tracking | [Exploration Loop](https://github.com/aladjov/CR/wiki/Exploration-Loop) |
 | Leakage-safe temporal data preparation | [Temporal Framework](https://github.com/aladjov/CR/wiki/Temporal-Framework) |

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

@@ -1,6 +1,6 @@
 [project]
 name = "churnkit"
-version = "0.75.1a1"
+version = "0.76.0a1"
 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.76.0a1/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.76.0a1}/src/customer_retention/__init__.py

@@ -17,7 +17,7 @@ Main module categories:
                 llm_context, iteration)
 """
 
-__version__ = "0.75.1a1"
+__version__ = "0.76.0a1"
 
 # Environment utilities (always available)
 from .core.compat import (
@@ -34,4 +34,14 @@ __all__ = [
     "is_spark_available",
     "is_databricks",
     "is_notebook",
+    # Databricks initialization
+    "databricks_init",
 ]
+
+
+def __getattr__(name: str):
+    if name == "databricks_init":
+        from .integrations.databricks_init import databricks_init
+
+        return databricks_init
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{churnkit-0.75.1a1 → churnkit-0.76.0a1}/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.76.0a1}/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.76.0a1}/src/customer_retention/core/compat/__init__.py

@@ -98,6 +98,8 @@ def merge(left: Any, right: Any, how: str = "inner", on: Any = None, **kwargs: A
     return pd.merge(left, right, how=how, on=on, **kwargs)
 
 
+native_pd = _pandas
+
 Timestamp = _pandas.Timestamp
 Timedelta = _pandas.Timedelta
 DatetimeIndex = _pandas.DatetimeIndex
@@ -147,6 +149,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:
@@ -165,6 +215,7 @@ compat = PandasCompat()
 
 __all__ = [
     "pd",
+    "native_pd",
     "DataFrame",
     "Series",
     "Timestamp",
@@ -208,6 +259,8 @@ __all__ = [
     "is_notebook",
     "get_display_function",
     "get_dbutils",
+    "safe_to_datetime",
+    "ensure_datetime_column",
     "ops",
     "DataOps",
 ]

churnkit-0.76.0a1/src/customer_retention/core/config/__init__.py

@@ -0,0 +1,74 @@
+from .column_config import ColumnConfig, ColumnType, DatasetGranularity
+from .experiments import (
+    CATALOG,
+    DATA_DIR,
+    EXPERIMENT_NAME,
+    EXPERIMENTS_DIR,
+    FEATURE_STORE_DIR,
+    FINDINGS_DIR,
+    MLRUNS_DIR,
+    OUTPUT_DIR,
+    SCHEMA,
+    WORKSPACE_PATH,
+    get_catalog,
+    get_data_dir,
+    get_experiment_name,
+    get_experiments_dir,
+    get_feature_store_dir,
+    get_findings_dir,
+    get_mlruns_dir,
+    get_notebook_experiments_dir,
+    get_schema,
+    get_workspace_path,
+    setup_experiments_structure,
+)
+from .pipeline_config import (
+    BronzeConfig,
+    DedupStrategy,
+    GoldConfig,
+    ModelingConfig,
+    PathConfig,
+    PipelineConfig,
+    SilverConfig,
+    ValidationConfig,
+)
+from .source_config import DataSourceConfig, FileFormat, Grain, SourceType
+
+__all__ = [
+    "ColumnType",
+    "ColumnConfig",
+    "DatasetGranularity",
+    "SourceType",
+    "FileFormat",
+    "Grain",
+    "DataSourceConfig",
+    "DedupStrategy",
+    "BronzeConfig",
+    "SilverConfig",
+    "GoldConfig",
+    "ModelingConfig",
+    "ValidationConfig",
+    "PathConfig",
+    "PipelineConfig",
+    "CATALOG",
+    "SCHEMA",
+    "WORKSPACE_PATH",
+    "EXPERIMENT_NAME",
+    "EXPERIMENTS_DIR",
+    "FINDINGS_DIR",
+    "DATA_DIR",
+    "MLRUNS_DIR",
+    "FEATURE_STORE_DIR",
+    "OUTPUT_DIR",
+    "get_catalog",
+    "get_schema",
+    "get_workspace_path",
+    "get_experiment_name",
+    "get_experiments_dir",
+    "get_findings_dir",
+    "get_data_dir",
+    "get_mlruns_dir",
+    "get_feature_store_dir",
+    "get_notebook_experiments_dir",
+    "setup_experiments_structure",
+]

{churnkit-0.75.1a1 → churnkit-0.76.0a1}/src/customer_retention/core/config/experiments.py

@@ -36,12 +36,32 @@ def get_feature_store_dir(default: Optional[str] = None) -> Path:
     return get_experiments_dir(default) / "feature_repo"
 
 
+def get_catalog(default: str = "main") -> str:
+    return os.environ.get("CR_CATALOG", default)
+
+
+def get_schema(default: str = "default") -> str:
+    return os.environ.get("CR_SCHEMA", default)
+
+
+def get_workspace_path(default: str | None = None) -> str | None:
+    return os.environ.get("CR_WORKSPACE_PATH", default)
+
+
+def get_experiment_name(default: str = "customer_retention") -> str:
+    return os.environ.get("CR_EXPERIMENT_NAME", default)
+
+
 EXPERIMENTS_DIR = get_experiments_dir()
 FINDINGS_DIR = get_findings_dir()
 DATA_DIR = get_data_dir()
 MLRUNS_DIR = get_mlruns_dir()
 FEATURE_STORE_DIR = get_feature_store_dir()
 OUTPUT_DIR = FINDINGS_DIR
+CATALOG = get_catalog()
+SCHEMA = get_schema()
+WORKSPACE_PATH = get_workspace_path()
+EXPERIMENT_NAME = get_experiment_name()
 
 
 def setup_experiments_structure(experiments_dir: Optional[Path] = None) -> None:

{churnkit-0.75.1a1 → churnkit-0.76.0a1}/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.76.0a1}/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)