How bhandarishikhar7313-cell/summer-analytics-project-2026-ca-iit-guwahati works
1. Overall shape
This repo is a two-part system: an offline analytics/model-training pipeline and an online Streamlit dashboard. Raw airline loyalty data is transformed into model artifacts, and the app layer loads those artifacts to produce customer-level intelligence and reports.
2. Primary data sources
The core inputs are four local CSV datasets under dataset/: customer loyalty history, monthly flight activity, calendar data, and the data dictionary. The architecture assumes 12 months of behavioral history per customer, which is the main unit of analysis throughout the system.
3. Data preparation boundary
dataset/scripts/ is the feature-engineering and dataset-building layer. These scripts convert raw CSVs into training-ready tables and tensors, including static features, sequence features, and future-value labels. This is the boundary between source data and ML-ready inputs.
4. Training subsystem
training/ contains the model-building pipelines for the project’s main predictive components: LSTM embeddings, XGBoost churn classification, hybrid modeling, and future-value regression. This layer produces the persisted artifacts stored under dataset/graphs/.
5. Artifact store / model registry
dataset/graphs/ acts as a local artifact repository rather than just a plotting folder. It holds trained models, embeddings, scalers, encoders, metrics, and feature-importance outputs. Runtime inference depends on these saved artifacts instead of retraining.
6. Behavioral modeling flow
The predictive pipeline starts with the LSTM encoder, which turns 12-month customer sequences into behavior embeddings. Those embeddings and engineered features then feed downstream churn and segment logic. This is the core behavioral intelligence layer of the platform.
7. Prediction and segmentation
The main inference logic lives in app/testing/ despite the name. It includes customer-level prediction, business profiling, retention logic, and report generation helpers. The app uses this layer to produce churn risk, priority, customer value, and segment labels for a selected customer or dataset.
8. Forecasting and value estimation
Separate regression models forecast future flights, distance, and loyalty points. These predictions are used to estimate future customer value and revenue at risk, which directly informs the retention strategy rather than just providing standalone forecasts.
9. Retention decision engine
The retention subsystem converts model outputs into business actions: priority tier, estimated loss, recommended interventions, and rationale. This is the bridge from ML outputs to decision support, and it is the main business logic boundary in the repo.
10. LLM reporting layer
The generative AI component uses Qwen 3 8B through Ollama to turn structured customer intelligence into executive summaries, customer messages, and management recommendations. This is a separate external runtime dependency, used after the predictive and retention layers have already produced structured inputs.
11. Streamlit presentation layer
app/Home.py is the dashboard entrypoint, with app/pages/ providing a multi-page workflow: overview, forecast, retention strategy, AI executive summary, customer message, and report export. The UI is organized as a guided analysis flow rather than a generic dashboard.
12. Output and export flow
The system’s end products are customer profiles, AI-generated narratives, and downloadable reports. The final pages consolidate structured ML outputs and LLM-generated text into exportable business intelligence for analysts and managers.
13. Architecture summary for diagramming
A good diagram should show: raw CSV inputs → preprocessing/feature engineering → model training/artifacts → Streamlit inference layer → retention logic → Ollama/Qwen report generation → interactive dashboard/export. The key boundaries are offline training vs. online app execution, and structured ML outputs vs. generated narrative outputs.
Main entry points: scripts Prep scripts · graphs Model store · business_predictor.py Customer intel · pages Pages
Components 21
Data & Artifacts
Raw datasets, engineered tables, tensors, and persisted model artifacts.
- Loyalty history · Customer loyalty history source dataset.
dataset/Customer Loyalty History.csv - Flight activity · Monthly customer flight activity source dataset.
dataset/Customer Flight Activity.csv - Calendar · Date and seasonality reference data.
dataset/Calendar.csv - Data dictionary · Schema and field definitions for the airline loyalty data.
dataset/Airline Loyalty Data Dictionary.csv - Model store · Persisted models, embeddings, scalers, encoders, metrics, and feature importances.
dataset/graphs
Offline Training
Feature engineering and model training pipelines that populate the artifact store.
- Prep scripts · Data loading, feature construction, tensorization, and training-table generation.
dataset/scripts - Training set · Builds merged customer-level datasets and labels from raw sources.
dataset/scripts/training_dataset.py - Features · Creates static, sequence, and derived behavioral features.
dataset/scripts/features.py - Tensors · Produces sequence tensors, scaled static inputs, encoders, and forecast labels.
dataset/scripts/tensors.py - Future labels · Constructs future-value training data for regression targets.
dataset/scripts/future_value_data.py - Training · Offline model training entrypoints for churn, hybrid, embeddings, and regression.
training - LSTM encoder · Learns behavior embeddings from 12-month customer sequences.
training/lstm_embeddings.py - Churn model · Baseline churn prediction model and feature importance pipeline.
training/xg_baseline.py - Hybrid model · Combines sequence embeddings with engineered features for downstream prediction.
training/hybrid.py - Value model · Forecasts future flights, distance, and loyalty-point value.
training/regressor.py
Streamlit App
Online inference, retention logic, LLM reporting, and user-facing pages.
- Inference · Loads artifacts and produces customer-level predictions and intermediate outputs.
app/testing/inference.py - Customer intel · Customer profiling, churn risk, customer value, and segment assignment.
app/testing/business_predictor.py - Retention engine · Converts model outputs into priority, estimated loss, and recommended actions.
app/testing/retention_engine.py - LLM reports · Uses Qwen 3 8B via Ollama to generate executive summaries and customer-facing narratives.
app/testing/llm_report.py - Dashboard · Main Streamlit entrypoint.
app/Home.py - Pages · Multi-page workflow for overview, forecast, retention, AI summary, message, and export.
app/pages
Connections 27
- Loyalty history → Prep scripts: raw input · Feeds customer history into preprocessing.
- Flight activity → Prep scripts: raw input · Feeds monthly activity into preprocessing.
- Calendar → Prep scripts: raw input · Provides time context for feature building.
- Data dictionary → Prep scripts: schema · Defines field meanings used during ingestion.
- Prep scripts → Training set: build · Creates merged training tables.
- Prep scripts → Features: derive · Generates engineered static and sequence features.
- Prep scripts → Tensors: tensorize · Produces scaled arrays and encoders.
- Prep scripts → Future labels: label prep · Builds future-target regression data.
- Training set → Churn model: train data · Supplies tabular inputs for churn models.
- Features → Hybrid model: feature input · Supplies engineered features to hybrid modeling.
- Tensors → LSTM encoder: sequence input · Supplies customer sequences for embedding learning.
- Tensors → Value model: forecast input · Supplies forecast tensors and targets.
- Future labels → Value model: targets · Provides future-value labels.
- LSTM encoder → Model store: save · Persists embedding and sequence models.
- Churn model → Model store: save · Persists churn baseline models and diagnostics.
- Hybrid model → Model store: save · Persists hybrid churn artifacts.
- Value model → Model store: save · Persists future-value predictors and metrics.
- Model store → Inference: load · Runtime inference depends on saved models and preprocessors.
- Inference → Customer intel: scores · Produces customer-level predictions and derived signals.
- Customer intel → Retention engine: decision input · Feeds business metrics into retention logic.
- Customer intel → LLM reports: structured context · Provides customer intelligence for narrative generation.
- Retention engine → LLM reports: strategy context · Provides actions and rationale for AI summaries.
- Inference → Dashboard: runtime data · Supplies dashboard views with scored outputs.
- Customer intel → Pages: analysis views · Feeds forecast and overview pages.
- Retention engine → Pages: strategy views · Feeds retention strategy and export pages.
- LLM reports → Pages: narratives · Feeds AI summary and customer message pages.
- Dashboard → Pages: navigation · Main entrypoint routes into the multi-page workflow.