perf: Add MEMORY_TRADEOFFS and PERFORMANCE documentation

- Introduced MEMORY_TRADEOFFS.md to explain memory vs deduplication trade-offs in anagram generation.
- Added PERFORMANCE.md detailing optimizations for handling large volumes of anagram generation efficiently.
- Created USAGE.md for comprehensive usage instructions, including installation, basic commands, and advanced generation modes.
- Enhanced generator with streaming and batch processing capabilities for improved memory management.
- Implemented quick hashing for deduplication to reduce memory footprint.
- Updated main.rs to support new command-line arguments for streaming and batch modes.
- Added tests to ensure letter removal maintains minimum word length and to verify anagram sorting functionality.

README.md

@@ -1,6 +1,6 @@
 # Anagram Generator
 
-Un générateur d'anagrammes prononçables en Rust pour créer des pseudonymes.
+Un générateur d'anagrammes prononçables haute performance en Rust pour créer des pseudonymes.
 
 ## Caractéristiques
 
@@ -10,6 +10,8 @@ Un générateur d'anagrammes prononçables en Rust pour créer des pseudonymes.
 - **Filtre les résultats** selon un score minimum de prononçabilité
 - **Retrait de lettres** : Supprime des lettres pour maximiser la prononçabilité
 - **Ajout de lettres** : Ajoute des voyelles ou lettres communes pour améliorer la prononçabilité
+- **Haute performance** : 3 modes de génération optimisés (standard, streaming, batch)
+- **Scalabilité** : Supporte jusqu'à 1 milliard de générations avec empreinte mémoire minimale
 - **Interface CLI** simple et intuitive
 - **46 tests unitaires** complets
 
@@ -31,16 +33,24 @@ cargo run -- --word <MOT> [OPTIONS]
 
 ### Options
 
+#### Options de base
 - `-w, --word <MOT>` : Le mot à partir duquel générer les anagrammes (optionnel - si absent, génère des mots aléatoires)
 - `-c, --count <NOMBRE>` : Nombre d'anagrammes/mots à générer (défaut: 10)
 - `-l, --length <NOMBRE>` : Longueur des mots aléatoires (défaut: 6, utilisé si --word non spécifié)
 - `-p, --prefix <PRÉFIXE>` : Préfixe pour commencer les mots aléatoires (utilisé uniquement si --word non spécifié)
 - `-s, --min-score <SCORE>` : Score minimum de prononçabilité (0-100, défaut: 50)
 - `-a, --max-attempts <NOMBRE>` : Nombre maximum de tentatives par anagramme (défaut: 1000)
+
+#### Options de transformation
 - `-r, --remove-letters <NOMBRE>` : Autoriser le retrait jusqu'à N lettres pour maximiser la prononçabilité
 - `--add-vowels <NOMBRE>` : Ajouter jusqu'à N voyelles pour maximiser la prononçabilité
 - `--add-letters <NOMBRE>` : Ajouter jusqu'à N lettres communes (voyelles + r,s,t,n,l) pour maximiser la prononçabilité
 
+#### Options de performance
+- `--streaming` : Mode streaming pour grandes quantités (mémoire constante ~10MB)
+- `--batch-size <NOMBRE>` : Mode batch avec taille de batch spécifiée (mémoire contrôlée)
+- `--progress` : Afficher la progression pour grandes générations
+
 ### Exemples
 
 Générer 10 anagrammes prononçables à partir du mot "exemple":
@@ -215,8 +225,45 @@ Le système de scoring évalue la prononçabilité selon plusieurs critères:
 Le système reconnaît ces clusters comme prononçables:
 bl, br, ch, cl, cr, dr, fl, fr, gl, gr, pl, pr, sc, sh, sk, sl, sm, sn, sp, st, sw, th, tr, tw, wh, wr
 
-## Tests
+## Modes de génération haute performance
 
+### Mode Standard (par défaut)
+Pour petites quantités (< 10k anagrammes) :
+```bash
+cargo run --release -- --word "programming" --count 1000
+```
+- Mémoire : ~1-10MB
+- Tous les résultats en mémoire et triés
+
+### Mode Streaming (recommandé pour 10k-100k)
+Génération à la demande avec faible latence :
+```bash
+cargo run --release -- --word "programming" --count 50000 --streaming --progress
+```
+- Mémoire : O(n) - croît avec le nombre d'anagrammes (~8 bytes par anagramme)
+- Résultats immédiats (latence très faible)
+- Déduplication 100%
+- ⚠️ Pour > 100k anagrammes, **préférer le mode batch** (mémoire contrôlée)
+
+### Mode Batch (recommandé pour > 100k)
+Traitement par batches pour très grandes quantités :
+```bash
+cargo run --release -- --word "algorithm" --count 10000000 --batch-size 100000 --progress
+```
+- Mémoire : proportionnelle au batch-size
+- Déduplication globale efficace
+- Idéal pour génération massive
+
+**Exemple extrême (1 milliard d'anagrammes)** :
+```bash
+cargo run --release -- --word "word" --count 1000000000 --batch-size 1000000 --progress > output.txt
+```
+
+Voir [docs/PERFORMANCE.md](docs/PERFORMANCE.md) pour plus de détails sur les optimisations.
+
+## Tests et benchmarks
+
+### Tests unitaires
 Exécuter les tests unitaires:
 
 ```bash
@@ -229,17 +276,44 @@ Exécuter les tests avec sortie détaillée:
 cargo test -- --nocapture
 ```
 
+### Benchmarks
+Exécuter les benchmarks de performance:
+
+```bash
+cargo bench
+```
+
+Les benchmarks comparent les performances des différents modes de génération.
+
 ## Structure du code
 
-- `PronounceabilityAnalyzer` : Analyse et score la prononçabilité des mots
-- `AnagramGenerator` : Génère des anagrammes aléatoires et filtre par prononçabilité
-- `Args` : Structure pour parser les arguments de ligne de commande avec clap
+Le projet suit les principes SOLID et Clean Code avec une architecture modulaire :
+
+- **`src/types.rs`** : Types de domaine (Anagram, PronouncabilityScore)
+- **`src/scorer.rs`** : Traits et configurations pour le scoring
+- **`src/analyzer.rs`** : Implémentation de l'analyse de prononçabilité
+- **`src/generator.rs`** : Générateur d'anagrammes (standard, streaming, batch)
+- **`src/error.rs`** : Gestion des erreurs
+- **`src/main.rs`** : Interface CLI
+- **`benches/`** : Benchmarks de performance
+
+Voir [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) pour une analyse détaillée de l'architecture.
+
+## Documentation
+
+- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** : Architecture et principes SOLID
+- **[PERFORMANCE.md](docs/PERFORMANCE.md)** : Optimisations et modes de génération
+- **[USAGE.md](docs/USAGE.md)** : Guide d'utilisation détaillé
 
 ## Dépendances
 
+### Production
 - `clap` (4.5) : Parsing des arguments de ligne de commande
 - `rand` (0.8) : Génération aléatoire pour mélanger les lettres
 
+### Développement
+- `criterion` (0.5) : Framework de benchmarking
+
 ## License
 
 MIT