Claude commited on
Commit
dd38857
·
unverified ·
1 Parent(s): 1992441

docs(reference): remove sprint narrative (Phase 2 L3)

Browse files

Couche reference/ : 6 fichiers nettoyés.

views.md (22 mentions → 0) : transformation du tableau « Bloc /
Origine (Sprint X) / Données nécessaires » en « Bloc / Données
nécessaires ». Pour un lecteur actuel, savoir que la métrique CER
existe « depuis le Sprint 2 » n'apporte rien — l'information utile
c'est « disponible toujours ». Le titre H1 « chantier 3 post-Sprint
97 » devient simplement « Vues HTML du rapport ».

text-view.md, alto-view.md, comparing-views.md : intro « Sprint
A14-S14/S15/S16 livre X » → « X est la première/deuxième/troisième
vue canonique ». Section « Statut » avec liste « ✅ Sprint S14
livré → ⏳ Sprint S17/S18 » → liste sans tags sprint, juste l'état
fonctionnel.

normalization-profiles.md : titre « chantier 2 post-Sprint 97 » →
« Profils de calcul ». Annotations « (Sprint XX) » dans la colonne
de description du tableau de profils → contenu fonctionnel.

reproducibility-snapshots.md : 5 mentions sprint en header, dans
les sous-sections « Préparation Sprint A12 » et dans les noms de
tests → suppressions.

Aucun contenu technique modifié : tableaux de métriques, exemples
de code, commandes, tout est identique.

Ratchet : ACTIVE_NARRATIVE_BASELINE 59 → 23 (-36).

docs/reference/alto-view.md CHANGED
@@ -1,12 +1,12 @@
1
  # AltoView — fidélité documentaire ALTO
2
 
3
- Sprint A14-S15 du rewrite ciblé livre `AltoView`, la deuxième vue
4
- canonique. Elle répond à la question : **"quel pipeline produit
5
- le meilleur ALTO exploitable ?"**
6
 
7
  ## Distinct de TextView
8
 
9
- | Aspect | TextView (S14) | AltoView (S15) |
10
  |---|---|---|
11
  | Question | "meilleur texte final ?" | "meilleur ALTO exploitable ?" |
12
  | Types acceptés | RAW_TEXT, CORRECTED_TEXT, ALTO, PAGE, CANONICAL | ALTO_XML uniquement |
@@ -107,7 +107,7 @@ Reportées à des sprints suivants :
107
 
108
  ## Statut
109
 
110
- - ✅ Sprint S15 — `AltoView` livré (3 métriques + pattern d'omission)
111
- - Sprint S16 — `SearchView` (recherchabilité fuzzy)
112
- - ⏳ Sprint S17 — intégration runner + RunManifest
113
- - ⏳ Sprint S18 — tests E2E sur le cas BnF central
 
1
  # AltoView — fidélité documentaire ALTO
2
 
3
+ `AltoView` est la deuxième vue canonique. Elle répond à la
4
+ question : **"quel pipeline produit le meilleur ALTO
5
+ exploitable ?"**
6
 
7
  ## Distinct de TextView
8
 
9
+ | Aspect | TextView | AltoView |
10
  |---|---|---|
11
  | Question | "meilleur texte final ?" | "meilleur ALTO exploitable ?" |
12
  | Types acceptés | RAW_TEXT, CORRECTED_TEXT, ALTO, PAGE, CANONICAL | ALTO_XML uniquement |
 
107
 
108
  ## Statut
109
 
110
+ - ✅ `AltoView` (3 métriques + pattern d'omission)
111
+ - `SearchView` (recherchabilité fuzzy)
112
+ - ⏳ Intégration runner + RunManifest
113
+ - ⏳ Tests E2E sur le cas BnF central
docs/reference/comparing-views.md CHANGED
@@ -1,9 +1,8 @@
1
  # Lire les 3 vues canoniques ensemble
2
 
3
- Sprint A14-S16 livre la troisième vue canonique du rewrite ciblé :
4
- `SearchView`. Avec `TextView` (S14) et `AltoView` (S15), on a
5
- maintenant **trois lentilles complémentaires** pour évaluer un
6
- même pipeline.
7
 
8
  ## Le tableau des 3 vues
9
 
@@ -110,8 +109,8 @@ cette grille de lecture :
110
 
111
  ## Statut
112
 
113
- - ✅ Sprint S14 — `TextView`
114
- - ✅ Sprint S15 — `AltoView`
115
- - ✅ Sprint S16 — `SearchView` + cohérence inter-vues
116
- - ⏳ Sprint S17 — intégration runner + RunManifest
117
- - ⏳ Sprint S18 — tests E2E sur le cas BnF central
 
1
  # Lire les 3 vues canoniques ensemble
2
 
3
+ `TextView`, `AltoView` et `SearchView` forment **trois lentilles
4
+ complémentaires** pour évaluer un même pipeline OCR sur un corpus
5
+ patrimonial.
 
6
 
7
  ## Le tableau des 3 vues
8
 
 
109
 
110
  ## Statut
111
 
112
+ - ✅ `TextView`
113
+ - ✅ `AltoView`
114
+ - ✅ `SearchView` + cohérence inter-vues
115
+ - ⏳ Intégration runner + RunManifest
116
+ - ⏳ Tests E2E sur le cas BnF central
docs/reference/normalization-profiles.md CHANGED
@@ -1,4 +1,4 @@
1
- # Profils de calcul — chantier 2 post-Sprint 97
2
 
3
  Picarones expose **7 profils de calcul** qui modulent les métriques
4
  calculées par le runner selon le use case. Chaque profil active un
@@ -55,10 +55,10 @@ Active les 12 hooks document-level historiques :
55
  | `line_metrics` | 10 | `line_metrics` | Distribution CER + Gini |
56
  | `hallucination` | 10 | `hallucination_metrics` | Détection VLM |
57
  | `calibration` | 42 | `calibration_metrics` | ECE/MCE (si confidences) |
58
- | `philological` | 61 | `philological_metrics` | 6 modules (Sprints 55-60) |
59
- | `searchability` | 86 | `searchability_metrics` | Fuzzy recall (Sprint 84) |
60
- | `numerical_sequences` | 86 | `numerical_sequence_metrics` | Sprint 85 |
61
- | `readability` | 87 | `readability_metrics` | Δ Flesch (Sprint 52) |
62
 
63
  12 agrégateurs corpus-level correspondants remplissent les attributs
64
  `aggregated_*` de chaque `EngineReport`.
 
1
+ # Profils de calcul
2
 
3
  Picarones expose **7 profils de calcul** qui modulent les métriques
4
  calculées par le runner selon le use case. Chaque profil active un
 
55
  | `line_metrics` | 10 | `line_metrics` | Distribution CER + Gini |
56
  | `hallucination` | 10 | `hallucination_metrics` | Détection VLM |
57
  | `calibration` | 42 | `calibration_metrics` | ECE/MCE (si confidences) |
58
+ | `philological` | 61 | `philological_metrics` | 6 modules philologiques |
59
+ | `searchability` | 86 | `searchability_metrics` | Fuzzy recall |
60
+ | `numerical_sequences` | 86 | `numerical_sequence_metrics` | Repérage et alignement de séquences numériques |
61
+ | `readability` | 87 | `readability_metrics` | Δ Flesch |
62
 
63
  12 agrégateurs corpus-level correspondants remplissent les attributs
64
  `aggregated_*` de chaque `EngineReport`.
docs/reference/reproducibility-snapshots.md CHANGED
@@ -1,7 +1,5 @@
1
  # Snapshots de reproductibilité
2
 
3
- > Sprint A8 (item M-12 du plan de remédiation).
4
-
5
  ## Pourquoi des snapshots ?
6
 
7
  Pour qu'un benchmark Picarones soit **citable scientifiquement**, un
@@ -116,7 +114,7 @@ git checkout 17cc5474abc
116
 
117
  ### Étape 2 — Récréer l'environnement Python
118
 
119
- Sprint A8 livre les lock files :
120
 
121
  ```bash
122
  python -m venv .venv && source .venv/bin/activate
@@ -167,7 +165,7 @@ Différences possibles légitimes :
167
  plus tard peut donner d'autres résultats. Le snapshot des prompts
168
  reste utile mais ne reproduit pas le LLM lui-même.
169
 
170
- ## Snapshot et publication scientifique (préparation Sprint A12)
171
 
172
  Pour un papier scientifique, citer Picarones doit indiquer :
173
 
@@ -208,13 +206,13 @@ reproductible (cf. Stodden et al., *Computational reproducibility*).
208
 
209
  ## Tests
210
 
211
- `tests/report/test_reproducibility_snapshots.py` (Sprint 27)
212
  valide que `snapshot_all()` est :
213
 
214
  - déterministe (même input → même bytes en sortie),
215
  - complet (toutes les clés top-level présentes),
216
  - robuste (ne crashe pas si git absent, si pricing.yaml manquant…).
217
 
218
- `tests/test_reproducibility_ops.py` (Sprint A8) ajoute la validation
219
  de la chaîne **lock file + Docker digest + snapshot** comme contrat
220
  opérationnel.
 
1
  # Snapshots de reproductibilité
2
 
 
 
3
  ## Pourquoi des snapshots ?
4
 
5
  Pour qu'un benchmark Picarones soit **citable scientifiquement**, un
 
114
 
115
  ### Étape 2 — Récréer l'environnement Python
116
 
117
+ Picarones livre des lock files :
118
 
119
  ```bash
120
  python -m venv .venv && source .venv/bin/activate
 
165
  plus tard peut donner d'autres résultats. Le snapshot des prompts
166
  reste utile mais ne reproduit pas le LLM lui-même.
167
 
168
+ ## Snapshot et publication scientifique
169
 
170
  Pour un papier scientifique, citer Picarones doit indiquer :
171
 
 
206
 
207
  ## Tests
208
 
209
+ `tests/report/test_reproducibility_snapshots.py`
210
  valide que `snapshot_all()` est :
211
 
212
  - déterministe (même input → même bytes en sortie),
213
  - complet (toutes les clés top-level présentes),
214
  - robuste (ne crashe pas si git absent, si pricing.yaml manquant…).
215
 
216
+ `tests/test_reproducibility_ops.py` ajoute la validation
217
  de la chaîne **lock file + Docker digest + snapshot** comme contrat
218
  opérationnel.
docs/reference/text-view.md CHANGED
@@ -1,9 +1,8 @@
1
  # TextView — première vue canonique
2
 
3
- Sprint A14-S14 du rewrite ciblé livre `TextView`, la première vue
4
- d'évaluation canonique. Elle répond à la question patrimoniale la
5
- plus fréquente : **"quel pipeline produit le meilleur texte
6
- final ?"**
7
 
8
  ## Cas d'usage central BnF
9
 
@@ -137,8 +136,8 @@ ViewResult(
137
 
138
  ## Statut
139
 
140
- - ✅ Sprint S14 — `TextView` livré (codé + testé)
141
- - Sprint S15 — `AltoView` (fidélité documentaire)
142
- - Sprint S16 — `SearchView` (recherchabilité fuzzy)
143
- - ⏳ Sprint S17 — intégration runner + RunManifest
144
- - ⏳ Sprint S18 — tests E2E sur le cas BnF central avec 3 pipelines
 
1
  # TextView — première vue canonique
2
 
3
+ `TextView` est la première vue d'évaluation canonique. Elle répond
4
+ à la question patrimoniale la plus fréquente : **"quel pipeline
5
+ produit le meilleur texte final ?"**
 
6
 
7
  ## Cas d'usage central BnF
8
 
 
136
 
137
  ## Statut
138
 
139
+ - ✅ `TextView` (codé + testé)
140
+ - `AltoView` (fidélité documentaire)
141
+ - `SearchView` (recherchabilité fuzzy)
142
+ - ⏳ Intégration runner + RunManifest
143
+ - ⏳ Tests E2E sur le cas BnF central avec 3 pipelines
docs/reference/views.md CHANGED
@@ -1,8 +1,8 @@
1
- # Vues HTML du rapport — chantier 3 post-Sprint 97
2
 
3
- Le rapport HTML Picarones est composé de **5 vues principales** historiques
4
- (navigables via la nav top) et de **3 nouvelles vues thématiques** (chantier 3)
5
- qui s'affichent comme cartes dans la vue `analyses`.
6
 
7
  Toutes les vues sont **adaptive** : une vue/section ne s'affiche que si elle
8
  a du signal à montrer (au moins une sous-section avec données exploitables).
@@ -33,32 +33,31 @@ pleine largeur, avec un patron commun :
33
  Si `some_html` est `""` (adaptive masking parce qu'aucune donnée), la
34
  carte n'apparaît pas.
35
 
36
- ### Sous-sections historiques (Sprints 5+10+39+42+55-60+86+87+89)
37
-
38
- | Bloc | Origine | Données nécessaires |
39
- |---|---|---|
40
- | Distribution CER | Sprint 2 | toujours |
41
- | Radar profil moteur | Sprint 2 | ≥ 1 moteur |
42
- | CER par document | Sprint 2 | toujours |
43
- | Temps d'exécution | Sprint 2 | durations propagées |
44
- | Qualité image ↔ CER | Sprint 5 | `aggregated_image_quality` |
45
- | Taxonomie | Sprint 5 | `aggregated_taxonomy` |
46
- | Courbes de fiabilité | Sprint 7 | `aggregated_calibration` |
47
- | NER (P/R/F1) | Sprint 41 | `aggregated_ner` (opt-in spaCy) |
48
- | Calibration ECE/MCE | Sprint 43 | `aggregated_calibration` |
49
- | Stratification | Sprint 46 | `script_type` par doc |
50
- | Profil philologique | Sprint 62 | `aggregated_philological` |
51
- | Recherchabilité fuzzy | Sprint 86 | `aggregated_searchability` |
52
- | Séquences numériques | Sprint 86 | `aggregated_numerical_sequences` |
53
- | Lisibilité (Δ Flesch) | Sprint 87 | `aggregated_readability` |
54
- | Spécialisation inter-moteurs | Sprint 89 | ≥ 2 moteurs avec taxonomie |
55
- | Analyse inter-moteurs | Sprint 37 | ≥ 2 moteurs |
56
- | Matrice de corrélation | Sprint 7 | toujours |
57
-
58
- ### Sous-sections du chantier 3 (post-Sprint 97)
59
-
60
- 3 nouvelles vues thématiques composables qui regroupent les **16 renderers
61
- orphelins** identifiés dans l'audit initial :
62
 
63
  #### Vue « Coût et performance » (`build_economics_view_html`)
64
 
@@ -101,8 +100,8 @@ Sous-sections :
101
 
102
  ## Vues spécifiques (rapport autonome)
103
 
104
- Deux vues du chantier 3 ne s'intègrent pas au rapport classique mais
105
- servent à composer des **rapports autonomes** :
106
 
107
  ### Vue « Pipeline composée » (`build_pipeline_view_html`)
108
 
@@ -112,13 +111,12 @@ Utilisée par `picarones pipeline run` (ou par tout outil qui consomme un
112
  `PipelineBenchmarkResult`). Sous-sections :
113
 
114
  - **Résumé pipeline** (`build_pipeline_summary_html` + `build_pipeline_steps_table_html`).
115
- - **DAG visuel** (`pipeline_dag_render.py` Sprint 95) — opt-in.
116
- - **Absorption d'erreur** par jonction (`error_absorption_render.py`
117
- Sprint 94) — opt-in.
118
- - **Comparaison incrémentale** par slot (`incremental_comparison_render.py`
119
- Sprint 96) — opt-in.
120
- - **Audit des modules** contribués (`module_audit_render.py`
121
- Sprint 97) — opt-in.
122
 
123
  ### Vue « Robustesse projetée » (`build_robustness_view_html`)
124
 
@@ -126,8 +124,8 @@ Module : [`picarones/reports/html/views/robustness.py`](../picarones/reports/htm
126
 
127
  Utilisée par le workflow `picarones robustness`. Sous-sections :
128
 
129
- - **Déficit projeté de robustesse** (`robustness_projection_render.py`
130
- Sprint 88).
131
 
132
  ## Convention de rendu partagée
133
 
 
1
+ # Vues HTML du rapport
2
 
3
+ Le rapport HTML Picarones est composé de **5 vues principales** (navigables
4
+ via la nav top) et de **3 vues thématiques** qui s'affichent comme cartes
5
+ dans la vue `analyses`.
6
 
7
  Toutes les vues sont **adaptive** : une vue/section ne s'affiche que si elle
8
  a du signal à montrer (au moins une sous-section avec données exploitables).
 
33
  Si `some_html` est `""` (adaptive masking parce qu'aucune donnée), la
34
  carte n'apparaît pas.
35
 
36
+ ### Sous-sections principales
37
+
38
+ | Bloc | Données nécessaires |
39
+ |---|---|
40
+ | Distribution CER | toujours |
41
+ | Radar profil moteur | ≥ 1 moteur |
42
+ | CER par document | toujours |
43
+ | Temps d'exécution | durations propagées |
44
+ | Qualité image ↔ CER | `aggregated_image_quality` |
45
+ | Taxonomie | `aggregated_taxonomy` |
46
+ | Courbes de fiabilité | `aggregated_calibration` |
47
+ | NER (P/R/F1) | `aggregated_ner` (opt-in spaCy) |
48
+ | Calibration ECE/MCE | `aggregated_calibration` |
49
+ | Stratification | `script_type` par doc |
50
+ | Profil philologique | `aggregated_philological` |
51
+ | Recherchabilité fuzzy | `aggregated_searchability` |
52
+ | Séquences numériques | `aggregated_numerical_sequences` |
53
+ | Lisibilité (Δ Flesch) | `aggregated_readability` |
54
+ | Spécialisation inter-moteurs | ≥ 2 moteurs avec taxonomie |
55
+ | Analyse inter-moteurs | ≥ 2 moteurs |
56
+ | Matrice de corrélation | toujours |
57
+
58
+ ### Vues thématiques composables
59
+
60
+ 3 vues thématiques composables qui regroupent les renderers spécialisés :
 
61
 
62
  #### Vue « Coût et performance » (`build_economics_view_html`)
63
 
 
100
 
101
  ## Vues spécifiques (rapport autonome)
102
 
103
+ Deux vues ne s'intègrent pas au rapport classique mais servent à
104
+ composer des **rapports autonomes** :
105
 
106
  ### Vue « Pipeline composée » (`build_pipeline_view_html`)
107
 
 
111
  `PipelineBenchmarkResult`). Sous-sections :
112
 
113
  - **Résumé pipeline** (`build_pipeline_summary_html` + `build_pipeline_steps_table_html`).
114
+ - **DAG visuel** (`pipeline_dag_render.py`) — opt-in.
115
+ - **Absorption d'erreur** par jonction
116
+ (`error_absorption_render.py`) — opt-in.
117
+ - **Comparaison incrémentale** par slot
118
+ (`incremental_comparison_render.py`) — opt-in.
119
+ - **Audit des modules** contribués (`module_audit_render.py`) — opt-in.
 
120
 
121
  ### Vue « Robustesse projetée » (`build_robustness_view_html`)
122
 
 
124
 
125
  Utilisée par le workflow `picarones robustness`. Sous-sections :
126
 
127
+ - **Déficit projeté de robustesse**
128
+ (`robustness_projection_render.py`).
129
 
130
  ## Convention de rendu partagée
131
 
tests/architecture/test_doc_governance.py CHANGED
@@ -339,7 +339,7 @@ def test_mkdocs_nav_excludes_archive_subdirs() -> None:
339
  #: - quelques fichiers à la racine (README, GOVERNANCE, SECURITY).
340
  #:
341
  #: Cible : 0 (Phase 2 — convergence narrative, lot D9 à prévoir).
342
- ACTIVE_NARRATIVE_BASELINE = 59
343
 
344
 
345
  def test_no_active_doc_contains_sprint_narrative() -> None:
 
339
  #: - quelques fichiers à la racine (README, GOVERNANCE, SECURITY).
340
  #:
341
  #: Cible : 0 (Phase 2 — convergence narrative, lot D9 à prévoir).
342
+ ACTIVE_NARRATIVE_BASELINE = 23
343
 
344
 
345
  def test_no_active_doc_contains_sprint_narrative() -> None: