Capstone: a real news recommender
The rest of this book taught the ideas. This capstone assembles them into a single, production-style application you can run, evaluate, track, serve, and put a UI on — the kind of end-to-end project you'd build on the job (or show in a portfolio).
The whole project lives in
code/capstone/. Every snippet in these chapters is{{#include}}'d from that real, runnable code, and every output shown was produced by running it.
What we build: a news recommender
A recommender for news articles — heavy on FIFA/soccer plus general categories (politics, tech, health, finance, …). Given a user's reading history it recommends articles; given a question it answers from the news (RAG); and it handles brand-new users (cold start) gracefully.
The architecture
┌────────────────────── offline ──────────────────────┐
data (MIND schema) │ embed articles → build ANN index │
news.tsv + behaviors │ compute trending (time decay) │
│ │ train stage-2 ranker on click logs │
└───────────────►│ evaluate (recall@k, NDCG, AUC) → log to MLflow │
└──────────────────────────┬───────────────────────────┘
│ model artifact
┌──────────────────────────▼──────── online ───────────┐
React UI ──HTTP──► │ FastAPI: │
(recs, search, ask) │ /recommend = decayed profile → ANN candidates → │
│ logistic ranker → top-k │
│ /search = vector search over articles │
│ /ask = RAG: retrieve + Claude (or offline) │
│ /feedback = online history update │
└──────────────────────────────────────────────────────┘
How it ties the whole series together
| Component | Built on |
|---|---|
| Article embeddings | content-based filtering |
| Time-decayed user profile | baselines + content-based |
| ANN candidate generation | the HNSW & IVF-PQ books |
| Two-stage candidate gen + ranking | neural & two-stage |
| Cold start → trending fallback | cold start |
| Evaluation (recall@k, NDCG, AUC) | metrics |
| RAG assistant | retrieval = vector search (HNSW/IVF-PQ books) |
The tech stack
- Python + NumPy — the recommender, ranker, and retrieval (from scratch).
- MLflow — experiment tracking + model artifact (Chapter 19).
- FastAPI — the serving API (Chapter 21).
- React (Vite) — the UI (Chapter 22).
- Claude (Anthropic API) — RAG generation, with an offline fallback (Chapter 20).
- Docker Compose — one command to run everything (Chapter 23).
Run it in five phases
You can stop after any phase — each works on its own:
Phase 0 setup pip install -r requirements.txt; python scripts/make_sample_data.py
Phase 1 train + track python -m newsreco.train (+ mlflow ui)
Phase 2 serve API uvicorn newsreco.api:app --port 8000
Phase 3 React UI cd frontend && npm install && npm run dev
Phase 4 real RAG export ANTHROPIC_API_KEY=... (else offline mode)
Phase 5 all-in-one docker compose up --build
A note on the dataset
We build on the Microsoft MIND news-recommendation dataset's schema (the standard real benchmark, which naturally includes sports/soccer). To keep the project runnable anywhere, it ships a realistic soccer-heavy sample in the same format; swapping in the full MIND download needs no code changes. Details in the next chapter. 👉