📡 TeleSentry AI

Explainable Telecom Fraud Detection Platform using Machine Learning, Rule-Based Intelligence, SHAP, FastAPI, and Streamlit

---

📖 Overview

TeleSentry AI is an end-to-end Telecom Fraud Detection Platform designed to identify suspicious calling behavior using a combination of:

• Rule-Based Fraud Intelligence
• Isolation Forest Anomaly Detection
• Random Forest Classification
• SHAP Explainability
• Interactive Streamlit Dashboard
• FastAPI Prediction Service

The system simulates realistic telecom users and fraudsters, engineers behavioral telecom features, detects suspicious activities, explains predictions, and exposes results through a dashboard and API.

---

🎯 Problem Statement

Telecommunication fraud has become increasingly sophisticated.

Common fraud patterns include:

• Digital Arrest Scams
• Mass Calling Operations
• Long Distance Fraud Rings
• Social Engineering Networks
• Automated Calling Bots

Traditional rule-based systems fail to detect new fraud patterns, while pure machine learning systems often lack interpretability.

TeleSentry AI combines both approaches to deliver:

• High detection accuracy
• Transparent predictions
• Real-time fraud assessment

---

🏗 Architecture

┌─────────────────────────────────────────┐
│          Synthetic Data Generator       │
│        (Telecom User Simulation)        │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│           Raw Synthetic Dataset         │
│      generated_dataset.csv (13k+)       │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│         Data Preprocessing Layer        │
│                                         │
│ • Cleaning                              │
│ • Validation                            │
│ • Train/Test Split                      │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│        Feature Engineering Layer        │
│                                         │
│ • call_intensity                        │
│ • distance_per_call                     │
│ • contact_circle_ratio                  │
│ • delivery_pattern                      │
│ • high_freq_long_distance               │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│          Rule Engine Layer              │
│                                         │
│ • Digital Arrest Detection              │
│ • Mass Calling Detection                │
│ • Long Distance Scam Detection          │
│ • Traveler Detection                    │
│ • Business User Detection               │
└──────────────────┬──────────────────────┘
                   │
                   ▼
      ┌─────────────────────────┐
      │      ML Layer           │
      │                         │
      │ Isolation Forest        │
      │ Random Forest           │
      └───────────┬─────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│          Evaluation Layer               │
│                                         │
│ Accuracy                                │
│ Precision                               │
│ Recall                                  │
│ F1 Score                                │
│ ROC-AUC                                 │
└──────────────────┬──────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────┐
│         Explainability Layer            │
│                                         │
│ SHAP Summary                            │
│ SHAP Waterfall                          │
│ Feature Importance                      │
└──────────────────┬──────────────────────┘
                   │
          ┌────────┴─────────┐
          ▼                  ▼
┌────────────────┐  ┌──────────────────┐
│ Streamlit UI   │  │   FastAPI API    │
│                │  │                  │
│ Dashboard      │  │ /predict         │
│ Analytics      │  │ /health          │
│ Live Predict   │  │ Swagger Docs     │
└────────────────┘  └──────────────────┘

System Flow

Synthetic Data Generation
          ↓
Data Preprocessing
          ↓
Feature Engineering
          ↓
Rule Engine
          ↓
Machine Learning Layer
          ↓
Evaluation Layer
          ↓
SHAP Explainability
          ↓
Streamlit Dashboard + FastAPI

---

📂 Project Structure

TeleSentry-AI/
│
├── api/
├── dashboard/
├── data/
├── notebooks/
├── reports/
├── saved_models/
├── src/
├── tests/
│
├── README.md
├── requirements.txt
├── requirements-lock.txt
├── LICENSE
├── VERSION
└── .env.example

---

⚙️ Features

Synthetic Telecom Dataset Generator

Generates realistic telecom profiles:

Legitimate Users

• Delivery Partners
• Business Users
• Regular Subscribers
• Traveling Professionals

Fraud Profiles

• Digital Arrest Bots
• Traditional Scammers
• Low Volume Fraudsters

---

Feature Engineering

Generated telecom intelligence features:

Feature	Description
call_intensity	Calling activity level
distance_per_call	Average call distance ratio
contact_circle_ratio	Contact diversity ratio
delivery_pattern	Delivery behavior pattern
high_freq_long_distance	Suspicious high-volume calling

---

Rule Engine

Fraud intelligence layer:

• Digital Arrest Detection
• Mass Calling Detection
• Long Distance Scam Detection
• Traveler Detection
• Business User Detection
• Delivery Pattern Detection

---

Machine Learning Models

Isolation Forest

Purpose:

• Unsupervised anomaly detection
• Detection of unusual telecom behavior

Random Forest

Purpose:

• Supervised fraud classification
• Fraud probability estimation

---

📊 Model Performance

Metric	Score
Accuracy	98%+
Precision	97%+
Recall	98%+
F1 Score	98%+
ROC-AUC	99%+

---

🧠 Explainable AI

TeleSentry AI uses SHAP (SHapley Additive Explanations).

Generated explanations include:

• SHAP Summary Plot
• SHAP Waterfall Plot
• Feature Importance Analysis

Top fraud indicators:

• avgCallDistance
• circleDiversity
• call_intensity
• avgDuration
• high_freq_long_distance

---

📈 Dashboard

Interactive Streamlit dashboard provides:

Dataset Overview

• Dataset statistics
• Fraud distribution
• User type analysis
• Operator analysis

Model Analytics

• Accuracy
• Precision
• Recall
• F1 Score
• ROC Curve
• Confusion Matrix

Live Fraud Prediction

Predict fraud risk using telecom activity metrics.

Rule Engine Analytics

Visualize fraud intelligence triggers.

SHAP Explainability

Interpret model decisions.

---

🚀 FastAPI Backend

Endpoints:

Root

GET /

Health Check

GET /health

Prediction

POST /predict

Example Request:

{
  "avg_duration": 5,
  "call_frequency": 150,
  "unique_contacts": 100,
  "avg_distance": 600,
  "circle_diversity": 8
}

Example Response:

{
  "prediction": "FRAUD",
  "fraud_probability": 0.98,
  "risk_level": "CRITICAL"
}

---

🛠 Installation

Clone Repository

git clone https://github.com/7vik2005/TeleSentry-AI.git

cd TeleSentry-AI

Install Dependencies

pip install -r requirements.txt

---

▶ Running The Project

Generate Dataset

python -m src.data_generation.generator

Apply Rule Engine

python -m src.rule_engine.rules

Train Models

python -m src.models.random_forest

Generate SHAP Explanations

python -m src.explainability.shap_explainer

Launch Dashboard

python -m streamlit run dashboard/app.py

Launch API

python -m uvicorn api.app:app --reload

---

📚 Technologies Used

• Python
• Pandas
• NumPy
• Scikit-Learn
• SHAP
• FastAPI
• Streamlit
• Plotly
• Matplotlib
• Faker

---

🔮 Future Enhancements

• XGBoost Integration
• Real Telecom Data Support
• Real-Time Streaming Detection
• Docker Deployment
• Cloud Deployment
• Automated Retraining Pipeline
• MLOps Integration

---

👨‍💻 Author

Satvik Jambagi

Machine Learning | Data Science | AI Engineering

---

📜 License

This project is licensed under the MIT License.