Movie Recommendation System

Content-based recommendations with embeddings and nearest neighbors

---

Quickstart • How It Works • CLI • Evaluation • Roadmap

---

Overview

A script-first recommender that transforms movie metadata and text into dense embeddings, builds a cosine neighbor index, and supports explainable recommendations.

Content-Based TF-IDF + genre + metadata features

Explainable Shared genres + top TF-IDF terms

Fast Retrieval Cosine nearest neighbors

Main Entrypoint

movie_recommender_pipeline.py

load/clean → features → embeddings → NN index → query/explain/export

---

Quickstart

Setup

cd ReccomenderSystem
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Train + Evaluate

python movie_recommender_pipeline.py --data n_movies.csv --train --method svd --evaluate

Query

python movie_recommender_pipeline.py --query "Cobra Kai" --topk 10

Explain + Export

python movie_recommender_pipeline.py --query "Cobra Kai" --topk 10 --explain --export-recs cobra_kai.json

---

How It Works

Stage	What Happens	Why
Clean	Dedupes, normalizes votes/stars, coerces numeric fields	Stable inputs, fewer edge cases
Features	TF-IDF on text + multi-hot genres + bucketed metadata	Semantic + structured signals
Compress	TruncatedSVD + L2 normalize	Sparse-safe dimensionality reduction
Embed	svd (default) or mlp (experimental)	Dense vectors for similarity
Retrieve	NearestNeighbors (cosine) index	Fast top-K recommendations
Explain	Shared genres + shared top TF-IDF terms	Inspectable, demo-friendly

---

Dataset

File	n_movies.csv
Columns	title, year, certificate, duration, genre, rating, description, stars, votes

---

CLI Reference

Training Commands

# SVD (recommended)
python movie_recommender_pipeline.py --data n_movies.csv --train --method svd --evaluate

# MLP (experimental)
python movie_recommender_pipeline.py --data n_movies.csv --train --method mlp --epochs 80 --evaluate

Query Commands

# Basic query
python movie_recommender_pipeline.py --query "Cobra Kai" --topk 10

# With explanations
python movie_recommender_pipeline.py --query "Cobra Kai" --topk 10 --explain

# Export to JSON
python movie_recommender_pipeline.py --query "Cobra Kai" --topk 10 --export-recs cobra_kai.json

Tuning Parameters

Parameter	Description
--embedding-dim 128	Increase representation capacity
--svd-dim 768	Increase compression capacity (slower)
--impute simple|ml|none	Control missing-value behavior
--use-hashing	Include HashingVectorizer features

---

Artifacts

All outputs saved to artifacts/:

File	Description
movies_clean.csv	Cleaned dataset
embeddings.npy	Dense movie embeddings
nn_index.joblib	Nearest neighbors index
tfidf.joblib	TF-IDF vectorizer
svd_pipe.joblib	SVD pipeline
meta.json	Run metadata

MLP-specific artifacts

• mlp_autoencoder.joblib
• mlp_scaler.joblib

---

Evaluation

The pipeline reports:

Metrics	genre_hit_rate@10, genre_jaccard@10
Baselines	Random, Same-genre

Experiment Notes

Finding	Implication
SVD is strongest baseline	Sparse-safe, fast, deterministic, stable neighbors
MLP is experimental	Reconstruction ≠ similarity learning
Coarse metrics can lie	Broad genres (Drama/Comedy) inflate hit-rate
Very high cosines	Space dominated by generic signals

Recommendation: Prefer SVD. Use Jaccard + baselines for honest evaluation.

---

Roadmap

Area	Planned Improvements
Quality	Rerank: cosine + rare-genre overlap + metadata matches (year/duration)
Signals	Genre IDF weighting, split text by field, curated keyword anchors
Retrieval	Optional ANN (hnswlib/faiss) + precomputed top-K cache
Evaluation	MRR/NDCG metrics, coverage/diversity, popularity bias reports
UX	Fuzzy title matching, richer explanations, export formats (JSONL/CSV)

---

Tech Stack

Core	Python, Pandas, NumPy
ML	Scikit-learn (TF-IDF, SVD, NearestNeighbors)
Storage	Joblib, NumPy arrays

---

_{Content-based recommendations with explainability}