Advanced AI Customer Intelligence Platform

Project Overview

This project is an end-to-end Customer Segmentation and Personalization System. It goes beyond traditional clustering by integrating deep behavioral analytics, predictive machine learning, explainable AI (SHAP), and an automated business strategy generator.

Core Architecture

1. Data Preprocessing Layer (src/data_processing.py): Handles ingestion, missing values, and feature engineering (calculating RFM metrics, Average Order Value, and Customer Lifetime Value proxy). It also normalizes the data for clustering.
2. Intelligent Segmentation Engine (src/segmentation.py): Implements K-Means, DBSCAN, Hierarchical Clustering, and Gaussian Mixture Models. Evaluates them dynamically using Silhouette and Davies-Bouldin scores to find optimal customer segments (e.g., High-Value Loyal vs. At-Risk).
3. Predictive Intelligence (src/predictive_models.py): Trains multiple models (XGBoost, Random Forest, Logistic Regression) to predict Customer Churn and forecasts future spending (CLV).
4. Explainable AI (src/explainability.py): Leverages SHAP (SHapley Additive exPlanations) to provide feature-level transparency into the predictive models (e.g., Why is this customer churning?).
5. Recommendation Engine (src/recommendation.py): Uses collaborative filtering to power cross-selling and product recommendations tailored to specific segments and individual transaction histories.
6. Strategy Generator (src/strategy_generator.py): Automatically interprets segment statistics into concrete, actionable business plans.
7. Interactive Dashboard (app.py): A complete Streamlit web application that unites all the ML modules into a cohesive, interactive UI.

Tech Stack

• Data & ML: Python, Pandas, NumPy, Scikit-Learn, XGBoost, SHAP
• Visualization: Plotly Express, Matplotlib, Seaborn
• Web App: Streamlit

Setup & Local Deployment

1. Ensure Python 3.10+ is installed.
2. Install dependencies:

   pip install -r requirements.txt

3. Generate the synthetic dataset (if not already done):

   python src/data_generator.py

4. Run the Streamlit Dashboard:

   streamlit run app.py

5. Open http://localhost:8501 in your browser.

Cloud Deployment (Render, Hugging Face Spaces, Streamlit Cloud)

This repository is 100% deployment-ready.

• For Streamlit Community Cloud / Hugging Face Spaces: Simply connect this GitHub repository and select app.py as the entry point. The platform will automatically install requirements.txt.
• For Render: Use a Python web service environment, set the start command to streamlit run app.py --server.port $PORT, and it will deploy seamlessly.

---

Built by Antigravity