🎬 RecomSystems_NMFV3 — NeuMF Movie Recommender

A complete recommendation-system project built on MovieLens 100K, combining classic collaborative filtering baselines with Neural Collaborative Filtering (NeuMF) and a Flask-powered full-stack demo app.

---

✨ Highlights

• End-to-end recommender pipeline for implicit feedback ranking
• Multiple model families for comparison:
  • Popularity baseline
  • ItemKNN
  • GMF / Matrix Factorization
  • Pure MLP
  • NeuMF variants (+ BPR and reranking experiments)
• Evaluation using ranking metrics:
  • NDCG@K
  • Hit Rate (HR@K)
• Demo-ready web app with:
  • User-wise recommendations
  • Strategy switching (hybrid, gmf, mlp, popularity)
  • Diversity / novelty controls
  • Movie title search

---

📁 Repository Structure

• CF_NeuMF_v3.ipynb — main experimentation notebook
• cf_neumf_v3.py — exported notebook pipeline (training + evaluation code)
• results.txt, resultsV4.txt — saved experiment result tables
• Project_final/
  • ml-100k/ — MovieLens 100K files
  • checkpoints/ — pretrained model checkpoints (gmf.pt, mlp.pt, metadata)
  • CF_NeuMF_v3_checkpoint.ipynb — checkpoint-focused notebook snapshot
  • neumf_fullstack/ — Flask API + frontend dashboard

---

🧠 Model & Evaluation Overview

The project uses an implicit-feedback setup (positive interactions from ratings thresholding), then evaluates models with leave-one-out ranking using fixed negatives per user.

Included experiments compare recommendation quality across classic and neural methods, with optional reranking strategies (genre-based and LLM-assisted) in the research workflow.

---

📊 Sample Results (from repository outputs)

From resultsV4.txt (NDCG@10):

• NeuMF baseline: 0.3394
• ItemKNN: 0.3386
• Pure MLP: 0.3332
• Popularity baseline: 0.2374

These show strong gains over the popularity baseline for learned models.

---

🚀 Run the Full-Stack Demo

From Project_final/neumf_fullstack:

pip install -r requirements.txt
python app.py

Then open:

• http://127.0.0.1:8000/

API Endpoints

• GET /api/health
• GET /api/stats
• GET /api/users?limit=200
• GET /api/users/random
• GET /api/search?q=toy&limit=12
• GET /api/recommend?user_id=0&k=10&strategy=hybrid

If checkpoints are missing, the service automatically falls back to popularity-based recommendations.

---

🛠️ Tech Stack

• Python
• PyTorch
• Pandas / NumPy
• Flask
• HTML/CSS/JavaScript
• MovieLens 100K dataset

---

✅ Best Entry Points

• For experiments: open CF_NeuMF_v3.ipynb
• For deployment demo: run Project_final/neumf_fullstack/app.py
• For final metrics snapshot: read resultsV4.txt