linear-coding-agent/generations/library_rag/docs_techniques/analyse_collections.md

# Analyse de Cohérence des Collections Weaviate

**Date**: 2025-12-09
**Analysé**: 3 collections, 51 objets

---

## Résumé Exécutif

### Problèmes Critiques Identifiés

1. **Désynchronisation schéma défini vs schéma réel** - Le schéma dans `schema.py` ne correspond PAS au schéma actuel dans Weaviate
2. **Collection Section manquante** - Définie dans `schema.py` mais inexistante dans Weaviate
3. **Collection Work inutilisée** - 0 objets, redondante avec les autres collections
4. **Duplication massive de données** - author/work répétés 50 fois au lieu d'utiliser des références
5. **Métadonnées vides** - TOC et hiérarchie non exploitées
6. **Auto-schema non contrôlé** - Propriétés ajoutées automatiquement sans validation

---

## 1. Collection Document

### Configuration Actuelle
- **Vectorizer**: `TEXT2VEC_TRANSFORMERS` ⚠️
- **Objets**: 1
- **Auto-generated**: OUI (toutes les propriétés)

### ❌ Problèmes Identifiés

#### 1.1 Schéma Auto-Généré
```
"This property was generated by Weaviate's auto-schema feature on Fri Dec 5 16:10:30 2025"
```
- Le schéma réel n'a **PAS été créé** via `schema.py`
- Weaviate a auto-généré le schéma lors de l'insertion
- **Conséquence**: Perte de contrôle sur les types et la configuration

#### 1.2 Vectorizer Incorrect
**Attendu** (schema.py:21):
```python
vectorizer_config=wvc.Configure.Vectorizer.none()
```

**Réel**:
```
Vectorizer: TEXT2VEC_TRANSFORMERS
```

**Impact**: Vectorisation inutile des métadonnées → gaspillage de ressources

#### 1.3 Skip Vectorization Ignoré
**Attendu** (schema.py:85-86):
```python
skip_vectorization=True  # Pour sectionPath et title
```

**Réel**:
```
Toutes les propriétés: Skip Vectorization = ❌
```

**Impact**: Toutes les métadonnées sont vectorisées inutilement

#### 1.4 Données Vides/Invalides
```json
{
  "toc": "[]",              // ❌ Vide alors que le document a une TOC
  "hierarchy": "{}",         // ❌ Vide alors que le document a une hiérarchie
  "pages": 0.0,              // ❌ Devrait être > 0
  "chunksCount": 50.0        // ⚠️ Float au lieu de INT
}
```

#### 1.5 Type DATE Perdu
**Attendu** (schema.py:66):
```python
data_type=wvc.DataType.DATE
```

**Réel**:
```
createdAt: TEXT
```

**Impact**: Impossible de filtrer par date efficacement

---

## 2. Collection Passage

### Configuration Actuelle
- **Vectorizer**: `TEXT2VEC_TRANSFORMERS` ✅
- **Objets**: 50
- **Description**: Correcte

### ⚠️ Problèmes Identifiés

#### 2.1 Propriétés Non-Définies Ajoutées
Le schéma dans `schema.py` définit 9 propriétés, mais Weaviate en a **12**:

**Propriétés supplémentaires auto-générées**:
- `chapterTitle` (TEXT)
- `chapterConcepts` (TEXT_ARRAY)
- `sectionLevel` (NUMBER)

**Problème**: Ces propriétés ne sont pas dans le schéma original et ont été ajoutées automatiquement sans validation.

#### 2.2 Skip Vectorization Non Respecté
Selon `schema.py`, AUCUNE propriété de Passage ne devrait avoir `skip_vectorization=True`.

**Réel**: Toutes les propriétés sont vectorisées ✅ (correct)

#### 2.3 Duplication Massive de Données

**author** répété 50 fois:
```json
"author": "Platon"  // x50 passages
```

**work** répété 50 fois:
```json
"work": "Ménon ou de la vertu"  // x50 passages
```

**Impact**:
- Gaspillage d'espace (50 × ~20 octets = 1 Ko juste pour author)
- Pas de normalisation
- Impossible de changer l'auteur globalement
- Pas de relation avec la collection Work

#### 2.4 Données Incohérentes

**orderIndex**:
- Min: 1, Max: 49 (attendu: 0-49 pour 50 chunks)
- ⚠️ Manque l'index 0 OU l'index 50

**keywords**:
- Parfois vide `[]` (11 passages)
- Pas de normalisation

**chapterConcepts**:
- **TOUJOURS vide** `[]` pour tous les passages
- Feature non utilisée → propriété inutile

**unitType**:
- 5 valeurs: `exposition`, `main_content`, `argument`, `transition`, `définition`
- Pas de validation (pourrait contenir n'importe quoi)

**section**:
- 13 valeurs uniques pour 50 passages
- Très variable: `"SOCRATE"`, `"MENON"`, `"Qu'est-ce que la vertu?"`, etc.
- Pas de format standard

---

## 3. Collection Work

### Configuration Actuelle
- **Vectorizer**: `NONE` ✅
- **Objets**: **0** ❌
- **Schéma**: Correct

### 🚨 Problèmes Critiques

#### 3.1 Collection Complètement Inutilisée
```
Nombre d'objets: 0
```

**Pourquoi existe-t-elle?**
- Définie dans `schema.py`
- Jamais utilisée par `weaviate_ingest.py`

#### 3.2 Redondance Totale
Les informations de Work sont **dupliquées** dans:
1. **Document.author** + **Document.title**
2. **Passage.author** + **Passage.work** (x50)

**Solution attendue**: Utiliser Work comme source unique avec des références croisées.

#### 3.3 Propriétés Inutiles
```python
year: INT              # Jamais renseigné
edition: TEXT          # Jamais renseigné
referenceSystem: TEXT  # Jamais renseigné
```

---

## 4. Collection Section (Manquante!)

### 🚨 Définie mais Inexistante

**Dans schema.py** (lignes 74-120):
```python
client.collections.create(
    name="Section",
    description="A section/chapter with its summary and key concepts...",
    ...
)
```

**Dans Weaviate**:
```
Collections: Document, Passage, Work
```

**Section est ABSENTE!**

### Impact
- Impossible de faire des résumés de chapitres vectorisés
- Perte de la hiérarchie structurée
- Feature complète non implémentée

---

## 5. Problèmes de Conception Architecturale

### 5.1 Absence de Relations Croisées

**Attendu** (architecture normalisée):
```
Work (1) ──< Document (N) ──< Passage (N)
           └──< Section (N) ──< Passage (N)
```

**Réel**:
```
Document (1)  [pas de lien]
Passage (50)  [pas de lien]
Work (0)      [vide]
Section       [manquant]
```

**Conséquence**: Impossible de naviguer entre collections

### 5.2 Pas de Cross-References
Weaviate v4 supporte les références croisées, mais elles ne sont **pas utilisées**:

```python
# Ce qu'on devrait avoir dans Passage:
wvc.Property(
    name="document",
    data_type=wvc.DataType.REFERENCE,
    references="Document"
)
```

### 5.3 Duplication vs Normalisation

**Taille actuelle (estimée)**:
- Document: 1 × ~500 octets = 500 B
- Passage: 50 × ~600 octets = 30 Ko
- **Total dupliqué**: author (50×) + work (50×) ≈ 2 Ko de redondance

**Avec normalisation**:
- Work: 1 objet avec author + title
- Passage: Référence UUID vers Work
- **Économie**: ~1.5 Ko + meilleure intégrité

---

## 6. Analyse des Données

### 6.1 Document "Platon_-_Menon_trad._Cousin"

```json
{
  "title": "Ménon ou de la vertu",
  "author": "Platon",
  "sourceId": "Platon_-_Menon_trad._Cousin",
  "language": "fr",
  "pages": 0.0,           // ❌ Invalide
  "chunksCount": 50.0,    // ✅ Mais devrait être INT
  "toc": "[]",            // ❌ Vide
  "hierarchy": "{}",      // ❌ Vide
  "createdAt": "2025-12-09T09:20:30.970580"
}
```

**Problèmes**:
1. `pages: 0` → Le PDF avait forcément des pages
2. `toc: "[]"` → Le système extrait une TOC (voir `llm_toc.py`), pourquoi est-elle vide?
3. `hierarchy: "{}"` → Idem, la hiérarchie devrait être remplie

### 6.2 Distribution des Passages

**Par unitType**:
- main_content: ~25
- argument: ~15
- exposition: ~5
- transition: ~3
- définition: ~2

**Par section (top 5)**:
- "SOCRATE": 8 passages
- "MENON": 7 passages
- "Qu'est-ce que la vertu?": 6 passages
- "Vérification de la réminiscence": 5 passages
- "La vertu s'enseigne-t-elle?": 8 passages

**Par chapterTitle (top 3)**:
- "Ménon ou de la vertu": 7 passages
- "Présentation": 6 passages
- "La vertu s'enseigne-t-elle?": 8 passages

⚠️ **Confusion**: `section` et `chapterTitle` se chevauchent sans logique claire

---

## 7. Écart Schema.py vs Weaviate Réel

| Aspect | schema.py | Weaviate Réel | État |
|--------|-----------|---------------|------|
| **Collections** | 4 (Document, Section, Passage, Work) | 3 (Document, Passage, Work) | ❌ Section manquante |
| **Document.vectorizer** | NONE | TEXT2VEC_TRANSFORMERS | ❌ Incorrect |
| **Document.createdAt** | DATE | TEXT | ❌ Type perdu |
| **Document.skip_vectorization** | Défini | Ignoré | ❌ Non appliqué |
| **Passage propriétés** | 9 | 12 | ⚠️ 3 ajoutées automatiquement |
| **Section** | Définie | Absente | ❌ Non créée |
| **Work objets** | N/A | 0 | ⚠️ Inutilisée |

**Cause probable**: Le schéma n'a **jamais été appliqué** correctement. Les collections ont été créées par auto-schema lors de la première insertion.

---

## 8. Recommandations

### 8.1 Actions Immédiates (Critiques)

1. **Supprimer et recréer le schéma**
   ```bash
   python schema.py  # Recréer proprement
   ```

2. **Vérifier que Section est créée**
   - Ajouter des logs dans `schema.py`
   - Vérifier avec `client.collections.list_all()`

3. **Réparer les métadonnées du Document**
   - Remplir `toc` avec les vraies données
   - Remplir `hierarchy` avec la structure
   - Corriger `pages` (nombre réel de pages du PDF)

4. **Nettoyer les propriétés orphelines**
   - Soit définir `chapterTitle`, `chapterConcepts`, `sectionLevel` dans le schéma
   - Soit les supprimer des données

### 8.2 Améliorations Architecturales

1. **Normaliser avec Work**
   ```python
   # Dans Passage, remplacer author/work par:
   wvc.Property(
       name="work_ref",
       data_type=wvc.DataType.REFERENCE,
       references="Work"
   )
   ```

2. **Ajouter Document → Passage reference**
   ```python
   wvc.Property(
       name="document_ref",
       data_type=wvc.DataType.REFERENCE,
       references="Document"
   )
   ```

3. **Implémenter Section**
   - Créer des objets Section pour chaque chapitre
   - Lier Section ← Passage via référence
   - Ajouter des résumés LLM aux sections

### 8.3 Validation des Données

1. **Ajouter des contraintes**
   - `unitType` → Enum validé
   - `orderIndex` → Doit aller de 0 à chunksCount-1
   - `pages` > 0

2. **Normaliser keywords**
   - Éviter les doublons
   - Normaliser la casse
   - Supprimer les arrays vides si non utilisés

3. **Standardiser section/chapterTitle**
   - Décider d'un format unique
   - Séparer titre de chapitre vs nom de locuteur

### 8.4 Pipeline d'Ingestion

**Modifier `weaviate_ingest.py`**:

1. Créer un objet **Work** d'abord
2. Créer un objet **Document** avec référence à Work
3. Créer des objets **Section** avec références
4. Créer des **Passages** avec références vers Document + Section
5. Valider les données avant insertion

---

## 9. Impact Business

### Problèmes Actuels

| Problème | Impact Utilisateur | Gravité |
|----------|-------------------|---------|
| Section manquante | Pas de navigation par chapitre | 🔴 Haute |
| TOC vide | Impossible de voir la structure | 🔴 Haute |
| Work inutilisée | Duplication, pas de filtre par œuvre | 🟡 Moyenne |
| Auto-schema | Schéma imprévisible, bugs futurs | 🔴 Haute |
| orderIndex incorrect | Ordre des passages peut être faux | 🟡 Moyenne |

### Bénéfices de la Correction

1. **Navigation structurée** via Section
2. **Recherche optimisée** avec références croisées
3. **Métadonnées riches** (TOC, hiérarchie)
4. **Intégrité des données** avec schéma strict
5. **Performance** (moins de duplication)

---

## 10. Plan d'Action Proposé

### Phase 1: Diagnostic Complet (1h)
- [ ] Vérifier pourquoi `schema.py` n'a pas été appliqué
- [ ] Examiner les logs d'insertion dans `weaviate_ingest.py`
- [ ] Identifier quand l'auto-schema s'est déclenché

### Phase 2: Correction du Schéma (2h)
- [ ] Supprimer toutes les collections
- [ ] Ré-exécuter `schema.py` avec logs
- [ ] Vérifier que les 4 collections existent avec le bon schéma
- [ ] Tester l'insertion d'un document de test

### Phase 3: Migration des Données (3h)
- [ ] Exporter les 50 passages actuels
- [ ] Créer un objet Work pour "Ménon"
- [ ] Créer un Document avec TOC/hierarchy remplis
- [ ] Créer des Sections par chapitre
- [ ] Ré-insérer les Passages avec références

### Phase 4: Validation (1h)
- [ ] Tester les requêtes avec références
- [ ] Vérifier l'intégrité des données
- [ ] Documenter le nouveau schéma
- [ ] Mettre à jour `README.md`

**Temps total estimé**: ~7 heures

---

## Conclusion

Le système actuel souffre d'une **désynchronisation majeure** entre le schéma défini et la réalité dans Weaviate. Les collections ont été créées par auto-schema au lieu d'utiliser le schéma explicite, ce qui a conduit à:

1. ❌ Perte de contrôle sur les types et la vectorisation
2. ❌ Collection Section complètement absente
3. ❌ Duplication massive de données
4. ❌ Métadonnées vides et invalides
5. ❌ Pas de relations entre collections

**Priorité**: Recréer proprement le schéma et migrer les données pour exploiter tout le potentiel de l'architecture vectorielle.