Movie Recommendation System

Abstract

1. Introduction

This project demonstrates an end-to-end movie recommendation workflow using synthetic movie metadata and rating interactions. It includes synthetic data generation, user-level train/test splitting, content-based recommendations, collaborative recommendations, hybrid recommendations, baseline comparisons, alpha-sweep evaluation, visual reports, structured recommendation exports, automated tests, and GitHub Actions CI.

A production-minded movie recommendation workflow for comparing content-based filtering, collaborative filtering, hybrid ranking, simple baselines, alpha-sweep evaluation, and structured recommendation outputs on a synthetic ratings dataset.

The goal is to show how a recommender-system demo can be evaluated honestly, not just how to generate recommendations.

2. Objective

Movie recommendation system with Python. Implements content-based filtering (TF-IDF + cosine similarity), collaborative filtering with matrix factorization (TruncatedSVD), and a hybrid approach. Evaluates with Precision@K, Recall@K, and NDCG. Includes rating distribution plots, top movies, and sample recommendations.

This project demonstrates how Python, Machine Learning can be applied to a real-world AI & Machine Learning problem.

3. Key Features / Modules

• Synthetic movie and ratings generator with deterministic seed behavior
• Content-based filtering using TF-IDF over movie genres
• Collaborative filtering using a sparse user-item matrix and TruncatedSVD
• Corrected SVD reconstruction using scikit-learn's inverse_transform
• Hybrid recommender that blends content and collaborative scores
• Alpha sweep to evaluate the hybrid blend from content-only to collaborative-only
• Baseline comparison against random, popularity, average-rating, Bayesian-average, and positive-count recommenders
• Ranking metrics with Precision@K, Recall@K, and NDCG@K
• Structured recommendation exports with rank, movie ID, title, genres, score, and reason
• Readable text recommendation files for sample users

4. Technology Stack

• scikit-learn
• matplotlib
• unittest
• ruff, black, mypy
• GitHub Actions

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Python 3.8 or later
• pip / virtualenv for dependencies
• VS Code, PyCharm or Jupyter Notebook
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/AmirhosseinHonardoust/Movie-Recommendation-System.git
cd Movie-Recommendation-System

pip install -r requirements.txt

python data/generate_ratings.py --users 800 --movies 1200 --seed 42 --outdir data

python src/build_recommender.py --ratings data/ratings.csv --movies data/movies.csv --outdir outputs --k 10 --alpha 0.6 --seed 42

python -m unittest discover -s tests -v

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Deploy the model as a web app with Streamlit, Flask or FastAPI
• Compare against an additional model and report the metric difference
• Add explainability (SHAP / Grad-CAM)

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. What dataset does the project use and how was it pre-processed?
2. Which algorithm / model architecture is used and why was it chosen over alternatives?
3. How are training and testing data split, and how is overfitting avoided?
4. Which evaluation metrics (accuracy, precision, recall, F1) are reported and what do they mean here?
5. How would you deploy this model for real users?

9. Source Code & License

This project is developed by AmirhosseinHonardoust and published on GitHub under the MIT License. Please follow the license terms and credit the original author when you use or modify this code.