Geniusia_v2/.kiro/specs/embedding-improvement/tasks.md

# Implementation Plan - Amélioration du Système d'Embeddings et Fine-tuning

## Phase 1: Fix FAISS et Abstraction de Base

- [x] 1. Créer l'abstraction EmbedderBase
  - Créer `geniusia2/core/embedders/__init__.py`
  - Créer `geniusia2/core/embedders/base.py` avec classe abstraite `EmbedderBase`
  - Définir méthodes: `embed()`, `get_dimension()`, `get_model_name()`, `supports_batch()`, `embed_batch()`
  - Ajouter docstrings complètes
  - _Requirements: 2.1, 2.2_

- [x] 2. Implémenter CLIPEmbedder
  - Créer `geniusia2/core/embedders/clip_embedder.py`
  - Wrapper autour du code CLIP existant dans `vision_analysis.py`
  - Implémenter toutes les méthodes de `EmbedderBase`
  - Gérer GPU/CPU automatiquement
  - Normaliser les embeddings (L2 norm)
  - _Requirements: 2.1, 2.2, 2.5, 6.4_

- [x] 3. Créer FAISSIndex corrigé
  - Créer `geniusia2/core/embedders/faiss_index.py`
  - Implémenter `add()` avec validation de dimension
  - Implémenter `search()` avec conversion distance→similarity
  - Implémenter `save()` et `load()` avec metadata
  - Implémenter `rebuild_if_needed()` pour changement de dimension
  - Gérer les cas d'erreur (dimension mismatch, fichier corrompu)
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5_

- [ ]* 3.1 Écrire tests unitaires pour FAISSIndex
  - Test add/search avec différentes dimensions
  - Test save/load round-trip
  - Test rebuild sur changement de dimension
  - Test gestion d'erreurs
  - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5_

- [ ]* 3.2 Écrire test de propriété pour FAISS round-trip
  - **Property 2: FAISS Index Persistence Round-trip**
  - **Validates: Requirements 1.3, 1.4**
  - Générer embeddings aléatoires, sauvegarder, charger, vérifier résultats identiques

- [x] 4. Créer EmbeddingManager
  - Créer `geniusia2/core/embedders/embedding_manager.py`
  - Implémenter sélection de modèle avec fallback
  - Implémenter cache LRU manuel (1000 entrées)
  - Utiliser hash MD5 de l'image comme clé de cache
  - Logger le modèle chargé au démarrage
  - _Requirements: 2.3, 2.4, 6.1, 6.2, 7.1, 7.3_

- [ ]* 4.1 Écrire tests pour EmbeddingManager
  - Test sélection de modèle
  - Test fallback sur erreur
  - Test cache hit/miss
  - Test éviction LRU
  - _Requirements: 2.4, 6.1, 6.2_

- [ ]* 4.2 Écrire test de propriété pour cache consistency
  - **Property 4: Cache Hit Consistency**
  - **Validates: Requirements 6.1**
  - Générer images aléatoires, embedder 2x, vérifier résultats identiques

- [x] 5. Intégrer dans vision_analysis.py
  - Remplacer le code CLIP direct par `EmbeddingManager`
  - Ajouter paramètre de config pour choisir le modèle (clip/pix2struct)
  - Migrer les embeddings existants si nécessaire
  - Maintenir backward compatibility
  - _Requirements: 2.3, 2.4_

- [x] 6. Intégrer dans workflow_matcher.py
  - Utiliser `EmbeddingManager` au lieu de CLIP direct
  - Utiliser `FAISSIndex` pour les recherches de similarité
  - Gérer le cas où l'index n'existe pas encore
  - _Requirements: 1.1, 1.2_

- [x] 7. Checkpoint - Tester le système de base
  - Lancer l'application en mode Assist
  - Vérifier que les embeddings sont générés correctement
  - Vérifier que FAISS fonctionne sans erreurs de dimension
  - Vérifier que le cache fonctionne
  - Tester save/load de l'index FAISS
  - Ensure all tests pass, ask the user if questions arise.

## Phase 2: Ajouter Pix2Struct

- [x] 8. Installer dépendances Pix2Struct
  - Ajouter `transformers>=4.35.0` à requirements
  - Ajouter `sentencepiece` à requirements
  - Créer script d'installation `install_pix2struct.sh`
  - Tester l'installation sur la machine cible
  - _Requirements: 3.1_

- [x] 9. Implémenter Pix2StructEmbedder
  - Créer `geniusia2/core/embedders/pix2struct_embedder.py`
  - Charger le modèle `google/pix2struct-base`
  - Extraire les hidden states de l'encoder comme embeddings
  - Normaliser les embeddings (L2 norm)
  - Gérer GPU/CPU automatiquement
  - Implémenter toutes les méthodes de `EmbedderBase`
  - _Requirements: 3.1, 3.2, 3.3, 3.5_

- [ ]* 9.1 Écrire tests pour Pix2StructEmbedder
  - Test chargement du modèle
  - Test génération d'embeddings
  - Test dimension consistency
  - Test GPU/CPU switching
  - _Requirements: 3.1, 3.2, 3.3_

- [ ]* 9.2 Écrire test de propriété pour interface compatibility
  - **Property 3: Embedder Interface Compatibility**
  - **Validates: Requirements 2.1, 2.2, 2.5**
  - Tester CLIP et Pix2Struct avec images PIL aléatoires, vérifier format de sortie

- [x] 10. Tester Pix2Struct vs CLIP
  - Créer script de benchmark `test_pix2struct_vs_clip.py`
  - Comparer la qualité des embeddings sur des screenshots UI
  - Mesurer les performances (temps, mémoire)
  - Documenter les résultats
  - _Requirements: 3.4, 6.5_

- [x] 11. Ajouter configuration pour sélection de modèle
  - Ajouter paramètre `embedding_model` dans config
  - Valeurs possibles: "clip", "pix2struct"
  - Défaut: "clip" (pour compatibilité)
  - Documenter dans README
  - _Requirements: 2.3, 7.1_

- [x] 12. Checkpoint - Tester Pix2Struct
  - Lancer avec `embedding_model=pix2struct`
  - Vérifier que le modèle charge correctement
  - Comparer la précision du matching avec CLIP
  - Vérifier le fallback si Pix2Struct échoue
  - Ensure all tests pass, ask the user if questions arise.

## Phase 3: Fine-tuning Léger

- [x] 13. Créer LightweightFineTuner
  - Créer `geniusia2/core/embedders/fine_tuner.py`
  - Implémenter collection d'exemples positifs/négatifs (deque maxlen=1000)
  - Implémenter trigger automatique tous les 10 exemples
  - Implémenter exécution en thread séparé
  - Implémenter sauvegarde/chargement de checkpoint
  - _Requirements: 4.1, 4.2, 4.3, 5.1, 5.5_

- [ ]* 13.1 Écrire tests pour LightweightFineTuner
  - Test collection d'exemples
  - Test trigger threshold
  - Test thread séparé (non-blocking)
  - Test checkpoint save/load
  - _Requirements: 4.1, 4.2, 4.3, 5.1_

- [ ]* 13.2 Écrire test de propriété pour example collection bounds
  - **Property 7: Example Collection Bounds**
  - **Validates: Requirements 4.1, 4.2**
  - Ajouter N exemples aléatoires (N > 1000), vérifier que len <= 1000

- [ ]* 13.3 Écrire test de propriété pour fine-tuning non-blocking
  - **Property 6: Fine-tuning Non-blocking**
  - **Validates: Requirements 5.1, 5.2**
  - Lancer fine-tuning, vérifier que embed() continue de fonctionner

- [x] 14. Implémenter fine-tuning pour CLIPEmbedder
  - Ajouter méthode `fine_tune()` à `CLIPEmbedder`
  - Utiliser contrastive loss (positifs vs négatifs)
  - Fine-tuner uniquement la dernière couche de projection
  - Utiliser learning rate faible (1e-4)
  - Limiter à 1 epoch pour rapidité
  - Retourner métriques (loss, accuracy)
  - _Requirements: 4.4, 5.2, 5.3, 7.2_

- [x] 15. Implémenter fine-tuning pour Pix2StructEmbedder
  - Ajouter méthode `fine_tune()` à `Pix2StructEmbedder`
  - Utiliser contrastive loss (positifs vs négatifs)
  - Fine-tuner uniquement la dernière couche de l'encoder
  - Utiliser learning rate faible (1e-4)
  - Limiter à 1 epoch pour rapidité
  - Retourner métriques (loss, accuracy)
  - _Requirements: 4.4, 5.2, 5.3, 7.2_

- [x] 16. Intégrer fine-tuning dans Orchestrator
  - Ajouter `LightweightFineTuner` à l'orchestrator
  - Appeler `add_positive_example()` quand workflow accepté et réussi
  - Appeler `add_negative_example()` quand workflow rejeté
  - Sauvegarder checkpoint à l'arrêt
  - Charger checkpoint au démarrage
  - _Requirements: 4.1, 4.2, 5.5_

- [x] 17. Ajouter logging et métriques
  - Logger le début/fin du fine-tuning
  - Logger les métriques (loss, accuracy, durée)
  - Logger le nombre d'exemples collectés
  - Créer fichier de log dédié `fine_tuning.log`
  - _Requirements: 7.2, 7.3_

- [x] 18. Checkpoint Final - Tester le système complet
  - Lancer l'application en mode Assist
  - Accepter plusieurs workflows → vérifier collection d'exemples positifs
  - Rejeter plusieurs workflows → vérifier collection d'exemples négatifs
  - Attendre le trigger (10 exemples) → vérifier que fine-tuning démarre
  - Vérifier que l'application continue de fonctionner pendant le fine-tuning
  - Vérifier que les métriques sont loggées
  - Vérifier que le modèle s'améliore après fine-tuning
  - Ensure all tests pass, ask the user if questions arise.

## Phase 4: Optimisations et Outils

- [x] 19. Optimiser les performances
  - Implémenter batch processing pour embed_batch()
  - Optimiser le cache (utiliser hash plus rapide si nécessaire)
  - Profiler les performances (temps, mémoire)
  - Ajuster les paramètres si nécessaire
  - _Requirements: 6.3, 6.4, 6.5_

- [ ]* 19.1 Écrire tests de performance
  - Mesurer temps d'embedding (GPU vs CPU)
  - Mesurer temps de recherche FAISS
  - Mesurer temps de fine-tuning
  - Vérifier que les seuils sont respectés
  - _Requirements: 6.5_

- [x] 20. Créer outils de visualisation
  - Créer script `visualize_embeddings.py`
  - Utiliser t-SNE ou UMAP pour visualiser les embeddings
  - Afficher les clusters de workflows similaires
  - Comparer CLIP vs Pix2Struct visuellement
  - _Requirements: 7.5_

- [x] 21. Créer outils de debugging
  - Créer script `debug_embeddings.py`
  - Afficher les embeddings pour une image donnée
  - Afficher les résultats de recherche FAISS
  - Afficher l'historique de fine-tuning
  - _Requirements: 7.4, 7.5_

- [x] 22. Documentation finale
  - Documenter l'architecture dans README
  - Documenter comment choisir entre CLIP et Pix2Struct
  - Documenter le système de fine-tuning
  - Créer guide de troubleshooting
  - _Requirements: All_

## Phase 5: Intégration dans l'Orchestrator

- [x] 23. Intégrer le système d'embeddings dans l'Orchestrator
  - Créer méthode `_init_new_embedding_system()`
  - Initialiser EmbeddingManager, FAISSIndex, LightweightFineTuner
  - Charger les checkpoints au démarrage
  - Gérer les erreurs d'initialisation
  - _Requirements: All_

- [x] 24. Implémenter l'indexation automatique des workflows
  - Créer méthode `_index_workflow_in_faiss()`
  - Convertir screenshots en embeddings
  - Indexer dans FAISS avec metadata
  - Logger les opérations
  - _Requirements: 1.1, 1.2, 1.3_

- [x] 25. Implémenter la collection d'exemples pour fine-tuning
  - Créer méthode `_add_positive_example_for_finetuning()`
  - Créer méthode `_add_negative_example_for_finetuning()`
  - Connecter aux callbacks de suggestions
  - Gérer la conversion d'images
  - _Requirements: 4.1, 4.2, 5.1_

- [x] 26. Implémenter la sauvegarde à l'arrêt
  - Créer méthode `_save_embedding_system_on_shutdown()`
  - Attendre la fin du fine-tuning en cours
  - Sauvegarder l'index FAISS
  - Sauvegarder le checkpoint du fine-tuner
  - Logger les statistiques
  - _Requirements: 1.3, 5.5_

- [x] 27. Créer tests d'intégration
  - Test d'initialisation du système
  - Test d'indexation de workflows
  - Test de collection d'exemples positifs/négatifs
  - Test du cache
  - Test de sauvegarde/chargement
  - _Requirements: All_

- [x] 28. Créer script de vérification
  - Vérifier l'installation de FAISS
  - Vérifier l'import des modules
  - Lancer les tests d'intégration
  - Vérifier les fichiers créés
  - Vérifier la documentation
  - _Requirements: All_

- [x] 29. Documentation de l'intégration
  - Créer EMBEDDING_SYSTEM_INTEGRATED.md
  - Documenter l'architecture complète
  - Documenter l'utilisation
  - Documenter le monitoring
  - Créer guide de troubleshooting
  - _Requirements: All_

## Statut Final

✅ **INTÉGRATION COMPLÈTE**

Le système d'embeddings est maintenant complètement intégré dans GeniusIA v2 :
- ✅ Tous les composants sont implémentés
- ✅ Tous les tests passent
- ✅ La documentation est complète
- ✅ Le système est prêt pour la production

**Date de complétion** : 20 novembre 2024