PyTorch FoodVision Mini

An end-to-end MLOps project demonstrating the evolution of a deep learning solution from a research notebook to a robust, modular, and interactive web application. This repository builds "FoodVision Mini," a model that classifies images of pizza, steak, and sushi, served through both Flask and FastAPI.

---

📋 Table of Contents

1. 🎯 Project Journey: From Notebook to MLOps
2. ✨ Key Features
3. 🏗️ Architectural Overview
4. 🛠️ Tech Stack
5. 📂 Project Structure
6. 🚀 Getting Started
7. 🛠️ Usage
8. 🔭 Future Work
9. 🙏 Acknowledgements

🎯 Project Journey: From Notebook to MLOps

This repository is more than just a collection of scripts; it's a practical demonstration of the MLOps lifecycle, showing how a project matures from research to a deployable application.

1. Phase 1: Research (Jupyter Notebook): The project began in a notebook (research.py), the ideal environment for rapid experimentation and model prototyping. While great for research, notebooks are difficult to version, test, and deploy.
2. Phase 2: Modularization: The notebook's code was refactored into a modular Python package (food_vision). This separated concerns like data setup, model building, and the training engine, making the code reusable and testable.
3. Phase 3: Automation (CLIs): With a modular core, we built train.py and predict.py. These Command-Line Interfaces allow for automated, repeatable training runs and predictions, essential for scripting experiments.
4. Phase 4: Interaction (Web Apps): To make the model accessible, we built two web UIs—one using Flask and one with FastAPI. This introduced new challenges, like handling long-running training jobs without blocking the UI.
5. Phase 5: Decoupling (Shared Logic): The final architectural step was to extract all application logic (state management, prediction handling) into a shared, framework-agnostic package (webapp). This left the Flask and FastAPI files as "thin wrappers," resulting in a clean, maintainable system aligned with modern software design.

✨ Key Features

• 🧠 Deep Learning Core: Built with PyTorch, leveraging transfer learning with EfficientNetB0, B2, and B4.
• 🏛️ 3-Tier Modular Architecture: Clean separation between the ML Core (food_vision), Web App Logic (webapp), and Web Frameworks (app_flask.py, app_fastapi.py).
• 🚀 Dual Web Frameworks: Provides identical web applications in Flask and FastAPI.
• 💪 Background Training: Train new models directly from the UI without blocking, thanks to background process management.
• 📡 Live Status Updates: The UI uses JavaScript polling for real-time feedback on training status (Idle, Running, Completed).
• 🖼️ Interactive Predictions: Predict by uploading an image or clicking a sample image for an instant demo.
• 🔌 Device Agnostic: Automatically utilizes NVIDIA GPUs (CUDA), Apple Silicon (MPS), or CPU.

🏗️ Architectural Overview

The project is intentionally designed in layers to promote maintainability and scalability.

1. food_vision (The ML Brain): This is the self-contained machine learning core. It knows everything about our models and data but knows nothing about the web.
2. webapp (The Application's Central Nervous System): This is the framework-agnostic "business logic" layer. It orchestrates the application's functionality, acting as the bridge between the web interface and the ML core. It handles state, configuration, and actions like starting training or making predictions.
3. app_*.py (The Web Interface): The app_fastapi.py and app_flask.py files are thin wrappers. Their only responsibilities are to define URL endpoints, parse incoming requests, call the webapp logic layer to do the actual work, and return a response.

This separation ensures that we could swap Flask for Django, or FastAPI for another framework, without rewriting any of the core ML or application logic.

🛠️ Tech Stack

Component	Tools/Technologies	Description
ML Framework	PyTorch, torchvision	The core deep learning library used for building, training, and running the EfficientNet models.
Experiment Tracking	TensorBoard	Used for visualizing training metrics like loss and accuracy, helping to compare experiment runs.
Web Backend	FastAPI, Flask	Two distinct, popular Python frameworks used to build the interactive web application interface.
Web Server	Uvicorn	A high-performance ASGI server required to run the FastAPI application.
CLI Tools	argparse	Standard Python library used to create user-friendly command-line interfaces for train.py and predict.py.
Data Handling	Pillow, requests	Libraries used for opening and processing images, and for downloading datasets from URLs.
Environment Management	python-dotenv	Manages environment variables, such as the Flask secret key, keeping them out of the source code.

📂 Project Structure

PyTorch-FoodVision-Mini/
├── food_vision/               # Core machine learning package
│   ├── __init__.py
│   ├── data_setup.py
│   ├── engine.py
│   ├── model_builder.py
│   ├── predict.py
│   └── utils.py
├── webapp/                   # Shared, framework-agnostic web logic
│   ├── __init__.py
│   ├── config.py
│   ├── logic.py
│   ├── state.py
│   └── utils.py
├── static/                   # CSS, JavaScript, and sample images
│   ├── css/style.css
│   ├── js/main.js
│   └── samples/
├── templates/                # Shared HTML templates for the UI
│   ├── index.html
│   └── result.html
├── app_flask.py              # Entry point for the Flask application
├── app_fastapi.py            # Entry point for the FastAPI application
├── train.py                  # CLI for training models
├── predict.py                # CLI for making predictions
├── requirements.txt          # Project dependencies
└── README.md

🚀 Getting Started

Step 0: Prerequisites

• Python 3.9+
• (Optional but Recommended) A CUDA-enabled GPU for faster training.

Step 1: Clone the Repository

git clone https://github.com/GoJo-Rika/PyTorch-FoodVision-Mini.git
cd PyTorch-FoodVision-Mini

Step 2: Set Up The Environment and Install Dependencies

We recommend using uv, a fast, next-generation Python package manager, for setup.

Recommended Approach (using uv)

1. Install uv on your system if you haven't already.

   # On macOS and Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # On Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Create a virtual environment and install dependencies with a single command:

   uv sync

   This command automatically creates a .venv folder in your project directory and installs all listed packages from requirements.txt.

   Note: For a comprehensive guide on uv, check out this detailed tutorial: uv-tutorial-guide.

Alternative Approach (using venv and pip)

If you prefer to use the standard venv and pip:

1. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

2. Install the required dependencies:

   pip install -r requirements.txt

🛠️ Usage

Running the Web UI

You can run either the Flask or FastAPI application. They provide the same UI and functionality.

Option A: Run with Flask

# Make sure your virtual environment is active
python app_flask.py

Navigate to http://127.0.0.1:5001.

Option B: Run with FastAPI and Uvicorn

# Make sure your virtual environment is active
uvicorn app_fastapi:app --reload

Navigate to http://127.0.0.1:8000.

Using the Command-Line Interface

For automation or advanced use, you can use the CLI scripts.

# Train a new model (e.g., EffNetB2 on 20% data for 10 epochs)
python train.py \
    --model effnetb2 \
    --data_name "pizza_steak_sushi_20_percent" \
    --epochs 10 \
    --data_url "https://github.com/GoJo-Rika/PyTorch-FoodVision-Mini/raw/main/data/pizza_steak_sushi_20_percent.zip"

# Make a prediction with a trained model
python predict.py 
    --image_path "https://raw.githubusercontent.com/mrdbourke/pytorch-deep-learning/main/images/04-pizza-dad.jpeg" \
    --model_path "models/effnetb0_pizza_steak_sushi_10_percent_5_epochs.pth" \
    --model_name "effnetb0"

🔭 Future Work

This project provides a solid foundation. Here are some advanced MLOps features that could be added:

• Asynchronous Training with a Job Queue: Replace the subprocess module with a robust system like Celery and Redis. This would allow for handling multiple training requests, retries, and better process management.
• Model Registry Integration: Use a tool like MLflow to track experiments, log hyperparameters, and version model artifacts for better reproducibility.
• CI/CD Pipeline: Implement a GitHub Actions workflow to automatically run tests, lint code, and deploy the application.
• Containerization: Dockerize the application to ensure a consistent, reproducible environment for deployment on any cloud service.
• Add a Project Walkthrough GIF: Record a short GIF or video demonstrating the web UI in action (training and prediction) and replace the placeholder below.
• Implement a Makefile: Create a Makefile to simplify common commands (e.g., make run-flask, make run-fastapi, make install).
• Add Unit Tests: Implement unit tests for the functions in the webapp/logic.py module to ensure reliability and prevent regressions.

🙏 Acknowledgements

This project is heavily inspired by and based on the incredible PyTorch for Deep Learning course by Daniel Bourke.

---