Aller au contenu

ADR-020 — Cascade de classification documentaire (extraction locale d'abord, fallback OCR multi-provider)
Statut Accepted
Date 10/06/2026 (fixes résilience queue d'analyse)
Décideurs Romain BAZIL (owner pipeline d'analyse), Nicolas Léonard
Origine Note Notion « Classification documentaire — décisions du 10 juin 2026 » + PR project-analysis #286

Contexte

La queue d'analyse classe chaque document entrant (compromis, bilans, baux, permis, pièces diverses) avant traitement par les agents. Trois incidents de production (projets EU, SAS KASS, Les jardins d'arvey) ont révélé la fragilité du chemin d'alors : OCR Manus systématique sur les PDF lourds (upload + polling 120 s, timeouts fréquents) et fallback « nom de fichier » dégradé invoqué trop tôt.

Deux constats déclenchent la refonte :

  1. La majorité des PDF du flux sont digitaux — leur texte est déjà encodé dans le fichier ; faire un aller-retour OCR externe dessus est un gaspillage de coût et de latence, et une dépendance réseau inutile sur le chemin nominal.
  2. L'OCR Manus n'est pas le bon outil par défaut sur les PDF scannés — sa mécanique upload/polling timeoute, alors que des alternatives à coût comparable (Mistral OCR via OpenRouter) sont plus robustes et se transmettent par URL.

La classification documentaire est la porte d'entrée de tout le pipeline : un mauvais routage ici se propage à l'aval. Elle mérite donc une cascade explicite et tracée, cohérente avec la doctrine de fiabilité.

Décision

Adopter une cascade de classification documentaire qui privilégie le chemin local et gratuit, et réserve l'OCR externe aux seuls cas où il apporte de la valeur, avec des fallbacks indépendants entre providers.

Routage de la classification documentaire 3 axes : format du fichier · texte extractible en local (seuil 100 caractères) · disponibilité du provider

Document à classifier

Format ?

Image OCR Manus (vision) (inchangé)

Autre (Word, Excel…) OCR Manus si < 10 Mo sinon nom de fichier

PDF Extraction locale pdf-parse gratuite, < 1 s, sans réseau

Texte extrait > 100 car. ?

Oui (PDF digital) Classification du texte par gpt-5.4-mini (via OpenRouter) confiance < 70 et doc < 10 Mo : 2ᵉ opinion OCR Mistral (meilleur des deux) OpenRouter KO : bascule OCR Manus (filet cross-provider, docs < 10 Mo)

Non (PDF scanné) 1. OCR Mistral 3 (mistral-ocr) PDF transmis par URL S3 présignée échec 2. Vision native gpt-5.4-mini (engine native : le modèle lit le PDF) échec 3. Nom de fichier seul confiance plafonnée à 60 → review humaine (HITL)

classification_documentaire_logique

1. EXTRACTION LOCALE D'ABORD
   pdf-parse extrait le texte en local (< 1 s, gratuit, sans réseau).
   → si ≥ 100 caractères trouvés : PDF digital → classification directe du texte.
   → si < 100 caractères : PDF scanné → bascule chaîne OCR (étape 3).

2. MODÈLE DE CLASSIFICATION PAR DÉFAUT
   CLASSIFICATION_MODEL = 'openai/gpt-5.4-mini'  (remplace gpt-4o-mini)
   Surcoût ≈ +5 $/mois pour 100 projets : ratio ×5 mais absolu négligeable.

3. FALLBACK OCR À 3 NIVEAUX (PDF scanné) — chaîne classifyScannedPdf,
   PDF transmis par URL S3 présignée (aucun download/upload serveur, viable 17 Mo+) :
     a. Mistral OCR 3        (mistral-ocr, ~2 $/1000 pages)        — premier choix
     b. Vision native        (gpt-5.4-mini lit le PDF, engine `native` OpenRouter)
                             — fallback INDÉPENDANT de Mistral
     c. Nom de fichier seul  — dernier recours, confiance plafonnée à 60
                             (reste visible en review manuelle)

4. PÉRIMÈTRE PROVIDER
   Mistral OCR : tous les PDF scannés (plus seulement les ≥ 10 Mo) + 2e opinion
                 sur confiance faible (< 70).
   Manus       : images, formats non-PDF (Word/Excel), et filet cross-provider
                 si OpenRouter est en panne sur le path texte.

Explication fonctionnelle — comment on détecte ce qui va chez Manus vs Mistral ?

Le routage ne repose pas sur une règle unique (l'ancien critère « ≥ 10 Mo → Mistral, sinon Manus » est abandonné). Il se décide sur trois axes lus dans l'ordre :

Axe 1 — Format du fichier. Un document non-PDF (image, Word, Excel) sort immédiatement de l'univers OpenRouter : il part chez Manus, qui reste le seul provider capable de les ingérer ici. Un PDF continue vers l'axe 2.

Axe 2 — Texte extractible localement (seuil 100 caractères). pdf-parse tente l'extraction locale : - ≥ 100 caractères → PDF digital : on classe directement le texte avec gpt-5.4-mini. Aucun OCR, ni Mistral ni Manus. C'est le chemin nominal, et c'est le plus fréquent. - < 100 caractères → PDF scanné : pas de texte exploitable, on bascule sur la chaîne OCR → Mistral OCR en premier choix (puis vision native, puis nom de fichier).

Axe 3 — Disponibilité du provider (filet transverse). Indépendamment de l'arbre ci-dessus, si OpenRouter est en panne sur le path texte, Manus reprend la main comme filet cross-provider. C'est le seul cas où un PDF peut repasser par Manus.

À cela s'ajoute un déclencheur de 2e opinion : quand la classification ressort avec une confiance < 70, on demande une seconde lecture — désormais via Mistral OCR (auparavant Manus).

Document entrant
│
├─ Format ≠ PDF (image, Word, Excel) ─────────────────────────► MANUS
│
└─ Format = PDF
   │
   ├─ pdf-parse ≥ 100 car. (digital) ─► classification texte gpt-5.4-mini
   │                                     (ni Mistral ni Manus)
   │
   └─ pdf-parse < 100 car. (scanné) ─► chaîne OCR (URL S3 présignée) :
        1. MISTRAL OCR  →  2. vision native gpt-5.4-mini  →  3. nom de fichier (conf. ≤ 60)

Orthogonal :
  • OpenRouter en panne (path texte)  ──► MANUS (filet cross-provider)
  • confiance < 70                    ──► 2e opinion via MISTRAL OCR

En une phrase : Mistral est le provider OCR par défaut de tout PDF scanné ; Manus n'est plus sollicité que pour ce que Mistral/OpenRouter ne savent pas faire (non-PDF) ou ne peuvent pas faire à l'instant T (panne OpenRouter).

Rationale

Cascade de fiabilité appliquée à la couche extraction

C'est la doctrine ADR-001 déclinée à l'ingestion : chemin pas cher d'abord, externe seulement en fallback, et confiance plafonnée sur le dernier recours pour garder le doute visible en review manuelle (HITL ciblé) plutôt que de laisser une classification fragile passer en silence.

Fallbacks indépendants = triangulation, pas consensus corrélé

Le fallback niveau 2 (vision native gpt-5.4-mini) lit le PDF avec sa propre vision, par un chemin distinct de Mistral OCR. Les deux approches ne partagent pas la même pipeline : si Mistral échoue, le fallback n'hérite pas de la même panne. C'est la triangulation défendue par la doctrine, et l'inverse de l'anti-pattern LIDAR #3 (consensus corrélé).

Less is more sur le chemin nominal

La majorité des PDF étant digitaux, pdf-parse les traite en local, gratuitement, en < 1 s, sans dépendance réseau. L'OCR (2 $/1000 pages + aller-retour) n'apporte de valeur que sur le scanné — même philosophie qu'OpenRouter (engine gratuit pdf-text pour le digital, mistral-ocr pour le raster).

Surcoût modèle négligeable, robustesse prioritaire

Passer de gpt-4o-mini à gpt-5.4-mini multiplie le coût de classification par ~5, mais en absolu cela représente ~+5 $/mois pour 100 projets. Sur les docs scannés, le coût est de toute façon dominé par l'OCR Mistral, identique quel que soit le modèle de classification.

Activer > construire, réduire la dépendance Manus

On bascule vers un provider OCR plus robuste (transmission par URL S3 présignée, viable pour les documents lourds) au lieu de durcir la mécanique upload/polling de Manus. Manus est conservé là où il est seul pertinent, pas comme défaut subi.

Conséquences

Ce qui change

  1. Chemin nominal : les PDF digitaux ne touchent plus l'OCR du tout (classification directe du texte extrait localement).
  2. Provider OCR par défaut : Mistral OCR pour tous les PDF scannés (abandon du seuil ≥ 10 Mo) et pour la 2e opinion < 70.
  3. Ordre de fallback : le « nom de fichier » n'est plus un premier recours mais le dernier, avec confiance plafonnée à 60.
  4. Modèle de classification : constante CLASSIFICATION_MODEL = 'openai/gpt-5.4-mini'.
  5. Rôle de Manus : réduit aux non-PDF (images, Word, Excel) et au filet cross-provider en cas de panne OpenRouter.

Ce qu'il faut faire

  • Surveiller le taux de PDF basculant en OCR (proxy du ratio scanné/digital réel du flux) et le coût OCR associé.
  • Garder la confiance plafonnée (≤ 60 sur nom de fichier) câblée à la review manuelle, pour que le dernier recours reste un signal HITL et pas une décision silencieuse.
  • Documenter la constante CLASSIFICATION_MODEL comme paramètre réglable : sa révision future ne nécessite pas un nouvel ADR (ce n'est pas une décision d'architecture).

Ce qu'il faut éviter

  • Réintroduire l'OCR systématique sur les PDF digitaux : coût + latence + dépendance réseau pour zéro gain.
  • Faire du nom de fichier un recours précoce : c'est le signal le moins fiable, réservé au tout dernier cran et marqué comme tel.
  • Empiler un fallback corrélé (un 2e provider sur la même pipeline qui tomberait en même temps) : conserver l'indépendance Mistral OCR ↔ vision native.

Alternatives écartées

  • OCR Mistral systématique sur tous les PDF (digital inclus) : ferait payer et attendre un aller-retour réseau sur le cas le plus fréquent (PDF digital), alors que pdf-parse le règle en local et gratuitement.
  • Garder Manus comme OCR par défaut sur les PDF scannés : c'est précisément la cause des incidents (timeouts upload/polling 120 s). Mistral via URL présignée est plus robuste sur les documents lourds.
  • Conserver le seuil ≥ 10 Mo pour décider Mistral vs Manus : critère de taille sans rapport avec la qualité d'OCR ; remplacé par un critère fonctionnel (type de fichier + texte extractible + disponibilité provider).
  • Fallback « nom de fichier » en premier recours : ancien comportement dégradé qui produisait des classifications peu fiables sans signal ; relégué en dernier cran avec confiance plafonnée.
  • Un ADR distinct pour le choix du modèle gpt-5.4-mini : écarté — c'est une constante réglable, pas une décision structurante ; pliée ici comme paramètre du chemin nominal.

Verbatims

« Surcoût ≈ +5 $/mois pour 100 projets : ratio ×5 mais absolu négligeable. Sur les docs scannés, le coût est dominé par l'OCR Mistral (identique quel que soit le modèle). » — Note Notion « Classification documentaire », 10/06/2026

« Manus reste utilisé pour : les images, les formats non-PDF (Word/Excel), et comme filet cross-provider si OpenRouter est en panne sur le path texte. » — Note Notion « Classification documentaire », 10/06/2026

Voir aussi

Sources