feat(recognition): add a shelf-scanner bench and retune the Qwen adapter

[arenier]

Livre l'étape 6 de #10 — le bench qualité qui départage les deux adapters ShelfScannerPort
sur photos réelles — et retouche l'adapter Qwen + le prompt de scan à la lumière de ce que le
bench a révélé (les étapes 1-5 et 7 sont déjà sur main, PR #39). C'est l'instrumentation de
phase 3 prévue par l'ADR 0005.

Contexte

Le contexte recognition a ses deux adapters (Gemini, Qwen/OpenRouter) derrière le port, l'endpoint
POST /scan et les tests sur réponses enregistrées. Ce qui manquait : de quoi choisir lequel des
deux devient le défaut, mesuré sur de vraies étagères plutôt qu'au jugé. Le bench a servi tout de
suite : il a montré l'adapter Qwen instable et le prompt trop timide, d'où leurs retouches ici.

Modifications

Regroupées par intention :

Projet / lib	Ce que ça établit
libs/shared/text-match	Primitive partagée : normalisation + égalité floue (Levenshtein, seuil 0.85). Sert au scoring et à la déduplication du bench ; la réconciliation s'en resservira.
tools/bench (logique pure)	Vérité terrain YAML (zod), scoring (rappel, précision, exactitude par champ, permutations, hallucination) avec déduplication des détections répétées, coût/usage, sélection de fournisseur, rendu Markdown. Testé en CI, sans réseau.
tools/bench (runner live)	Instrumente fetch (latence, tokens), appelle les deux adapters, écrit le tableau. Jamais en CI — un appel payant par photo.
libs/recognition/infrastructure (prod)	Adapter Qwen : défaut qwen3-vl-235b → qwen2.5-vl-72b ; json_object → json_schema ; max_tokens. Et le prompt de scan partagé rendu exhaustif (balayage systématique de toute l'étagère) — le modèle s'arrêtait trop tôt. Le prompt interdit aussi les champs vides (le domaine rejette tout le payload sur un champ vide) et les doublons.
package.json (racine)	tools/* ajouté au glob des workspaces Yarn. Raccourci yarn bench.
Docs	Protocole (tools/bench/README.md), modèle de vérité terrain, note de décision docs/decisions/0001, carte d'architecture CLAUDE.md.

Le bench est un projet Nx dédié tagué type:app / scope:api. La logique pure reste sans provider.

Tests

yarn check (lint + test + build, 8 projets) vert. Notamment :

 recognition-infrastructure   30 tests   (Qwen : json_schema, max_tokens, modèle par défaut)
 bench                        39 tests   (scoring + déduplication, render, ground-truth, usage, config)

Le prompt est partagé par les deux adapters à dessein (le bench mesure les modèles, pas les
prompts) ; sa qualité se valide par le bench manuel, pas par un test unitaire (ADR 0005). Le runner
live n'a pas de test automatisé (un appel payant par photo) ; exécuté à la main sur le jeu de
référence — voir Points d'attention.

ADR concernés

• ADR 0005 — VLM seul derrière le port ; le
  bench est son instrumentation de phase 3. Le choix de modèle, de format et le prompt sont des
  décisions de niveau inférieur, réversibles par configuration, hors ADR.
• ADR 0002 — frontières hexagonales : seul un
  type:app connaît infrastructure, d'où le tag du bench.
• ADR 0008 — catégories strictes respectées.

Aucune décision structurante sans ADR ; le rejet en bloc d'un payload à champ vide (ADR 0005) est
conservé — c'est le prompt qui empêche les champs vides, pas le validateur qui s'assouplit.

Points d'attention

• Détection : nettement améliorée par le prompt exhaustif, pas encore mesurée. Sur un probe
  jetable (même modèle/prompt), Qwen 72b passe de 7 → 19 livres sur une étagère clairsemée et de
  10 → 42 sur une dense — le modèle s'arrêtait trop tôt, pas un problème d'image ni de tokens
  (complétion loin du plafond). Le prompt agressif rouvrait deux défauts, tous deux traités ici :
  champs vides (le prompt les interdit, sinon le domaine perd toute la photo) et doublons
  (dédupliqués dans le scoring). Reste à confirmer contre la vérité terrain.
• La sélection du fournisseur n'est pas faite : elle exige une vérité terrain vérifiée à la
  main. Tant qu'elle n'est pas saisie, SHELF_SCANNER_PROVIDER reste à stub.
• tools/bench/tsconfig.lib.json épingle lib: es2023 (pour toSorted) — outil Node-26 only.
• La logique de scoring (matching glouton, permutations, hallucinations, déduplication) est à relire
  en premier : tools/bench/src/lib/scoring.ts et ses tests.

Hors scope

• La sélection du gagnant et la bascule du défaut SHELF_SCANNER_PROVIDER (après vérité terrain).
• Le découpage d'image en tuiles (option C, ADR 0005) — le levier suivant pour la détection.
• Toute persistance des photos ou des résultats — la sortie du bench est gitignorée.

Avance #10 (étape 6) — ne clôt pas l'issue : la sélection du fournisseur et la bascule du défaut
restent en attente de la vérité terrain vérifiée à la main.

🤖 Generated with Claude Code

[arenier]

Review · 🔴 À ne pas merger

Réserves — Lint max-lines introduit par le diff, CI rouge (libs/recognition/infrastructure/src/lib/qwen-shelf-scanner.adapter.ts:73) · Logique pure coût/usage non testée (tools/bench/vitest.config.mts:12)

La PR livre l'étape 6 de #10 : le bench qualité qui départage les deux adapters ShelfScannerPort sur photos réelles, plus la lib partagée shared-text-match. Le diff est soigné et bien documenté, et les frontières Nx sont correctes. Mais il embarque aussi un changement du vrai adapter Qwen (modèle par défaut + décodage contraint par schéma) dont les ajouts font franchir la limite max-lines-per-function d'oxlint à deux fonctions — ce qui fait échouer la CI (check). Verdict 🔴 par le code, pas par la CI.

CI rouge sur check (oxlint) — la cause est un défaut du diff, reprise ci-dessous en bloquant.

🔴 Bloquants

• Lint max-lines-per-function introduit par le diff (libs/recognition/infrastructure/src/lib/qwen-shelf-scanner.adapter.ts:73, libs/recognition/infrastructure/src/lib/qwen-shelf-scanner.adapter.spec.ts:94) — l'ajout du bloc response_format: { type: 'json_schema', … } + max_tokens fait passer la méthode privée post à 51 lignes (max 50) ; les nouveaux it poussent une fonction du spec à 61 lignes. yarn oxlint --type-aware s'arrête sur ces deux erreurs (catégories strictes, ADR 0008) → CI check en échec. La description annonce pourtant « yarn check … vert » et « fonctions courtes » : ce n'est plus vrai sur la tête. → Extraire un helper (p. ex. buildRequestBody/buildResponseFormat) pour ramener post sous 50 lignes, et factoriser/scinder le bloc de test concerné.

🟠 À corriger

• Logique pure de usage.ts et config.ts hors périmètre de test (tools/bench/vitest.config.mts:12) — l'include est limité à src/lib/**, ce qui exclut des fonctions pures et sans réseau : estimateCost/readUsage (usage.ts) et mediaTypeOf/providerSpec (config.ts, provider inconnu → throw, formule de coût, parsing des deux schémas d'usage). Ces chiffres alimentent directement la note docs/decisions/0001 qui posera le défaut de prod ; une régression y passerait inaperçue. Le commentaire du vitest.config.mts ne justifie que l'exclusion du runner live (appel payant), pas celle de ces fonctions, testables comme scoring/render/ground-truth. → Déplacer ces fonctions vers src/lib/ (ou élargir l'include à ces fichiers) et ajouter les specs (mapping d'extension, provider inconnu, coût avec/sans reportedCostUsd, les deux formes de payload usage).

💬 Questions

• tools/bench/tsconfig.lib.json:9 (lib: es2023) — déviation du repo (es2022), assumée dans la description et justifiée par toSorted() sur un outil Node-26-only jamais bundlé ailleurs. Pas d'objection.
• Le titre feat(bench): (qui deviendra le sujet du squash sur main) sous-vend le changement de comportement de prod de QwenShelfScannerAdapter (modèle par défaut qwen3-vl-235b → qwen2.5-vl-72b, json_object → json_schema, max_tokens). Ce changement est bien testé (nouveaux it sur réponses enregistrées, ADR 0005) — la remarque porte sur la trace laissée sur main, pas sur le fond.

✍️ Style & altitude

Rien à signaler. Les commentaires portent systématiquement un pourquoi (glouton plutôt qu'assignation optimale, zéro plutôt que NaN, séparation logique pure / réseau, choix du 72B) et non un quoi — exactement ce que demande CLAUDE.md.

Relecture statique : lecture de code + CI (read-only). Ni lint, ni test, ni build lancés — un 🟢 veut dire « rien trouvé en lecture », pas « ça compile ».

---

Generated by Claude Code

[arenier]

Triage de la review du 02/09. Les deux points ont été vérifiés dans le code (le 🔴 reproduit par oxlint --type-aware, le 🟠 par lecture de l'include vitest) : les deux sont fondés. Corrigés dans e353967, yarn check local repassé au vert. PR remise en draft le temps du tour.

Point	Verdict	Traitement
🔴 max-lines-per-function (post 51 · spec 61) → CI check rouge	Fondé	✅ Corrigé e353967
🟠 Logique pure usage.ts/config.ts hors périmètre de test	Fondé	✅ Corrigé e353967
💬 lib: es2023 (déviation es2022)	Constat (sans objection du relecteur)	⛔ Rien à faire
💬 Titre feat(bench): sous-vend le changement de prod Qwen	Fondé	✅ Corrigé (retitré + description rafraîchie)

Vérifications point par point (2)

1. max-lines-per-function — reproduit, puis corrigé

Reproduit sur la tête avant correctif (la cause exacte invoquée, pas la CI seule) :

$ yarn oxlint --type-aware
qwen-shelf-scanner.adapter.ts:73:21  error  max-lines-per-function: `post` has too many lines (51). Max 50.
qwen-shelf-scanner.adapter.spec.ts:94:56  error  max-lines-per-function: function has too many lines (61). Max 50.
exit 1

CI check = failure confirmée côté GitHub. Ma revendication « yarn check vert » n'était donc plus vraie sur la tête — j'avais lancé nx lint (ESLint/frontières) mais pas oxlint --type-aware (qui porte max-lines) après les commits json_schema/max_tokens.

Correctif : post() délègue la construction du corps à une méthode privée requestBody() ; le describe du spec est scindé en deux. Après :

$ yarn oxlint --type-aware   → exit 0
$ yarn check                 → exit 0  (lint + test + build, 8 projets)

2. Logique pure non testée — fondé, comblé

L'include vitest du bench était src/lib/**, ce qui laissait hors CI des fonctions pures qui alimentent les chiffres de docs/decisions/0001 : estimateCost/readUsage (usage.ts), mediaTypeOf/env/requireEnv/selectedProviders (config.ts).

Correctif : include élargi à src/** (un spec est découvert par ce glob, jamais un module source seul — le runner live n'a toujours aucun spec, donc rien de payant en CI) ; readUsage exporté ; deux specs ajoutés :

• usage.spec.ts — estimateCost (coût rapporté / estimé au token / provider inconnu → null / rien consommé → null) et readUsage (les deux formes de payload usage + corps non-JSON).
• config.spec.ts — mediaTypeOf (extensions connues/inconnues), env/requireEnv (trim, absent → throw), selectedProviders (deux défauts + modèles épinglés, override modèle, provider inconnu → throw).

Bench : 22 → 37 tests.

Point non relevé · Ce qui reste ouvert

Point non relevé par la review — la description de la PR était périmée : elle affirmait « Qwen n'a pas pu être mesuré » et le mettait hors scope, alors que depuis, OpenRouter a été rendu joignable, les deux fournisseurs ont été mesurés, et l'adapter Qwen a changé de défaut (235b→72b), de format (json_schema) et gagné un max_tokens. Corrigé : titre → feat(recognition): add a shelf-scanner bench and retune the Qwen adapter, description réécrite.

Ce qui reste ouvert (📌, non traité ici) :

• Détection insuffisante : même Gemini sous-liste ces étagères denses ; le json_schema n'a pas rescapé le 235B. C'est le vrai chantier ouvert par le bench — hors scope de ce triage.
• Sélection du gagnant + bascule du défaut SHELF_SCANNER_PROVIDER : en attente de la vérité terrain vérifiée à la main.

---

Generated by Claude Code