Feed log and training

Every post served is logged with the signals it was ranked on; what the reader does next labels it; ml/train_ranker.py learns from the labels and the API picks up the model within a minute.

The loop

1. ServeA Following, favourites or For You page is served and each post written to FeedLog with its signals and position.
2. ReadThe front end reports impressions, dwell and opens; likes, comments and Not interested come through their own endpoints.
3. LabelEach report marks the viewer's rows for that post served in the last hour.
4. Trainmake train fits one model per outcome on the last 7 days and checks it against the formula.
5. PublishONNX files and latest.json go to blob storage.
6. RankThe API loads the new model within a minute; For You's ranker says model:<version>.

The feed log

FeedLog (Postgres) has one row per post served to one viewer in one feed:

• A post served to the same viewer in the same feed within 30 minutes isn’t logged again, so refreshing doesn’t flood the log.
• An action labels the viewer’s rows for that post served in the last hour (the attribution window).
• Opening, liking, commenting, Not interested and Show more all imply Seen. Not interested and Show more cancel each other: the latest press wins.
• Dwell adds up across reports.
• Logging the signals as served keeps training and serving on the same numbers.

What the model learns

ml/train_ranker.py reads the rows marked Seen from the last 7 days (--days) and refuses to train on fewer than 2,000 (--min-rows). A post served but never reported as seen says nothing either way, so it’s left out. Each row gets five labels, one LightGBM classifier each (a “head”):

• Position is an input, so the model learns how much the top spot itself adds; the API scores every post at position 0 so a post isn’t rewarded for having been near the top before.
• Exploration rows count three times (EXPLORED_WEIGHT): they’re the only data not shaped by the ranker’s own choices.
• Evaluation is on the newest 20% of rows (a time split, as the model will be used on the future): AUC for each head, and NDCG@10 and AUC of the combined value against the formula, per feed session.
• Export: each head to ONNX, checked against LightGBM’s own predictions, written as models/ranker/<version>-<head>.onnx, then models/ranker/latest.json last, so the API never points at a model that isn’t there yet. latest.json lists the heads, the weights, the metrics, signal importances, and the source.

Whose behaviour

--source picks the rows:

The admin dashboard labels a model trained on synthetic data, and it shouldn’t be served to real members.

Publishing elsewhere

cd ml
uv run train_ranker.py                            # to ../.blobs (local blob storage)
uv run train_ranker.py --s3-bucket my-bucket      # to S3, where a server's API reads it
uv run train_ranker.py --s3-endpoint http://localhost:4566 --s3-bucket feedfabric-media   # LocalStack
DATABASE_URL=postgresql://… uv run train_ranker.py

The API’s RankerModel checks models/ranker/latest.json at most once a minute. A model whose signal list differs from the API’s RankingFeatures.Names is refused and the formula is used; ml/train_ranker.py keeps its own copy of that list (FEATURES), so change both together. The same goes for the formula, which the trainer re-implements to compare against.

Why front ends matter here

Every label above except likes and comments comes from what the client reports. A front end that never sends impressions produces no Seen rows, so nothing it serves becomes training data; one that never sends dwell produces no long reads or skips. Reading signals shows how to report them correctly.