churnkit 0.76.0a3__tar.gz → 0.76.1a2__tar.gz

{churnkit-0.76.0a3 → churnkit-0.76.1a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: churnkit
-Version: 0.76.0a3
+Version: 0.76.1a2
 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.76.0a3 → churnkit-0.76.1a2}/exploration_notebooks/00_start_here.ipynb

@@ -70,17 +70,22 @@
    "outputs": [],
    "source": [
     "from customer_retention.analysis.notebook_progress import track_and_export_previous\n",
+    "\n",
     "track_and_export_previous(\"00_start_here.ipynb\")\n",
     "\n",
     "try:\n",
     "    import customer_retention\n",
-    "    from customer_retention.core.config.experiments import FINDINGS_DIR, EXPERIMENTS_DIR, OUTPUT_DIR, setup_experiments_structure\n",
-    "    print(f\"customer_retention is installed\")\n",
+    "    from customer_retention.core.config.experiments import (\n",
+    "        EXPERIMENTS_DIR,\n",
+    "        FINDINGS_DIR,\n",
+    "        OUTPUT_DIR,\n",
+    "        setup_experiments_structure,\n",
+    "    )\n",
+    "    print(\"customer_retention is installed\")\n",
     "except ImportError:\n",
     "    print(\"customer_retention not found. Install with:\")\n",
     "    print(\"  uv sync\")\n",
-    "    print(\"  # or: pip install -e .\")\n",
-    "from customer_retention.stages.temporal import TEMPORAL_METADATA_COLS"
+    "    print(\"  # or: pip install -e .\")"
    ]
   },
   {
@@ -284,8 +289,8 @@
    "outputs": [],
    "source": [
     "# Download Bank Customer Churn dataset\n",
-    "import subprocess\n",
     "import shutil\n",
+    "import subprocess\n",
     "\n",
     "FIXTURES_DIR.mkdir(parents=True, exist_ok=True)\n",
     "bank_churn_path = FIXTURES_DIR / \"bank_customer_churn.csv\"\n",

{churnkit-0.76.0a3 → churnkit-0.76.1a2}/exploration_notebooks/01_data_discovery.ipynb

@@ -82,6 +82,7 @@
    "outputs": [],
    "source": [
     "from customer_retention.analysis.notebook_progress import track_and_export_previous\n",
+    "\n",
     "track_and_export_previous(\"01_data_discovery.ipynb\")\n",
     "\n",
     "from datetime import datetime\n",
@@ -94,7 +95,6 @@
     "from customer_retention.analysis.visualization import ChartBuilder, console, display_figure, display_table\n",
     "from customer_retention.core.config.column_config import DatasetGranularity\n",
     "from customer_retention.core.config.experiments import (\n",
-    "    EXPERIMENTS_DIR,\n",
     "    FINDINGS_DIR,  # noqa: F401 - required for test validation\n",
     "    OUTPUT_DIR,\n",
     "    setup_experiments_structure,\n",
@@ -137,10 +137,12 @@
     "# =============================================================================\n",
     "\n",
     "# DATA_PATH: Path to your data file (CSV, Parquet, or Delta)\n",
-    "DATA_PATH = \"../tests/fixtures/customer_retention_retail.csv\"\n",
+    "DATA_PATH = \"../tests/fixtures/customer_emails.csv\"\n",
+    "# or databricks /Volumes/churnkit/landing/datasets/customer_emails.csv\n",
+    "\n",
     "\n",
     "# TARGET_COLUMN: Your prediction target (set to None for auto-detection)\n",
-    "TARGET_COLUMN = \"unsubscribed\"\n",
+    "TARGET_COLUMN = None\n",
     "\n",
     "# ENTITY_COLUMN: Customer/user ID column (set to None for auto-detection)\n",
     "ENTITY_COLUMN = None\n",
@@ -169,7 +171,7 @@
     "#\n",
     "# EVENT-LEVEL (multiple rows per customer):\n",
     "# DATA_PATH = \"../tests/fixtures/customer_transactions.csv\"\n",
-    "DATA_PATH = \"../tests/fixtures/customer_emails.csv\"\n",
+    "# DATA_PATH = \"../tests/fixtures/customer_emails.csv\"\n",
     "# =============================================================================\n",
     "\n",
     "# OUTPUT_DIR: All outputs go here (gitignored)\n",
@@ -887,14 +889,14 @@
     "if time_col and time_col in df.columns:\n",
     "    exclude_cols = list(TEMPORAL_METADATA_COLS) + ([valid_entity_col] if valid_entity_col else [])\n",
     "    availability = analyze_feature_availability(df, time_col, exclude_columns=exclude_cols)\n",
-    "    \n",
+    "\n",
     "    console.start_section()\n",
     "    console.header(\"Feature Availability\")\n",
     "    console.metric(\"Data Span\", f\"{availability.data_start.date()} to {availability.data_end.date()} ({availability.time_span_days} days)\")\n",
-    "    \n",
+    "\n",
     "    if availability.new_tracking or availability.retired_tracking or availability.partial_window:\n",
     "        if availability.new_tracking:\n",
-    "            console.warning(f\"New tracking ({len(availability.new_tracking)}): {', '.join(availability.new_tracking[:5])}\" + \n",
+    "            console.warning(f\"New tracking ({len(availability.new_tracking)}): {', '.join(availability.new_tracking[:5])}\" +\n",
     "                          (f\" +{len(availability.new_tracking)-5} more\" if len(availability.new_tracking) > 5 else \"\"))\n",
     "        if availability.retired_tracking:\n",
     "            console.warning(f\"Retired tracking ({len(availability.retired_tracking)}): {', '.join(availability.retired_tracking[:5])}\" +\n",
@@ -902,7 +904,7 @@
     "        if availability.partial_window:\n",
     "            console.warning(f\"Partial window ({len(availability.partial_window)}): {', '.join(availability.partial_window[:5])}\" +\n",
     "                          (f\" +{len(availability.partial_window)-5} more\" if len(availability.partial_window) > 5 else \"\"))\n",
-    "        \n",
+    "\n",
     "        console.subheader(\"Recommendations\")\n",
     "        for rec in availability.recommendations[:5]:\n",
     "            if rec[\"column\"] != \"_general_\":\n",
@@ -913,7 +915,7 @@
     "    else:\n",
     "        console.success(\"All features have full temporal coverage\")\n",
     "    console.end_section()\n",
-    "    \n",
+    "\n",
     "    # Store structured availability metadata for downstream use\n",
     "    features_info = {\n",
     "        feat.column: FeatureAvailabilityInfo(\n",

{churnkit-0.76.0a3 → churnkit-0.76.1a2}/exploration_notebooks/01a_a_temporal_text_deep_dive.ipynb

@@ -109,22 +109,27 @@
    "outputs": [],
    "source": [
     "from customer_retention.analysis.notebook_progress import track_and_export_previous\n",
+    "\n",
     "track_and_export_previous(\"01a_a_temporal_text_deep_dive.ipynb\")\n",
     "\n",
-    "from customer_retention.analysis.auto_explorer import ExplorationFindings, TextProcessingMetadata\n",
-    "from customer_retention.analysis.visualization import ChartBuilder, display_figure, display_table, console\n",
-    "from customer_retention.core.config.column_config import ColumnType, DatasetGranularity\n",
-    "from customer_retention.stages.profiling import (\n",
-    "    TextColumnProcessor, TextProcessingConfig, TextColumnResult,\n",
-    "    TimeWindowAggregator, AggregationPlan,\n",
-    "    EMBEDDING_MODELS, get_model_info, list_available_models\n",
-    ")\n",
-    "import pandas as pd\n",
-    "import numpy as np\n",
-    "import plotly.graph_objects as go\n",
     "import plotly.express as px\n",
+    "import plotly.graph_objects as go\n",
     "from plotly.subplots import make_subplots\n",
-    "from customer_retention.core.config.experiments import FINDINGS_DIR, EXPERIMENTS_DIR, OUTPUT_DIR, setup_experiments_structure"
+    "\n",
+    "from customer_retention.analysis.auto_explorer import ExplorationFindings, TextProcessingMetadata\n",
+    "from customer_retention.analysis.visualization import ChartBuilder, display_figure\n",
+    "from customer_retention.core.config.column_config import ColumnType\n",
+    "from customer_retention.core.config.experiments import (\n",
+    "    EXPERIMENTS_DIR,\n",
+    "    FINDINGS_DIR,\n",
+    ")\n",
+    "from customer_retention.stages.profiling import (\n",
+    "    TextColumnProcessor,\n",
+    "    TextProcessingConfig,\n",
+    "    TimeWindowAggregator,\n",
+    "    get_model_info,\n",
+    "    list_available_models,\n",
+    ")"
    ]
   },
   {
@@ -296,7 +301,7 @@
    },
    "outputs": [],
    "source": [
-    "from customer_retention.stages.temporal import load_data_with_snapshot_preference, TEMPORAL_METADATA_COLS\n",
+    "from customer_retention.stages.temporal import load_data_with_snapshot_preference\n",
     "\n",
     "df, data_source = load_data_with_snapshot_preference(findings, output_dir=str(FINDINGS_DIR))\n",
     "charts = ChartBuilder()\n",
@@ -478,28 +483,28 @@
     "        print(f\"\\n{'='*70}\")\n",
     "        print(f\"Column: {col_name}\")\n",
     "        print(f\"{'='*70}\")\n",
-    "        \n",
+    "\n",
     "        text_series = df[col_name].fillna(\"\")\n",
-    "        \n",
+    "\n",
     "        non_empty = (text_series.str.len() > 0).sum()\n",
     "        avg_length = text_series.str.len().mean()\n",
-    "        \n",
-    "        print(f\"\\n\\U0001f4ca Statistics:\")\n",
+    "\n",
+    "        print(\"\\n\\U0001f4ca Statistics:\")\n",
     "        print(f\"   Total events: {len(text_series):,}\")\n",
     "        print(f\"   Non-empty: {non_empty:,} ({non_empty/len(text_series)*100:.1f}%)\")\n",
     "        print(f\"   Avg length: {avg_length:.0f} characters\")\n",
-    "        \n",
+    "\n",
     "        # Texts per entity\n",
     "        texts_per_entity = df.groupby(ENTITY_COLUMN)[col_name].apply(\n",
     "            lambda x: (x.fillna(\"\").str.len() > 0).sum()\n",
     "        )\n",
-    "        print(f\"\\n\\U0001f465 Text events per entity:\")\n",
+    "        print(\"\\n\\U0001f465 Text events per entity:\")\n",
     "        print(f\"   Mean: {texts_per_entity.mean():.1f}\")\n",
     "        print(f\"   Median: {texts_per_entity.median():.0f}\")\n",
     "        print(f\"   Max: {texts_per_entity.max():,}\")\n",
-    "        \n",
+    "\n",
     "        # Sample texts\n",
-    "        print(f\"\\n\\U0001f4dd Sample texts:\")\n",
+    "        print(\"\\n\\U0001f4dd Sample texts:\")\n",
     "        samples = text_series[text_series.str.len() > 10].head(3)\n",
     "        for i, sample in enumerate(samples, 1):\n",
     "            truncated = sample[:80] + \"...\" if len(sample) > 80 else sample\n",
@@ -547,26 +552,26 @@
    "source": [
     "if text_columns and findings.is_time_series:\n",
     "    processor = TextColumnProcessor(text_config)\n",
-    "    \n",
+    "\n",
     "    print(\"Processing TEXT columns...\")\n",
     "    print(\"(This may take a moment for large datasets)\\n\")\n",
-    "    \n",
+    "\n",
     "    results = []\n",
     "    df_with_pcs = df.copy()\n",
-    "    \n",
+    "\n",
     "    for col_name in text_columns:\n",
     "        print(f\"\\n{'='*70}\")\n",
     "        print(f\"Processing: {col_name}\")\n",
     "        print(f\"{'='*70}\")\n",
-    "        \n",
+    "\n",
     "        df_with_pcs, result = processor.process_column(df_with_pcs, col_name)\n",
     "        results.append(result)\n",
-    "        \n",
-    "        print(f\"\\n\\u2705 Per-event processing complete:\")\n",
+    "\n",
+    "        print(\"\\n\\u2705 Per-event processing complete:\")\n",
     "        print(f\"   Components: {result.n_components}\")\n",
     "        print(f\"   Explained variance: {result.explained_variance:.1%}\")\n",
     "        print(f\"   Features: {', '.join(result.component_columns)}\")\n",
-    "    \n",
+    "\n",
     "    print(f\"\\n\\nDataFrame now has {len(df_with_pcs.columns)} columns (added {len(df_with_pcs.columns) - len(df.columns)} PC columns)\")"
    ]
   },
@@ -620,11 +625,11 @@
     "    all_pc_columns = []\n",
     "    for result in results:\n",
     "        all_pc_columns.extend(result.component_columns)\n",
-    "    \n",
+    "\n",
     "    print(f\"\\n{'='*70}\")\n",
     "    print(\"AGGREGATION PLAN\")\n",
     "    print(f\"{'='*70}\")\n",
-    "    \n",
+    "\n",
     "    aggregator = TimeWindowAggregator(ENTITY_COLUMN, TIME_COLUMN)\n",
     "    plan = aggregator.generate_plan(\n",
     "        df_with_pcs,\n",
@@ -634,16 +639,16 @@
     "        include_event_count=False,\n",
     "        include_recency=False\n",
     "    )\n",
-    "    \n",
-    "    print(f\"\\n\\U0001f4ca Plan Summary:\")\n",
+    "\n",
+    "    print(\"\\n\\U0001f4ca Plan Summary:\")\n",
     "    print(f\"   Entity column: {plan.entity_column}\")\n",
     "    print(f\"   Time column: {plan.time_column}\")\n",
     "    print(f\"   Windows: {[w.name for w in plan.windows]}\")\n",
     "    print(f\"   Value columns: {len(plan.value_columns)}\")\n",
     "    print(f\"   Aggregation functions: {plan.agg_funcs}\")\n",
     "    print(f\"   Total features to create: {len(plan.feature_columns)}\")\n",
-    "    \n",
-    "    print(f\"\\n\\U0001f4dd Sample feature names:\")\n",
+    "\n",
+    "    print(\"\\n\\U0001f4dd Sample feature names:\")\n",
     "    for feat in plan.feature_columns[:10]:\n",
     "        print(f\"   - {feat}\")\n",
     "    if len(plan.feature_columns) > 10:\n",
@@ -694,28 +699,28 @@
     "        print(f\"\\n{'='*70}\")\n",
     "        print(f\"PC Feature Distributions: {result.column_name}\")\n",
     "        print(f\"{'='*70}\")\n",
-    "        \n",
+    "\n",
     "        # Distribution of PC1 and PC2\n",
     "        if len(result.component_columns) >= 2:\n",
     "            fig = make_subplots(rows=1, cols=2,\n",
     "                                subplot_titles=(result.component_columns[0], result.component_columns[1]))\n",
-    "            \n",
+    "\n",
     "            fig.add_trace(go.Histogram(\n",
     "                x=df_with_pcs[result.component_columns[0]],\n",
     "                nbinsx=50, marker_color='steelblue', opacity=0.7\n",
     "            ), row=1, col=1)\n",
-    "            \n",
+    "\n",
     "            fig.add_trace(go.Histogram(\n",
     "                x=df_with_pcs[result.component_columns[1]],\n",
     "                nbinsx=50, marker_color='coral', opacity=0.7\n",
     "            ), row=1, col=2)\n",
-    "            \n",
+    "\n",
     "            fig.update_layout(\n",
     "                title=f\"PC Feature Distributions: {result.column_name}\",\n",
     "                height=350, template=\"plotly_white\", showlegend=False\n",
     "            )\n",
     "            display_figure(fig)\n",
-    "        \n",
+    "\n",
     "        # Scatter plot of PC1 vs PC2\n",
     "        if len(result.component_columns) >= 2:\n",
     "            fig = px.scatter(\n",
@@ -781,13 +786,14 @@
     "            processing_approach=\"pca\"\n",
     "        )\n",
     "        findings.text_processing[result.column_name] = metadata\n",
-    "        \n",
+    "\n",
     "        print(f\"\\u2705 Added text processing metadata for {result.column_name}\")\n",
-    "    \n",
+    "\n",
     "    findings.save(FINDINGS_PATH)\n",
     "    print(f\"\\nFindings saved to: {FINDINGS_PATH}\")\n",
     "\n",
     "from customer_retention.analysis.notebook_html_exporter import export_notebook_html\n",
+    "\n",
     "export_notebook_html(Path(\"01a_a_temporal_text_deep_dive.ipynb\"), EXPERIMENTS_DIR / \"docs\")\n"
    ]
   },
@@ -834,25 +840,25 @@
     "    print(\"\\n\" + \"=\"*70)\n",
     "    print(\"PRODUCTION PIPELINE RECOMMENDATIONS\")\n",
     "    print(\"=\"*70)\n",
-    "    \n",
+    "\n",
     "    print(\"\\n\\U0001f527 Bronze Layer (per-event processing):\")\n",
     "    for result in results:\n",
     "        print(f\"\\n   {result.column_name}:\")\n",
-    "        print(f\"     Action: embed_reduce\")\n",
+    "        print(\"     Action: embed_reduce\")\n",
     "        print(f\"     Model: {text_config.embedding_model}\")\n",
     "        print(f\"     Components: {result.n_components}\")\n",
     "        print(f\"     Output: {', '.join(result.component_columns[:3])}...\")\n",
-    "    \n",
+    "\n",
     "    print(\"\\n\\U0001f527 Silver Layer (entity aggregation):\")\n",
     "    print(f\"   Windows: {AGGREGATION_WINDOWS}\")\n",
     "    print(f\"   Functions: {AGGREGATION_FUNCS}\")\n",
-    "    print(f\"   Example features:\")\n",
+    "    print(\"   Example features:\")\n",
     "    for result in results[:1]:\n",
     "        pc1 = result.component_columns[0]\n",
     "        for window in AGGREGATION_WINDOWS[:2]:\n",
     "            for func in AGGREGATION_FUNCS[:2]:\n",
     "                print(f\"     - {pc1}_{func}_{window}\")\n",
-    "    \n",
+    "\n",
     "    print(\"\\n\\U0001f4a1 The pipeline generator will create these transformations automatically.\")"
    ]
   },