A comprehensive machine learning project for predicting food delivery times in urban settings. This project addresses the critical business problem of late deliveries that hurt customer trust, increase support costs, and risk customer churn.
macOS Users - Important: You need to install libomp for LightGBM/XGBoost to work properly:
brew install libompThis project uses uv for dependency management. We strongly recommend using uv run instead of python or pip commands.
- Clone the repository:
git clone <repository-url>
cd delivery-time-prediction- Install dependencies with uv:
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# or install via Homebrew with
brew install uv
# Install project dependencies
uv syncRecommended approach: Use the provided training script with uv run:
# Train the model using the example script
uv run model_pipeline/examples/train_model.pyThis will:
- Load the data from
data/Food_Delivery_Times.csv - Run the complete ML pipeline
- Train and compare 12 different models
- Save the best model to
models/ - Generate performance reports
# Start the FastAPI server
uv run run_api.pyThe server will start on http://localhost:8000 by default.
API documentation*is available at http://localhost:8000/docs. You can test the API directly from Docs.
The API automatically discovers and uses the first available model in the models/ directory:
- Auto-discovery: Scans
models/directory for.pklfiles - Consistent ordering: Uses alphabetical sorting for predictable model selection
- Fallback: Falls back to
ridge_regression.pklif no models found - Override: Can be overridden with
MODEL_PATHenvironment variable
GET /healthGET /model/infoPOST /predictRequest Body:
{
"Distance_km": 10.5,
"Weather": "Clear",
"Traffic_Level": "Medium",
"Time_of_Day": "Evening",
"Vehicle_Type": "Bike",
"Preparation_Time_min": 15.0,
"Courier_Experience_yrs": 3.5
}POST /predict/batch# Health check
curl http://localhost:8000/health
# Single prediction
curl -X POST "http://localhost:8000/predict" \
-H "Content-Type: application/json" \
-d '{
"Distance_km": 10.5,
"Weather": "Clear",
"Traffic_Level": "Medium",
"Time_of_Day": "Evening",
"Vehicle_Type": "Bike",
"Preparation_Time_min": 15.0,
"Courier_Experience_yrs": 3.5
}' | jqThis project includes comprehensive analysis and documentation:
- EDA Report - Complete exploratory data analysis with business insights
- Model Notes - Detailed model development process and findings
- Pipeline Summary - Technical implementation overview
- Error Insights - Analysis of prediction errors and patterns
- Explainability - Model interpretability and feature importance
- Strategic Reflections - Strategic insights and business recommendations
- SQL Queries - Comprehensive SQL queries for data analysis
- SQL Insights - Key findings from SQL analysis
- EDA.ipynb - Interactive exploratory data analysis
All analysis plots are saved in notebooks/images/ including:
- Feature distribution analysis
- Correlation heatmaps
- Model performance comparisons
- Error distribution analysis
- Feature importance plots
delivery-time-prediction/
├── data/ # Data files
│ ├── Food_Delivery_Times.csv # Raw dataset
│ └── model_comparison_results.csv # Comparison Results of all 12 models
├── notebooks/ # Jupyter notebooks
│ ├── EDA.ipynb # Exploratory Data Analysis
│ └── images/ # Generated analysis plots
├── model_pipeline/ # Production ML pipeline
│ ├── __init__.py
│ ├── config.py # Configuration parameters
│ ├── preprocessing.py # Data preprocessing
│ ├── feature_engineering.py # Feature engineering
│ ├── models.py # Model training & evaluation
│ ├── predict.py # Prediction interface
│ ├── pipeline.py # Main pipeline orchestrator
│ ├── utils.py # Utility functions
│ ├── README.md # Pipeline documentation
│ └── examples/ # Usage examples
│ ├── __init__.py
│ ├── train_model.py # Training script
│ ├── make_predictions.py # Prediction examples
│ └── custom_pipeline.py # Custom pipeline examples
├── api/ # FastAPI application
│ ├── __init__.py
│ ├── app.py # Main FastAPI application
│ ├── models.py # Pydantic models
│ ├── predictor_service.py # Predictor service wrapper
│ └── config.py # API configuration
├── models/ # Saved models
│ └── ridge_regression.pkl # Best performing model
├── results/ # Model results
│ ├── model_comparison.csv # Model comparison results
│ └── overfitting_analysis.csv # Overfitting analysis results
├── sql/ # SQL analysis
│ ├── sql_queries.sql # SQL queries for data analysis
│ └── sql_insights.md # SQL analysis insights
├── tests/ # Test files
│ ├── __init__.py
│ ├── test_pipeline.py # Pipeline tests
│ └── test_prediction.py # Prediction tests
├── run_api.py # API server startup script
├── main.py # Main application entry point
├── pyproject.toml # Project dependencies
├── uv.lock # Dependency lock file
├── LICENSE # License file
├── EDA_report.md # EDA analysis report
├── error_insights.md # Error analysis insights
├── explainability.md # Model explainability report
├── model_notes.md # Model development notes
├── PIPELINE_SUMMARY.md # Pipeline summary
├── strategic_reflections.md # Strategic insights
└── README.md # This file
Run the test script to verify everything works:
uv run python test_pipeline.pyThis will:
- Initialize the pipeline
- Load and process data
- Train models
- Make test predictions
- Verify all components work correctly
Core dependencies managed via pyproject.toml:
- pandas >= 2.3.3
- numpy (via pandas)
- scikit-learn >= 1.7.2
- xgboost >= 3.0.5
- lightgbm >= 4.6.0
- matplotlib >= 3.10.7
- seaborn >= 0.13.2
- scipy >= 1.16.2
- fastapi >= 0.119.0
- uvicorn >= 0.38.0
Note: This project requires Python >= 3.12
| Rank | Model | Test R² | Test RMSE | Test MAE | MAPE (%) |
|---|---|---|---|---|---|
| 1 | Ridge Regression | 0.8199 | 8.98 | 6.04 | 10.77 |
| 2 | Linear Regression | 0.8193 | 9.00 | 6.06 | 10.83 |
| 3 | Lasso Regression | 0.8032 | 9.39 | 6.55 | 12.76 |
| 4 | LightGBM | 0.7900 | 9.70 | 6.90 | 12.47 |
| 5 | Random Forest | 0.7855 | 9.80 | 7.08 | 13.35 |
Full and more detailed results available in data/model_comparison_results.csv after running training pipeline.
- Hyperparameter tuning with GridSearch/RandomSearch
- Feature selection optimization
- Ensemble methods
- Real-time prediction API
- Model monitoring and drift detection
- A/B testing framework
- Integration with delivery platforms
- Model versioning and rollback capabilities
Contributions are welcome. Please feel free to submit a Pull Request.
See LICENSE file for details.
Data Science Team
For issues or questions:
- Check the documentation in
model_pipeline/README.md - Review examples in
model_pipeline/examples/ - Run
uv run python test_pipeline.pyto diagnose issues - Open an issue on GitHub