feat: NeuMF

[parinaB]

What changed

Replaced the existing TruncatedSVD-based collaborative filtering with a Neural Matrix Factorization (NeuMF) model implemented in PyTorch.
Added a fallback mechanism to keep SVD as default when USE_NEUMF=false, ensuring full backward compatibility.

Updated evaluation pipeline to support both SVD and NeuMF seamlessly.

Why

SVD is a linear matrix factorization method and cannot capture complex, non-linear user–item relationships or implicit feedback patterns.

NeuMF improves this by:

• Learning non-linear interactions via MLP
• Combining GMF + MLP towers
• Supporting end-to-end training with binary cross entropy
• Using negative sampling for implicit feedback

This leads to better recommendation quality and more expressive user modeling.

How to test

# Example:
pip install -r requirements.txt
python evaluation.py
# (Optional) Enable NeuMF
export USE_NEUMF=true
python evaluation.py

Screenshots (if UI change)

Checklist

• [✓] I have read the CONTRIBUTING.md
• [✓] My code follows PEP8 style (flake8 .)
• [✓] I have tested my changes locally
• [✓] I have added/updated tests where applicable
• [✓] I can explain every line of code I've written
• [✓] I have NOT used AI-generated code without understanding and attributing it

Related issue

Closes #126

AI assistance disclosure

• I did not use AI assistance for this PR
• [✓] I used AI assistance for: evaluation pipeline fixes and PR structuring

[github-actions]

🎉 Welcome to Hybrid Recommender, @parinaB! This is your first contribution here!

PR Description Checklist:
✅ What changed section
✅ Why section
✅ How to test section
✅ Related issue linked

✅ PR description looks complete!

What happens next:

1. A mentor (@leonagoel) will review your changes
2. CI checks must pass (lint + smoke test)
3. Once approved, labels will be added for GSSoC points
4. PR will be merged after approval

⏱️ Please respond to review comments within 48 hours.

📖 Make sure your changes follow our CONTRIBUTING.md

[github-actions]

🎉 Welcome to Hybrid Recommender, @parinaB!

Thank you for submitting your first PR! Here's what happens next:

1. 🔍 A mentor (@leonagoel) will review your changes
2. ✅ CI checks must pass (lint + smoke test)
3. 🏷️ Labels will be added for GSSoC points after approval
4. 🔀 PR will be merged once approved

⏱️ Please respond to review comments within 48 hours.

📖 Make sure your changes follow our CONTRIBUTING.md

Happy contributing! 🚀

[parinaB]

@leonagoel could u kindly review...

[github-actions]

⚠️ Main branch was just updated!

PR #157 ("Feature/price range filter") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #156 ("feat: add meta title, description and OG tags (closes #102)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #155 ("Add debounced auto-save for user preferences") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #151 ("Feature/add wishlist system") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #178 ("Refactor architecture, add semantic NLP embeddings, dynamic hybrid ra…") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #149 ("docs: add troubleshooting and setup verification guide") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #150 ("feat: add product comparison feature with side by side table (#108)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[leonagoel]

✅ Marked as approved but cannot auto-merge — this PR has conflicts.

Please resolve conflicts and push again, then re-add the status:approved label.

[leonagoel]

Thanks for the PR, @parinaB! NeuMF (Neural Matrix Factorization) is a valuable addition to the recommender system. However there are conflicts in 7 files that need to be resolved first.

Conflicting files:

• collaborative_model.py
• content_model.py
• data_adapter.py
• data_preprocessing.py
• dataset_manager.py
• evaluation.py
• hybrid_model.py

This looks like your branch may be significantly behind main. Please do a full rebase:

git fetch origin
git rebase origin/main
# resolve conflicts file by file
git add collaborative_model.py content_model.py data_adapter.py data_preprocessing.py dataset_manager.py evaluation.py hybrid_model.py
git rebase --continue
git push --force-with-lease

Since there are many conflicts, you may find it easier to click "Resolve conflicts" on GitHub for each file individually.

Once resolved and CI passes, this will be auto-merged. Please address within 48 hours.

[github-actions]

⚠️ Main branch was just updated!

PR #183 ("fix: resolve undefined llm_explain parameter crash (#173)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #141 ("Fix formatting in README installation instructions") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[parinaB]

@leonagoel resolved.. please take a look .. thank you

[github-actions]

⚠️ Main branch was just updated!

PR #142 ("feat(async): add Celery-Redis async recommendation pipeline") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #184 ("Fix search API to return actual database products instead of mock items.") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #185 ("Add empty state message with icon for no recommendations") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #186 ("docs: add README badges for contributers, PRs, GSSoC and licence (#17)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #187 ("feat: add favicon to the web application") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #188 ("Add SVG illustration and clear button for empty search results") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #189 ("fix: enable text-based fallback explanations when LLM is offline (#174)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #190 ("feat: add favicon to HybridRec frontend (#37)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #198 ("Fix NameError in recommend endpoint title handling") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #201 ("fix: improve upload validation security") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1624 ("feat: Celery task progress tracking and webhook notifications (Issue #1577)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1625 ("feat: GNN RGCN integration scaffold with knowledge-graph dataset path (Issue #1576)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1626 ("feat: add A/B testing framework for recommendation algorithm variants…") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1632 ("Add a title * Fix/popularity boost score cap Add a description Comment") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1040 ("fixed: Duplicate PR template files cause Git conflicts on case-insens…") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1527 ("fix(model): fix IndentationError in select_bandit_arm and unindented bandit arm weight assignment") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1633 ("fix: Duplicate results-processing loop removed from search_items(#1631)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1640 ("fix: resolve hybrid_model merge conflicts and add explanation string") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1641 ("Fix/svd memory leak") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1642 ("Feature/evaluation dashboard") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1643 ("Feature/streamlit tfidf config") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1644 ("Fix/strict csrf origin validation") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1645 ("Feature/svd online updating") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1647 ("fix: add title query param endpoint to resolve HTTP 422 (#1075)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1648 ("fix(federated): prevent regularization decay in aggregate_updates") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1650 ("fix: remove duplicate code block in hybrid_model.py causing Indentati…") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1653 ("fix: remove duplicate /api/recommend route") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1654 ("build: add faiss dependency for two-tower retrieval") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1655 ("fix: enforce stronger signup password validation") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1660 ("security: reject unissued csrf tokens") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1661 ("feat: add KNN-based user collaborative filtering (Issue #51)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1665 ("fix: add missing faiss-cpu dependency to requirements.txt ") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1515 ("feat: harden realtime recommendation WebSocket flow") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1668 ("fix(ci): resolve syntax and indentation errors breaking upstream main") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1669 ("feat(rate-limit): implement Token Bucket algorithm for rate-limiting middleware for search API protection") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1675 ("fix: IDOR vulnerability on purchases endpoints (#294)") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1676 ("docs: add required Supabase initialization steps to Docker setup guide") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1677 ("fix: implement background cache cleanup to prevent OOM") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1678 ("feat: add recommendation feedback loop support") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀

[github-actions]

⚠️ Main branch was just updated!

PR #1679 ("fix: use gin_trgm_ops for GIN trigram index") was just merged into main.

Please rebase your branch to avoid conflicts:

git fetch origin
git rebase origin/main
git push --force-with-lease

Keeping your branch up to date prevents merge conflicts. 🚀