docs/reference/text-view.md

TextView — première vue canonique

Sprint A14-S14 du rewrite ciblé livre TextView, la première vue d'évaluation canonique. Elle répond à la question patrimoniale la plus fréquente : "quel pipeline produit le meilleur texte final ?"

Cas d'usage central BnF

Une bibliothèque numérique veut comparer 3 pipelines hétérogènes sur le même corpus :

1. Tesseract → texte brut (RAW_TEXT)
2. OCR + LLM + remapping ALTO → ALTO XML enrichi (ALTO_XML)
3. VLM avec sortie markdown structurée → CANONICAL_DOCUMENT

Sans TextView, comparer ces 3 pipelines est trompeur : ils ne produisent pas le même type d'artefact. Avec TextView, chaque sortie est projetée vers du texte plat avant calcul de CER/WER, et le rapport documente explicitement ce que la vue ignore (géométrie, structure de blocs, ordre de lecture, IDs, formatage).

API

from picarones.evaluation.views import build_text_view

# Vue canonique avec valeurs par défaut
view = build_text_view()

# Vue spécialisée (par exemple : OCR seul, sans ALTO/PAGE)
from picarones.domain import ArtifactType
view_ocr_only = build_text_view(
    candidate_types=frozenset({
        ArtifactType.RAW_TEXT,
        ArtifactType.CORRECTED_TEXT,
    }),
    metric_names=("cer", "wer"),
    normalization_profile="medieval_french",
)

Types acceptés (par défaut)

Type	Projection	Justification
RAW_TEXT	identité	déjà du texte
CORRECTED_TEXT	identité	déjà du texte (modifié par un LLM)
ALTO_XML	AltoToText	extraction par ordre de lecture, gestion césure
PAGE_XML	PageToText	extraction depuis <TextEquiv><Unicode>
CANONICAL_DOCUMENT	CanonicalToText	décode markdown, aplatit JSON canonique

Métriques (par défaut)

cer, wer, mer, wil — toutes typées (RAW_TEXT, RAW_TEXT) puisque la comparaison se fait toujours après projection vers texte plat.

Dimensions explicitement ignorées

Le ViewResult propage dans ignored_dimensions les dimensions que cette vue ne mesure pas :

• geometry — coordonnées HPOS/VPOS/WIDTH/HEIGHT des mots
• block_structure — découpage en TextBlock / TextRegion
• reading_order — ordre de lecture spatial
• ids — identifiants stables des éléments
• confidence — scores de confiance par mot
• formatting — gras / italique / titre

Ces dimensions sont éventuellement évaluées par d'autres vues :

• geometry, block_structure, reading_order, ids → AltoView (S15)
• confidence → vue calibration (existante via S5 metrics)

Garde-fou méthodologique

Chaque ViewResult produit par TextView porte un warnings explicite :

Cette vue compare les sorties textuelles finales après projection éventuelle. Les pipelines qui produisent ALTO/PAGE/markdown sont projetés vers du texte plat — leurs structures spatiale et documentaire ne sont PAS évaluées ici. Pour évaluer la qualité ALTO, voir AltoView (S15).

Ce warning sera affiché en tête du bloc TextView dans le rapport HTML (S22) pour signaler à un lecteur exactement la portée de la comparaison.

Exemple de ViewResult

ViewResult(
    view_name="text_final",
    candidate_artifact_id="bnf_doc:vlm:canonical_document",
    ground_truth_artifact_id="bnf_doc:gt:raw_text",
    metric_values={
        "cer": 0.04,
        "wer": 0.12,
        "mer": 0.04,
        "wil": 0.18,
    },
    failed_metrics={},
    projection_report=ProjectionReport(
        source_artifact_id="bnf_doc:vlm:canonical_document",
        source_type=ArtifactType.CANONICAL_DOCUMENT,
        target_type=ArtifactType.RAW_TEXT,
        projector_name="canonical_to_text",
        lossy=True,
        ignored_dimensions=("structure", "formatting", "headers", "links"),
        warnings=("Markdown / JSON canonique projeté en texte plat...",),
    ),
    warnings=(
        "Cette vue compare les sorties textuelles finales...",
        "Markdown / JSON canonique projeté en texte plat...",
    ),
    ignored_dimensions=(
        "geometry", "block_structure", "reading_order", "ids",
        "confidence", "formatting", "structure", "headers", "links",
    ),
)

Limites assumées

• Pas de comparaison fuzzy / search recall — c'est SearchView (S16).
• Pas d'évaluation structurelle ALTO — c'est AltoView (S15).
• CANONICAL_DOCUMENT peut perdre beaucoup de structure ; le warning du ProjectionReport le signale.
• Pas de pondération inter-pipelines — chaque pipeline est évalué indépendamment ; le ranking et l'agrégation sont la responsabilité du caller (typiquement le rapport HTML S22).

Statut

• ✅ Sprint S14 — TextView livré (codé + testé)
• ⏳ Sprint S15 — AltoView (fidélité documentaire)
• ⏳ Sprint S16 — SearchView (recherchabilité fuzzy)
• ⏳ Sprint S17 — intégration runner + RunManifest
• ⏳ Sprint S18 — tests E2E sur le cas BnF central avec 3 pipelines