ScanMyCar

Une plateforme intelligente pour évaluer les véhicules d'occasion

ScanMyCar est une application Streamlit qui combine décodage VIN, extraction de documents, vision par ordinateur et machine learning pour aider les professionnels de l'automobile à estimer précisément le prix d'achat et l'état des véhicules d'occasion.

---

Table des matières

1. Vue d'ensemble
2. Fonctionnalités
3. Architecture
4. Installation
5. Guide d'utilisation
6. Structure du projet
7. Modules clés
8. Variables de session Streamlit
9. Règles critiques (avant refactor)
10. Roadmap

---

Vue d'ensemble

Objectif

Automatiser l'évaluation des véhicules d'occasion en combinant :

• Décodage VIN via API NHTSA VPIC
• Extraction OCR et parsing de documents (factures, annonces)
• Détection de dommages par vision par ordinateur (YOLO)
• Prédiction ML du risque de panne
• Estimation du prix via modèle de pricing
• Synthèse IA (LLM) pour recommandation finale

Public cible

Garages professionnels, concessionnaires automobiles, expertises automobiles

---

Fonctionnalités

Fonctionnalité	Description	Implémentation
Décodage VIN	Récupération automatique des métadonnées véhicule	NHTSA VPIC API
Préremplissage de formulaire	Extraction intelligente depuis VIN + factures	Heuristiques regex + parsing
Upload de documents	Factures PDF, images, annonces	Pdfplumber + OCR
Détection de dommages	Identification automatique des zones endommagées	YOLO (ultralytics)
Estimation de coûts	Calcul de coûts de réparation	Heuristique bbox + ML
Pricing ML	Estimation du prix d'achat	Random Forest (joblib)
Prédiction de panne	Score de risque de panne à 12 mois	Modèle ML embarqué
Synthèse IA	Recommandation finale et analyse	Groq API (LLM)
Historique	Conservation des évaluations en session	Session state Streamlit

---

Architecture

Flux global

┌──────────────────────────────────────────────────────────────────┐
│                    UTILISATEUR (Garage)                          │
└──────────────────────────────────────────────────────────────────┘
                                 │
                    ┌────────────┴────────────┐
                    │                         │
                    ▼                         ▼
           ┌─────────────────┐     ┌──────────────────┐
           │ STEP 1: VIN     │     │ Upload Factures  │
           │ + API VPIC      │     │ (OCR + parsing)  │
           └────────┬────────┘     └────────┬─────────┘
                    │                       │
                    └───────────┬───────────┘
                                ▼
                    ┌──────────────────────┐
                    │ STEP 2: Informations │
                    │ (formulaire éditable)│
                    └──────────┬───────────┘
                               ▼
                    ┌──────────────────────┐
                    │ STEP 3: Factures     │
                    │ (ajout/vérification) │
                    └──────────┬───────────┘
                               ▼
            ┌──────────────────────────────────────┐
            │    STEP 4: Photos + Détection      │
            │    YOLO + Coûts de réparation      │
            └──────────────┬───────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
  ┌──────────┐      ┌────────────┐     ┌────────────┐
  │ Pricing  │      │ Breakdown  │     │ Damages +  │
  │   ML     │      │  ML Model  │     │   Repair   │
  └────┬─────┘      └─────┬──────┘     │    Cost    │
       │                  │            └─────┬──────┘
       └──────────────────┼────────────────────┘
                          ▼
                  ┌───────────────────┐
                  │  LLM (Groq API)   │
                  │ Synthèse finale   │
                  └─────────┬─────────┘
                            ▼
                  ┌───────────────────┐
                  │ RÉSULTAT FINAL    │
                  │ + RECOMMANDATION  │
                  └───────────────────┘

Couches technologiques

┌─────────────────────────────────────────────┐
│         INTERFACE UTILISATEUR               │
│         (Streamlit + HTML/CSS)              │
├─────────────────────────────────────────────┤
│       ORCHESTRATION & LOGIQUE MÉTIER        │
│      (app.py - gestion du formulaire)       │
├─────────────────────────────────────────────┤
│  MODULES D'ANALYSE & EXTRACTION             │
│ ┌─────────┬────────────┬──────────────┐     │
│ │  OCR    │  VIN API   │  Document    │     │
│ │ Parsing │  (NHTSA)   │  Processing  │     │
│ └─────────┴────────────┴──────────────┘     │
├─────────────────────────────────────────────┤
│  MODÈLES ML & VISION PAR ORDINATEUR         │
│ ┌──────────┬────────────┬──────────────┐    │
│ │ Pricing  │ Breakdown  │ YOLO Damage  │    │
│ │ Random   │ Predictor  │ Detection    │    │
│ │ Forest   │            │              │    │
│ └──────────┴────────────┴──────────────┘    │
├─────────────────────────────────────────────┤
│  API & SERVICES EXTERNES                    │
│ ┌──────────┬────────────┬──────────────┐    │
│ │ Groq LLM │ NHTSA API  │  Pdfplumber  │    │
│ └──────────┴────────────┴──────────────┘    │
└─────────────────────────────────────────────┘

---

Installation

Prérequis

• Python >= 3.8
• pip (gestionnaire de paquets)
• Clés API : Groq (optionnel pour LLM sans serveur)

Étapes d'installation

1. Cloner ou télécharger le projet

cd CarScan

2. Créer un environnement virtuel

python -m venv .venv

# Sur Linux/macOS
source .venv/bin/activate

# Sur Windows
.venv\Scripts\activate

3. Installer les dépendances

pip install -r requirements.txt

4. Configurer les variables d'environnement

Créer un fichier .env à la racine du projet :

# Groq API (pour LLM)
GROQ_API_KEY=your_groq_api_key_here

# Autres clés si nécessaire
# DATABASE_URL=...
# OCR_API_KEY=...

5. Charger les modèles ML

Les modèles doivent être présents dans le répertoire models/ :

• models/modele_prix.pkl — Modèle de pricing (Random Forest)
• models/modele_liquidite.pkl — Modèle de liquidité
• models/encodeurs_prix.pkl — Encodeurs pour pricing
• models/encodeurs_liquidite.pkl — Encodeurs pour liquidité
• models/car_damage_model.pt — Modèle YOLO pour détection de dommages

Note : Ces fichiers sont générés via les notebooks de training et doivent être téléchargés séparément.

6. Lancer l'application

streamlit run app.py

L'application sera accessible à http://localhost:8501

---

Guide d'utilisation

Pour l'utilisateur final (professionnel du garage)

Step 1 : VIN + Factures optionnelles

1. Entrer le VIN (17 caractères) du véhicule
2. L'API NHTSA remplit automatiquement certains champs (marque, modèle, année, etc.)
3. Optionnel : Upload des factures (PDF, JPG, PNG) pour préremplissage intelligent
4. Les factures sont parsées et leurs informations extraites (km, accidents, état pneus, etc.)
5. Cliquer sur « Suivant » pour continuer

Important : Ne pas auto-naviguer après lecture du VIN. L'utilisateur doit explicitement cliquer « Suivant ».

Step 2 : Informations générales

1. Vérifier/corriger les champs préremplis
2. Compléter les champs manquants :
   • Kilométrage, portes, places
   • Carburant, transmission, entrainement
   • État batterie/pneus/freins
   • Historique d'entretien
   • Problèmes moteur signalés
3. Les badges [VIN] et [Facture] indiquent la source des données
4. Cliquer sur « Suivant »

Step 3 : Factures et documents

1. Ajouter/vérifier les factures d'entretien et réparations
2. Les nouvelles factures sont parsées et préremplissent automatiquement certains champs
3. Cette étape est critique pour la validation humaine
4. Cliquer sur « Suivant »

Step 4 : Photos et soumission

1. Upload des photos du véhicule
2. Détection automatique des dommages via YOLO
3. Affichage des dommages avec confiance et estimation des coûts de réparation
4. Affichage de la prédiction ML de risque de panne (probabilité à 12 mois)
5. Cliquer sur « Terminer l'évaluation »
6. L'IA génère une synthèse et une recommandation finale

Résultat final

• Estimation du prix brut (Argus)
• Pénalité de liquidité (temps de revente estimé)
• Coûts de réparation (dommages détectés)
• Score de risque de panne
• Recommandation synthétisée par l'IA basée sur tous les facteurs

---

Structure du projet

CarScan/
├── app.py                              # Application principale Streamlit
├── api_call.py                         # Wrapper LLM, OCR, appels API
├── damage_detector.py                  # Détection YOLO de dommages
├── breakdown_predictor.py              # Modèle ML prédiction panne
├── pricing_engine.py                   # Modèle ML estimation prix
├── requirements.txt                    # Dépendances Python
├── README.md                           # (Ce fichier)
├── Logo_ScanMyCar.png                  # Logo de l'application
├── .env                                # Variables d'environnement (à créer)
├── autos.csv                           # Dataset de référence (optionnel)
├── models/                             # Répertoire des modèles ML
│   ├── modele_prix.pkl
│   ├── modele_liquidite.pkl
│   ├── encodeurs_prix.pkl
│   ├── encodeurs_liquidite.pkl
│   └── car_damage_model.pt
├── temp_photos/                        # Photos uploadées (temporaire)
├── model_training.ipynb                # Notebook d'entraînement des modèles
├── pricing_and_resale_time_models.ipynb # Notebook de pricing & liquidité
└── Exemple de test complet/            # Fichiers de test/documentation

---

Modules clés

1. app.py — Cœur de l'application

Responsabilités :

• Gestion complète du wizard (4 étapes)
• Gestion de la session Streamlit (eval_data, eval_photos, etc.)
• Navigation entre pages (landing, evaluate, evaluations, profile)
• Préremplissage via VIN et factures
• Affichage badges [VIN] et [Facture]
• Construction du prompt final pour l'IA

Points d'entrée clés :

• _map_vpic_result_to_eval_data() — Transformation résultat VIN API
• parse_invoice_files() — Orchestration du parsing des factures
• prefill_eval_data_from_invoice_text() — Extraction heuristique depuis texte
• _build_formulaire() — Construction du résumé texte pour l'IA
• evaluate_car_page() — Wizard principal (4 steps)

2. api_call.py — Intégration IA & OCR

Responsabilités :

• Appel à l'API Groq (LLM)
• Extraction OCR de documents (PDF, images)
• Construction du prompt système

Fonctions principales :

• api_call(formulaire_text) — Envoi du prompt à l'IA
• extract_document_text(data, filename) — OCR + parsing document
• search_parts_prices() — Recherche de prix de pièces (optionnel)

3. damage_detector.py — Vision par ordinateur

Responsabilités :

• Chargement du modèle YOLO
• Détection de dommages sur images
• Estimation des coûts de réparation

Fonctions principales :

• load_model() — Cache la ressource YOLO
• detect_damage(image_path) — Retourne liste de bounding boxes + confiances
• estimate_damage_cost(damages) — Calcul heuristique : $200 base + $0.05/pixel

4. breakdown_predictor.py — Prédiction de panne

Responsabilités :

• Chargement du modèle ML de prédiction
• Évaluation du risque de panne à 12 mois

Fonction principale :

• predict_breakdown_probability(vehicle_features) → (prob_pct, risk_level)
  • Retourne probabilité en % et niveau de risque (low, moderate, high, very high)

5. pricing_engine.py — Estimation de prix

Responsabilités :

• Préparation des features pour le modèle Random Forest
• Encoding des variables catégorielles
• Prédiction du prix et calcul de la pénalité de liquidité

Fonction principale :

• estimer_prix_et_liquidite(data_dict) → (prix_estime, malus_liq, jours_revente)

---

Variables de session Streamlit

Variables critiques à ne pas renommer

Variable	Type	Scope	Description
eval_step	int (1-4)	Session	Étape courante du wizard
eval_data	dict	Session	Données du formulaire principal
eval_photos	list[File]	Session	Photos uploadées
eval_invoices	list[File]	Session	Factures uploadées
invoice_text_parts	list[str]	Session	Texte extrait des factures (parsé)
parsed_invoice_names	list[str]	Session	Noms des factures déjà parsées (pour éviter reparse)
_prefilled_fields	list[str]	Session	Clés remplies par VIN (pour badges)
_invoice_prefilled_fields	list[str]	Session	Clés remplies par factures (pour badges)
damage_results	list[dict]	Session	Résultats détection dommages par photo
all_damages	list[dict]	Session	Agrégation de tous les dommages
repair_cost	float	Session	Coût total estimé des réparations
evaluations	list[dict]	Session	Historique des évaluations (session courante)
logged_in	bool	Session	État d'authentification utilisateur
user	dict	Session	Infos utilisateur (email, company_name, etc.)
page	str	Session	Page active (landing, evaluate, evaluations, profile)

Contenu clé de eval_data

eval_data = {
    # Identifiant véhicule
    "vin": "1HGBH41JXMN109186",
    
    # Métadonnées VIN
    "marque": "Honda",
    "modele": "Civic",
    "annee": 2018,
    "carrosserie": "Sedan",
    "taille_moteur": 1.8,
    "cylindres": 4,
    "entrainement": "Traction",
    "finition": "EX",
    "usine": "Japan",
    "securite": "...",
    
    # Données utilisateur
    "km": 85000,
    "portes": 4,
    "places": 5,
    "type_carburant": "Essence",
    "transmission": "Manuelle",
    "vitesses": 5,
    
    # État du véhicule
    "condition": "Bon",
    "owners": "Second",
    "accidents": 0,
    "entretien": "Good",
    "etat_batterie": "Good",
    "etat_pneus": "Good",
    "etat_freins": "Good",
    "engine_issues": False,
    "damages": "Quelques rayures mineures",
    
    # Métadonnées
    "_prefilled_fields": ["marque", "modele", "annee"],
    "_vin_fetched": "1HGBH41JXMN109186",
}

---

Ressources utiles

• Streamlit Documentation
• NHTSA VPIC API
• Groq API (LLM)
• Ultralytics YOLO
• Scikit-learn Machine Learning
• Pdfplumber (OCR)