buzz-rss/README.md

buzz-rss — RSS/Atom → Matrix, gefilterd op OV-relevantie

Maubot-plugin nl.eddydevink.rss (fork van xyz.maubot.rss) die nieuwsfeeds pollt en alleen openbaar-vervoer-gerelateerde berichten doorplaatst naar Matrix-rooms (optioneel ook alleen de link naar een WhatsApp-groep).

De filterlogica is bewust vast in code (niet via config) en volgt één businessregel:

Precision boven recall — liever een relevant OV-artikel missen dan één niet-OV-artikel ten onrechte doorlaten. (Gebruikersbesluit 2026-09-10)

Functionaliteit

• Abonneren op feeds per room, met per-feed meldingssjabloon en m.notice-optie.
• Conditional fetch (ETag/Last-Modified) en backoff bij faalende feeds.
• HTML-scrape-modus: bronnen zonder RSS/Atom/JSON worden als pagina gepolled via per-feed feed.scrape_config (zie buzzrss/html_scrape.py; eerste productiefeed: CNV).
• Paywall-uitsluiting (exclude_paywalled) en titel-dedup over feeds (title_dedup_days: zelfde titel van een andere site van dezelfde uitgever = niet dubbel posten).
• Per-run logfile met aantallen (run_log_file).
• WhatsApp-forward: alleen entry.link wordt gepost (vooruit-links, zonder titel), met dedup-check tegen de doelgroep. Uit zolang whatsapp_api/whatsapp_chat_id leeg zijn.

Commando's

Prefix uit config (command_prefix, default rss), eventueel zonder !:

Commando	Aliassen	Werking
!rss subscribe <url>	s, sub	Deze room op een feed abonneren (nieuwe feed wordt direct geïndexeerd)
!rss unsubscribe <feed-id>	u, unsub	Abonnement van deze room opzeggen
!rss subscriptions	ls, list, subs	Abonnementen in deze room + huidige filter
!rss template <feed-id> [sjabloon]	t, tpl	Meldingssjabloon bekijken/wijzigen (variabelen: $title, $link, $summary, $feed_title, …)
!rss notice <feed-id> <true|false>	n	Als m.notice versturen i.p.v. m.text
!rss filter	f, set-filter, show-filter, get-filter	Toont het vaste OV-matchfilter

Bestuurders: admins uit de config, of gebruikers met een powerlevel ≥ dat van het RSS-state-event in die room (default 50 als geen level is ingesteld). Bij een room-tombstone worden abonnementen automatisch naar de vervangende room verplaatst.

Het OV-matchfilter (v1.15)

De volledige classificatie + de werkwijze voor nieuwe woorden staat in buzzrss/bot.py, boven MATCH_FILTER_STRONG — dat blok is leidend bij elke wijziging. Samengevat, in drie regels:

1. staat er een STERK signaal in de TITEL?         -> PLAATSEN
2. score = som unieke groeps-gewichten ≥ 3 én de titel bevat een signaal? -> PLAATSEN
3. anders                                          -> NIET PLAATSEN

• Sterk (2 punten, titel = zelfstandig): vervoerders (NS, ProRail, Arriva, RET, GVB, Qbuzz, Deutsche Bahn, TESO, ...), spoorjargon (spoorstoring, spoorlijn, wisselstoring, treinstoring, ertms, perron, ...), bus-samenstellingen (bushalte, buslijn, busbaan, buschauffeur), tramverkeer/tramlijn, metrolijn, intercity/streekvervoer/veerdienst/buurtbus, conducteur, ov-chipkaart/ovpay, openbaar vervoer, lightrail, 'lijn 12', ICE-frasen, rangeer... én de dienststoring-zin ('sprinters rijden niet', 'metro rijdt niet').
• Ambugue (1 punt; halte/tram/metro/spoorbrug 2) — contextafhankelijk, nooit zelfstandig voldoende, alleen als combinatie: bus, trein, station(s), reiziger/passagier, vervoer(der), sprinter, pendelbus/shuttlebus, dienstregeling, ontsporen, spoor.
• Semantische groepen tellen één keer per artikel: 'bus' + 'buslijn' + 'busvervoer' + 'busstation' is één bus-signaal (bus-samenstelling, bus, station — nooit vier onafhankelijke signalen).
• Geen whitelist, geen blacklist: woordgrenzen en koppelteken-lookbehinds weren structureel 'schoolbus'/'VW-bus', 'stationsstraat'/'stationair'/ 'stationcar'/'treinstraat'/'treinweg'. Bekende false positives blijven geweerd: krant 'De Metro', café 'De Tram', atleet-'sprinter', werkwoord 'brengen', idioom 'goed met elkaar overweg kunnen', 'een wijk opwaarderen', brandweerjargon 'sein brandmeester', figuratief 'weer op de rails', achternaam 'Hermes', buitenlandse veerboot-/busrampen, 'restaurant/woning naast busstation'.

Tests

python3 validate_filter.py

Vaste invarianten + regressie (momenteel 110 cases):

1. gewichten geldig (sterk 2; ambigu in {1, 2}), drempel 3;
2. trefwoorden matchen hooguit één groep per categorie (geen overlappende regexes);
3. semantische varianten ('bus' + 'buslijn' + 'busvervoer', 'station'-reeks) leveren samen één signaal op;
4. regressie: bekende positive/negative/combinatie-cases (precision-first).

Verplicht vóór elke filterwijziging (zie AGENTS.md): het classificatiebeleid in buzzrss/bot.py lezen, validate_filter.py groen, en de compleetheids-audit: OV-gap-scan over de afgewezen artikelen van de specialist-feeds (SpoorPro, Treinreiziger, Mobiliteit; query op entry in PostgreSQL-schema mbp_rss), nieuwe woordkandidaten klasseer je volgens het beleid (minimaal één extra taalmodel; enige stem 'TWIJFEL'/'NIET-OV' ⇒ zwak).

Configuratie

Zie base-config.yaml (wordt in het gebouwde .mbp meegeleverd):

Sleutel	Default	Werking
update_interval	60	Poll-interval in minuten
max_backoff	7200	Maximale backoff (minuten) bij faalende feeds
poll_parallelism_limit	10	Maximaal aantal feeds tegelijk pollend
spam_sleep	2	Pauze tussen berichten bij broadcast (‑1 = parallel)
command_prefix	rss	Commando-prefix
notification_template	New post in $feed_title: [$title]($link)	Standaard meldingssjabloon
run_log_file	/data/buzzrss-runs.log	Per-run samenvattingsregel (leeg = uit)
whatsapp_api / whatsapp_session / whatsapp_chat_id	–	WhatsApp-forward (leeg adapter = uit)
exclude_paywalled	true	Betaalmuur-artikelen overslaan
title_dedup_days	30	Cross-feed titel-dedup-venster (0 = uit)
admins	–	Gebruikers die room-permissies mogen omzeilen

Deploy

Productie draait het geïnstalleerde .mbp (maubot), niet deze werkdirectory — een commit is pas actief na build + upload + restart. Exacte recepten staan in de maubot-beheerskill (skill://maubot) en de Obsidian-vault (Matrix Synapse en MAS.md).

In het kort:

1. mbc build uit de VOLLEDIGE bron (buzzrss/ + maubot.yaml + base-config.yaml —
   zonder base-config.yaml faalt de instance met BaseMissingError)
2. POST /_matrix/maubot/v1/plugins/upload?allow_override=true (admin-login)
3. docker restart matrix-bot-maubot

NOOIT maubot reload gebruiken — die laat zombie-commandhandlers achter (één commando → N antwoorden). Alleen een proces-herstart wist de handlers.

Architectuur in het kort

• Poll-loop → per feed conditional-fetch of HTML-scrape → nieuwe entries (feed_id + id PK-dedup) → cross-feed titel-dedup → _filter_passes → broadcast naar alle subscriptions + optioneel WhatsApp (_send_whatsapp).
• Persistente tabel whatsapp_posted voor WhatsApp-dedup.
• DB: PostgreSQL-schema mbp_rss (feed, entry, subscription, whatsapp_posted); migraties via maubot's UpgradeTable (buzzrss/migrations.py).

Licentie

AGPL-3.0-or-later (upstream: maubot/rss, © Tulir Asokan).