| --- |
| 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. |
|
|
