This repository contains the POPROX recommender code — the end-to-end logic for producing recommendations using article data, user histories and profiles, and trained models.
This repository includes a devcontainer configuration that we recommend using for development and testing of the recommender code. It is not a good solution for running evaluations (see below for non-container setup), but is the easiest and most reliable way to set up your development environment across platforms.
To use the devcontainer, you need:
- VS Code (other editors supporting DevContainer may also work, but this is the best-supported and best-tested).
- Docker (probably also works with Podman or other container CLIs, but we test with Docker).
With those installed, open the repository in VS Code, and it should prompt you to re-open in the dev container; if it does not, open the command palette (Ctrl+Shift+P) and choose “Dev Containers: Rebuild and Reopen in Container”.
On Linux, install the Docker Engine, and add your user to the docker
group so you can create containers without root.
On Windows, install Docker Desktop, Rancher Desktop, or similar.
On MacOS, you can install Docker or Rancher Desktop linked above, or you can use Colima, which we recommend for simplicity and licensing clarity. To install and use Colima:
$ brew install colima docker
$ colima start -m 4It should also be possible to directly use Lima, but we have not tested or documented support for that.
We manage software environments for this repository with uv, and model and
data files with dvc. The uv.lock file provides a locked dependency set
for reproducibly running the recommender code with all dependencies on Linux and
macOS (we use the devcontainer for development support on Windows).
The devcontainer automatically installs the development environment; if you want to manually install it, you can run:
uv sync --extra cpuThe dev container environment already has the environment active.
A few useful commands for the terminal:
-
Run the tests:
$ pytest tests
Note
If you have a CUDA-enabled Linux system, you can use the cuda extra to get
CUDA-enabled PyTorch for POPROX batch inference. To install this, run:
$ uv sync --extra cudaTo get the data and models, there are two steps:
- Obtain the credentials for the S3 bucket and put them in
.env(the environment variablesAWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY) dvc pull
Local endpoint testing requires building and running the Docker image:
$ docker buildx build -t poprox-recommender:test .
$ docker run -d -p 9000:8080 --name=recommender poprox-recommender:testYou can then send a request to the endpoint:
$ python scripts/send-request.py -p 9000Pass the -h option to send-request.py to see command-line options.
The default setup for this package is CPU-only, which works for basic testing
and for deployment, but is very inefficient for evaluation. The current set of
models work on both CUDA (on Linux with NVidia cards) and MPS (macOS on Apple
Silicon). To make use of a GPU, do the following:, run dvc repro under the
eval-cuda or dev-cuda environment (using either pixi run or pixi shell).
Timing information for generating recommendations with the MIND validation set:
| Machine | CPU | GPU | Rec. Time | Rec. Power | Eval Time |
|---|---|---|---|---|---|
| Cruncher | EPYC 7662 (2GHz) | A40 (CUDA) | 45m¹ | 418.5 Wh | 24m |
| Screamer | i9 14900K (3.2GHz) | 4090 (CUDA) | 28m16s² | 14m | |
| Ranger | Apple M2 Pro | - | <20hr³ | 30m³ | |
| Ranger | Apple M2 Pro | M2 (MPS) | <12hr³ |
Footnotes:
- Using 12 worker processes
- Using 8 worker processes
- Estimated based on early progress, not run to completion.
If you are not using the devcontainer, set up pre-commit to make sure that
code formatting rules are applied as you make changes:
pre-commit installIf you update the dependencies in poprox-recommender, or add code that requires
a newer version of poprox-concepts, you need to regenerate the lock file with
pixi update. To update just poprox-concepts, run:
pixi update poprox_conceptsTo update all dependencies, run:
pixi updateThe devcontainer automatically configures several VS Code extensions and
settings; we also provide an extensions.json listing recommended extensions
for this repository.