This documentation provides the necessary information for implementing a recommendation system (“recsystem” for short) compatible with the Renewal competition platform, as well as documentation for the sample implementation in Python which can be extended to implement your own recsystem with a minimal amount of boilerplate code.
Table of Contents
You can implement your recsystem in several ways:
Use the high-level interface of the reference implementation. This allows you to write your recsystem by creating a Python file containing a few functions that follow a pre-defined format. The reference system does the rest of the heavy lifting while you focus on your recommendation algorithm. This is the easiest way to get started. See the Quickstart Guide.
More experienced Python coders who find the high-level interface too limiting may wish to explore the lower-level reference implementation provided by the
renewal_recsystem.RenewalRecsystembase class. This provides a lot of boilerplate functionality such as handling of the WebSocket connection and JSON-RPC details, so you can focus on just the details of your recommendation algorithms. However, it requires more experience with object-oriented programming and asyncio.
You may implement a recsystem completely from scratch, either in Python or any other language, as the protocol for recsystems is based on open standards. The full documentation provides the details needed to do this. Reference implementations in new languages would be a welcome contribution to the project, but may be outside the scope of a single competition (depending on the length of the competition).
A recommendation system can be written in any language: It connects to the Renewal Backend over HTTP(S) and communicates with it using standard web technologies, namely WebSockets using the JSON-RPC protocol.
The Backend also provides a RESTful API against which recsystems can make additional calls for data lookups (e.g. to fetch articles and user histories).
The REST and JSON-RPC interfaces, and all other details of implementing a recsystem are documented in detail in the full documentation.
Prerequisites: Python 3.7 or greater.
Using a Python “virtual environment” to install the package is highly recommended, as this ensures it will be installed in an isolated environment that will not conflict with the rest of your Python installation. See Creating a virtual environment.
To install the
renewal_recsystem package, first clone this git repository:
$ git clone https://gitlri.lri.fr/renewal/recsystems.git $ cd recsystems/
Then from the root of the repository, install it with:
$ pip install .
Alternatively, this can be done in a single command like:
$ pip install git+https://gitlri.lri.fr/renewal/recsystems.git
For installing to do development on the package itself, install in “editable” mode like:
$ pip install -e .
The package is not currently published on a package index like PyPI, but may be in the future.
You can make a quick check that the installation worked by running:
$ python -m renewal_recsystem --help
The following steps are good to check if you plan to do development on this package; if you only intend to use it for implementing your own recsystem it is not necessary to run the tests or build the documentation.
Running the tests¶
To run the tests, first install the test dependencies by changing directories to the root of the repository and running:
$ pip install -e .[tests]
Then simply run the tests with
Building the documentation¶
To build the documentation for this repository, first install the documentation dependencies by changing directories to the root of the repository and running:
$ pip install -e .[docs]
$ cd docs/ $ make html
The HTML docs will be output to
This package also implements the baseline recsystem service used by the renewal backend to provide recommendations as a baseline against which contest participant recsystems can be compared, and which provides backup recommendations when participant recsystems become unreachable.
To run the baseline recsystem, install the package, then run:
$ python -m renewal_recsystem --token=<token> renewal_recsystem.baseline.popularity
$ python -m renewal_recsystem --token=<token> renewal_recsystem.baseline.random
The only required flag is
--token to provide the authentication token
for the recsystem (this is provided by an administrator when registering
this recsystem with the backend). The token is a JSON Web
Token (JWT) and can be provided either directly as a
string, or as the path to a file containing the JWT and nothing else
The baseline takes some other optional command line parameters which can be listed by running:
$ python -m renewal_recsystem --help
The positional parameter is the name of the Python module which implements the recommendation system itself:
random: articles are simply returned at random
popularity: for every batch of articles requested, the articles are returned prioritized by “popularity” as measured by their number of clicks and their overall rating by users
Each command-line flag can also be passed as an environment variable
instead. The associated environment variable is the same as the flag but
all uppercase and prefixed with
RENEWAL_. For example, instead of passing
--token=<token> you can set the environment variable
New recsystems can be implemented by providing your own Python module defining some basic callback functions; see full documentation for more details.
- Quickstart Guide
- Recsystem Interface Documentation
- How Recsystems Work
- Renewal Backend API
- Primer on WebSockets and JSON-RPC