📡 TelecomAI Assistant

An intelligent AI-powered telecom business analytics dashboard built with Python, Machine Learning, and Large Language Models.

🎯 Project Overview

TelecomAI Assistant is a complete data-driven web application that helps telecom companies:

• Predict customer churn using Machine Learning (80% accuracy)
• Recommend the best data packages for each customer
• Analyze bundle purchase patterns and app usage trends
• Answer any business question through an AI chatbot powered by Llama 3
• Generate automated business reports from real telecom datasets

🚀 Live Demo

This application runs locally on your machine. Follow the Installation & Setup section below to run it.

Note: This is a locally hosted application. Clone the repository, install dependencies, add your Groq API key, and run streamlit run app.py to launch.

🛠️ Tech Stack

Technology	Purpose
Python 3.11	Core programming language
Streamlit	Web dashboard framework
Pandas	Data analysis and manipulation
Scikit-learn	Machine Learning models
Plotly	Interactive charts and visualizations
Groq API + Llama 3	AI chatbot (free, no credit card needed)
Joblib	Saving and loading ML models
python-dotenv	Secure API key management
openpyxl	Excel file reading

📊 Datasets Used

Dataset	Records	Description
IBM Telco Customer Churn	7,043 customers	Churn prediction and revenue analysis
Bundle Purchases May 2026	33,025 purchases	Bundle sales and revenue data
Addon Subscription Report	5,919 records	Subscription analytics
Data Usage November 2025	16,670 customers	App-level usage breakdown
Data Usage October 2025	17,150 customers	Monthly comparison data
Postpaid November 2025	436 customers	Postpaid usage analytics
Postpaid October 2025	432 customers	Month-over-month comparison
Service Usage Files	178 records	Individual customer bucket data

🤖 AI Features

• Churn Prediction — Random Forest Classifier with 80% accuracy
• Usage Prediction — Linear Regression for spending forecast
• Package Recommendation — Rule-based engine for personalized plans
• AI Chat Assistant — Llama 3 (70B) via Groq API with real dataset context
• Automated Reports — Download business reports as TXT and CSV

📁 Project Structure

telecom-ai-assistant/ │ ├── app.py # Main Streamlit dashboard ├── model_builder.py # ML model training script ├── load_all_data.py # New dataset loading functions ├── test_models.py # Model testing script ├── test_groq.py # Groq API connection test │ ├── data/ # Dataset files (not uploaded - see below) │ └── telecom.csv │ ├── models/ # Saved ML models (generated by model_builder.py) │ ├── churn_model.pkl │ ├── scaler_churn.pkl │ ├── usage_model.pkl │ ├── scaler_usage.pkl │ └── recommendation_engine.pkl │ ├── .env # API keys (NOT uploaded - create your own) ├── .gitignore # Files excluded from Git └── README.md # This file

⚙️ Installation & Setup

Step 1 — Clone the Repository

git clone https://github.com/YOUR_USERNAME/telecom-ai-assistant.git
cd telecom-ai-assistant

Step 2 — Create Virtual Environment

python -m venv .venv

Activate on Windows:

(Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned) ; (& .\.venv\Scripts\Activate.ps1)

Activate on Mac/Linux:

source .venv/bin/activate

Step 3 — Install Dependencies

pip install pandas numpy scikit-learn joblib streamlit plotly groq python-dotenv openpyxl reportlab

Step 4 — Get Free Groq API Key

1. Go to console.groq.com
2. Sign up with Google account (free — no credit card needed)
3. Click API Keys → Create API Key
4. Copy the key (starts with gsk_...)

Step 5 — Create .env File

Create a file called .env in the project root: GROQ_API_KEY=gsk_your_real_key_here

Step 6 — Add Dataset Files

Download the IBM Telco Customer Churn dataset from Kaggle:

• Search: "Telco Customer Churn" on kaggle.com
• Download WA_Fn-UseC_-Telco-Customer-Churn.csv
• Rename it to telecom.csv
• Place it inside the data/ folder

Step 7 — Train the ML Models

python model_builder.py

This creates all 5 model files inside the models/ folder.

Step 8 — Test the Connection

python test_groq.py

You should see: ✅ Groq is working!

Step 9 — Run the Application

streamlit run app.py

Open your browser at: http://localhost:8501

📱 Application Pages

📊 Dashboard

• 8 KPI metric cards from all datasets
• Churn distribution pie chart
• Bundle purchase analysis charts
• App usage breakdown (Facebook, YouTube, TikTok, Netflix, Gaming)
• October vs November comparison

👤 Customer Analysis

• Interactive sliders for customer profile input
• Real-time churn probability prediction (ML)
• Predicted spending amount
• Package recommendation with reason
• Churn risk gauge chart
• App usage comparison charts
• Bundle purchase channel analysis

🤖 AI Chat Assistant

• Powered by Llama 3 (70B parameters) via Groq API
• Answers questions about all 9 datasets
• Quick-question buttons for common queries
• Full conversation memory within session
• Example questions:
  • Which packages should we promote next month?
  • Which app uses the most data in November 2025?
  • Which customers are most likely to churn?
  • What is the predicted revenue for next month?

📄 Reports

• Complete churn analysis by contract type and internet service
• Bundle purchase revenue charts
• October vs November usage comparison
• Postpaid customer comparison
• AI-generated recommendations table
• Download full report as TXT
• Download key metrics as CSV

🔑 API Information

Item	Detail
AI Provider	Groq Cloud
Model	llama-3.3-70b-versatile
Cost	Free tier
Speed	~1-2 seconds per response
Context	Real dataset statistics injected via system prompt

📈 ML Model Performance

Model	Algorithm	Accuracy
Churn Prediction	Random Forest Classifier	~80%
Spend Prediction	Linear Regression	RMSE ~430
Package Recommendation	Rule-based Engine	N/A

👨‍💻 Developer Notes

• The .env file is excluded from Git for security — never commit API keys
• Dataset files are excluded from Git — download from Kaggle and place in data/
• Run model_builder.py once to generate all model files before running the app
• The Groq API is free — go to console.groq.com to get your key

Author

Kaviya