🦋 ButterflyFlow — AI-Driven Churn Defender for Telecoms

ButterflyFlow is a full-stack, AI-powered churn-prevention platform designed to help telecom customer-success teams retain high-value users.

It identifies early signals of potential churn, provides insights into why customers are disengaging, and empowers support teams with automated, Gemini-generated retention strategies — all through a sleek and intuitive Streamlit dashboard.

Whether it's billing dissatisfaction, poor network experience, or unresolved issues, ButterflyFlow not only predicts who’s at risk but also tells you what to do about it — including one-click email execution via Gmail API.

🏁 Submitted to the Hackathon: Code the Cloud'25

---

✨ Key Features

#	Capability	What it Delivers
1. Predict‐Churn	Binary churn score (0 – 1) using TabNet at 94 % accuracy.
2. Churn Category	Multi-class CatBoost model pinpoints why each user might churn (pricing, network, support wait-time, etc.).
3. Interactive Dashboard	Streamlit UI shows global KPIs, cohort heatmaps, and per-customer 360° panels (tenure, ARPU, usage, complaints).
4. Risk Filtering	Quick filters (e.g. risk > 0.70) surface high-priority customers so agents can act fast.
5. Gemini Chatbot Assistant	Embedded chat explains churn drivers in plain English and suggests personalized retention tactics.
6. One-Click Email Outreach	Agents approve Gemini’s script → Gmail API sends an on-brand email instantly.
7. Campaign Mode	Bulk-select churn segments and auto-launch retention campaigns, tracking open & response rates.
8. Real-Time Updates	New data streams into MongoDB; the dashboard refreshes without a full redeploy.

---

⚙️ Tech Stack & Tools

Category	Technology	Icons
🧠 Machine Learning	TabNet (Google), CatBoost
🧰 Backend/Storage	MongoDB Atlas
🖼️ Frontend	Streamlit
🔮 AI Assistant	Gemini API
📧 Email Automation	Gmail API
📈 Deployment-Ready	Python 3.10+, virtualenv

---

📊 Dataset

• Source: Kaggle – Telco Customer Churn 11-13
• Rows: 7 043 customers × 21 raw features
• Pipeline: outlier clipping · categorical encoding · 30-day rolling aggregates · class balancing.

---

🖼️ Screenshots

---

🚀 Getting Started

🔧 Setup

1. Clone this repo:

   git clone https://github.com/your-username/butterflyflow.git
   cd butterflyflow

2. Create and activate a virtual environment:

   python -m venv .venv
   .venv\Scripts\activate      # For Windows
   source .venv/bin/activate   # For macOS/Linux

3. Install dependencies:

   pip install -r requirements.txt

4. Set your environment variables (either via .env or manually):

   MONGODB_URI="your-mongodb-connection-string"
   GEMINI_API_KEY="your-gemini-key"
   GOOGLE_CREDENTIALS_JSON="path/to/gmail_service_account.json"

---

▶️ Run the Application

To launch the dashboard using Streamlit:

python -m streamlit run "C:/link/AIChurn/AIChurn.py"

Once launched, open your browser and navigate to:

http://localhost:8501

You're now ready to explore churn predictions, insights, and retention strategies in real-time! 🎯

---

MIT License

Copyright (c) 2025 Kowshika

Permission is hereby granted, free of charge, to any person obtaining a copy...