prabham205/telecom-customer-churn-prediction-and-retention-recommendation

Purpose and entry points

This repository implements telecom customer churn prediction and retention recommendations, with analytical dashboards, an API surface, and an AI retention assistant. Primary runtime entry points are api/main.py for the service layer and app/streamlit_app.py plus app/pages/ for the Streamlit interface. Model training is initiated through scripts/train.py.

Data and feature pipeline

Raw customer data originates at data/raw/Telco_customer_churn.xlsx. The data path is organized as load, clean, engineer features, and preprocess:

• src/data/loader.py

• src/data/cleaner.py

• src/data/feature_engineering.py

• src/preprocessing/pipeline.py

The fitted preprocessing artifact is persisted at artifacts/preprocessor.joblib, creating a boundary between training-time transformations and inference-time inputs.

Model training, evaluation, and inference

The training layer supports several model implementations under src/models/, including lightgbm_model.py, xgboost_model.py, random_forest.py, logistic_regression.py, and dnn_model.py. Evaluation is centralized in src/models/evaluate.py, with recorded metrics at models/model_metrics.json.

Online or application-facing scoring is separated into src/prediction/predictor.py. This boundary should consume the persisted preprocessing/model artifacts rather than reproduce training logic.

Risk, value, and retention decisioning

Prediction outputs are converted into business actions through distinct domain modules:

• Churn-risk interpretation: src/risk/risk_engine.py

• Revenue-at-risk calculation: src/business/revenue_at_risk.py

• Customer prioritization: src/recommendation/priority_engine.py

• Rule-based retention and offer selection: src/recommendation/retention_rules.py and src/recommendation/offer_engine.py

This establishes a control flow of customer data → churn prediction → risk/value assessment → prioritized retention recommendation.

Generative AI and agent workflow

The AI retention assistant is structured as an agent graph rather than being embedded directly in the dashboard. Its workflow/state boundary is represented by:

• agent/graph.py

• agent/nodes.py

• agent/state.py

Prompt content is isolated in agent/prompts.py; LLM access and offer generation are isolated in genai/llm_client.py and genai/offer_generator.py. This separates deterministic recommendation logic from external LLM-driven assistance.

Delivery surfaces and operational concerns

The Streamlit UI exposes executive KPIs, customer-risk views, retention recommendations, AI assistance, and model performance through app/pages/01_Executive_Dashboard.py through app/pages/05_Model_Performance.py. Reusable visualization and presentation components reside in app/components/.

The API request/response boundary is represented by api/main.py and api/schemas.py. Monitoring is explicitly separated in src/monitoring/drift_monitor.py. Deployment infrastructure includes Dockerfile; dependencies and environment configuration are defined by requirements.txt, .env.example, and config.yaml.