swirl/mf-wine-recommender

MF Wine Recommender

Biased Matrix Factorization model for wine recommendations, trained on real user-wine ratings from the Swirl platform.

Model Details

Property	Value
Architecture	Biased MF with optional side-feature projection
Latent dimension	16
Side features	Yes (768-dim wine embeddings)
Parameters	29,710
Users	75
Wines	194
Best epoch	5
Val RMSE	1.1956
Val MAE	0.7387912273406982
Version	mf-v1

Scoring formula

r_hat = mu + b_u + b_i + p_u · q_i  [+ side_feature_projection]

Two-stage scoring for production:

• Stage 1: MF dot-product score (collaborative filtering)
• Stage 2: Cosine similarity between user preference centroid and wine embedding (content-based, weight = 0.2)

Usage

from matrix_factorization.inference import MFScorer

scorer = MFScorer.load("model_mf_v3.pt")
score = scorer.score(user_id="...", wine_id="...")

Training

uv run export_rating_matrix.py --embeddings -o data/ratings.pt
uv run train_mf.py --data data/ratings.pt --side-features --epochs 50 -o model_mf_v1.pt