# Implementation Plan: FAISS Rebuild Propre

**Auteur :** Dom, Alice Kiro - 22 décembre 2025

## Overview

Implémentation du système FAISS Rebuild Propre pour éliminer la pollution d'index et maintenir la cohérence des prototypes d'apprentissage. L'approche est "clear + reindex complet" depuis une source canonique.

## Tasks

- [x] 1. Améliorer FAISSManager.clear() pour reset complet de l'état IVF ✅
  - Modifier `core/embedding/faiss_manager.py`
  - Ajouter reset de `training_vectors.clear()`
  - Définir `is_trained` selon le type d'index (Flat=True, IVF=False)
  - Reset `next_id` à 0
  - _Requirements: 1.2, 1.3, 1.4, 1.5_
  - **FAIT:** Méthode clear() améliorée avec reset complet IVF training state

- [ ]* 1.1 Écrire test property pour clear() reset complet
  - **Property 1: Clear Operation Completeness**
  - **Validates: Requirements 1.2, 1.3, 1.4, 1.5**

- [x] 2. Implémenter FAISSManager.reindex() pour reconstruction propre ✅
  - [x] 2.1 Créer méthode `reindex(items, force_train_ivf=True)` ✅
    - Appeler `self.clear()` au début
    - Itérer sur items et appeler `add_embedding()` pour chaque vecteur valide
    - Compter les items traités
    - _Requirements: 2.1, 2.2, 2.4, 2.5_
    - **FAIT:** Méthode reindex() implémentée avec clear + add_embedding

  - [x] 2.2 Ajouter force training IVF pour petits volumes ✅
    - Vérifier si `index_type == "IVF"` et `force_train_ivf == True`
    - Appeler `_train_ivf_index()` si `not is_trained` et `training_vectors` non vide
    - _Requirements: 2.3_
    - **FAIT:** Force training IVF implémenté

  - [x] 2.3 Retourner le nombre d'items indexés ✅
    - Return `count` à la fin de la méthode
    - _Requirements: 2.4_
    - **FAIT:** Retour du count d'items indexés

- [ ]* 2.4 Écrire tests property pour reindex()
  - **Property 3: Reindex Consistency**
  - **Property 4: Invalid Vector Handling**
  - **Property 5: IVF Training Consistency**
  - **Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5**

- [x] 3. Implémenter extraction de vecteurs multi-version dans WorkflowPipeline ✅
  - [x] 3.1 Créer méthode `_extract_node_vector(node)` ✅
    - Vérifier `template.embedding_prototype` (liste)
    - Fallback vers `embedding.vector_id` (fichier)
    - Fallback vers `screen_template.embedding_prototype_path` (legacy)
    - Retourner None si aucun vecteur trouvé
    - Gérer exceptions avec try/catch
    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5_
    - **FAIT:** Méthode _extract_node_vector() avec support multi-version

- [ ]* 3.2 Écrire tests property pour extraction multi-version
  - **Property 6: Vector Extraction Multi-Format**
  - **Property 7: Vector Extraction Graceful Failure**
  - **Validates: Requirements 3.1, 3.2, 3.3, 3.4, 3.5**

- [x] 4. Refactoriser WorkflowPipeline._index_workflow_embeddings() ✅
  - [x] 4.1 Construire liste canonique d'items ✅
    - Itérer sur `workflow.nodes`
    - Appeler `_extract_node_vector()` pour chaque node
    - Construire tuple `(node_id, vector, metadata)` avec workflow_id et node_id
    - _Requirements: 4.1, 4.2_
    - **FAIT:** Construction liste canonique avec métadonnées enrichies

  - [x] 4.2 Appeler reindex() avec force_train_ivf=True ✅
    - `n = self.faiss_manager.reindex(items, force_train_ivf=True)`
    - Logger le nombre d'items indexés avec workflow_id
    - _Requirements: 4.3, 4.4_
    - **FAIT:** Appel reindex() avec force training IVF

  - [x] 4.3 Gérer cas où aucun vecteur valide trouvé ✅
    - Vérifier si `items` est vide
    - Logger warning approprié
    - _Requirements: 4.5_
    - **FAIT:** Gestion gracieuse des cas sans vecteurs

- [ ]* 4.4 Écrire tests property pour indexation workflow
  - **Property 8: Workflow Indexing Completeness**
  - **Property 9: IVF Training Force in Pipeline**
  - **Validates: Requirements 4.1, 4.2, 4.3**

- [ ] 5. Checkpoint - Valider fonctionnalités de base
  - Exécuter tous les tests unitaires et property
  - Vérifier que clear() et reindex() fonctionnent correctement
  - Valider extraction multi-version
  - Demander feedback utilisateur si questions

- [ ] 6. Implémenter logique de déclenchement de rebuild
  - [ ] 6.1 Ajouter trigger après validation de prototype
    - Dans le code de validation post-conditions
    - Appeler `trigger_faiss_rebuild()` si `post_conditions_ok and prototype_updated`
    - _Requirements: 5.1_

  - [ ] 6.2 Ajouter trigger en fin de session batch
    - Dans `end_learning_session()`
    - Appeler `trigger_faiss_rebuild()`
    - _Requirements: 5.2_

  - [ ] 6.3 Implémenter protection contre triggers excessifs
    - Ajouter flag `_rebuild_pending` pour éviter rebuilds multiples
    - Ne pas trigger sur chaque frame update
    - _Requirements: 5.3_

  - [ ] 6.4 Ajouter logging des opérations de rebuild
    - Logger début de rebuild avec timestamp
    - Logger fin de rebuild avec durée et nombre d'items
    - _Requirements: 5.4_

  - [ ] 6.5 Gérer échecs de rebuild gracieusement
    - Try/catch autour de reindex()
    - Maintenir index existant en cas d'échec
    - Logger erreur avec détails
    - _Requirements: 5.5_

- [ ]* 6.6 Écrire tests property pour trigger logic
  - **Property 10: Trigger Logic Validation**
  - **Property 11: Batch Session Trigger**
  - **Property 12: Frame Update Restraint**
  - **Property 13: Rebuild Failure Resilience**
  - **Validates: Requirements 5.1, 5.2, 5.3, 5.5**

- [x] 7. Créer suite de tests complète ✅
  - [x] 7.1 Créer `tests/unit/test_faiss_reindex.py` ✅
    - Test `test_faiss_clear_resets_state()`
    - Test `test_faiss_reindex_flat_removes_old_entries()`
    - Test `test_faiss_reindex_ivf_trains_even_small()`
    - Test `test_extract_node_vector_multi_version()`
    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5_
    - **FAIT:** Suite de tests unitaires complète créée

- [ ]* 7.2 Écrire tests property pour validation complète
  - **Property 14: Flat Index Reindex Cleanup**
  - **Property 15: IVF Small Dataset Training**
  - **Property 16: Metadata Consistency After Reindex**
  - **Property 17: Search Accuracy After Reindex**
  - **Property 18: Index State Validation**
  - **Validates: Requirements 6.1, 6.2, 6.3, 6.4, 6.5**

- [ ]* 7.3 Créer tests d'intégration
  - Test `test_workflow_pipeline_reindex_integration()`
  - Test `test_reindex_performance_large_dataset()`
  - Valider end-to-end avec workflow réel

- [x] 8. Créer script utilitaire rebuild_faiss_simple.py ✅
  - Créer script à la racine du projet
  - Charger tous les prototypes depuis storage
  - Appeler reindex() avec tous les prototypes
  - Logger résultats et statistiques
  - Ajouter options CLI (--dry-run, --verbose, --index-type)
  - **FAIT:** Script utilitaire complet avec options CLI

- [x] 9. Créer documentation utilisateur ✅
  - Créer `docs/guides/FAISS_REBUILD_GUIDE.md`
  - Documenter quand déclencher un rebuild
  - Documenter comment utiliser rebuild_faiss_simple.py
  - Ajouter exemples d'utilisation
  - Documenter troubleshooting
  - **FAIT:** Documentation complète créée

- [ ] 10. Checkpoint Final - Validation complète
  - Exécuter tous les tests (unitaires, property, intégration)
  - Valider performance sur gros datasets
  - Tester script rebuild_faiss_simple.py
  - Valider documentation
  - Demander validation utilisateur finale

## Notes

- Les tâches marquées avec `*` sont optionnelles et peuvent être sautées pour un MVP plus rapide
- Chaque tâche référence les requirements spécifiques pour la traçabilité
- Les checkpoints assurent une validation incrémentale
- Les tests property valident les propriétés de correctness universelles
- Les tests unitaires valident des exemples spécifiques et cas limites