Category Classification Engine

API Django de classification automatique des frais annexes de Bons de Commande (BDC) automobile en France.

Le moteur utilise un pipeline à 3 niveaux : règles regex déterministes → modèle SetFit fine-tuné → revue humaine (A_CLASSIFIER). Toute la configuration se fait via Django Admin — aucune modification de code nécessaire.

Onboarding : Créer un moteur de classification

Cette section décrit comment constituer un nouveau jeu de catégories de A à Z.

Étape 1 — Extraire et analyser les données source

À partir des Bons de Commande réels, extraire le tableau des frais annexes (libellés + montants). Analyser la fréquence et la sémantique des libellés pour identifier les regroupements naturels.

Questions à se poser :

• Quels libellés reviennent le plus souvent ? (fréquence = priorité)
• Y a-t-il des familles sémantiques claires (taxes, garanties, traitements, accessoires...) ?
• Quel est le seuil de fréquence minimum pour justifier une catégorie dédiée ?
• Certains libellés sont-ils composites (ex : "immat + transport") ? Ils iront en A_CLASSIFIER.

Étape 2 — Définir les catégories

Pour chaque catégorie identifiée, créer une entrée dans Django Admin (/admin/classifier/category/) avec :

• key : identifiant slug unique (ex: carte_grise, garantie_extension)
• name : libellé lisible en français
• description : périmètre exact — ce qui entre et ce qui n'entre pas
• code_comptable : compte PCG (ex: 6354, 607, 6226)
• tva : régime TVA applicable (ex: TVA 20%, Hors champ TVA, Mixte)
• order : ordre d'affichage

Minimum recommandé : 5 catégories. Maximum pratique sur un seul modèle : ~20.

Étape 3 — Constituer le jeu d'entraînement

Pour chaque catégorie, collecter 8 à 30 libellés réels et variés issus des BDC. La variété compte plus que la quantité : Carte grise, CG, Certificat immatriculation, Carte Grise + malus sont 4 exemples qui valent mieux que 20 fois Carte grise.

Le jeu d'entraînement peut être fourni de deux manières :

• Fichier JSON : src/classifier/fixtures/training_data.json (format {"categorie": ["libelle1", "libelle2"]})
• Saisie directe dans Django Admin : /admin/classifier/trainingexample/

Étape 4 — Importer les données

# Import complet depuis les fichiers JSON (supprime l'existant)
docker compose exec category_web_app python manage.py import_training_data --clear

# Import incrémental (préserve l'existant, ignore les doublons)
docker compose exec category_web_app python manage.py import_training_data

# Preview sans modifier la base
docker compose exec category_web_app python manage.py import_training_data --dry-run

# Exemples uniquement (skip les règles regex)
docker compose exec category_web_app python manage.py import_training_data --skip-rules

Étape 5 — Ajouter les règles regex

Les règles regex capturent les cas déterministes sans passer par le modèle ML (confiance fixe 0.95, <1ms). Elles prennent effet immédiatement après sauvegarde dans l'Admin, sans redémarrage.

Dans Django Admin (/admin/classifier/categoryrule/) :

• pattern : regex Python (ex: (?i)\bcarte\s*grise\b)
• priority : entier — plus petit = évalué en premier (0–5 haute, 6–10 normale, 11+ basse)
• description : note humaine sur ce que capture la règle

Règles de priorité importantes :

• Les catégories très spécifiques (ex: carte_grise) reçoivent une priorité basse (1-3) pour être évaluées en premier
• Les catégories génériques (ex: frais_administratif) reçoivent une priorité haute (11-14), évaluées en dernier
• Si un libellé matche des règles de 2 catégories différentes → envoyé automatiquement en A_CLASSIFIER (multi-match)

Étape 6 — Entraîner le modèle

# Entraînement (~90s sur CPU)
docker compose exec category_web_app python manage.py train_setfit

# Avec évaluation de précision sur un holdout de 20%
docker compose exec category_web_app python manage.py train_setfit --evaluate

# OBLIGATOIRE après l'entraînement — le serveur web tourne dans un processus séparé
docker compose restart category_web_app

Étape 7 — Tester avec des données réelles

# Obtenir un token JWT
TOKEN=$(curl -s -X POST https://categoryclassification.aiichaa.com/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YOUR_PASSWORD"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access'])")

# Classifier des frais annexes
curl -s https://categoryclassification.aiichaa.com/api/v1/classify/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"frais_annexes": [{"name": "Carte Grise", "prix": "238"}, {"name": "Waxoyl", "prix": "219"}]}'

Analyser les résultats :

• Items method: rules ou method: setfit → classifiés automatiquement
• Items method: rules_multi_match → libellés composites, revue humaine requise
• Items en A_CLASSIFIER → envoyer via /api/v1/feedback/ avec la bonne catégorie

Étape 8 — Boucle feedback → révision → réentraînement

1. L'application cliente collecte les items A_CLASSIFIER et envoie des corrections à POST /api/v1/feedback/
2. Un ticket Mantis est automatiquement créé pour chaque feedback soumis
3. Le responsable révise depuis l'Admin Django (lien direct dans le ticket Mantis) — il peut uniquement modifier correct_category et le statut d'approbation
4. Une fois les feedbacks traités, appliquer les corrections et réentraîner :

docker compose exec category_web_app python manage.py apply_feedback --retrain
docker compose restart category_web_app

Pipeline de Classification

POST /api/v1/classify/  (JWT requis)
        │
        ▼
┌─────────────────────────────────────────┐
│ Niveau 1 : RÈGLES REGEX (depuis la DB)  │
│ Déterministe, <1ms, confiance 0.95      │
│ Match unique  → catégorie               │
│ Multi-match   → A_CLASSIFIER            │
└────────────────┬────────────────────────┘
                 │ aucun match
                 ▼
┌─────────────────────────────────────────┐
│ Niveau 2 : MODÈLE SETFIT                │
│ Fine-tuné sur vos données, ~50ms/item   │
│ conf >= seuil → catégorie               │
│ conf < seuil  → A_CLASSIFIER            │
└────────────────┬────────────────────────┘
                 │ faible confiance
                 ▼
┌─────────────────────────────────────────┐
│ Niveau 3 : A_CLASSIFIER (revue humaine) │
└─────────────────────────────────────────┘

Réentraînement du modèle : ce qui se passe exactement

L'entraînement est toujours de zéro (non incrémental). Voici exactement ce que fait train_setfit :

1. Chargement de toutes les catégories actives et leurs exemples depuis la DB (sources : import initial + feedbacks appliqués + saisies manuelles)
2. Suppression de l'ancien modèle sur disque (src/classifier/fixtures/setfit_model/)
3. Chargement du modèle de base depuis le cache HuggingFace local (déjà dans l'image Docker — aucun téléchargement réseau)
4. Fine-tuning contrastif : SetFit génère des paires positives/négatives et ajuste les poids du SentenceTransformer pour que vos catégories soient bien séparées dans l'espace vectoriel
5. Entraînement de la tête de classification (LogisticRegression) sur les nouveaux embeddings
6. Sauvegarde du modèle complet sur disque
7. Mise à jour du cache en mémoire — mais uniquement dans le processus du management command

Points importants :

• Ajouter 1 seul exemple a peu d'effet — il est noyé parmi les 300+ existants
• Ajouter 5 à 10 exemples variés sur une catégorie problématique a un effet mesurable
• apply_feedback --retrain ajoute les feedbacks approuvés au corpus puis réentraîne
• apply_feedback supprime aussi le libellé de la mauvaise catégorie s'il y était
• Si un feedback entre en conflit avec une règle regex existante, il est signalé — il faut corriger la règle dans l'Admin
• L'ancien modèle est irrrécupérable une fois l'entraînement lancé (pas de rollback)
• Durée : ~90s sur CPU, quelle que soit la taille du corpus (jusqu'à ~500 exemples)

Boucle d'amélioration continue

  ┌────── API classifie les frais ◄──────────────────┐
  │                                                   │
  ▼                                                   │
  Items A_CLASSIFIER → client envoie POST /feedback/ │
  │                                                   │
  ▼                                                   │
  Ticket Mantis créé automatiquement                  │
  │                                                   │
  ▼                                                   │
  Responsable révise dans Django Admin                │
  (approuve / refuse / corrige la catégorie)          │
  │                                                   │
  ▼                                                   │
  manage.py apply_feedback --retrain                  │
  │                                                   │
  └───────────────────────────────────────────────────┘

Quick Start

# 1. Configurer l'environnement
cp .env.example .env
# Éditer .env avec vos valeurs (voir section Configuration)

# 2. Build et démarrage
docker compose up --build -d

# 3. Migrations
docker compose exec category_web_app python manage.py makemigrations classifier
docker compose exec category_web_app python manage.py migrate

# 4. Importer catégories, règles regex et exemples d'entraînement
docker compose exec category_web_app python manage.py import_training_data --clear

# 5. Entraîner le modèle SetFit (~90s sur CPU)
docker compose exec category_web_app python manage.py train_setfit

# 6. Redémarrer pour charger le modèle en mémoire
docker compose restart category_web_app

# 7. Obtenir un token JWT
curl -X POST http://localhost:8042/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "adminPass"}'

Configuration

Variables d'environnement (.env)

Ports

Authentification (JWT)

Tous les endpoints sauf /api/v1/status/ nécessitent un token Bearer JWT.

# Obtenir un token
curl -X POST http://localhost:8042/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "adminPass"}'

# Utiliser le token
curl http://localhost:8042/api/v1/categories/ \
  -H "Authorization: Bearer eyJ..."

# Rafraîchir un token expiré (expire après 5 minutes)
curl -X POST http://localhost:8042/api/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "eyJ..."}'

Throttling : 100 req/min pour les accès anonymes, 1000 req/min pour les accès authentifiés.

API Endpoints

Classifier des frais (POST /api/v1/classify/)

{
  "frais_annexes": [
    {"name": "Carte Grise (hors malus éventuel)", "prix": "238,00"},
    {"name": "Waxoyl", "prix": "219,00"},
    {"name": "immat + transport", "prix": "450,00"}
  ],
  "confidence_threshold": 0.55
}

Réponse :

{
  "frais_annexes": {
    "carte_grise": [
      {"name": "carte_grise_1", "code": "Carte Grise (hors malus éventuel)",
       "prix": "238,00", "confidence": 0.95, "method": "rules"}
    ],
    "traitement_carrosserie": [
      {"name": "traitement_carrosserie_1", "code": "Waxoyl",
       "prix": "219,00", "confidence": 0.95, "method": "rules"}
    ],
    "A_CLASSIFIER": [
      {"name": "A_CLASSIFIER_1", "code": "immat + transport",
       "prix": "450,00", "confidence": 0.0, "method": "rules_multi_match",
       "matched_categories": ["frais_administratif", "transport_livraison"],
       "needs_review": true}
    ]
  },
  "meta": {
    "total_items": 3, "classified": 2, "needs_review": 1,
    "processing_time_ms": 14.2,
    "methods": {"rules": 2, "rules_multi_match": 1, "setfit": 0}
  }
}

Soumettre un feedback (POST /api/v1/feedback/)

{
  "original_libelle": "Frais Aménagement DANGEL",
  "predicted_category": "A_CLASSIFIER",
  "correct_category": "options_vehicule",
  "notes": "DANGEL = kit aménagement 4x4"
}

Les 15 catégories (+ A_CLASSIFIER)

Chaque catégorie porte des métadonnées comptables gérées dans l'Admin :

• code_comptable : compte du Plan Comptable Général (ex: 6354, 607)
• tva : régime TVA (ex: TVA 20%, Hors champ TVA, Mixte : Assurance exonérée / Services TVA 20%)

Management Commands

import_training_data — Import des données initiales

Importe catégories, exemples d'entraînement et règles regex depuis les fichiers JSON de src/classifier/fixtures/.

docker compose exec category_web_app python manage.py import_training_data --clear    # clean install
docker compose exec category_web_app python manage.py import_training_data            # incremental
docker compose exec category_web_app python manage.py import_training_data --dry-run  # preview
docker compose exec category_web_app python manage.py import_training_data --skip-rules

train_setfit — Entraîner le modèle SetFit

docker compose exec category_web_app python manage.py train_setfit             # entraînement
docker compose exec category_web_app python manage.py train_setfit --evaluate  # + évaluation
docker compose exec category_web_app python manage.py train_setfit --dry-run   # preview données

Après entraînement, pas besoin de redémarrer : chaque worker gunicorn détecte la nouvelle mtime de MODEL_DIR et recharge le modèle automatiquement à la prochaine requête.

apply_feedback — Appliquer les corrections humaines

Traite uniquement les feedbacks approuvé (depuis Django Admin) : ajoute les libellés comme exemples d'entraînement dans la bonne catégorie, les retire de la mauvaise, et signale les conflits avec les règles regex. Les feedbacks en attente et refusé sont ignorés.

docker compose exec category_web_app python manage.py apply_feedback --dry-run   # preview
docker compose exec category_web_app python manage.py apply_feedback --retrain   # appliquer + réentraîner

Synchronisation multi-environnements (MinIO)

Pour partager un modèle et les feedbacks entre dev et staging :

# Modèle — depuis l'env qui entraîne, vers l'env de service
python manage.py push_model_to_s3 --note "fb round 2026-05-12"
python manage.py pull_model_from_s3              # latest
python manage.py pull_model_from_s3 --tag=2026-05-12T11-01-33Z   # version pinnée
python manage.py pull_model_from_s3 --force      # re-télécharge même si .version local correspond

# Feedback — typiquement staging → dev pour rapatrier les corrections clients
python manage.py dump_feedback --upload-to-s3 staging              # vers feedback/staging/<ts>.json
python manage.py load_feedback --from-s3-latest staging            # idempotent (UUID-based)
python manage.py load_feedback --from-s3-latest staging --dry-run  # preview

Pour recharger le modèle dans tous les workers d'un environnement sans redémarrer le conteneur :

curl -X POST "https://catclass-api.example.com/api/v1/admin/reload-model/?pull=1" \
  -H "Authorization: Bearer $STAFF_JWT"

Inspection à distance (sans SSH)

Trois endpoints en lecture seule pour observer ce qui se passe en production :

# Compteurs : volume 24h/7j/30j, breakdown méthodes/catégories, feedback queue, modèle, dernier training
curl -H "Authorization: Bearer $STAFF_JWT" \
  "https://catclass-api.example.com/api/v1/admin/stats/" | jq

# Logs filtrés : low-confidence des dernières 24h
curl -H "Authorization: Bearer $STAFF_JWT" \
  "https://catclass-api.example.com/api/v1/admin/logs/?confidence_lt=0.5&limit=20" | jq

# File de feedback pending
curl -H "Authorization: Bearer $STAFF_JWT" \
  "https://catclass-api.example.com/api/v1/admin/feedback/?status=pending&limit=50" | jq

Filtres disponibles :

• /admin/logs/ : since, until (ISO 8601 ou YYYY-MM-DD), category, method, confidence_lt, confidence_gte, libelle_contains
• /admin/feedback/ : status (pending/approved/denied), applied (true/false), predicted_category, correct_category, since, until, libelle_contains
• Pagination uniforme : limit (défaut 50, max 500), offset

Modèles de données

Prérequis système

RAM : ~1.5 GB en inférence, ~2-3 GB pendant l'entraînement.

PyTorch est installé en variante CPU uniquement (index https://download.pytorch.org/whl/cpu) pour éviter de tirer la version CUDA de 8 GB. Cette installation se fait dans une couche Docker séparée, avant la copie de requirements.txt, ce qui évite de re-télécharger PyTorch à chaque changement de dépendances.

Architecture des fichiers

src/
├── config/
│   ├── settings.py     # JWT, throttling, DB, Mantis
│   ├── urls.py         # Routes : homepage, admin, JWT, api/v1/
│   └── views.py        # Homepage — rendu de ce README en HTML
└── classifier/
    ├── engine/
    │   ├── categories.py   # Cache des catégories depuis la DB
    │   ├── rules.py        # Niveau 1 : regex + détection multi-match
    │   ├── embeddings.py   # Niveau 2 : SetFit (chargement, inférence, entraînement)
    │   ├── classifier.py   # Orchestrateur du pipeline (règles → SetFit → fallback)
    │   ├── model_storage.py    # Upload/download du modèle vers MinIO/S3
    │   └── feedback_sync.py    # Sérialisation des feedbacks pour sync cross-env
    ├── fixtures/
    │   ├── training_data.json   # Snapshot des exemples d'entraînement
    │   ├── regex_rules.json     # Snapshot des règles regex
    │   └── setfit_model/        # Modèle fine-tuné (généré par train_setfit, gitignored)
    ├── management/commands/
    │   ├── import_training_data.py  # JSON fixtures → DB
    │   ├── train_setfit.py          # Entraînement SetFit depuis la DB
    │   ├── apply_feedback.py        # Feedbacks approuvés → exemples d'entraînement
    │   ├── push_model_to_s3.py      # Upload du modèle local vers MinIO
    │   ├── pull_model_from_s3.py    # Download du modèle depuis MinIO (atomic swap)
    │   ├── dump_feedback.py         # Export feedbacks → fichier ou MinIO
    │   └── load_feedback.py         # Import feedbacks (idempotent sur UUID)
    ├── models.py        # Category, CategoryRule, TrainingExample, logs, feedbacks
    ├── serializers.py
    ├── views.py         # Endpoints API (JWT-protected)
    ├── admin.py         # Interface d'administration Django
    └── services.py      # Intégration Mantis Bug Tracker

Tests

docker compose exec category_web_app python manage.py test classifier -v2

Un jeu de test complet de 86 items couvrant toutes les catégories et les cas limites est disponible dans postman/test_classify_body.json.