anagram-generator/docs/USAGE.md

# Guide d'utilisation

## Installation et compilation

```bash
# Compiler en mode release (optimisé)
cargo build --release

# L'exécutable se trouve dans
target/release/anagram-generator
```

## Utilisation basique

### Générer des anagrammes d'un mot
```bash
# 10 anagrammes par défaut
cargo run --release -- --word "programming"

# Spécifier le nombre d'anagrammes
cargo run --release -- --word "programming" --count 100

# Avec un score minimum de prononçabilité
cargo run --release -- --word "programming" --count 50 --min-score 60
```

### Générer des mots aléatoires prononçables
```bash
# 10 mots de 6 lettres par défaut
cargo run --release

# Spécifier la longueur et le nombre
cargo run --release -- --count 20 --length 8

# Avec un préfixe
cargo run --release -- --count 10 --prefix "sup"

# Avec un score minimum
cargo run --release -- --count 50 --min-score 70
```

## Modes de génération avancés

### Mode Streaming (recommandé pour > 10k anagrammes)

Le mode streaming génère les anagrammes à la demande avec une mémoire plafonnée.

```bash
# Générer 1 million d'anagrammes en streaming
cargo run --release -- --word "programming" --count 1000000 --streaming

# Avec indicateur de progression
cargo run --release -- --word "programming" --count 1000000 --streaming --progress

# Rediriger vers un fichier
cargo run --release -- --word "programming" --count 10000000 --streaming > anagrams.txt
```

**Avantages** :
- Mémoire plafonnée (~8MB maximum)
- Premiers résultats immédiats
- Idéal pour pipeline avec autres outils

**⚠️ Important - Déduplication limitée** :
- Les **100 000 premiers** anagrammes sont garantis **uniques**
- Au-delà, des **duplicatas peuvent apparaître** (la mémoire reste constante à ~8MB)
- Pour une déduplication **100% complète**, utilisez le **mode batch** à la place

### Mode Batch (recommandé pour > 1M anagrammes)

Le mode batch traite les anagrammes par groupes pour optimiser la mémoire.

```bash
# Générer 10 millions d'anagrammes par batches de 100k
cargo run --release -- --word "programming" --count 10000000 --batch-size 100000

# Avec progression
cargo run --release -- --word "programming" --count 10000000 --batch-size 100000 --progress

# Batch size optimal selon RAM disponible
# RAM 4GB : batch-size 50000-100000
# RAM 8GB : batch-size 100000-500000
# RAM 16GB+ : batch-size 500000-1000000
```

**Avantages** :
- Mémoire contrôlée (proportionnelle au batch size)
- Déduplication globale
- Idéal pour très grandes générations

### Mode Standard (recommandé pour < 10k anagrammes)

Mode par défaut, tous les anagrammes en mémoire.

```bash
# Simple et rapide pour petites quantités
cargo run --release -- --word "programming" --count 1000
```

## Options de transformation

### Suppression de lettres

Permet de retirer des lettres pour améliorer la prononçabilité.

```bash
# Autoriser la suppression de jusqu'à 2 lettres
cargo run --release -- --word "programming" --count 50 --remove-letters 2

# Utile pour mots difficiles
cargo run --release -- --word "strengths" --count 20 --remove-letters 3 --min-score 70
```

### Ajout de voyelles

Ajoute des voyelles pour améliorer la prononçabilité.

```bash
# Ajouter jusqu'à 2 voyelles
cargo run --release -- --word "rhythm" --count 30 --add-vowels 2

# Combiné avec score minimum
cargo run --release -- --word "crypt" --count 20 --add-vowels 2 --min-score 65
```

### Ajout de lettres communes

Ajoute des voyelles et consonnes communes (r, s, t, n, l).

```bash
# Ajouter jusqu'à 3 lettres communes
cargo run --release -- --word "xyz" --count 50 --add-letters 3 --min-score 60
```

## Configuration avancée

### Nombre de tentatives

Contrôle le nombre d'essais pour générer chaque anagramme.

```bash
# Augmenter pour mots difficiles ou scores élevés
cargo run --release -- --word "xyz" --count 10 --max-attempts 5000 --min-score 70

# Réduire pour génération plus rapide (au risque de générer moins d'anagrammes)
cargo run --release -- --word "hello" --count 100 --max-attempts 500
```

## Exemples d'utilisation avancée

### Pipeline avec tri et filtrage
```bash
# Générer, filtrer et trier
cargo run --release -- --word "programming" --count 10000 --streaming \
  | grep -v "^[0-9]*\. .*x" \
  | sort -t':' -k2 -nr
```

### Génération massive vers fichier
```bash
# 100 millions d'anagrammes en streaming
cargo run --release -- \
  --word "algorithm" \
  --count 100000000 \
  --streaming \
  --progress \
  --min-score 55 \
  > anagrams_100M.txt 2> progress.log
```

### Génération par batches avec traitement
```bash
# Traiter chaque batch séparément
cargo run --release -- \
  --word "computer" \
  --count 50000000 \
  --batch-size 1000000 \
  --progress \
  | split -l 1000000 - batch_
```

### Comparaison de performance
```bash
# Mode standard (petite quantité)
time cargo run --release -- --word "test" --count 1000

# Mode streaming (grande quantité)
time cargo run --release -- --word "test" --count 100000 --streaming > /dev/null

# Mode batch (très grande quantité)
time cargo run --release -- --word "test" --count 1000000 --batch-size 100000 > /dev/null
```

## Benchmarks

### Exécuter les benchmarks de performance
```bash
cargo bench
```

Les benchmarks comparent :
- Génération standard vs streaming
- Différentes tailles de batches
- Impact mémoire

### Résultats typiques (indicatifs)

| Mode | Quantité | Temps | Mémoire |
|------|----------|-------|---------|
| Standard | 1,000 | ~0.5s | ~5MB |
| Standard | 10,000 | ~5s | ~50MB |
| Streaming | 100,000 | ~50s | ~10MB |
| Streaming | 1,000,000 | ~8min | ~10MB |
| Batch (100k) | 10,000,000 | ~80min | ~50MB |

## Recommandations

### Pour développement et tests
```bash
cargo run --release -- --word "test" --count 100 --min-score 60
```

### Pour génération quotidienne
```bash
cargo run --release -- --word "myword" --count 10000 --streaming --progress
```

### Pour génération massive
```bash
cargo run --release -- \
  --word "myword" \
  --count 100000000 \
  --batch-size 1000000 \
  --progress \
  --min-score 50 \
  > output.txt 2> progress.log
```

### Pour mots difficiles
```bash
cargo run --release -- \
  --word "difficultword" \
  --count 1000 \
  --remove-letters 2 \
  --add-vowels 1 \
  --max-attempts 5000 \
  --min-score 65
```

## Aide complète

```bash
# Afficher toutes les options
cargo run --release -- --help
```

## Dépannage

### Peu d'anagrammes générés
```bash
# Solutions :
# 1. Réduire le score minimum
--min-score 40

# 2. Augmenter les tentatives
--max-attempts 5000

# 3. Activer les transformations
--remove-letters 2 --add-vowels 1
```

### Performance lente
```bash
# Solutions :
# 1. Compiler en mode release
cargo build --release

# 2. Utiliser le mode streaming pour grandes quantités
--streaming

# 3. Utiliser des batches plus petits
--batch-size 50000
```

### Mémoire insuffisante
```bash
# Solutions :
# 1. Utiliser le mode streaming
--streaming

# 2. Réduire la taille des batches
--batch-size 10000

# 3. Rediriger vers fichier au lieu de garder en mémoire
> output.txt
```