🎯 Two-Stage Recommender System

Two-Tower retrieval → FAISS ANN candidate generation → XGBoost LambdaMART re-ranking

Served via FastAPI, demo UI via Streamlit, experiments tracked in MLflow. Docker packaging: deferred — see TODO.md.

---

🧭 Architecture

📥 raw interactions (user, item, rating/implicit signal)
        │
        ▼
🛠️  feature engineering (src/features.py)
        │
        ▼
🗼 Two-Tower model (src/two_tower.py)  ── trained with MLflow logging (src/train_two_tower.py)
        │
   user_emb / item_emb
        │
        ▼
🔎 FAISS index over item_emb (src/build_faiss_index.py)
        │
        ▼
🧺 candidate generation: top-K per user (K=200 default)
        │
        ▼
🪜 XGBoost LambdaMART re-ranker (src/train_ranker.py) — uses candidate + user/item features
        │
        ▼
🏆 final top-N ranked list
        │
        ├── ⚡ FastAPI serving (api/main.py)  → /recommend/{user_id}
        └── 🖥️  Streamlit demo (app/streamlit_app.py)

---

⚙️ Setup

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

---

🔄 Pipeline (run in order)

python src/generate_synthetic_data.py      # or drop your own data in data/
python src/features.py
python src/train_two_tower.py              # logs to MLflow (mlruns/)
python src/build_faiss_index.py
python src/train_ranker.py

---

▶️ Serve

uvicorn api.main:app --reload --port 8000
streamlit run app/streamlit_app.py

---

📊 MLflow UI

mlflow ui --backend-store-uri ./mlruns

---

📁 Project layout

data/                          raw + processed interaction data
src/
  features.py                  feature engineering / encoding
  two_tower.py                 model definition (user tower, item tower)
  train_two_tower.py           training loop + MLflow logging
  build_faiss_index.py         builds FAISS index from item embeddings
  train_ranker.py              XGBoost LambdaMART re-ranker on candidates
  generate_synthetic_data.py   fallback synthetic dataset generator
models/                        saved artifacts (embeddings, faiss index, xgb model)
api/main.py                    FastAPI serving layer
app/streamlit_app.py           Streamlit demo UI

📌 See TODO.md for what's stubbed vs. deferred.