The Problem
Organizations building real-time personalized recommenders lack structured, hands-on resources that cover the full ML lifecycle—from feature engineering and model training to MLOps deployment and LLM-enhanced ranking. Most tutorials address isolated components (e.g., model architecture or batch pipelines) without integrating feature stores, online serving, and interactive UIs into a cohesive system.
What This Does
This repository provides a complete, end-to-end course for architecting a real-time personalized recommender system for H&M fashion articles. The recsys/ directory implements a Feature/Training/Inference (FTI) architecture across three phases: feature engineering (recsys/features/) using Polars, model training (recsys/training/) with two-tower neural networks (recsys/training/twotower.py and recsys/training/ranking.py), and online inference (recsys/inference/) with ranking predictors and transformers. MLOps infrastructure leverages Hopsworks AI Lakehouse via recsys/hopsworksintegration/, including feature store integration (recsys/hopsworksintegration/featurestore.py), two-tower serving (recsys/hopsworksintegration/twotowerserving.py), and LLM ranking serving (recsys/hopsworksintegration/llmrankingserving.py). The Streamlit UI (streamlitapp.py) and recsys/ui/ modules enable interaction tracking and feature group updates. A four-stage recommender design is visualized in assets/4stagerecommenderarchitecture.png and embedded in the notebooks (notebooks/1fpcomputingfeatures.ipynb through notebooks/7ipcreatingdeploymentsllmranking.ipynb).
How To Use It
Setup: Install dependencies via uv sync or pip install -e . from the repository root. The pyproject.toml at the root and recsys/hopsworksintegration/llmranker/requirements.txt define the dependency surface. A .env.example file is provided—copy it to .env and populate Hopsworks project credentials, API keys, and the Streamlit deployment configuration.
Configuration: Environment variables are managed through .env. The Makefile includes targets for common operations (e.g., make train, make serve). GitHub Actions workflows in .github/workflows/mlpipelines.yaml orchestrate offline pipeline execution and can be manually triggered via the setup action at .github/actions/setup/action.yaml.
Running it: Launch the Streamlit interface with streamlit run streamlitapp.py. The deployed recommender scales to zero in 0-cost mode; the first interaction after a cold start requires 1–2 minutes to provision an instance. The live demo is available at https://decodingml-hands-on-personalized-recommender.streamlit.app/.
Real-World Use
A typical workflow begins with feature computation using recsys/features/articles.py and recsys/features/interaction.py to generate user and item interaction matrices via Polars. The two-tower model (recsys/training/twotower.py) trains user and item embeddings stored in the Hopsworks feature store. During inference, recsys/inference/rankingpredictor.py serves real-time rankings, while recsys/inference/llmrankingpredictor.py applies LLM-based re-ranking for personalization. The recsys/ui/interactiontracker.py captures clickstream data to refresh feature groups incrementally.
Code Health & Issues
Medium – No test files detected: Repository-wide untested code paths; no evidence of a test directory or pytest configuration, risking undetected regressions during feature or model changes. Low – Dependencies declared without a lockfile: pyproject.toml lists dependencies but no uv.lock or requirements.txt lock ensures reproducible builds across environments. High – Possible secrets committed to the repo: assets/githubactions_secrets.png suggests credentials may have been checked in; rotate any keys referenced in .env.example and avoid committing secret values.
The Bottom Line
This repo delivers a rare, holistic walkthrough of a real-time recommender system—from data ingestion and feature engineering to KServe deployment and LLM-enhanced ranking—backed by functional notebooks and a deployed Streamlit demo. It is well-suited for individual learners, instructors, or small teams wanting to operationalize an FTI architecture with Hopsworks; larger organizations may need to add testing, lockfile hygiene, and secret management guardrails before production use.