📉 SaaS Churn Predictor (Single-File API)

"Solve one painful problem. Use the least amount of code."

A production-ready Micro-SaaS API that predicts user churn risk using OpenRouter and FastAPI. Built entirely in a single file (main.py) following the "47-line" philosophy.

---

⚡ Features

• 🎯 Precision Churn Analysis: Uses LLMs (amazon/nova-2-lite-v1) to analyze user profiles, usage stats, and support tickets.
• 🛡️ Rate Limiting: Built-in 10 req/min limit per IP using slowapi.
• 📊 Usage Metering: In-memory tracking of API usage per user.
• 🚀 Single-File Architecture: No database, no complex folder structures. Just main.py.
• 🔌 Standardized API: Fully typed Pydantic V2 models/schemas.

🛠️ Stack

• Python 3.10+
• FastAPI (Server)
• OpenRouter (LLM Interface)
• SlowAPI (Rate Limiting)
• Pydantic (Validation)

🚀 Quick Start

1. Clone & Install

git clone https://github.com/Hardik-369/ChurnX.git
cd ChurnX
pip install -r requirements.txt

2. Configure Key

Create a .env file:

OPENROUTER_API_KEY=sk-or-v1-your-key-here

3. Run

python main.py

Server starts at http://localhost:8000

📡 API Usage

Predict Churn

POST /predict_churn

{
  "user_id": "u123",
  "profile": {
    "plan": "Pro",
    "mrr": 49,
    "country": "US",
    "signup_date": "2024-01-01"
  },
  "usage_stats": {
    "last_seen_at": "2025-01-15",
    "login_days_last_30": 2,
    "feature_usage": {"feature_a": 0, "feature_b": 0}
  },
  "support_messages": [
    {"timestamp": "2025-01-10", "text": "Considering cancelling."}
  ]
}

Response:

{
  "user_id": "u123",
  "churn_risk_score": 85,
  "risk_level": "high",
  "reasons": ["Low login frequency", "Explicit cancellation intent"],
  "recommended_actions": ["Offer discount", "Schedule success call"]
}

Check Usage

GET /usage/{user_id}

{"user_id": "u123", "usage_count": 5}

📜 License

MIT License. Feel free to use this as a template for your own Micro-SaaS.