ML Target Prediction API

A machine learning project for predicting a user's target action based on session data, device information, traffic source, and geographic characteristics.

The project includes the complete ML solution development cycle: data analysis and preprocessing, training and comparison of machine learning models, selection of the best model, and creation of a REST API for obtaining predictions.

---

Technical Assignment

Project Goal

Develop a machine learning model that predicts whether a user will perform a target action based on user session data.

Target variable:

• 0 — target action was not performed;
• 1 — target action was performed.

Main Tasks

2. Perform exploratory data analysis (EDA).
3. Analyze missing values and data types.
4. Clean and preprocess the data.
5. Create and prepare the target variable.
6. Split the data into training and test sets.
7. Prepare features for model training.
8. Train several classification models.
9. Compare model performance.
10. Select the best-performing model.
11. Save the trained model.
12. Create a REST API using FastAPI.
13. Implement prediction requests using JSON.
14. Test the API with different input examples.
15. Prepare requirements.txt with the versions of the libraries used.

---

Project Overview

At the beginning of the project, the original dataset was analyzed. The data structure, feature types, missing values, target variable distribution, and other characteristics of the dataset were examined.

After the analysis, the data was cleaned and the features were prepared for further machine learning model training.

Special attention was paid to the class imbalance of the target variable. Therefore, not only overall accuracy but also other classification performance metrics were considered when evaluating the models.

---

Model Training and Comparison

Three classification models were trained and compared:

• Logistic Regression;
• Random Forest;
• CatBoost.

The models were evaluated using relevant performance metrics, including ROC-AUC.

After conducting the experiments, CatBoost achieved the best results among the tested models.

Therefore, CatBoost was selected as the final model for the project.

The trained model was saved as:

model.pkl

REST API

A REST API was created using FastAPI to provide predictions.

The API accepts user data in JSON format, passes it to the trained model, and returns the prediction result.

Example request

{
  "utm_adcontent": "ad_123",
  "utm_keyword": "keyword",
  "device_category": "desktop",
  "device_os": "Windows",
  "device_brand": "Apple",
  "device_model": "Mac",
  "device_screen_resolution": "1920x1080",
  "device_browser": "Chrome",
  "geo_country": "Russia",
  "geo_city": "Moscow"
}

Example result — target = 0

{
  "target": 0
}

Example result — target = 1

{
  "target": 1
}

The API was tested with different input data. As a result, both prediction outcomes (target = 0 and target = 1) were successfully processed.

API Testing

• starting the FastAPI application;
• loading the trained model;
• verifying correct JSON request processing;
• passing data to the model;
• receiving predictions;
• correctly returning target = 0;
• correctly returning target = 1.

FastAPI's automatic Swagger documentation was also used to test the API.

After starting the application, the documentation is available at:

http://127.0.0.1:8000/docs

Technologies Used

Machine Learning

• Python
• Pandas
• Scikit-learn
• CatBoost
• Dill

API

• FastAPI
• Uvicorn
• Pydantic

Tools

• Jupyter Notebook
• Git
• GitLab

Library Versions

To ensure project reproducibility, the versions of the main libraries are specified in requirements.txt:

fastapi==0.118.3
uvicorn==0.51.0
pandas==2.3.3
scikit-learn==1.7.2
dill==0.4.0
pydantic==2.12.4

The CatBoost library is also required to run the final model.

Project Structure

final-ml-project/
│
├── ml-target-api/
│   ├── main.py
│   ├── requirements.txt
│   └── .gitignore
│
├── ml-target-prediction/
│   ├── Final project.ipynb
│   ├── model.pkl
│   └── ...
│
├── .gitignore
└── README.md

Running the Project

1. Clone the repository

git clone https://gitlab.skillbox.ru/lada_bahdanovich/final-ml-project.git
cd final-ml-project

2. Install dependencies

pip install -r ml-target-api/requirements.txt

3. Start the API

Navigate to the API directory:

cd ml-target-api

Start the application:

uvicorn main:app --reload

After starting, the API will be available locally. Swagger documentation:

http://127.0.0.1:8000/docs

Conclusion

As a result of completing the project:

the original dataset was analyzed; the data was cleaned and preprocessed; class imbalance was taken into account; Logistic Regression, Random Forest, and CatBoost were trained and compared; CatBoost was selected as the model with the best results; the trained model was saved as model.pkl; a REST API was created using FastAPI; the API was tested with different input data; both prediction outcomes, target = 0 and target = 1, were successfully verified; the versions of the main dependencies were specified; JSON request and response examples were added; the project was prepared for local execution and further use.