Copyright: Vadim Bulavintsev (GPL v2)

MeritRank Python Web service

This repository contains an ASGI and a Dockerfile for a web service calculating and serving MeritRank scores.

HTTP API usage (ASGI)

The basic usage is covered in the test suite. To run the FastAPI-based ASGI implementation:

poetry install
poetry shell
uvicorn meritrank_service.asgi:create_meritrank_app --reload --factory

If all runs fine, you should be able to point your browser to http://127.0.0.1:8000/docs, see the autogenerated Swagger documentation and experiment with the API in-browser.

Loading edges at service startup

To load edges from Postgres database on init, add the database URL to the environment variable POSTGRES_DB_URL. If the variable is non-null, the ASGI will try to connect to the database and load all the contents of the edges table. The table is expected to be in the format src(str), dst(str), amount(float)

Example:

env POSTGRES_DB_URL="postgres://postgres:12345678@localhost:54321/postgres" uvicorn meritrank_service.asgi:create_meritrank_app --reload --factory

Gravity-specific configuration

Ego warmup

To enable warmup of ego calculation for every "user" node in the DB, set environment variable EGO_WARMUP="True". The warmup is performed asynchronously at startup, and only if POSTGRES_DB_URL was properly set. During the warmup the service is going to be much less responsive than usual.

Zero node heartbeat

It is possible to build a global ranking (not Sybil-toleran, obviously), and create a "Zero node" that will point with its edges to the top N nodes. This can be used to create a "boostrap policy" or a "curated" list of recommendations. To enable zero heartbeat, set environment variable ZERO_NODE to the name of the node that should be used as the Zero. If set, this will schedule a periodic recalculation of the global ranking and reestablishment of the Zero node. By default, the recalculation period is 1 hour.

The environment variables controlling the period of the recalculation and the limit of top nodes to add are ZERO_HEARTBEAT_PERIOD (in seconds) and ZERO_TOP_NODES_LIMIT respectively (100 by default).

Zero recalulation is scheduled to perform synchronously after the warmup (if enabled). If the warmup is disabled, Zero will be recalculated immediately after the service start.

Subscribing to updates from Postgres

Meritrank-service can subscribe to receive edges data from Postgres in real-time by using Postgres NOTIFY-LISTEN mechanism. To use it, you first have to add some NOTIFY triggers to Postgres:

Example SQL trigger for notification

CREATE OR REPLACE FUNCTION notify_edge_change() RETURNS trigger AS $$
BEGIN
    PERFORM pg_notify('edges', json_build_object('src', NEW.subject, 'dest', NEW.object, 'weight', NEW.amount)::text);
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER my_trigger
AFTER INSERT OR UPDATE ON my_table
FOR EACH ROW EXECUTE FUNCTION notify_edge_change();

Meritrank-service expects the data to be in JSON format, the same as used in add_edge REST call. To enable the listen feature, run the service with POSTGRES_EDGES_CHANNEL envirionment variable set to the corresponding Postgres NOTIFY channel, e.g. POSTGRES_EDGES_CHANNEL=edges. (And don't forget to set POSTGRES_DB_URL too, of course)

Logging

You can enable logging by setting the environment variable MERITRANK_DEBUG_LEVEL to the desirable Python logging level, e.g. MERITRANK_DEBUG_LEVEL=INFO. By default, the error level is set to ERROR, meaning that only errors are logged.

Docker

To build and run the docker container:

sudo docker build --no-cache -t meritrank  .
docker run -d -p 127.0.0.1:8888:8000 meritrank