CONFIGURATION.md

# Configuration de l'Application d'Annotation

Cette documentation explique comment configurer l'application pour un déploiement en production sur Hugging Face Spaces avec plusieurs annotateurs.

## Table des matières

1. [Vue d'ensemble](#vue-densemble)
2. [Étape 1 : Créer le Dataset de stockage](#étape-1--créer-le-dataset-de-stockage)
3. [Étape 2 : Configurer les Secrets HF](#étape-2--configurer-les-secrets-hf)
4. [Étape 3 : Configurer les Annotateurs](#étape-3--configurer-les-annotateurs)
5. [Étape 4 : Pousser sur HF Spaces](#étape-4--pousser-sur-hf-spaces)
6. [Utilisation pour les Annotateurs](#utilisation-pour-les-annotateurs)
7. [Récupération des Annotations](#récupération-des-annotations)

---

## Vue d'ensemble

L'application implémente 3 systèmes de sécurité et persistance :

1. **Authentification** : Mot de passe unique pour accéder à l'app
2. **Dispatch** : Chaque annotateur voit uniquement sa portion du dataset
3. **Persistance** : Sauvegarde automatique sur un Dataset HuggingFace privé

---

## Étape 1 : Créer le Dataset de stockage

1. Allez sur https://huggingface.co/new-dataset

2. Créez un nouveau dataset **PRIVÉ** :
   - Nom : `ffgen-annotations-storage` (ou autre)
   - Type : Dataset
   - Visibilité : **Private** ⚠️ Très important !

3. Laissez-le vide, l'app créera automatiquement la structure

---

## Étape 2 : Configurer les Secrets HF

### 2.1 Créer un Token HuggingFace

1. Allez dans vos settings HF : https://huggingface.co/settings/tokens
2. Créez un nouveau token avec les permissions **write**
3. Copiez le token (format : `hf_xxxxxxxxxxxx`)

### 2.2 Ajouter les Secrets dans le Space

1. Allez dans votre Space : `https://huggingface.co/spaces/VOTRE-USERNAME/feedbacks-scoring-app`
2. Cliquez sur **Settings**
3. Scrollez vers **Variables and secrets**
4. Ajoutez les secrets suivants :

| Nom | Valeur | Description |
|-----|--------|-------------|
| `APP_PASSWORD` | `VotreMotDePasse2025!` | Mot de passe pour accéder à l'app |
| `HF_TOKEN` | `hf_xxxxxxxxxxxx` | Token avec droits d'écriture |
| `HF_DATASET_REPO` | `VOTRE-USERNAME/ffgen-annotations-storage` | Nom du dataset de stockage |

**Important** :
- Le token doit avoir les droits d'écriture
- Le dataset doit être privé pour protéger les annotations

---

## Étape 3 : Configurer les Annotateurs

### Option A : Configuration automatique (recommandé)

Créez un fichier `annotators.json` dans le dossier `data/` :

```json
{
  "annotator_1": {
    "name": "Alice Dupont",
    "start_idx": 0,
    "end_idx": 100,
    "description": "Première portion du dataset"
  },
  "annotator_2": {
    "name": "Bob Martin",
    "start_idx": 100,
    "end_idx": 200,
    "description": "Deuxième portion"
  },
  "annotator_3": {
    "name": "Charlie Durand",
    "start_idx": 200,
    "end_idx": 300,
    "description": "Troisième portion"
  }
}
```

### Option B : Configuration via Secret HF

Ajoutez un secret `ANNOTATOR_CONFIG` avec la configuration JSON en une ligne :

```json
{"annotator_1":{"name":"Alice","start_idx":0,"end_idx":100},"annotator_2":{"name":"Bob","start_idx":100,"end_idx":200}}
```

### Utilisation du script de génération FFGen

Si vous avez déjà utilisé le script `create_annotation_study.py` de FFGen :

```bash
# Depuis FFGen/3_data_processing/
python create_annotation_study.py \
    matis35/code-feedback-infonce \
    --num-samples 300 \
    --num-subsets 3 \
    --output-dir annotation_study
```

Cela crée 3 subsets de ~100 items chacun + gold standard.

Pour l'app, configurez les annotateurs correspondants :
- annotator_1 : subset_01 (indices 0-100)
- annotator_2 : subset_02 (indices 100-200)
- annotator_3 : subset_03 (indices 200-300)

---

## Étape 4 : Pousser sur HF Spaces

1. Commitez tous les changements :
```bash
git add .
git commit -m "Add authentication, dispatch and HF persistence"
```

2. Poussez vers HF :
```bash
git push origin main
```

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

4. Une fois prêt, vérifiez que l'app démarre correctement

---

## Utilisation pour les Annotateurs

### Workflow complet

1. **Accès à l'application**
   - URL : `https://huggingface.co/spaces/VOTRE-USERNAME/feedbacks-scoring-app`
   - Entrer le mot de passe fourni

2. **Sélection de l'identité**
   - Choisir son identifiant dans la liste
   - Le système affiche automatiquement la portion assignée

3. **Chargement du dataset**
   - Option 1 : Upload d'un fichier JSONL
   - Option 2 : Chargement depuis HF Hub
   - Le dataset est automatiquement filtré selon la portion

4. **Annotation**
   - Scorer les feedbacks (1-5)
   - Ajouter des commentaires optionnels
   - La progression est sauvegardée automatiquement

5. **Sauvegarde**
   - **Importante** : Cliquer sur "☁️ Sauvegarder sur HF" régulièrement
   - Cette sauvegarde est permanente (survit aux redémarrages)
   - La sauvegarde locale est perdue tous les 48h

6. **Export (optionnel)**
   - Télécharger le JSONL en local pour backup

### Instructions à donner aux annotateurs

> **Bienvenue sur l'outil d'annotation FFGen !**
>
> 1. Mot de passe : `[VOTRE_MOT_DE_PASSE]`
> 2. Choisissez votre identifiant dans la liste
> 3. Chargez le dataset (demandez le lien HF ou le fichier)
> 4. Annotez les feedbacks selon les critères fournis
> 5. **Important** : Sauvegardez sur HF toutes les 30-60 minutes
> 6. Vous pouvez fermer et reprendre plus tard
>
> Questions ? Contactez [VOTRE_EMAIL]

---

## Récupération des Annotations

### Méthode 1 : Via HuggingFace Hub (recommandé)

1. Allez sur votre dataset de stockage :
   `https://huggingface.co/datasets/VOTRE-USERNAME/ffgen-annotations-storage`

2. Dans le dossier `annotations/`, vous trouverez tous les fichiers :
   - `annotation_annotator_1_20250127_143022.json`
   - `annotation_annotator_2_20250127_151533.json`
   - etc.

3. Téléchargez-les ou utilisez la CLI :
```bash
huggingface-cli download \
    VOTRE-USERNAME/ffgen-annotations-storage \
    --repo-type dataset \
    --local-dir ./annotations
```

### Méthode 2 : Via l'API Python

```python
from huggingface_hub import HfApi, hf_hub_download
import json

api = HfApi(token="hf_xxxxxxxxxxxx")

# Lister tous les fichiers
files = api.list_repo_files(
    repo_id="VOTRE-USERNAME/ffgen-annotations-storage",
    repo_type="dataset"
)

# Télécharger et charger chaque annotation
for file in files:
    if file.startswith("annotations/"):
        local_path = hf_hub_download(
            repo_id="VOTRE-USERNAME/ffgen-annotations-storage",
            filename=file,
            repo_type="dataset",
            token="hf_xxxxxxxxxxxx"
        )

        with open(local_path, 'r') as f:
            data = json.load(f)
            print(f"Annotator: {data['annotator_name']}")
            print(f"Scores: {len(data['scores'])}")
```

### Méthode 3 : Utiliser le script de merge FFGen

Si vous avez des gold items pour calculer l'accord inter-annotateurs :

```bash
cd FFGen/3_data_processing

# Analyser l'accord
python analyze_agreement.py \
    ../../annotations/annotation_*.json \
    --gold-file annotation_study/matis35_code-feedback-infonce_gold_standard.json

# Merger les scores
python merge_scores.py \
    ../../annotations/annotation_*.json \
    -o final_annotations.jsonl
```

---

## Dépannage

### Le Space ne démarre pas
- Vérifiez que tous les secrets sont bien configurés
- Regardez les logs du Space (onglet Logs)
- Vérifiez que le `HF_TOKEN` a les droits d'écriture

### L'authentification ne marche pas
- Vérifiez que `APP_PASSWORD` est bien dans les secrets
- Pas d'espaces avant/après le mot de passe

### La sauvegarde HF échoue
- Vérifiez que `HF_TOKEN` a les droits d'écriture
- Vérifiez que `HF_DATASET_REPO` existe et est privé
- Regardez les messages d'erreur dans l'app

### Un annotateur voit le dataset complet
- Vérifiez la configuration dans `annotators.json`
- Vérifiez que les indices start_idx/end_idx sont corrects
- Rechargez le dataset après modification de la config

### Les annotations sont perdues
- Rappelez aux annotateurs de sauvegarder sur HF
- La sauvegarde locale est réinitialisée tous les 48h
- Les sauvegardes HF sont permanentes

---

## Architecture Technique

```
┌─────────────────────────────────────────────────────────┐
│                    HF Space (Public)                     │
│  ┌────────────────────────────────────────────────────┐ │
│  │  1. Authentification (APP_PASSWORD)                │ │
│  │      ↓                                              │ │
│  │  2. Sélection Annotateur                           │ │
│  │      ↓                                              │ │
│  │  3. Filtrage Dataset (start_idx, end_idx)          │ │
│  │      ↓                                              │ │
│  │  4. Interface d'Annotation                         │ │
│  │      ↓                                              │ │
│  │  5. Sauvegarde Cloud (HF_TOKEN)                    │ │
│  └────────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────┐
│      HF Dataset (Private): annotations-storage          │
│  ┌────────────────────────────────────────────────────┐ │
│  │  annotations/                                       │ │
│  │    ├── annotation_annotator_1_timestamp.json       │ │
│  │    ├── annotation_annotator_2_timestamp.json       │ │
│  │    └── annotation_annotator_3_timestamp.json       │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```

---

## Sécurité et Bonnes Pratiques

✅ **À faire** :
- Utiliser des mots de passe forts (12+ caractères)
- Garder le dataset de stockage **PRIVÉ**
- Révoquer les tokens après l'étude
- Sauvegarder régulièrement sur HF
- Tester avec un annotateur avant le déploiement complet

❌ **À éviter** :
- Partager le token HF publiquement
- Utiliser le même mot de passe que vos autres comptes
- Rendre le dataset de stockage public
- Compter uniquement sur la sauvegarde locale
- Modifier la config en cours d'annotation

---

## Support

Pour toute question ou problème :
- Issues GitHub : [LIEN_REPO]
- Email : [VOTRE_EMAIL]
- Documentation FFGen : `FFGen/README.md`