---
license: mit
tags:
  - recommendation
  - matrix-factorization
  - wine
  - pytorch
library_name: pytorch
---

# 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

```python
from matrix_factorization.inference import MFScorer

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

## Training

```bash
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
```