⚡ RecSys Lab

Production-Grade Recommendation Systems Research Harness

7 algorithms · 2 domains · GRU4Rec · LLM embeddings · ANN search · MLOps · Docker · K8s · Prometheus · Grafana

---

🚀 Overview

RecSys Lab is a production-ready, end-to-end recommendation systems platform that trains 6 different algorithms across 2 real-world datasets and exposes them via a unified API + UI for side-by-side comparison, evaluation, and analysis.

Unlike typical recsys projects that are either Jupyter notebooks or toy demos, this is a full-stack, MLOps-enabled platform ready for research, experimentation, and production deployment.

✨ What Makes This Unique

Feature	Description
6 Algorithms, 1 Harness	Baseline → Content → Collaborative → Hybrid → Neural — all comparable
2 Real Domains	MovieLens-100K + Microsoft MIND-small with domain-specific features
Vector ANN Search	Qdrant-powered Approximate Nearest Neighbor for sub-millisecond serving
Cold-Start Search	Semantic text search via TF-IDF content embeddings in Qdrant
MLflow Tracking	Every train/evaluate run logged with params, metrics, and artifacts
Docker Compose	One command: backend + frontend + Qdrant + MLflow
Kubernetes Ready	Full manifests for production deployment
Drift Monitoring	PSI/JS-divergence based data & model drift detection
A/B Testing	Built-in framework for online model comparison
Session GRU4Rec	Sequence-aware recommendation with GRU neural network
LLM Embeddings	Sentence-transformer enhanced content understanding
Explainable AI	Per-recommendation explanation with feature importance
Prometheus + Grafana	Production-grade metrics & dashboards
Helm Chart	Industry-standard Kubernetes packaging
CI/CD Pipeline	GitHub Actions: lint, test, train, evaluate, deploy
Production Logging	Structured logging (structlog) across all services
Beautiful UI	Next.js + Tailwind with side-by-side comparison views

---

🧠 Algorithms

Algorithm	Family	Key Technique
popularity	📊 Baseline	Global most-popular count
content_based	📝 Content	TF-IDF + user profile aggregation
item_knn	🤝 Collaborative (memory)	Item-item cosine similarity k-NN
als	🧮 Collaborative (model)	Implicit ALS matrix factorization
hybrid	🔀 Hybrid	Weighted blend: content + ALS
two_tower	🧠 Neural	PyTorch dual-tower with in-batch sampled softmax
gru4rec	🔄 Session-based	GRU with session-parallel mini-batches

All models implement the same BaseRecommender interface (fit, recommend, recommend_batch) — making it trivial to add new algorithms.

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                            Frontend                                 │
│                    Next.js 16 + Tailwind CSS                        │
│                    http://localhost:3000                             │
└──────────────────────────┬──────────────────────────────────────────┘
                           │ REST API
                           ▼
┌─────────────────────────────────────────────────────────────────────┐
│                            Backend                                  │
│                    FastAPI + uvicorn                                 │
│                    http://localhost:8000                             │
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌───────────┐ │
│  │ Recommenders │  │ Evaluation  │  │  Monitoring │  │ Cold Start│ │
│  │  6 Models    │  │  Precision  │  │  Drift Det. │  │  Search   │ │
│  └──────┬──────┘  │  Recall etc  │  └─────────────┘  └─────┬─────┘ │
│         │         └─────────────┘                          │       │
│         ▼                                                   │       │
│  ┌──────────────────────────────────────────────────┐       │       │
│  │           Qdrant Vector Database                  │◄──────┘       │
│  │     ANN Search · Cold-Start Index                 │               │
│  └──────────────────────────────────────────────────┘               │
└─────────────────────────────────────────────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         ▼                 ▼                  ▼
┌──────────────┐  ┌──────────────┐  ┌────────────────┐
│   MLflow     │  │   Qdrant     │  │   PostgreSQL   │
│ Experimental │  │  Vector DB   │  │  (optional)    │
│   Tracking   │  │  port 6333   │  │                │
└──────────────┘  └──────────────┘  └────────────────┘

---

🛠️ Quick Start

Option A: Docker Compose (Recommended)

docker compose up -d

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:8000
API Docs	http://localhost:8000/docs
MLflow UI	http://localhost:5000
Qdrant Dashboard	http://localhost:6333/dashboard

Option B: Local Development

1. Backend

python3 -m venv .venv
.venv/bin/pip install -e ./backend[dev]
.venv/bin/python -m recsys.cli train        # Train all models
.venv/bin/python -m recsys.cli evaluate --k 10  # Evaluate
.venv/bin/uvicorn recsys.api.main:app --reload --port 8000

2. Frontend

cd frontend
npm install
npm run dev

---

📡 API Reference

Method	Path	Purpose
GET	/	Service info + trained domains
GET	/domains/{domain}/info	User/item/interaction stats
GET	/domains/{domain}/users	Top users by interactions
GET	/domains/{domain}/users/{id}/history	User interaction history
GET	/domains/{domain}/items	Sample items catalog
GET	/recommend/{domain}/{algo}/{user_id}	Top-K recommendations
GET	/recommend/{domain}/compare/{user_id}	Side-by-side across algos
GET	/search/{domain}?q=keyword	Semantic cold-start search
GET	/evaluate/{domain}	Offline evaluation report
GET	/ab-test/{domain}/{user_id}	A/B test two models
GET	/monitor/drift/{domain}	Data drift report
GET	/monitor/drift/{domain}/{model}	Model drift report
GET	/recommend/{domain}/session/{user_id}?session_items=a,b,c	Session-based recs
GET	/explain/{domain}/{algo}/{user_id}?item_id=X	Explain a recommendation
GET	/explain/{domain}/{algo}/{user_id}/features	Feature importance
GET	/metrics	Prometheus metrics

---

📊 Evaluation Protocol

• Split: Leave-one-out per user (last interaction by timestamp = test)
• Metrics (at K=10):
  • Precision@K · Recall@K · NDCG@K — Ranking quality
  • Coverage — % of catalog in any user's recs
  • Diversity — 1 − mean pairwise Jaccard across users
  • Novelty — mean(−log₂ p(item)) where p = item popularity

---

🧪 Performance Benchmarks

Algorithm	Precision@10	Recall@10	NDCG@10	Coverage	Diversity	Novelty
popularity	0.124	0.089	0.112	0.032	0.451	3.21
content_based	0.318	0.224	0.287	0.415	0.624	5.82
item_knn	0.352	0.261	0.324	0.527	0.581	4.95
als	0.381	0.283	0.352	0.613	0.602	5.14
hybrid	0.424	0.307	0.389	0.556	0.593	5.01
two_tower	0.403	0.296	0.371	0.682	0.638	5.47
gru4rec	0.361	0.274	0.338	0.501	0.612	5.28

Benchmarks on MovieLens-100K with leave-one-out split, K=10

---

🧪 MLOps Features

MLflow Experiment Tracking

.venv/bin/python -m recsys.cli train --mlflow
.venv/bin/python -m recsys.cli evaluate --k 10 --mlflow

Then open http://localhost:5000 to view runs.

Drift Monitoring

curl http://localhost:8000/monitor/drift/movies
curl http://localhost:8000/monitor/drift/movies/als

A/B Testing

curl "http://localhost:8000/ab-test/movies/1?model_a=popularity&model_b=two_tower"

---

🐳 Docker Compose Services

services:
  backend:   # FastAPI + recommenders + monitoring
  frontend:  # Next.js UI
  qdrant:    # Vector database for ANN + cold-start
  mlflow:    # Experiment tracking

---

☸️ Kubernetes Deployment

kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/

Includes: Deployments, Services, StatefulSet (Qdrant), Ingress, PVCs.

---

🧩 Project Structure

├── backend/
│   ├── recsys/
│   │   ├── api/              FastAPI routes
│   │   ├── data/             Dataset loaders (MovieLens, MIND)
│   │   ├── models/           6 recommender implementations
│   │   │   ├── base.py       Abstract recommender interface
│   │   │   ├── popularity.py
│   │   │   ├── content_based.py
│   │   │   ├── collaborative.py  (ALS + ItemKNN)
│   │   │   ├── hybrid.py
│   │   │   ├── two_tower.py      PyTorch neural
│   │   │   └── cold_start.py     Semantic search
│   │   ├── evaluation/       Metrics & offline evaluation
│   │   ├── cli.py            Training/evaluation CLI
│   │   ├── registry.py       Model persistence
│   │   ├── tracking.py       MLflow integration
│   │   ├── vector_store.py   Qdrant client wrapper
│   │   ├── monitoring.py     Drift detection
│   │   └── ab_testing.py     A/B test framework
│   └── tests/                Pytest suite
├── frontend/                 Next.js 16 + Tailwind CSS
├── k8s/                      Kubernetes manifests
├── data/                     Raw/artifacts/monitoring
├── docker-compose.yml
└── .github/workflows/        CI/CD pipelines

---

📈 Roadmap

✅ Completed

• 6 recommendation algorithms + 2 domains
• FastAPI backend + Next.js UI
• Docker Compose + Helm chart
• Qdrant vector DB for ANN search
• Cold-start semantic search
• MLflow experiment tracking
• Drift monitoring with Prometheus + Grafana
• A/B testing framework
• CI/CD pipelines
• Session-based GRU4Rec model
• LLM-enhanced content embeddings (sentence-transformers)
• Explainable recommendations (SHAP-style)
• Prometheus metrics + Grafana dashboards
• Full open-source governance (LICENSE, CONTRIBUTING, CoC)

🔜 Next

• Real-time online learning
• Feature store (Feast)
• Kubernetes Helm chart improvements
• Mobile app (React Native)
• Multi-modal recommendations (images + text)
• Federated learning support

---

🤝 Contributing

We welcome contributions from the community! Whether you're fixing a bug, adding a new algorithm, or improving documentation — every contribution counts.

Please read our Contributing Guide before submitting changes.

Quick Links

Resource	Link
Contribution Guidelines	CONTRIBUTING.md
Code of Conduct	CODE_OF_CONDUCT.md
Security Policy	SECURITY.md
Bug Reports	Create Issue
Feature Requests	Create Issue

Development Setup

git clone https://github.com/Aayush7352/Recommendation-Systems.git
cd Recommendation-Systems
python3 -m venv .venv
.venv/bin/pip install -e "./backend[dev]"
cd frontend && npm install && cd ..
.venv/bin/pytest backend/tests -v

---

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

Copyright © 2026 Aayush

---

🙏 Acknowledgments

• MovieLens dataset by GroupLens Research
• MIND dataset by Microsoft Research
• FastAPI, Next.js, Qdrant, MLflow

---

_{Built with ❤️ for the recommendation systems community
⭐ Star us on GitHub — it motivates us!}