Quick Start Guide

Set up ChurnGuard and make your first prediction in 5 minutes

Prerequisites: Python 3.12+, pip, 2GB RAM

1 Install Dependencies

cd /home/murat/churn-prediction-system
python3 -m pip install --break-system-packages -r requirements.txt

2 Train Models

chmod +x RUN_TESTS.sh
./RUN_TESTS.sh
Result: 7 ML models trained (Telco: 96.74% ROC AUC, Banking: 99.56% ROC AUC)

3 Start APIs

Terminal 1: Telco API

python3 -m uvicorn api.main:app --reload --port 8000

Terminal 2: Banking API

python3 -m uvicorn banking.api.main:banking_app --reload --port 8001

4 Make Your First Prediction

Telco Example

curl -X POST "https://predictivs.com/api/telco/log_activity" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "TEST_001",
    "call_duration_mins": 50.0,
    "data_usage_gb": 2.0,
    "support_tickets_count": 8,
    "contract_type": "Monthly",
    "monthly_charge": 120.0
  }'

Response:

{
  "customer_id": "TEST_001",
  "churn_probability": 0.9973,
  "risk_level": "High",
  "crm_notified": true
}

Banking Example

curl -X POST "https://predictivs.com/api/banking/banking/log_activity" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "BANK_001",
    "account_age_months": 6,
    "account_type": "Checking",
    "num_products": 1,
    "average_balance": 2500.00,
    "total_transaction_count": 8,
    "credit_card_usage_ratio": 0.95,
    "loan_amount": 15000.00,
    "mobile_app_logins": 2,
    "complaint_count": 7
  }'

Response:

{
  "customer_id": "BANK_001",
  "churn_probability": 1.0,
  "risk_level": "Critical",
  "clv": 378.50,
  "priority": 3,
  "retention_actions": [
    "Senior management meeting",
    "6-month fee waiver"
  ]
}

5 Explore with Swagger UI

Telco API

https://predictivs.com/api/telco/docs

Banking API

https://predictivs.com/api/telco/docs

Next Steps

API Reference

Explore all endpoints and parameters

ML Guide

Customize and retrain models

Troubleshooting

ModuleNotFoundError 
python3 -m pip install --break-system-packages -r requirements.txt
Port already in use 
lsof -i :8000
kill -9 <PID>