README.md

metadata

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

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