docs/WORKFLOW.md

Workflow — finalisation du module IA YELY

Organisation recommandée pour arriver à un livrable démontrable : tests de type production, suivi des performances, apprentissage continu, documentation complète, interface web de démo, déploiement.

1. Arborescence cible du dépôt

yely_ai_module/
├── app/                    # code de production (déjà en place)
├── models/                 # modèle(s) sérialisé(s) — voir §3 versioning
├── train/                  # scripts d'entraînement (référence)
├── tests/
│   ├── test_postprocess.py     # ✅ fait
│   ├── test_rules.py           # ✅ fait
│   ├── test_api.py              # ✅ fait (mocké)
│   ├── test_monitoring.py       # ✅ fait (feedback + métriques + endpoints)
│   └── test_integration.py      # à lancer : vrai modèle, vraies images
├── tools/
│   └── check_seen_image.py      # ✅ fait
├── monitoring/                  # ✅ fait — §2
│   ├── metrics.py                 # ✅ agrégation logs/api.log (succès, confiance, blocages)
│   └── feedback.py                 # ✅ collecte + conversion des corrections pompiste
├── docs/                         # ✅ fait — §4
│   ├── WORKFLOW.md                # ce fichier
│   ├── LIMITATIONS.md             # ✅ fait
│   ├── ARCHITECTURE.md            # ✅ fait
│   ├── PREPROCESSING.md           # ✅ fait
│   ├── RECOGNIZER.md              # ✅ fait
│   ├── POSTPROCESS_RULES.md       # ✅ fait
│   ├── API.md                     # ✅ fait
│   └── MONITORING.md              # ✅ fait
├── web/                           # ✅ fait — §5, interface de démo
│   ├── index.html                 # démo /analyze
│   ├── stats.html                 # tableau de bord /metrics + /failures (soutenance)
│   ├── feedback.html              # correction d'une lecture (préremplie depuis stats.html)
│   └── config.js
└── requirements.txt

2. Tests "comme en production"

Objectif : valider le comportement réel, pas seulement la logique unitaire.

1. Test d'intégration avec le vrai modèle (tests/test_integration.py) : envoyer une vraie photo à recognize_screen (pas de mock), vérifier que la réponse a la bonne forme et un temps de réponse mesuré.
2. Test API bout-en-bout : lancer uvicorn, envoyer une requête HTTP réelle via httpx/curl, sur 3-5 photos couvrant les scénarios du cahier des charges (§14) : nette/cohérente, floue, incohérente, montant seul, litres seuls.
3. Test de charge léger : mesurer le temps de réponse sur 10 requêtes séquentielles (le modèle doit rester chargé en mémoire entre les requêtes — vérifier qu'il n'y a pas de rechargement).
4. Rapport de test (§15 du cahier des charges) : générer un tableau photo → attendu → obtenu → écart, à partir des images du dossier Images datasetdiversifié/ (celles non utilisées à l'entraînement).

3. Suivi des performances + apprentissage continu

Suivi (monitoring/)

• Chaque appel à /analyze log déjà la requête/réponse dans logs/api.log. À ajouter : un identifiant de version du modèle (model_version) dans chaque entrée, pour pouvoir comparer les performances entre versions.
• monitoring/metrics.py : script qui parcourt logs/api.log et calcule périodiquement : taux de succès, distribution des confidence_score, taux de blocage par cause (floue/incohérence/confiance).

Apprentissage continu (boucle de feedback)

Le principe : chaque photo traitée par l'API est déjà sauvegardée (photos/<uuid>.jpg). Il manque la boucle qui transforme ces photos en nouvelles données d'entraînement :

1. Endpoint de correction (POST /feedback) : le pompiste (ou un contrôle a posteriori côté YELY) envoie transaction_id + les valeurs réellement correctes. Stocké dans monitoring/feedback.jsonl.
2. Script de conversion (monitoring/feedback.py) : transforme les entrées corrigées en nouvelles entrées annotations.json (même format que l'annotation manuelle), en réutilisant photos/<uuid>.jpg comme image source.
3. Ré-entraînement périodique : relancer split_lines.py → prepare_doctr_dataset.py → finetune_doctr.py quand un nombre suffisant de nouvelles corrections est accumulé (ex. tous les 50). Important (retenu de cette session) : ne jamais modifier le dataset pendant qu'un entraînement tourne (lecture disque à la volée) ; toujours nettoyer dataset_lines//dataset_doctr/ avant de régénérer (déjà corrigé).
4. Versioning des modèles : chaque nouveau modèle entraîné va dans models/v<N>/, avec son propre history.json. Le modèle "actif" utilisé par l'API est un lien/chemin configurable (CRNN_MODEL_PATH en variable d'environnement), pas une réécriture du fichier précédent — pour pouvoir revenir en arrière si une nouvelle version est pire.

4. Documentation (docs/)

Un fichier par aspect, cible = qu'un lecteur qui n'a pas suivi le développement comprenne le rôle et les choix de chaque module :

• ARCHITECTURE.md : schéma du pipeline complet (image → écran → lignes → CRNN → postprocess → rules → réponse), et pourquoi ce découpage.
• PREPROCESSING.md : détection d'écran, découpage en lignes, limites connues (cas où la détection choisit la mauvaise zone — voir l'incident du bandeau de marque confondu avec l'écran).
• RECOGNIZER.md : choix du CRNN, format d'entrée/sortie, le bug resize corrigé et pourquoi c'était important.
• POSTPROCESS_RULES.md : normalisation numérique, règle de priorité fuel_price configuré > lu à l'écran, moteur de règles de blocage.
• API.md : contrat de l'endpoint, exemples de requêtes/réponses.
• MONITORING.md : comment lire les logs, comment fonctionne la boucle de feedback.
• LIMITATIONS.md : déjà fait — diversité du dataset, précision actuelle.

5. Interface web de démo

Objectif : une page simple, présentable en soutenance, qui appelle l'API et affiche le résultat de façon lisible pour un non-développeur (le formulaire technique test_api_form.html existant sert de base, mais mérite une version "présentation" séparée : moins de champs bruts, plus visuelle).

Contenu minimal :

• Upload/prise de photo (accepte l'appareil photo sur mobile via capture="environment").
• Choix du prix du litre (pré-rempli, modifiable).
• Affichage : bannière succès/bloqué, valeurs détectées, calculées, statut de cohérence — pas le JSON brut par défaut (accessible en option).
• Appel vers l'URL de l'API configurée (variable d'environnement au build).

6. Déploiement

Frontend (web/) → Netlify : parfaitement adapté (fichiers statiques, pas de build nécessaire), pas de souci particulier.

API IA → PAS d'hébergement serverless classique (Vercel, Netlify Functions...). Point d'attention important avant d'aller plus loin : ce type d'hébergement limite la taille du build (souvent ~250 Mo décompressés) et le temps d'exécution par requête. Cette API embarque PyTorch + doctr + OpenCV, qui dépassent déjà largement cette taille à eux seuls, et l'inférence CRNN prend actuellement 60-100+ secondes par image (bien au-delà des temps d'exécution autorisés, même sur les plans payants). Déployer tel quel sur ce type de plateforme échouera au build ou au timeout, pas juste "sera lent".

Décision retenue : Hugging Face Spaces (Docker SDK) pour l'API. Gratuit, pensé pour les démos ML, pas de limite stricte de temps d'exécution comme un hébergement serverless, Dockerfile déjà préparé (yely_ai_module/Dockerfile).

Étapes de déploiement (à faire manuellement, action externe) : 1. Créer un Space sur huggingface.co → SDK "Docker" → visibilité au choix. 2. Ajouter en tête de yely_ai_module/README.md le bloc de configuration attendu par HF Spaces : ```yaml

title: YELY AI Module emoji: ⛽ colorFrom: blue colorTo: green sdk: docker app_port: 7860

3. Pousser le contenu de `yely_ai_module/` (avec `models/crnn_fuel_pump_best.pt`
inclus) vers le dépôt git du Space.
4. Noter l'URL publique du Space (`https://<user>-<space>.hf.space`) — c'est
l'URL que le frontend Netlify appellera pour `/analyze`.
5. Ajouter `CORSMiddleware` dans `app/main.py` pour autoriser le domaine
Netlify du frontend (sinon le navigateur bloquera les réponses).
6. (Optionnel, payant) Activer le **stockage persistant** du Space et
définir la variable d'environnement `YELY_DATA_DIR` sur son point de
montage — sans quoi `photos/`, `logs/` et `monitoring/feedback.jsonl`
sont perdus à chaque redémarrage/veille du Space. Voir
`docs/MONITORING.md` §3 pour la marche à suivre complète et l'impact si
on s'en passe pour la démo.

## 7. Ordre d'exécution recommandé (vu le délai serré)

1. Terminer l'entraînement en cours, figer le modèle livré.
2. Tests d'intégration réels (§2.1-2.2) — valide que tout fonctionne
vraiment avant de documenter/déployer.
3. Interface web de démo (§5) branchée sur l'API en local — utilisable pour
répéter la démo même sans déploiement cloud.
4. Documentation (§4) — peut se faire en parallèle du reste.
5. Déploiement (§6) — une fois l'hébergement de l'API décidé.
6. Monitoring/apprentissage continu (§3) — le plus gros morceau, à
présenter comme "conçu et partiellement implémenté" si le temps manque
(c'est un livrable attendu — §8.6/§15 — mais l'essentiel du temps
restant doit sécuriser une démo qui fonctionne).