Hugging Face's logo

Spaces:
sks01dev
/
Customer-Conversion-Prediction
Sleeping

App Files Community
Customer-Conversion-Prediction / readme.md
sks01dev's picture
sks01dev
Upload 15 files
d64524a verified
preview code
|
raw
history blame contribute delete
3.8 kB

Customer Conversion Prediction API

Python FastAPI Docker License

This project demonstrates deploying a machine learning model with FastAPI and Docker.
The model predicts the probability of a lead converting to a customer based on simple features.

Table of Contents

Project Overview

We use a pre-trained Logistic Regression model with a DictVectorizer to process input features:

  • lead_source (categorical: organic_search, social_media, paid_ads, referral, events)
  • annual_income (numeric)
  • number_of_courses_viewed (numeric)

The model is served via FastAPI, and can be deployed using Docker.

Requirements

Setup & Installation

1. Clone the repository 

git clone <your-repo-url>
cd <repo-folder>

2. Install dependencies with uv 

# Install uv globally if not already
pip install uv

# Initialize uv project
uv init

# Install dependencies from pyproject.toml
uv sync --frozen

3. Verify Python and library versions 

python --version
uv --version

Running Locally

  1. Make sure the model.bin file is in the project directory.
  2. Run the FastAPI server:
uvicorn predict:app --host 0.0.0.0 --port 9696
  1. Open API docs in your browser: http://localhost:9696/docs

Docker Deployment

1. Build Docker image 

docker build -t customer-conversion-prediction .

2. Run container 

docker run -d -p 9696:9696 customer-conversion-prediction
  • Access the API at http://localhost:9696/predict.

3. Test API inside Python 

import requests

url = "http://localhost:9696/predict"
client = {
    "lead_source": "organic_search",
    "number_of_courses_viewed": 4,
    "annual_income": 80304.0
}

response = requests.post(url, json=client)
print(response.json())

Using the API

Request format 

{
    "lead_source": "paid_ads",
    "number_of_courses_viewed": 2,
    "annual_income": 79276.0
}

Response format 

{
    "convert_probability": 0.533,
    "converted": true
}
  • convert_probability: probability of conversion
  • converted: True if probability >= 0.5, else False

Project Structure 

.
├── Dockerfile
├── model.bin
├── pyproject.toml
├── uv.lock
├── predict.py
└── README.md
  • Dockerfile: defines container image
  • predict.py: FastAPI app and prediction code
  • model.bin: pre-trained ML model
  • pyproject.toml & uv.lock: dependency management
  • README.md: project documentation

License

This project is for educational purposes for ML Zoomcamp 2025.

References