---
title: rc-ranked
emoji: 🎬
colorFrom: gray
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
short_description: MovieLens recommender (MF / Two-Tower) served via FastAPI
---

# rc-ranked — Dockerized recommender API

A FastAPI service wrapping the [`rc-ranked`](https://github.com/onlymehdi/rc-ranked) MovieLens recommender (Matrix Factorization + Two-Tower, PyTorch). Built to run on Hugging Face Spaces (Docker SDK, CPU Basic).

## Bundled checkpoints

Both trained checkpoints ship with the image (Git LFS) under `checkpoints/`:

| File | Model | Trained on | Best HR@10 | NDCG@10 |
|------|-------|------------|-----------:|--------:|
| `mf_best.pt` | Matrix Factorization | ml-32m | 0.0852 | 0.0419 |
| `two_tower_best.pt` | Two-Tower (id + side feats) | ml-32m | 0.0615 | 0.0298 |

Default served model is **MF** (the stronger one per the held-out test split).

## Configuration (optional env vars / Space variables)

| Name | Default | Purpose |
|------|---------|---------|
| `ACTIVE_MODEL` | `mf` | Switch between `mf` and `two_tower`. The matching checkpoint is loaded automatically. |
| `CHECKPOINT_PATH` | derived | Override the checkpoint file path explicitly. |
| `CONFIG_PATH` | `config/default.yaml` | YAML config inside the container. |
| `GDRIVE_CHECKPOINT_ID` | unset | Optional Drive fallback used only if the resolved local path is missing. |
| `ALLOWED_ORIGINS` | `*` | Comma-separated CORS origins. |

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Service info + endpoint list |
| GET | `/health` | Liveness probe |
| GET | `/info` | Model + vocab metadata (active model, dataset, num_users, num_items) |
| GET | `/recommend/{user_id}?k=10&filter_seen=true` | Top-K recommendations for a raw MovieLens user id. Falls back to popularity for unknown users. |
| GET | `/recommend/cold?k=10` | Globally popular items (cold-start path). |

Example response:
```json
{
  "user_id": 1,
  "k": 5,
  "filter_seen": true,
  "strategy": "model",
  "items": [
    {"rank": 1, "movie_id": 318,  "title": "Shawshank Redemption, The (1994)", "score": 8.42},
    {"rank": 2, "movie_id": 858,  "title": "Godfather, The (1972)",            "score": 8.31}
  ]
}
```

## Cold start time

On first boot the container will:

1. Download the MovieLens ml-32m archive from grouplens.org (~250 MB).
2. Preprocess + leave-one-out split (a few minutes on CPU Basic).

The checkpoint itself is already inside the image, so model load is instant. Subsequent restarts on the same container reuse the cached dataset.