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).