churnkit 0.75.0a1__py3-none-any.whl

churnkit-0.75.0a1.data/data/share/churnkit/exploration_notebooks/09_business_alignment.ipynb

@@ -0,0 +1,572 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7074023b",
+   "metadata": {
+    "papermill": {
+     "duration": 0.002564,
+     "end_time": "2026-02-02T13:03:54.779668",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:54.777104",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "# Chapter 9: Business Alignment\n",
+    "\n",
+    "**Purpose:** Align data exploration with business objectives and constraints.\n",
+    "\n",
+    "**Outputs:**\n",
+    "- Business context documentation\n",
+    "- Success metrics definition\n",
+    "- Constraints and requirements\n",
+    "\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6204d96d",
+   "metadata": {
+    "papermill": {
+     "duration": 0.001754,
+     "end_time": "2026-02-02T13:03:54.783320",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:54.781566",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "## 9.1 Setup"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "36b7856f",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-02-02T13:03:54.788245Z",
+     "iopub.status.busy": "2026-02-02T13:03:54.788106Z",
+     "iopub.status.idle": "2026-02-02T13:03:56.567208Z",
+     "shell.execute_reply": "2026-02-02T13:03:56.566685Z"
+    },
+    "papermill": {
+     "duration": 1.782784,
+     "end_time": "2026-02-02T13:03:56.568124",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:54.785340",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "from customer_retention.analysis.notebook_progress import track_and_export_previous\n",
+    "track_and_export_previous(\"09_business_alignment.ipynb\")\n",
+    "\n",
+    "from customer_retention.analysis.auto_explorer import ExplorationFindings\n",
+    "from customer_retention.analysis.visualization import display_table\n",
+    "import pandas as pd\n",
+    "from customer_retention.core.config.experiments import FINDINGS_DIR, EXPERIMENTS_DIR, OUTPUT_DIR, setup_experiments_structure\n",
+    "from customer_retention.stages.temporal import TEMPORAL_METADATA_COLS\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "820fd2e1",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-02-02T13:03:56.572098Z",
+     "iopub.status.busy": "2026-02-02T13:03:56.571946Z",
+     "iopub.status.idle": "2026-02-02T13:03:56.796802Z",
+     "shell.execute_reply": "2026-02-02T13:03:56.796402Z"
+    },
+    "papermill": {
+     "duration": 0.227756,
+     "end_time": "2026-02-02T13:03:56.797497",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.569741",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "# === CONFIGURATION ===\n",
+    "from pathlib import Path\n",
+    "\n",
+    "# FINDINGS_DIR imported from customer_retention.core.config.experiments\n",
+    "\n",
+    "findings_files = [f for f in FINDINGS_DIR.glob(\"*_findings.yaml\") if \"multi_dataset\" not in f.name]\n",
+    "if not findings_files:\n",
+    "    raise FileNotFoundError(f\"No findings files found in {FINDINGS_DIR}. Run notebook 01 first.\")\n",
+    "\n",
+    "# Prefer aggregated findings (from 01d) over event-level findings\n",
+    "# Pattern: *_aggregated* in filename indicates aggregated data\n",
+    "aggregated_files = [f for f in findings_files if \"_aggregated\" in f.name]\n",
+    "non_aggregated_files = [f for f in findings_files if \"_aggregated\" not in f.name]\n",
+    "\n",
+    "if aggregated_files:\n",
+    "    # Use most recent aggregated file\n",
+    "    aggregated_files.sort(key=lambda f: f.stat().st_mtime, reverse=True)\n",
+    "    FINDINGS_PATH = str(aggregated_files[0])\n",
+    "    print(f\"Found {len(aggregated_files)} aggregated findings file(s)\")\n",
+    "    print(f\"Using: {FINDINGS_PATH}\")\n",
+    "    if non_aggregated_files:\n",
+    "        print(f\"   (Skipping {len(non_aggregated_files)} event-level findings)\")\n",
+    "else:\n",
+    "    # Fall back to most recent non-aggregated file\n",
+    "    non_aggregated_files.sort(key=lambda f: f.stat().st_mtime, reverse=True)\n",
+    "    FINDINGS_PATH = str(non_aggregated_files[0])\n",
+    "    print(f\"Found {len(findings_files)} findings file(s)\")\n",
+    "    print(f\"Using: {FINDINGS_PATH}\")\n",
+    "\n",
+    "findings = ExplorationFindings.load(FINDINGS_PATH)\n",
+    "\n",
+    "print(f\"\\nLoaded findings for {findings.column_count} columns\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9c6ad68b",
+   "metadata": {
+    "papermill": {
+     "duration": 0.001286,
+     "end_time": "2026-02-02T13:03:56.800501",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.799215",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "## 9.2 Business Context\n",
+    "\n",
+    "Define the business context for this project."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a947050e",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-02-02T13:03:56.804379Z",
+     "iopub.status.busy": "2026-02-02T13:03:56.804249Z",
+     "iopub.status.idle": "2026-02-02T13:03:56.806909Z",
+     "shell.execute_reply": "2026-02-02T13:03:56.806232Z"
+    },
+    "papermill": {
+     "duration": 0.00536,
+     "end_time": "2026-02-02T13:03:56.807553",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.802193",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "BUSINESS_CONTEXT = {\n",
+    "    \"project_name\": \"Customer Churn Prediction\",\n",
+    "    \"business_objective\": \"Reduce customer churn by 20% through proactive retention campaigns\",\n",
+    "    \"stakeholders\": [\"Marketing Team\", \"Customer Success\", \"Data Science\"],\n",
+    "    \"timeline\": \"Q1 2025\",\n",
+    "    \"budget_constraints\": \"$50k for retention campaigns per month\"\n",
+    "}\n",
+    "\n",
+    "print(\"Business Context:\")\n",
+    "for key, value in BUSINESS_CONTEXT.items():\n",
+    "    print(f\"  {key}: {value}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "947806c0",
+   "metadata": {
+    "papermill": {
+     "duration": 0.001199,
+     "end_time": "2026-02-02T13:03:56.810126",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.808927",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "## 9.3 Success Metrics"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "aec679b2",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-02-02T13:03:56.813855Z",
+     "iopub.status.busy": "2026-02-02T13:03:56.813739Z",
+     "iopub.status.idle": "2026-02-02T13:03:56.821979Z",
+     "shell.execute_reply": "2026-02-02T13:03:56.821450Z"
+    },
+    "papermill": {
+     "duration": 0.010836,
+     "end_time": "2026-02-02T13:03:56.822560",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.811724",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "SUCCESS_METRICS = [\n",
+    "    {\n",
+    "        \"Metric\": \"Model AUC\",\n",
+    "        \"Target\": \">= 0.80\",\n",
+    "        \"Priority\": \"High\",\n",
+    "        \"Rationale\": \"Need strong discrimination to prioritize high-risk customers\"\n",
+    "    },\n",
+    "    {\n",
+    "        \"Metric\": \"Precision at 20%\",\n",
+    "        \"Target\": \">= 0.60\",\n",
+    "        \"Priority\": \"High\",\n",
+    "        \"Rationale\": \"Limited budget means we can only target top 20% of predictions\"\n",
+    "    },\n",
+    "    {\n",
+    "        \"Metric\": \"Churn Rate Reduction\",\n",
+    "        \"Target\": \"20%\",\n",
+    "        \"Priority\": \"High\",\n",
+    "        \"Rationale\": \"Primary business objective\"\n",
+    "    },\n",
+    "    {\n",
+    "        \"Metric\": \"Model Latency\",\n",
+    "        \"Target\": \"< 100ms\",\n",
+    "        \"Priority\": \"Medium\",\n",
+    "        \"Rationale\": \"Required for real-time scoring\"\n",
+    "    },\n",
+    "    {\n",
+    "        \"Metric\": \"Fairness (Demographic Parity)\",\n",
+    "        \"Target\": \"Ratio >= 0.8\",\n",
+    "        \"Priority\": \"Medium\",\n",
+    "        \"Rationale\": \"Ensure equitable treatment across segments\"\n",
+    "    }\n",
+    "]\n",
+    "\n",
+    "metrics_df = pd.DataFrame(SUCCESS_METRICS)\n",
+    "print(\"Success Metrics:\")\n",
+    "display(metrics_df)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5dc340a7",
+   "metadata": {
+    "papermill": {
+     "duration": 0.001352,
+     "end_time": "2026-02-02T13:03:56.825447",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.824095",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "## 9.4 Deployment Requirements"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "27e74568",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-02-02T13:03:56.829419Z",
+     "iopub.status.busy": "2026-02-02T13:03:56.829310Z",
+     "iopub.status.idle": "2026-02-02T13:03:56.832011Z",
+     "shell.execute_reply": "2026-02-02T13:03:56.831338Z"
+    },
+    "papermill": {
+     "duration": 0.005715,
+     "end_time": "2026-02-02T13:03:56.832732",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.827017",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "DEPLOYMENT_REQUIREMENTS = {\n",
+    "    \"scoring_mode\": \"Both batch and real-time\",\n",
+    "    \"batch_frequency\": \"Daily\",\n",
+    "    \"real_time_latency\": \"< 100ms p99\",\n",
+    "    \"infrastructure\": \"Databricks\",\n",
+    "    \"model_registry\": \"MLflow\",\n",
+    "    \"monitoring\": \"Required - drift detection and performance tracking\",\n",
+    "    \"retraining\": \"Monthly or on significant drift\"\n",
+    "}\n",
+    "\n",
+    "print(\"Deployment Requirements:\")\n",
+    "for key, value in DEPLOYMENT_REQUIREMENTS.items():\n",
+    "    print(f\"  {key}: {value}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "154da6ba",
+   "metadata": {
+    "papermill": {
+     "duration": 0.00148,
+     "end_time": "2026-02-02T13:03:56.835906",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.834426",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "## 9.5 Data Constraints"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f6682f6e",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-02-02T13:03:56.839748Z",
+     "iopub.status.busy": "2026-02-02T13:03:56.839615Z",
+     "iopub.status.idle": "2026-02-02T13:03:56.844180Z",
+     "shell.execute_reply": "2026-02-02T13:03:56.843643Z"
+    },
+    "papermill": {
+     "duration": 0.007327,
+     "end_time": "2026-02-02T13:03:56.844666",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.837339",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "DATA_CONSTRAINTS = [\n",
+    "    {\n",
+    "        \"Constraint\": \"PII Handling\",\n",
+    "        \"Requirement\": \"No direct PII in features (names, SSN, etc.)\",\n",
+    "        \"Status\": \"To verify\"\n",
+    "    },\n",
+    "    {\n",
+    "        \"Constraint\": \"Data Freshness\",\n",
+    "        \"Requirement\": \"Features must be available within 24 hours\",\n",
+    "        \"Status\": \"To verify\"\n",
+    "    },\n",
+    "    {\n",
+    "        \"Constraint\": \"Historical Depth\",\n",
+    "        \"Requirement\": \"Minimum 12 months of history for training\",\n",
+    "        \"Status\": \"To verify\"\n",
+    "    },\n",
+    "    {\n",
+    "        \"Constraint\": \"Protected Attributes\",\n",
+    "        \"Requirement\": \"Age, gender, race should not be direct features\",\n",
+    "        \"Status\": \"To verify\"\n",
+    "    }\n",
+    "]\n",
+    "\n",
+    "constraints_df = pd.DataFrame(DATA_CONSTRAINTS)\n",
+    "print(\"Data Constraints:\")\n",
+    "display(constraints_df)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dadb506b",
+   "metadata": {
+    "papermill": {
+     "duration": 0.00146,
+     "end_time": "2026-02-02T13:03:56.847876",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.846416",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "## 9.6 Intervention Strategy"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "97c21062",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-02-02T13:03:56.851591Z",
+     "iopub.status.busy": "2026-02-02T13:03:56.851490Z",
+     "iopub.status.idle": "2026-02-02T13:03:56.855665Z",
+     "shell.execute_reply": "2026-02-02T13:03:56.855228Z"
+    },
+    "papermill": {
+     "duration": 0.007099,
+     "end_time": "2026-02-02T13:03:56.856357",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.849258",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "INTERVENTIONS = [\n",
+    "    {\n",
+    "        \"Risk Level\": \"High (>0.8)\",\n",
+    "        \"Intervention\": \"Personal call from account manager\",\n",
+    "        \"Cost\": \"$50/customer\",\n",
+    "        \"Expected Effectiveness\": \"40% retention\"\n",
+    "    },\n",
+    "    {\n",
+    "        \"Risk Level\": \"Medium (0.5-0.8)\",\n",
+    "        \"Intervention\": \"Personalized email + discount offer\",\n",
+    "        \"Cost\": \"$10/customer\",\n",
+    "        \"Expected Effectiveness\": \"20% retention\"\n",
+    "    },\n",
+    "    {\n",
+    "        \"Risk Level\": \"Low (<0.5)\",\n",
+    "        \"Intervention\": \"Automated engagement email\",\n",
+    "        \"Cost\": \"$0.50/customer\",\n",
+    "        \"Expected Effectiveness\": \"5% retention\"\n",
+    "    }\n",
+    "]\n",
+    "\n",
+    "interventions_df = pd.DataFrame(INTERVENTIONS)\n",
+    "print(\"Intervention Strategy:\")\n",
+    "display(interventions_df)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d54fd4f3",
+   "metadata": {
+    "papermill": {
+     "duration": 0.00165,
+     "end_time": "2026-02-02T13:03:56.859839",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.858189",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "## 9.7 Save Business Context to Findings"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6cba5547",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2026-02-02T13:03:56.864013Z",
+     "iopub.status.busy": "2026-02-02T13:03:56.863903Z",
+     "iopub.status.idle": "2026-02-02T13:03:56.938199Z",
+     "shell.execute_reply": "2026-02-02T13:03:56.937543Z"
+    },
+    "papermill": {
+     "duration": 0.077367,
+     "end_time": "2026-02-02T13:03:56.938923",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.861556",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "findings.metadata = findings.metadata or {}\n",
+    "findings.metadata[\"business_context\"] = BUSINESS_CONTEXT\n",
+    "findings.metadata[\"success_metrics\"] = SUCCESS_METRICS\n",
+    "findings.metadata[\"deployment_requirements\"] = DEPLOYMENT_REQUIREMENTS\n",
+    "\n",
+    "findings.save(FINDINGS_PATH)\n",
+    "print(f\"Business context saved to: {FINDINGS_PATH}\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18808635",
+   "metadata": {
+    "papermill": {
+     "duration": 0.012662,
+     "end_time": "2026-02-02T13:03:56.953575",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.940913",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "---\n",
+    "\n",
+    "## Next Steps\n",
+    "\n",
+    "Continue to **10_spec_generation.ipynb** to generate production specifications."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f0b54317",
+   "metadata": {
+    "papermill": {
+     "duration": 0.01307,
+     "end_time": "2026-02-02T13:03:56.974482",
+     "exception": false,
+     "start_time": "2026-02-02T13:03:56.961412",
+     "status": "completed"
+    },
+    "tags": []
+   },
+   "source": [
+    "> **Save Reminder:** Save this notebook (Ctrl+S / Cmd+S) before running the next one.\n",
+    "> The next notebook will automatically export this notebook's HTML documentation from the saved file."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.4"
+  },
+  "papermill": {
+   "default_parameters": {},
+   "duration": 5.393777,
+   "end_time": "2026-02-02T13:03:59.592619",
+   "environment_variables": {},
+   "exception": null,
+   "input_path": "/Users/Vital/python/CustomerRetention/exploration_notebooks/09_business_alignment.ipynb",
+   "output_path": "/Users/Vital/python/CustomerRetention/exploration_notebooks/09_business_alignment.ipynb",
+   "parameters": {},
+   "start_time": "2026-02-02T13:03:54.198842",
+   "version": "2.6.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}