SEAL-inspired Text Classifier 🤖

Un pipeline de classification de texte auto-adaptatif inspiré du Self-Adapting Language Model (SEAL) utilisant LoRA pour l'adaptation en temps réel.

Note importante : Ce projet implémente les concepts d'adaptation automatique inspirés du SEAL, mais n'est pas une reproduction exacte du SEAL MIT. Il sert de démonstration éducative des principes d'auto-adaptation avec LoRA.

🎯 Objectif

Ce projet démontre comment un modèle de classification peut s'adapter automatiquement en temps réel lorsqu'il fait des erreurs, en utilisant la technique LoRA (Low-Rank Adaptation) pour un fine-tuning léger et efficace. Deux modes sont disponibles : basique (éducatif) et avancé (proche du SEAL MIT).

🔬 Fonctionnement

Mode Basique

1. Classification initiale : Utilise DistilBERT pré-entraîné pour classer des textes
2. Détection d'erreur : Compare la prédiction avec le vrai label
3. Adaptation LoRA : Si erreur détectée, fine-tune le modèle sur cet exemple avec LoRA
4. Mise à jour : Recharge le modèle adapté et continue sur l'exemple suivant
5. Boucle : Répète le processus sur tout le dataset

Mode Avancé (SEAL-like) 🧠

1. Classification avec confiance : Calcule un score de confiance pour chaque prédiction
2. Décision intelligente : Adapte seulement si erreur + confiance faible
3. Mémoire adaptative : Système de mémoire avec historique des adaptations
4. Oubli sélectif : Supprime automatiquement les adaptations obsolètes
5. Priorisation : Classe les exemples par importance d'apprentissage

🏗️ Architecture

📦 seal_text_classifier/
├── 📁 data/                    # Datasets CSV avec colonnes "text", "label"
│   └── sample.csv             # Dataset d'exemple (68 exemples)
├── 📁 model/                   # Poids LoRA sauvegardés
│   ├── lora_weights_adapt_*   # Adaptations successives
│   └── memory.json            # Mémoire adaptative (mode avancé)
├── 📁 src/                     # Code source modulaire
│   ├── utils.py               # Fonctions utilitaires (chargement modèle/tokenizer)
│   ├── classify.py            # Module de prédiction (simple + confiance)
│   ├── adapt.py               # Module d'adaptation LoRA
│   ├── memory.py              # Système de mémoire adaptative
│   └── loop.py                # Boucles SEAL (basique + avancée)
├── main.py                    # Point d'entrée CLI
├── requirements.txt           # Dépendances Python
├── LICENSE                    # Licence MIT
├── EXAMPLES.md                # Guide d'utilisation détaillé
└── README.md                  # Documentation

🚀 Installation & Usage

Prérequis

• Python 3.8+
• 2GB RAM minimum
• GPU optionnel (CPU supporté)

Installation

# Cloner le repo
git clone https://github.com/amdjadouxx/seal_text_classifier.git
cd seal_text_classifier

# Installer les dépendances
pip install -r requirements.txt

Utilisation basique

# Lancer avec le dataset par défaut (mode simple)
python main.py

# Spécifier un dataset personnalisé
python main.py --data data/mon_dataset.csv

# Spécifier le dossier de sauvegarde LoRA
python main.py --data data/sample.csv --lora model/custom_lora

Mode SEAL Avancé (MIT-like) 🧠

# Mode avancé avec mémoire adaptative et décisions intelligentes
python main.py --advanced

# Avec seuil de confiance personnalisé
python main.py --advanced --confidence-threshold 0.6

# Mode avancé complet
python main.py --advanced --data data/sample.csv --confidence-threshold 0.8 --lora model/advanced_lora

🆚 Comparaison avec le SEAL MIT

Aspect	Notre SEAL Basique	Notre SEAL Avancé	SEAL MIT (Recherche)
Adaptation	✅ LoRA simple sur erreurs	🧠 LoRA intelligent + confiance	🚀 Multi-niveaux + méta-learning
Mémoire	❌ Aucune	✅ Mémoire avec oubli sélectif	🚀 Mémoire hiérarchique complexe
Décisions	❌ Réactif (toutes erreurs)	✅ Proactif (seuil confiance)	🚀 Anticipation prédictive
Oubli	❌ Accumulation simple	✅ Oubli sélectif basique	🚀 Oubli intelligent multi-critères
Complexité	🎯 Simple (éducatif)	🎯 Modérée (proche MIT)	🔬 Très complexe (recherche)
Performance	⚡ Rapide	⚡ Efficace	🚀 État de l'art

Notre objectif : Fournir une implémentation compréhensible et utilisable des concepts SEAL pour l'apprentissage et l'expérimentation.

🆚 Modes disponibles

Mode Basique

• Adaptation sur chaque erreur
• Approche simple et directe
• Bon pour comprendre les concepts

Mode Avancé (MIT-like)

• 🧠 Mémoire adaptative : Système de mémoire avec oubli sélectif
• 🎯 Adaptation intelligente : Décisions basées sur la confiance
• 📊 Priorisation : Classement des exemples par importance
• 🗑️ Oubli sélectif : Suppression des adaptations obsolètes
• 📈 Statistiques avancées : Métriques détaillées de performance

Format du dataset

Votre fichier CSV doit contenir deux colonnes :

text,label
"J'adore ce film !",positive
"Ce produit est terrible.",negative

🔧 Technologies utilisées

• 🤗 Transformers : Chargement et utilisation de DistilBERT
• 🎯 PEFT : Implémentation LoRA pour l'adaptation efficace
• 📊 Datasets : Gestion des données
• 🔥 PyTorch : Framework de deep learning
• 🐼 Pandas : Manipulation des données CSV
• 🔢 NumPy : Calculs numériques pour la mémoire adaptative

📈 Exemples de sortie

Mode Basique

🤖 SEAL Text Classifier - Mode Basique
============================================================
🚀 Démarrage SEAL sur device: cpu
📊 Dataset chargé: 68 exemples depuis data/sample.csv

📝 Exemple 1/68
   Texte: J'adore ce film !
   Prédiction: negative | Vrai label: positive
   ❌ Erreur détectée. Adaptation...
   ✅ Modèle adapté et rechargé depuis model/lora_weights_adapt_1

📝 Exemple 2/68
   Texte: Service client très réactif.
   Prédiction: positive | Vrai label: positive
   ✅ Bonne prédiction.

============================================================
📊 STATISTIQUES FINALES
============================================================
Exemples traités: 68
Prédictions correctes initiales: 34
Adaptations effectuées: 34
🎉 Boucle SEAL terminée avec succès!

Mode Avancé (SEAL-like)

🧠 SEAL Text Classifier - Mode Avancé (MIT-like)
============================================================
💡 Seuil de confiance: 0.7
💾 Mémoire adaptative activée
🎯 Adaptation intelligente activée

🚀 Démarrage SEAL sur device: cpu
📊 Dataset: 68 exemples | Mémoire: 0 adaptations

📝 Exemple 1/68
   Texte: J'adore ce film !
   Prédiction: negative (confiance: 0.523)
   Vrai label: positive
   ❌ Erreur - Adaptation (priorité: 0.834)
   🧠 Adapté et mémorisé (ID: 1)

📝 Exemple 2/68
   Texte: Ce produit est terrible.
   Prédiction: positive (confiance: 0.891)
   Vrai label: negative
   ⏭️  Erreur ignorée (confiance élevée: 0.891)

============================================================
📊 STATISTIQUES SEAL AVANCÉ
============================================================
Exemples traités: 68
Prédictions correctes: 34
Erreurs détectées: 34
Adaptations intelligentes: 20
Adaptations ignorées: 14
Confiance moyenne: 0.756

🧠 MÉMOIRE ADAPTATIVE:
Total adaptations mémorisées: 20
Taille mémoire: 0.05 MB

🎯 Efficacité d'adaptation: 58.8%
💡 Économie d'adaptations: 14 évitées
🎉 SEAL Avancé terminé!

⚙️ Configuration LoRA

Les paramètres LoRA peuvent être ajustés dans src/adapt.py :

lora_config = LoraConfig(
    r=8,                           # Rang (8-64 recommandé)
    lora_alpha=16,                 # Facteur d'échelle  
    target_modules=["q_lin", "v_lin"],  # Couches à adapter
    lora_dropout=0.1,              # Régularisation
    task_type=TaskType.SEQ_CLS     # Tâche de classification
)

🔬 Principe scientifique

LoRA (Low-Rank Adaptation)

Au lieu de modifier tous les poids du modèle, LoRA :

1. Fige les poids originaux W
2. Ajoute une décomposition de rang faible : ΔW = A × B
3. Calcule : output = W×input + A×B×input

Avantages :

• 98% moins de paramètres à entraîner
• 10-100x plus rapide
• Préserve les connaissances pré-entraînées
• Modularité (multiples adaptateurs)

🤝 Contribution

Les contributions sont les bienvenues ! Pour contribuer :

1. Fork le projet
2. Créez une branche (git checkout -b feature/amelioration)
3. Committez vos changements (git commit -am 'Ajout fonctionnalité')
4. Poussez vers la branche (git push origin feature/amelioration)
5. Ouvrez une Pull Request

📄 Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

🙏 Remerciements

• Équipe Hugging Face pour les transformers et PEFT
• Auteurs du papier LoRA original
• Communauté open source