# Universal AI Language Exam Framework (UALEF)

## Version
- Framework: v0.5
- Date: 2025-10-30
- Status: Core concepts defined, implementation pending

## Overview

Framework universel pour générer, administrer et corriger des exams de langue avec l'aide de l'IA.

## Workflow Core (A → Z)

### INPUT
Travail du mois (chapters complétés pour un segment donné)

### STEP 1: Génération Exam (AI)
- **Input** : Chapters complétés durant le mois pour un segment (ex: Hanyu Ch 1, 3, 4, 5)
- **Process** :
  - AI scan le contenu des chapters (vocab, grammar, textes)
  - AI génère exam selon **Global Segment Framework** (structure définie par type de segment)
  - AI produit un fichier JSON structuré avec toutes les questions
- **Output** : `Exams/{Segment}/YYYY-MM/exam.json`
- **Validation** : Script vérifie structure JSON avant publication

### STEP 2: Passage Exam (Étudiant)
- **Input** : `exam.json` (questions générées par AI)
- **Process** :
  - Étudiant copie `exam.json` → `exam-answers.json`
  - Étudiant charge le fichier dans interface HTML
  - Étudiant remplit les champs `"answer": "..."` pour chaque question
  - Interface sauvegarde automatiquement les réponses
- **Output** : `Exams/{Segment}/YYYY-MM/exam-answers.json` (complet)

### STEP 3: Correction AI
- **Input** : `exam-answers.json` (contient questions + réponses étudiant)
- **Process** :
  - AI évalue chaque réponse selon critères du **Global Segment Framework**
  - AI attribue un score (`rate`) pour chaque question
  - AI génère feedback détaillé par exercice
  - AI calcule score total et statut (PASS/DIFFICULTY/CRITICAL)
- **Output** : `Exams/{Segment}/YYYY-MM/exam-corrected.json`

### OUTPUT
- Score total /100
- Statut : PASS (>80%) / DIFFICULTY (50-80%) / CRITICAL (<50%)
- Feedback détaillé par exercice
- Recommandations pour amélioration

---

## Concepts Clés

### 1. Segment Types
Deux types de segments existent dans un système d'apprentissage :

#### **Skill Segments** (Direct)
Segments qui correspondent à une compétence linguistique spécifique
- **Objectif** : Développer une skill directe (parler, écrire, lire, écouter)
- **Évaluation** : Performance dans cette skill
- **Exemples** :
  - Kouyu (Speaking): pronunciation, fluency, naturalness, grammar
  - Tingli (Listening): comprehension, detail retention, inference
  - Xiezuo (Writing): grammar, vocabulary, coherence, structure
  - LEDU (Reading): comprehension, speed, inference, vocabulary

#### **Foundation Segments** (Enabler)
Segments qui servent de base pour développer les skills
- **Objectif** : Construire les fondations (grammaire, vocabulaire, structures)
- **Évaluation** : Compréhension et application des concepts
- **Exemples** :
  - Hanyu Jiaocheng: grammar mastery, vocabulary retention, structure comprehension
  - General language courses qui ne focusent pas sur une skill spécifique

**Important** : Les Foundation segments ne testent pas la production libre mais la compréhension et l'application contrôlée des concepts.

### 2. Segment Framework (Global)
Standards généraux pour chaque segment (adapté selon le type)

### 3. Correction Framework (Spécifique)
Généré avec chaque exam, inclut:
- Réponses attendues
- Rubrique de scoring détaillée
- Points clés à évaluer
- Barèmes spécifiques

### 4. Double Framework Approach
- **Global Segment Framework** = cohérence et standards
- **Correction Framework** = flexibilité et spécificité
- Combinaison = correction juste et adaptée

---

## Avantages du Système

✅ **Scalable**: Fonctionne pour n'importe quel segment, n'importe quelle langue
✅ **Consistent**: Double framework assure cohérence des corrections
✅ **Flexible**: Correction framework s'adapte au contenu spécifique
✅ **Transparent**: Critères clairs dès la génération de l'exam
✅ **AI-Assisted**: Correction rapide et détaillée avec feedback actionnable

---

## Technical Implementation

### Format & Storage

**Format universel** : JSON + HTML interface

**Structure des fichiers** :
```
Exams/
  ├── Foundation/
  │   └── YYYY-MM/
  │       ├── exam.json              # Généré par AI
  │       ├── exam-answers.json      # Rempli par étudiant
  │       └── exam-corrected.json    # Généré par AI
  ├── Speaking/
  │   └── YYYY-MM/
  │       ├── exam.json
  │       ├── exam-answers.json
  │       └── exam-corrected.json
  ├── Reading/
  │   └── YYYY-MM/ ...
  └── [autres segments]/
      └── YYYY-MM/ ...
```

**Fichiers** :
1. **exam.json** : Questions + structure, généré par AI
2. **exam-answers.json** : Copie de exam.json + réponses de l'étudiant
3. **exam-corrected.json** : Même structure + scores (`rate`) + feedback

### Structure JSON Universelle

Tous les exams suivent cette structure de base :

```json
{
  "metadata": {
    "exam_id": "{segment}-{YYYY-MM}",
    "month": "YYYY-MM",
    "segment": "{segment_name}",
    "segment_type": "foundation|skill",
    "chapters_covered": ["1", "3", "4", "5"],
    "generated_date": "YYYY-MM-DD",
    "total_points": 100
  },
  "exercices": {
    "exercice1_name": {
      "total_points": X,
      "items": {
        "item1": {
          "question_data": "...",
          "expected": "...",
          "points": X,
          "answer": "",      // Rempli par étudiant
          "rate": null       // Rempli par AI lors de correction
        },
        "item2": { ... }
      }
    },
    "exercice2_name": { ... }
  },
  "correction": {
    "total_score": null,           // Rempli par AI
    "status": null,                // PASS|DIFFICULTY|CRITICAL
    "feedback_by_exercice": {},    // Rempli par AI
    "overall_feedback": "",        // Rempli par AI
    "strengths": [],               // Rempli par AI
    "weaknesses": [],              // Rempli par AI
    "recommendations": []          // Rempli par AI
  }
}
```

**Champs clés** :
- **Question data** : Généré par AI (varie selon exercice)
- **answer** : Rempli par étudiant dans `exam-answers.json`
- **rate** : Rempli par AI dans `exam-corrected.json` (score obtenu)

### Validation

#### Validation Structurelle (mécanique)
Comme un compilateur, vérifie la structure sans évaluer le contenu :

- ✅ JSON est parsable
- ✅ Metadata complet (exam_id, month, segment, chapters, etc.)
- ✅ Tous les exercices définis dans le Segment Framework sont présents
- ✅ Chaque exercice a le bon nombre d'items (selon framework)
- ✅ Structure rigide respectée (ex: `item1`, `item2`, ..., `itemN` - pas de tableaux)
- ✅ Tous les champs requis existent et ne sont pas vides

**Avantage structure rigide** :
```json
// ❌ Mauvais (array - AI peut oublier des éléments)
"words": [
  { "l1": "parler", "l2": "说" },
  // Oups, AI a oublié word #8
]

// ✅ Bon (objets nommés - impossible d'oublier)
"words": {
  "word1": { "l1": "parler", "l2": "说" },
  "word2": { "l1": "ami", "l2": "朋友" },
  ...
  "word20": { "l1": "livre", "l2": "书" }
}
```

#### Validation de Contenu (basique)
Vérifications simples et mécaniques :

- ✅ Textes ont longueur minimum (ex: >100 caractères)
- ✅ Total des points = 100
- ✅ Chaque item a un score `points` > 0
- ✅ Champs texte ne sont pas vides (question_data, expected, etc.)

#### Validation de Qualité (optionnelle)
**Stratégie initiale** : Trust & Iterate
- Pas de validation AI-to-AI au début
- Si problèmes récurrents → ajouter AI review ou ajuster prompts

**Si nécessaire plus tard** :
- AI-2 review la qualité du contenu généré par AI-1
- Checklist : grammaire, niveau approprié, cohérence, etc.

#### Script de Validation
À créer : `validate-exam.js` ou `validate-exam.py`

Usage :
```bash
node validate-exam.js Exams/Foundation/2025-01/exam.json
# Output: ✅ Valid ou ❌ Errors with details
```

### Génération par AI

**Input requis** :
- Liste des chapters complétés durant le mois
- Contenu des chapters (vocab lists, grammar structures, textes)
- Global Segment Framework (structure de l'exam à générer)

**Process** :
1. AI lit les chapters et extrait le contenu pertinent
2. AI génère exam selon structure rigide du Segment Framework
3. AI produit `exam.json` avec structure complète
4. Script de validation vérifie le JSON
5. Si ✅ valid → exam publié, si ❌ errors → regénération ou correction

**Prompt pattern** (à définir pour chaque segment) :
```
Generate an exam for {segment} segment based on chapters {list}.

Output format: JSON following this EXACT structure:
{structure template}

Requirements:
- Use ONLY vocabulary and grammar from the provided chapters
- Follow the rigid structure (word1, word2, ... wordN)
- Ensure all fields are filled
- Total points must equal 100

Chapters content:
{chapters data}
```

### Correction par AI

**Input** : `exam-answers.json` (contient questions + réponses étudiant)

**Process** :
1. AI évalue chaque réponse selon critères du Global Segment Framework
2. AI attribue `rate` (score obtenu) pour chaque item
3. AI génère feedback par exercice
4. AI calcule score total
5. AI détermine statut (PASS/DIFFICULTY/CRITICAL)
6. AI produit recommandations

**Output** : `exam-corrected.json` avec :
- Champs `rate` remplis partout
- Section `correction` complète
- Feedback actionnable et détaillé

**Prompt pattern** (à définir pour chaque segment) :
```
Correct this exam based on the Global Segment Framework.

Exam with student answers:
{exam-answers.json}

Segment Framework criteria:
{criteria}

For each answer:
1. Evaluate according to criteria
2. Assign rate (score earned)
3. Provide specific feedback if incorrect

Then provide:
- Total score
- Status (PASS >80%, DIFFICULTY 50-80%, CRITICAL <50%)
- Overall feedback
- Strengths and weaknesses
- Recommendations for improvement

Output format: JSON (same structure with rate + correction fields filled)
```

---

## Questions Restantes

1. **Global Segment Framework** :
   - ✅ Structure JSON définie
   - ❓ Contenu spécifique pour chaque Skill Segment (Speaking, Writing, etc.)

2. **Interface HTML** :
   - Comment charger exam.json
   - Comment sauvegarder exam-answers.json
   - Auto-save et validation côté client

3. **Prompts détaillés** :
   - Prompt de génération spécifique par segment
   - Prompt de correction spécifique par segment

---

## Prochaines Étapes

- [x] Définir workflow universel A→Z
- [x] Définir format et storage (JSON + fichiers)
- [x] Définir structure JSON universelle
- [x] Définir stratégie de validation (structurelle + contenu + qualité)
- [ ] Créer Foundation Segment Framework complet (structure JSON détaillée)
- [ ] Créer Skill Segment Frameworks (Speaking, Reading, Writing, Listening)
- [ ] Créer scripts de validation
- [ ] Définir prompts de génération par segment
- [ ] Définir prompts de correction par segment
- [ ] Créer interface HTML
- [ ] Tester avec exam pilote (Foundation)
- [ ] Itérer et raffiner

---

## Notes

Ce framework est conçu pour être universel et s'adapter à n'importe quel apprentissage de langue, pas seulement le chinois. Il peut être adapté pour d'autres systèmes d'apprentissage utilisant l'IA comme assistant pédagogique.