# :brain: + :computer: ML - Project description
## Spring 2025

### Introduction
During the class **Machine Learning**, you will get to implement one large group project. The goal of this course is to give you the skills required to build real-world ML applications. The group project’s main goal is to teach you new tools and best practices of **MLOps**.

You are in control of your project and will be able to make choices in terms of design and tooling. Most importantly, find a project that excites you, maybe that even serves a real-world use case. Pick a cool name and work in teams 👫🚀.

You could use this as a template

> [](https://github.com/nevermind78/ml-project/tree/main)

### Practicals
- Form teams of **2 - 3 students**.
- There will be **3 milestone meetings** where you can present your results.
- The topics covered in lectures and in labs are split into **6 sprints**. The components to be implemented during the group project follow the same 6 sprints. We recommend following the pace of the sprints (so implement the components in the same sprint), but as long as you have them implemented for the milestone meetings, it’s fine.
- Each sprint has several **work packages**.
- Note that all work packages are **not mandatory**. Some components are just optional. You can achieve a perfect score without them if you show great quality in the required work packages. But the optional ones can help you increase your score if not.
- There will be some time after each class to sit down with your team and make progress on your projects. The teaching staff will be in the same room and can provide support.

### Handovers
You will get to show your work in two ways:

#### 1. Milestone presentations
There will be **3 milestone presentations** where you will get to present your work.

| MS | Topics | Sprints |
|----|--------|---------|
| 1 | Present your general use case, the data preparation, and the result from your model experimentation. | Sprint 1 & 2 |
| 2 | Present your architecture for model serving, model deployment, and (if possible) model pipeline. | Sprint 3 (& 4) |
| 3 | Present your overall project work. You can present a demo of your model/use case and any other topic you think is relevant. | All sprints |

#### 2. Code submissions
The way to share your implementation will be through **code reviews**.

- Make sure to share your GitHub repo with the teaching staff.
- Follow **Gitflow** practices:
- Develop individual features on feature branches based on `develop` and merge them as you go.
- At significant milestones, create a Pull Request (PR) from the `develop` branch to the `master` branch and include me as reviewer.
- **Careful to follow naming conventions**.
- The **README** and other markdown files will be used as the main documentation points. All important aspects of your project should be explained there.
- We recommend using the main README to explain the project structure and have different markdown files per building blocks (e.g., `EXPERIMENTATION.md`, `DEPLOYMENT.md`, …).
- The PR description should include main new changes and what the teaching staff should actually have a look at.
- The teaching staff won’t run the codes, so make sure to heavily document all important points in markdown files.
- For this project, also include non-code material in the repo such as presentation decks.
- Once ready, send a link to the pull request to the teaching staff **by email**. Tagging the teaching staff in GitHub is not enough.

---

## Building blocks
This section covers the components you should implement for your project. The structure follows the overall course sprints.

### Sprint 1: Project organization
This sprint will focus on overall project setup and organization. It mostly covers functional aspects of a project as well as collaboration and communication tools.

Note that for each sprint, some concepts are explained in the 2nd week. The `WX` next to a task indicates in which week we’ll cover that topic in lecture/lab.

| # | Week | Work package | Requirement |
|----|------|--------------|-------------|
| 1.1 | W01 | Pick a team | Required |
| | | $\bullet$ Try to mix skills and experience | |
| | | $\bullet$ If you didn’t find one, let one of the teachers know, and we’ll allocate you to one* | |
| 1.2 | W02 | Select a use case | Required |
| | | Source options: | |
| | | $\bullet$ Previous course | |
| | | $\bullet$ Kaggle Datasets | |
| | | $\bullet$ Datacamp | |
| | | Make sure to pick a use case where data is available. | |
| | | Note that the ML modeling itself won’t be a big part of the course. | |
| | | If you can pick data from one of your previous course projects, that’s perfect. | |
| | | Ideally, pick something with interesting data and a real-world application. | |
| 1.3 | W02 | Define your use case | Required |
| | | $\bullet$ Fill in a ML Canvas template page | |
| | | $\bullet$ You can skip the *Inference* part as we will tackle that in a later sprint. | |
| 1.4 | W02 | Find a cool name for your project | Required |
| 1.5 | W02 | Setup communication channel | Required |
| | | $\bullet$ Discord | |
| | | $\bullet$ Trello board | |
| | | $\bullet$ … | |
| 1.6 | W02 | Setup a code versioning repository | Required |
| | | $\bullet$ We recommend GitHub as we will cover GitHub Actions during this course | |
| 1.7 | W02 | Submit your project by sending a filled-in project card to the teaching staff with basic information about your project. | Required |
| | | We might give you some feedback and ask for parts to be changed. | |

---

### Sprint 2: Cloud & model development
The goal of this sprint is to prepare your data and train and optimize your ML model.
Note that you will **not** be graded on the performance of your model, only on your development methodology.
So do **not spend much time optimizing your data or model.**

| # | Week | Work package | Requirement |
|----|------|--------------|-------------|
| 2.1 | W03 | Prepare your data and run an Exploratory Data Analysis. | Required |
| 2.2 | W03 | Prepare your (**Cloud**) environment. That means creating a Cloud project, granting correct access rights to all members of your group, and setting up a billing account. | Required ( **Cloud Optional**)|
| | | **Attention**: You can have free credits for the Cloud, as explained during the course. | |
| 2.3 | W04 | Train your ML model | Required |
| 2.4 | W04 | Evaluate your ML model | Required |
| 2.5 | W03 & W04 | Document your data analysis and model performance | Required |

---

### Sprint 3: API implementation
This sprint focuses on building a **model serving API**, a **Docker container(Optioanl)** hosting the model serving, and **deploying** your model serving API.

On top of that, *if you are interested*, you can experiment with managed services such as Sagemaker Predict or Vertex Predictions.

| # | Week | Work package | Requirement |
|----|------|--------------|-------------|
| 3.1 | W05 | Build an **API** to **serve your model** and any extra logic that is needed to serve it (e.g., using Flask). | Required |
| | | You should be able to run the API locally. | |
| 3.2 | W05 | Package your model serving API in a **Docker container**. | Required |
| | | This too should be run locally. | |
| 3.3 | W06 | **Deploy** your model serving API in a free hosting service [**render**](https://render.com/) or [**zeabar**](https://zeabur.com/) ,..... You should be able to call your model to generate new predictions from another machine. | Required |
| | | **Attention**: If you are using Aws or Azure : This can incur Cloud **costs**. Make sure to use a platform where you have credits and not burn through them. You can ask for support from the teaching staff in that regard. | |

---

### Sprint 4: Model Pipeline
In this sprint, you will implement a **model pipeline** to automate the steps of your model training, deployment, and serving. Since you are using free tools and services, you will implement a lightweight pipeline using **GitHub Flow** to manage your codebase and automate tasks.

#### Key Components:
1. **Streamlit App**: A user interface for interacting with your model.
2. **API Hosted on Render**: A web service to serve your model predictions.
3. **Local Training Script (`train.py`)**: A script to train and save your model using `joblib`.
4. **GitHub Flow**: A lightweight CI/CD pipeline to manage code changes and automate tasks.

| # | Week | Work package | Requirement |
|----|------|--------------|-------------|
| 4.1 | W08 | **Set up GitHub Flow**: Implement a lightweight CI/CD pipeline using GitHub Flow. | Required |
| | | - Use feature branches for development and merge them into the `main` branch via Pull Requests (PRs). | |
| | | - Automate tasks such as running tests, linting, and deploying the API or Streamlit app using GitHub Actions. | |
| 4.2 | W08 | **Train and Deploy Model Locally**: Use `train.py` to train your model and save it using `joblib`. | Required |
| | | - Ensure the trained model is saved in a format that can be loaded by your API and Streamlit app. | |
| | | - Document the steps to run the training script locally. | |
| 4.3 | W08 | **Deploy API to Render**: Deploy your model serving API to Render. | Required |
| | | - Ensure the API can load the trained model and serve predictions. | |
| | | - Document the deployment process and provide the API endpoint URL. | |
| 4.4 | W08 | **Build and Deploy Streamlit App**: Create a Streamlit app to interact with your model. | Required |
| | | - The app should allow users to input data and display predictions from the API. | |
| | | - Deploy the Streamlit app using a free hosting service (e.g., Streamlit Sharing). | |
| 4.5 | W08 | **Automate Pipeline Tasks**: Use GitHub Actions to automate tasks such as: | Optional |
| | | - Running tests and linting on PRs. | |
| | | - Automatically deploying the API to Render when changes are merged into `main`. | |
| | | - Automatically deploying the Streamlit app when changes are merged into `main`. | |

#### Example Workflow:
1. **Development**:
- Create a feature branch for new changes.
- Develop and test locally.
- Push changes to the feature branch and create a PR.
2. **Code Review**:
- Use GitHub Actions to run tests and linting on the PR.
- Get approval from teammates and merge into `main`.
3. **Deployment**:
- GitHub Actions automatically deploys the API to Render and the Streamlit app to its hosting service.
- Ensure the API and app are functioning as expected.

#### Documentation:
- Document the entire pipeline in your repository's `README.md` or a dedicated `PIPELINE.md` file.
- Include instructions for running the training script, deploying the API, and deploying the Streamlit app.
- Provide links to the deployed API and Streamlit app.
---

### Sprint 5: Optimization & Monitoring
In this sprint, you will focus on optimizing your pipeline and monitoring your deployed application. Since you are using free tools and services, the focus will be on lightweight optimization and monitoring strategies.

| # | Week | Work package | Requirement |
|----|------|--------------|-------------|
| 5.1 | W09 | **Optimize Local Training**: Improve the efficiency of your local training script (`train.py`). | Optional |
| | | - Use techniques like feature engineering, hyperparameter tuning, or model selection to improve training efficiency. | |
| | | - Document any changes made to the training process. | |
| 5.2 | W09 | **Monitor API Performance**: Set up basic monitoring for your API hosted on Render. | Optional |
| | | - Use Render's built-in monitoring tools or integrate with free services like [UptimeRobot](https://uptimerobot.com/) to track API uptime and performance. | |
| | | - Document the monitoring setup and include screenshots or logs in your repository. | |
| 5.3 | W10 | **Enhance Streamlit App**: Improve the user interface and functionality of your Streamlit app. | Optional |
| | | - Add features like input validation, error handling, or visualizations to make the app more user-friendly. | |
| | | - Deploy the updated app to Streamlit Sharing. | |

---

### Sprint 6: CI/CD
In this last sprint, you will finalize your CI/CD pipeline using **GitHub Actions** to automate tasks such as testing, linting, and deployment. This will ensure that your application is robust and can be updated efficiently.

| # | Week | Work package | Requirement |
|----|------|--------------|-------------|
| 6.1 | W10 | **Set Up GitHub Actions**: Implement a CI/CD pipeline using GitHub Actions to automate tasks. | Required |
| | | - Include at least one step, such as running tests or linting, in your pipeline. | |
| 6.2 | W10 | **Automate Deployment**: Configure GitHub Actions to automatically deploy your API to Render and your Streamlit app to its hosting service when changes are merged into `main`. | Optional |
| | | - Ensure the deployment process is reliable and well-documented. | |
| 6.3 | W10 | **Add Linting**: Use `pylint` or `flake8` to enforce code quality in your repository. | Optional |
| | | - Add a GitHub Actions workflow to run linting on every PR. | |
| 6.4 | W10 | **Add Unit Tests**: Write unit tests for critical parts of your code (e.g., API endpoints, training script) using `pytest`. | Optional |
| | | - Add a GitHub Actions workflow to run tests on every PR. | |
| 6.5 | W10 | **Document CI/CD Pipeline**: Document your CI/CD pipeline in your repository's `README.md` or a dedicated `CI_CD.md` file. | Required |
| | | - Include details about the workflows, how to trigger them, and how to troubleshoot issues. | |

---

#### Example CI/CD Workflow:
1. **Development**:
- Create a feature branch for new changes.
- Develop and test locally.
- Push changes to the feature branch and create a PR.
2. **Code Review**:
- GitHub Actions automatically runs linting and tests on the PR.
- Get approval from teammates and merge into `main`.
3. **Deployment**:
- GitHub Actions automatically deploys the API to Render and the Streamlit app to its hosting service.
- Ensure the API and app are functioning as expected.

---

#### Documentation:
- Document the entire CI/CD pipeline in your repository's `README.md` or a dedicated `CI_CD.md` file.
- Include instructions for running linting and tests locally.
- Provide links to the deployed API and Streamlit app.