fluxrec

Personal Miniflux article recommender. Ranks your incoming RSS entries with a title-only classifier trained on the ones you star, and serves the top picks as an RSS feed you subscribe to in Miniflux itself. Read-only toward Miniflux. No deps beyond stdlib + vendored ML core.

Requirements

Miniflux ≥ 2.0.49 (uses the changed_after/published_after entry filters)
Go ≥ 1.25 to build; everything else is stdlib + the vendored core in core/
Training runs wherever you read (export/train); serve runs next to Miniflux and only needs the model file

Commands

fluxrec export     stars + sampled negatives → labels.jsonl   (local)
fluxrec train      labels.jsonl → model.json + report.json    (local)
fluxrec serve      poll, score, RSS at /recommendations.xml   (server)
fluxrec retrostar  model-ranked candidates to star by hand    (cold start)
fluxrec score      debug: stdin titles → stdout scores

Setup

just auth           # prints the two export lines; paste them in your shell
# one-time: retroactively star 50–100 remembered-good entries in Miniflux
# then weekly-ish:
just retrain          # export + train; read report.json (precision@15)
just ship myhost      # scp model.json + restart serve (myhost = ssh alias)
# finally: subscribe your Miniflux to https://server/recommendations.xml

Deploy serve only after a real model exists with an honest precision@15.

Files

labels.jsonl       canonical label store (survives Miniflux deletion)
export_state.json  local incremental cursor
export_run.json    per-run summary (overwritten each export)
model.json         TF-IDF vocab + LR weights (trained locally, shipped to server)
report.json        train's validation report (precision@15 headline metric)
cursor.json        server poll cursor
runs.jsonl         server run log; doubles as the RSS render source

Notes

Serve surfaces: GET /recommendations.xml, GET /api/status, and POST /api/poll (out-of-schedule poll; serialized with scheduled polls, short cooldown, curl -X POST https://server/api/poll).
Never writes to Miniflux. Never needs credentials in the repo.
Training stays on the local PC; the server only scores (low RAM).
Deploy serve only after a train run on enough organic stars shows an honest precision@15 in report.json; tiny validation sets lie.
Server state dir: sudo install -d -o <user> -g <user> ~/fluxrec-data before the first compose up (Docker otherwise creates it as root).