QUICKSTART.md

# Guide de Démarrage Rapide

Configuration en 5 minutes pour déployer l'application d'annotation sécurisée.

## Prérequis

- Un compte HuggingFace
- Accès à votre Space `matis35/feedbacks-scoring-app`
- Le dataset à annoter (format JSONL ou sur HF Hub)

## Étape 1 : Créer le Dataset de Stockage (2 min)

1. Allez sur https://huggingface.co/new-dataset
2. Nom : `ffgen-annotations-storage`
3. Visibilité : **Private** (très important!)
4. Cliquez sur "Create dataset"
5. Laissez-le vide, ne chargez rien

✅ Vous avez maintenant : `matis35/ffgen-annotations-storage`

## Étape 2 : Créer un Token HF (1 min)

1. Allez sur https://huggingface.co/settings/tokens
2. Cliquez "New token"
3. Nom : `annotation-app-write`
4. Type : **Write** (important!)
5. Cliquez "Generate token"
6. **Copiez le token** (format `hf_xxxxxxxxxxxx`)

⚠️ Gardez ce token en sécurité, ne le partagez pas!

## Étape 3 : Configurer les Secrets (2 min)

1. Allez sur votre Space : https://huggingface.co/spaces/matis35/feedbacks-scoring-app
2. Cliquez sur **Settings** (en haut)
3. Scrollez vers "Variables and secrets"
4. Ajoutez ces 3 secrets :

### Secret 1 : APP_PASSWORD
- Nom : `APP_PASSWORD`
- Valeur : Choisissez un mot de passe fort (ex: `Annotator2025!`)
- Type : Secret

### Secret 2 : HF_TOKEN
- Nom : `HF_TOKEN`
- Valeur : Le token copié à l'étape 2 (`hf_xxxxx`)
- Type : Secret

### Secret 3 : HF_DATASET_REPO
- Nom : `HF_DATASET_REPO`
- Valeur : `matis35/ffgen-annotations-storage`
- Type : Secret

✅ Les 3 secrets doivent être visibles dans la liste

## Étape 4 : Configurer les Annotateurs (2 min)

### Option A : Configuration basique (3 annotateurs)

Copiez le fichier exemple :
```bash
cd feedbacks-scoring-app
cp data/annotators.json.example data/annotators.json
```

Éditez `data/annotators.json` selon votre dataset :
```json
{
  "annotator_1": {
    "name": "Alice",
    "start_idx": 0,
    "end_idx": 100
  },
  "annotator_2": {
    "name": "Bob",
    "start_idx": 100,
    "end_idx": 200
  },
  "annotator_3": {
    "name": "Charlie",
    "start_idx": 200,
    "end_idx": 300
  }
}
```

### Option B : Utiliser vos subsets FFGen

Si vous avez utilisé `create_annotation_study.py` :

```bash
# Vous avez créé 10 subsets avec create_annotation_study.py
# Configurez 10 annotateurs correspondants

# Exemple pour 10 annotateurs, 40 items chacun
python -c "
import json

config = {}
for i in range(10):
    config[f'annotator_{i+1}'] = {
        'name': f'Annotateur {i+1}',
        'start_idx': i * 40,
        'end_idx': (i + 1) * 40,
        'description': f'Subset {i+1}/10'
    }

with open('data/annotators.json', 'w') as f:
    json.dump(config, f, indent=2)

print('✅ Config créée pour 10 annotateurs')
"
```

## Étape 5 : Pousser sur HF (1 min)

```bash
cd feedbacks-scoring-app

# Vérifier les changements
git status

# Commiter
git add .
git commit -m "Add secure authentication and HF persistence"

# Pousser vers HF Spaces
git push origin main
```

Le Space va rebuilder automatiquement (3-5 minutes).

## Étape 6 : Tester (2 min)

1. Attendez que le Space soit "Running" (vert)
2. Ouvrez l'app : https://huggingface.co/spaces/matis35/feedbacks-scoring-app
3. Testez la connexion :
   - Entrez le mot de passe (`APP_PASSWORD`)
   - Sélectionnez un annotateur
   - Vérifiez que ça fonctionne

## Étape 7 : Distribuer aux Annotateurs

Envoyez ce message à vos annotateurs :

```
Bonjour,

Voici les informations pour accéder à l'outil d'annotation :

URL : https://huggingface.co/spaces/matis35/feedbacks-scoring-app
Mot de passe : [VOTRE_APP_PASSWORD]
Votre identifiant : [annotator_X]

Instructions :
1. Ouvrez l'URL et entrez le mot de passe
2. Sélectionnez votre identifiant dans la liste
3. Chargez le dataset (je vous enverrai le lien/fichier)
4. Annotez les feedbacks selon les critères ci-dessous
5. IMPORTANT : Cliquez sur "☁️ Sauvegarder sur HF" toutes les 30-60 minutes
6. Vous pouvez fermer et reprendre plus tard

Critères d'annotation :
- Score 1 : [DÉFINIR]
- Score 2 : [DÉFINIR]
- Score 3 : [DÉFINIR]
- Score 4 : [DÉFINIR]
- Score 5 : [DÉFINIR]

Questions ? Contactez-moi : [VOTRE_EMAIL]
```

## Vérification Post-Déploiement

✅ Checklist de vérification :

- [ ] Le Space démarre sans erreur
- [ ] L'authentification fonctionne
- [ ] La sélection d'annotateur fonctionne
- [ ] Le chargement de dataset fonctionne
- [ ] Le filtrage par portion fonctionne (vérifier les nombres)
- [ ] La sauvegarde HF fonctionne (vérifier dans le dataset)
- [ ] L'export JSONL fonctionne
- [ ] Les annotateurs peuvent se connecter

## Commandes Utiles

### Voir les logs du Space
```bash
# Via l'interface web : Settings > Logs
# Ou regarder en temps réel depuis l'onglet "Logs"
```

### Vérifier les annotations sauvegardées
```bash
# Allez sur : https://huggingface.co/datasets/matis35/ffgen-annotations-storage
# Vous devriez voir un dossier annotations/ avec des fichiers .json
```

### Télécharger toutes les annotations
```bash
huggingface-cli download \
    matis35/ffgen-annotations-storage \
    --repo-type dataset \
    --local-dir ./collected_annotations
```

### Analyser l'accord inter-annotateurs (si gold items)
```bash
cd FFGen/3_data_processing

python analyze_agreement.py \
    ../../collected_annotations/annotations/*.json \
    --gold-file annotation_study/gold_standard.json
```

## Dépannage Express

### Le Space ne démarre pas
```bash
# Vérifiez les logs
# Problème courant : secret mal configuré
# Solution : Vérifiez Settings > Variables and secrets
```

### "HF Storage not configured"
```bash
# Il manque HF_TOKEN ou HF_DATASET_REPO
# Ajoutez-les dans Settings > Secrets
```

### "Authentication failed"
```bash
# APP_PASSWORD incorrect ou manquant
# Vérifiez Settings > Secrets
```

### Un annotateur voit tout le dataset
```bash
# Problème dans annotators.json
# Vérifiez start_idx et end_idx
# Rechargez le dataset après correction
```

### Les annotations disparaissent
```bash
# Les annotateurs n'ont pas sauvegardé sur HF
# Rappelez-leur de cliquer sur "☁️ Sauvegarder sur HF"
# La sauvegarde locale est perdue tous les 48h
```

## Support

Documentation complète : [CONFIGURATION.md](CONFIGURATION.md)

Problèmes ?
- Vérifiez d'abord les logs du Space
- Consultez la section Dépannage de CONFIGURATION.md
- Ouvrez une issue GitHub si nécessaire

---

**Temps total : ~15 minutes**

Prochain fichier à lire : [CONFIGURATION.md](CONFIGURATION.md) pour les détails complets.