# 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/.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/.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/`, 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://-.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).