README.md

---
title: YELY AI Module
emoji: ⛽
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
app_port: 7860
short_description: Solution d'IA basée sur la vision par ordinateur
---

# YELY — Module IA de vérification pompiste

Module autonome livré pour le cahier des charges YELY : lecture automatique
du terminal de pompe (prix, volume, prix du litre), calcul et vérification
de cohérence, exposés via une API.

Contrairement à la version précédente du prototype (qui s'appuyait sur
PaddleOCR/EasyOCR, des OCR génériques), ce module utilise un **modèle CRNN
entraîné sur nos propres données** (`models/crnn_fuel_pump_best.pt`) —
voir `docs/LIMITATIONS.md` pour un bilan honnête de sa précision actuelle
et des pistes d'amélioration.

## Structure

```
yely_ai_module/
├── app/
│   ├── main.py           # API FastAPI (/analyze)
│   ├── preprocessing.py  # détection écran + découpage en lignes
│   ├── recognizer.py     # chargement du CRNN + inférence
│   ├── postprocess.py    # normalisation numérique, calculs, cohérence
│   ├── rules.py          # moteur de règles métier (blocage/succès)
│   └── config.py         # seuils configurables (config.yaml)
├── models/
│   └── crnn_fuel_pump_best.pt   # modèle sérialisé (livrable)
├── train/                # scripts d'entraînement (reproductibilité)
├── tests/                # tests unitaires (postprocess, règles)
├── web/                  # interface web de démo (déploiement Netlify)
├── docs/                 # documentation par module + limites identifiées
├── Dockerfile            # déploiement Hugging Face Spaces
└── requirements.txt
```

## Installation

```bash
cd yely_ai_module
pip install -r requirements.txt
```

## Lancer l'API

```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

Ne pas utiliser `--reload` en usage normal : ça redémarre tout le worker
(et donc recharge le modèle CRNN, ~30-60s) à chaque modification de fichier.

## Appeler l'API

```bash
curl -X POST http://127.0.0.1:8000/analyze \
  -F "image=@photo_pompe.jpg" \
  -F "fuel_price=700" \
  -F "driver_id=chauffeur-42" \
  -F "pompiste_id=pompiste-7" \
  -F "station_id=station-3"
```

### Réponse

```json
{
  "success": true,
  "image_quality": "valid",
  "detected_liters": 14.28,
  "detected_amount": 10000.0,
  "fuel_price": 700.0,
  "calculated_amount": 9996.0,
  "calculated_liters": null,
  "is_consistent": true,
  "confidence_score": 0.93,
  "message": "Données vérifiées avec succès.",
  "driver_id": "chauffeur-42",
  "pompiste_id": "pompiste-7",
  "station_id": "station-3",
  "transaction_datetime": "2026-07-05T20:00:00+00:00",
  "photo_reference": "<uuid>.jpg"
}
```

Champs conformes au §13 du cahier des charges. Le `fuel_price` fourni par
l'appelant (système YELY) fait toujours autorité sur un prix lu à l'écran
(règle métier n°1).

## Tests

```bash
pytest tests/
```

## Ré-entraîner le modèle

```bash
cd train
python prepare_doctr_dataset.py   # si le dataset a changé
python finetune_doctr.py --epochs 60
```

Voir `docs/LIMITATIONS.md` avant de ré-entraîner : le principal facteur
limitant est la diversité du jeu de données, pas les hyperparamètres.

## Déploiement

Voir `docs/WORKFLOW.md` §6 : frontend (`web/`) sur Netlify, API sur
Hugging Face Spaces (ce dépôt, via le `Dockerfile` à la racine).