# 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

- 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.