Show article scores in RSS digest (#2)

Co-authored-by: julienoh <7431012+julienoh@users.noreply.github.com>

Author: julienoh

CHANGELOG.md

@@ -7,6 +7,13 @@ Le projet suit un versionnement informel (pas de tags pour l'instant).
 
 ## [Non publié]
 
+### Added
+- **2026-08-08** — Ajout dans chaque catégorie du digest RSS d'une annexe
+  déterministe **Évaluation du scoring**. Chaque article retenu (score 3 à 5)
+  affiche son score initial de phase 1 et la raison du modèle de filtrage.
+  Le rendu est produit par Python, sans appel LLM supplémentaire, et couvert
+  par des tests unitaires.
+
 ### Fixed
 - **2026-08-07** — Suppression du trou de collecte nocturne : les horaires
   7h/13h/19h créent un intervalle de 12h incompatible avec l'ancienne fenêtre

MEMORY.md

@@ -4,7 +4,7 @@
 > Se lit au début de chaque nouvelle conversation pour reprendre le contexte.
 > Se met à jour à la fin de chaque session productive.
 
-**Dernière mise à jour** : 2026-08-07
+**Dernière mise à jour** : 2026-08-08
 
 ---
 
@@ -15,6 +15,10 @@ le 2026-04-19. Tourne 3x/jour via GitHub Actions, synthétise avec Claude
 Haiku (scoring) + Sonnet (synthèse), servi par GitHub Pages, consommé
 dans Reeder iOS.
 
+**2026-08-08** — Les articles retenus affichent désormais dans le digest leur
+score initial (3 à 5) et la raison du filtrage. L'annexe est rendue par Python
+après la synthèse afin de garantir l'association score/article sans appel LLM.
+
 **2026-08-07** — Garde-fous critiques de collecte et de coût : la fenêtre
 repart du dernier run réussi au lieu d'un lookback fixe, avec 60 min de
 chevauchement. Les candidats sont triés par fraîcheur puis plafonnés à
@@ -78,6 +82,11 @@ documentait 3 déclencheurs mais le workflow n'en avait que 2.
 - **2026-08-07** — Plafonds appliqués avant le scoring LLM : 50 articles par
   source et 200 par run, avec priorité aux articles datés les plus récents
 
+### Observabilité du scoring
+
+- **2026-08-08** — Score + raison visibles pour chaque article retenu dans le RSS
+  → rendu déterministe depuis `score_phase1`, sans confier l'association au LLM
+
 ### Licence et ouverture
 
 - **2026-04-21** — Licence MIT (vs Apache, AGPL, pas de licence)

README.md

@@ -56,7 +56,10 @@ digest.py  ←─── cron 3x/jour (GitHub Actions)
     ├── 7. PHASE 3 — Synthèse (LLM de synthèse, 1 appel par catégorie OPML)
     │       Markdown éditorial : 1-2 phrases par sujet, regroupement thématique
     │
-    └── 8. Génère le RSS puis avance last_success.json après succès
+    ├── 8. Annexe de scoring déterministe (Python, aucun appel LLM)
+    │       Pour chaque article retenu : score phase 1 (3-5) + raison
+    │
+    └── 9. Génère output/digest.xml puis avance last_success.json après succès
             │
             ├──► git commit → main (seen.json + last_success.json + digest.xml)
             ├──► audit détaillé → artefact Actions, rétention 30 jours
@@ -94,7 +97,8 @@ OPML (catégories → feeds)
                                 LLM de synthèse (par catégorie)
                                 input : articles dédupliqués
                                 output : Markdown avec puces et liens
-                                      └─► feedgen → digest.xml (RSS 2.0)
+                                      └─► annexe Python score + raison/article
+                                            └─► feedgen → digest.xml (RSS 2.0)
                                             └─► 1 item RSS par run
 ```
 
@@ -151,12 +155,14 @@ veille/
 │   ├── audit-summary.md      # Synthèse compteurs par run, 30 derniers jours
 │   └── audit-errors.md       # Erreurs survenues par run, 30 derniers jours
 ├── tests/
-│   └── test_collection.py    # Tests fenêtre de collecte + plafonds de coût
+│   ├── test_collection.py    # Tests fenêtre de collecte + plafonds de coût
+│   └── test_score_details.py # Tests du rendu de scoring visible
 ├── collection.py             # Fenêtre dynamique, priorité temporelle, plafonds
 ├── digest.py                 # Pipeline complet (load, fetch, score, dédup, synth, audit)
 ├── audit.py                  # Logs Markdown des 3 phases (cf. §6 Logs d'audit)
 ├── llm_client.py             # Mini-abstraction LLM (route anthropic/ vs openrouter/)
 ├── prompt.py                 # Prompts LLM isolés (itérables indépendamment du code)
+├── score_details.py          # Annexe score + raison, rendue sans LLM
 ├── requirements.txt          # feedparser, feedgen, anthropic, openai, httpx
 ├── seen.json                 # Hashes SHA1 des articles traités (fenêtre 14 jours)
 ├── last_success.json         # Timestamp du dernier run terminé avec succès
@@ -181,6 +187,11 @@ applique les plafonds par source puis par run. Ce module est testé sans réseau
 risquer de casser la logique Python, et l'historique git des changements
 de prompts est séparé de celui du code.
 
+**`score_details.py`** : produit l'annexe visible d'évaluation du scoring à
+partir des données de phase 1. Le rendu est déterministe : aucun modèle ne peut
+oublier un score ou l'associer au mauvais article. Seuls les articles retenus
+(scores 3 à 5) apparaissent, avec leur raison.
+
 **`sources.opml`** : source de vérité des feeds. Le script le lit à chaque run —
 modifier l'OPML suffit pour ajouter/retirer une source. Même fichier utilisable
 dans Reeder pour abonnement direct.
@@ -455,6 +466,20 @@ trouver la nouvelle URL.
 - La phase 2 est intra-catégorie : les doublons cross-catégorie ne sont pas
   détectés actuellement (cf. roadmap).
 
+### Évaluer la pertinence du scoring dans le digest
+
+Chaque catégorie du bulletin se termine par **Évaluation du scoring**. Pour
+chaque article réellement transmis à la synthèse, cette annexe affiche :
+
+```text
+5/5 — Titre — Source. Raison : justification du modèle de filtrage
+```
+
+Le score affiché est `score_phase1`, c'est-à-dire la note initiale avant la
+déduplication. Les scores 1 et 2 restent exclus du digest et sont consultables
+dans `logs/audit-details.md`. L'annexe est construite par Python après la
+synthèse ; elle ne dépend donc pas du respect d'une consigne par le LLM.
+
 ### Mettre à jour les modèles LLM
 
 Quand le fournisseur publie de nouveaux modèles, mettre à jour dans `digest.py` :
@@ -620,6 +645,14 @@ finale (regroupement thématique, ton éditorial, Markdown structuré) demande
 plus de nuance, donc un modèle plus capable. Séparer les deux rôles permet de
 choisir le bon modèle pour chaque tâche, sans surdimensionner le filtrage.
 
+### Pourquoi les scores sont-ils rendus par Python ?
+
+Le LLM de synthèse peut regrouper plusieurs articles sous une même puce. Lui
+demander d'insérer les scores créerait un risque d'omission ou de mauvaise
+association. L'annexe est donc générée depuis les objets d'articles après la
+phase 2 : chaque titre, lien, score initial et raison restent liés sans appel
+supplémentaire et peuvent être couverts par des tests unitaires.
+
 ### Pourquoi un seul item RSS par run ?
 
 Le digest est un **bulletin éditorial**, pas un agrégateur. Un item par run

digest.py

@@ -44,6 +44,7 @@
 from collection import compute_collection_cutoff, limit_articles
 from llm_client import complete
 from prompt import SCORING_PROMPT, DEDUP_PROMPT, SYNTHESIS_PROMPT
+from score_details import render_score_details
 
 # ---- Configuration -----------------------------------------------------------
 # Tous les paramètres ajustables du pipeline sont regroupés ici.
@@ -610,7 +611,8 @@ def main():
         print(f"  synthèse {cat} ({len(items)} articles)")
         result = synthesize(cat, items)
         if result:
-            sections[cat] = result
+            score_details = render_score_details(items)
+            sections[cat] = f"{result.rstrip()}\n\n{score_details}" if score_details else result
 
     if sections:
         write_rss(sections)

score_details.py

@@ -0,0 +1,54 @@
+"""Rendu déterministe des scores visibles dans le bulletin RSS."""
+
+from __future__ import annotations
+
+
+VISIBLE_SCORES = {3, 4, 5}
+
+
+def render_score_details(articles: list[dict]) -> str:
+    """Retourne une annexe Markdown score + raison pour les articles retenus.
+
+    Le rendu est produit par Python, sans nouvel appel LLM, afin de garantir
+    que chaque score reste associé au bon article. ``score_phase1`` est la
+    référence : il représente la note initiale avant une éventuelle déduplication.
+    """
+    visible = []
+    for position, article in enumerate(articles):
+        score = _article_score(article)
+        if score in VISIBLE_SCORES:
+            visible.append((position, score, article))
+
+    if not visible:
+        return ""
+
+    visible.sort(key=lambda item: (-item[1], item[0]))
+    lines = ["**Évaluation du scoring**", ""]
+    for _, score, article in visible:
+        title = _escape_markdown(article.get("title", "Sans titre"))
+        source = _escape_markdown(article.get("source", "Source inconnue"))
+        reason = _escape_markdown(article.get("raison", ""))
+        link = str(article.get("link", "")).strip()
+        title_md = f"[{title}]({link})" if link.startswith(("https://", "http://")) else title
+
+        line = f"- **{score}/5** — {title_md} — {source}"
+        if reason:
+            line += f". Raison : {reason}"
+        lines.append(line)
+
+    return "\n".join(lines)
+
+
+def _article_score(article: dict) -> int | None:
+    value = article.get("score_phase1", article.get("score"))
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _escape_markdown(value: object) -> str:
+    text = " ".join(str(value or "").split())
+    for char in ("\\", "*", "_", "[", "]"):
+        text = text.replace(char, "\\" + char)
+    return text

tests/test_score_details.py

@@ -0,0 +1,61 @@
+import unittest
+
+from score_details import render_score_details
+
+
+class ScoreDetailsTests(unittest.TestCase):
+    def test_renders_only_scores_three_to_five_with_reasons(self):
+        articles = [
+            self.article("Score 3", 3, "utile"),
+            self.article("Score 1", 1, "bruit"),
+            self.article("Score 5", 5, "critique"),
+            self.article("Score 4", 4, "important"),
+            self.article("Score 2", 2, "marginal"),
+        ]
+
+        rendered = render_score_details(articles)
+
+        self.assertIn("**5/5**", rendered)
+        self.assertIn("**4/5**", rendered)
+        self.assertIn("**3/5**", rendered)
+        self.assertIn("Raison : critique", rendered)
+        self.assertIn("Raison : important", rendered)
+        self.assertIn("Raison : utile", rendered)
+        self.assertNotIn("Score 1", rendered)
+        self.assertNotIn("Score 2", rendered)
+        self.assertLess(rendered.index("Score 5"), rendered.index("Score 4"))
+        self.assertLess(rendered.index("Score 4"), rendered.index("Score 3"))
+
+    def test_uses_original_phase_one_score(self):
+        article = self.article("Article dédupliqué", 2, "raison finale")
+        article["score_phase1"] = 5
+
+        rendered = render_score_details([article])
+
+        self.assertIn("**5/5**", rendered)
+        self.assertNotIn("**2/5**", rendered)
+
+    def test_escapes_untrusted_text_and_ignores_non_http_links(self):
+        article = self.article("Titre [test]", 4, "raison *forte*")
+        article["link"] = "javascript:alert(1)"
+
+        rendered = render_score_details([article])
+
+        self.assertIn(r"Titre \[test\]", rendered)
+        self.assertIn(r"raison \*forte\*", rendered)
+        self.assertNotIn("javascript:", rendered)
+
+    @staticmethod
+    def article(title, score, reason):
+        return {
+            "title": title,
+            "source": "Source",
+            "link": "https://example.com/article",
+            "score": score,
+            "score_phase1": score,
+            "raison": reason,
+        }
+
+
+if __name__ == "__main__":
+    unittest.main()