blob: eb847654b2263ad969fb921c8e9143507ef67367 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
|
# 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).
|
