# Analyse Architecture Weaviate - Library RAG

**Date**: 2026-01-03
**Dernier commit**: `b76e56e` - refactor: Suppression tous fonds beiges header section
**Status**: Production (13,829 vecteurs indexés)

---

## 📋 Table des Matières

1. [Vue d'Ensemble de la Base Weaviate](#1-vue-densemble-de-la-base-weaviate)
2. [Collections et leurs Relations](#2-collections-et-leurs-relations)
3. [Focus: Œuvre, Document, Chunk - La Hiérarchie Centrale](#3-focus-œuvre-document-chunk---la-hiérarchie-centrale)
4. [Stratégie de Recherche: Résumés → Chunks](#4-stratégie-de-recherche-résumés--chunks)
5. [Outils Weaviate: Utilisés vs Non-Utilisés](#5-outils-weaviate-utilisés-vs-non-utilisés)
6. [Recommandations pour Exploiter Weaviate à 100%](#6-recommandations-pour-exploiter-weaviate-à-100)
7. [Annexes Techniques](#7-annexes-techniques)

---

## 1. Vue d'Ensemble de la Base Weaviate

### 1.1 Architecture Générale

Library RAG utilise **Weaviate 1.34.4** comme base vectorielle pour indexer et rechercher des textes philosophiques. L'architecture suit un modèle **normalisé avec dénormalisation stratégique** via nested objects.

```
┌─────────────────────────────────────────────────────────────┐
│                    WEAVIATE DATABASE                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Work (0 objets)          Document (16 objets)              │
│  └─ Métadonnées œuvre     └─ Métadonnées édition           │
│     (vectorisé)              (non vectorisé)                │
│                                                              │
│  Chunk (5,404 objets) ⭐   Summary (8,425 objets)           │
│  └─ Fragments vectorisés   └─ Résumés vectorisés           │
│     COLLECTION PRINCIPALE     (recherche hiérarchique)      │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### 1.2 Statistiques Clés

| Collection | Objets | Vectorisé | Taille estimée | Utilisation |
|------------|--------|-----------|----------------|-------------|
| **Chunk** | **5,404** | ✅ Oui (text + keywords) | ~3 MB | **Recherche sémantique principale** |
| **Summary** | **8,425** | ✅ Oui (text + concepts) | ~5 MB | Recherche hiérarchique par chapitres |
| **Document** | **16** | ❌ Non | ~10 KB | Métadonnées éditions |
| **Work** | **0** | ✅ Oui (title + author)* | 0 B | Prêt pour migration |

**Total vecteurs**: 13,829 (5,404 chunks + 8,425 summaries)
**Ratio Summary/Chunk**: 1.56 (1.6 résumés par chunk, excellent pour recherche hiérarchique)

\* *Work est configuré avec vectorisation depuis migration 2026-01 mais actuellement vide*

### 1.3 Modèle de Vectorisation

**Modèle**: BAAI/bge-m3
**Dimensions**: 1024
**Contexte**: 8192 tokens
**Langues supportées**: Grec ancien, Latin, Français, Anglais

**Migration Dec 2024**: MiniLM-L6 (384-dim) → BGE-M3 (1024-dim)
- **Gain**: 2.7x plus riche en représentation sémantique
- **Performance**: Meilleure sur textes philosophiques/académiques
- **Multilingue**: Support natif grec/latin

---

## 2. Collections et leurs Relations

### 2.1 Architecture des Collections

```
Work (Œuvre philosophique)
  │
  │ Nested in Document.work: {title, author}
  │ Nested in Chunk.work: {title, author}
  ▼
Document (Édition/traduction spécifique)
  │
  │ Nested in Chunk.document: {sourceId, edition}
  │ Nested in Summary.document: {sourceId}
  ▼
  ├─► Chunk (Fragments de texte, 200-800 chars)
  │     └─ Vectorisé: text, keywords
  │     └─ Filtres: sectionPath, unitType, orderIndex
  │
  └─► Summary (Résumés de chapitres/sections)
        └─ Vectorisé: text, concepts
        └─ Hiérarchie: level (1=chapitre, 2=section, 3=subsection)
```

### 2.2 Collection Work (Œuvre)

**Rôle**: Représente une œuvre philosophique canonique (ex: Ménon de Platon)

**Propriétés**:
```python
title: TEXT (VECTORISÉ)           # "Ménon", "République"
author: TEXT (VECTORISÉ)          # "Platon", "Peirce"
originalTitle: TEXT [skip_vec]    # "Μένων" (grec)
year: INT                         # -380 (avant J.-C.)
language: TEXT [skip_vec]         # "gr", "la", "fr"
genre: TEXT [skip_vec]            # "dialogue", "traité"
```

**Vectorisation**: Activée depuis 2026-01
- ✅ `title` vectorisé → recherche "dialogues socratiques" trouve Ménon
- ✅ `author` vectorisé → recherche "philosophie analytique" trouve Haugeland

**Status actuel**: Vide (0 objets), prêt pour migration

### 2.3 Collection Document (Édition)

**Rôle**: Représente une édition ou traduction spécifique d'une œuvre

**Propriétés**:
```python
sourceId: TEXT                    # "platon_menon_cousin"
edition: TEXT                     # "trad. Cousin, 1844"
language: TEXT                    # "fr" (langue de cette édition)
pages: INT                        # 120
chunksCount: INT                  # 338 (nombre de chunks extraits)
toc: TEXT (JSON)                  # Table des matières structurée
hierarchy: TEXT (JSON)            # Hiérarchie complète des sections
createdAt: DATE                   # 2025-12-09T09:20:30

# Nested object
work: {
  title: TEXT                     # "Ménon"
  author: TEXT                    # "Platon"
}
```

**Vectorisation**: ❌ Non (métadonnées uniquement)

### 2.4 Collection Chunk ⭐ (PRINCIPALE)

**Rôle**: Fragments de texte optimisés pour recherche sémantique (200-800 caractères)

**Propriétés vectorisées**:
```python
text: TEXT (VECTORISÉ)            # Contenu du fragment
keywords: TEXT_ARRAY (VECTORISÉ)  # ["justice", "vertu", "connaissance"]
```

**Propriétés de filtrage** (non vectorisées):
```python
sectionPath: TEXT [skip_vec]      # "Présentation > Qu'est-ce que la vertu?"
sectionLevel: INT                 # 2 (profondeur hiérarchique)
chapterTitle: TEXT [skip_vec]     # "Présentation"
canonicalReference: TEXT [skip_vec] # "Ménon 80a" ou "CP 5.628"
unitType: TEXT [skip_vec]         # "argument", "définition", "exposition"
orderIndex: INT                   # 42 (position séquentielle 0-based)
language: TEXT [skip_vec]         # "fr", "en", "gr"
```

**Nested objects** (dénormalisation):
```python
work: {
  title: TEXT                     # "Ménon"
  author: TEXT                    # "Platon"
}
document: {
  sourceId: TEXT                  # "platon_menon_cousin"
  edition: TEXT                   # "trad. Cousin"
}
```

**Exemple d'objet**:
```json
{
  "text": "SOCRATE. - Peux-tu me dire, Ménon, si la vertu peut s'enseigner?",
  "keywords": ["vertu", "enseignement", "question socratique"],
  "sectionPath": "Présentation > Qu'est-ce que la vertu?",
  "sectionLevel": 2,
  "chapterTitle": "Présentation",
  "canonicalReference": "Ménon 70a",
  "unitType": "argument",
  "orderIndex": 0,
  "language": "fr",
  "work": {
    "title": "Ménon ou de la vertu",
    "author": "Platon"
  },
  "document": {
    "sourceId": "platon_menon_cousin",
    "edition": "trad. Cousin"
  }
}
```

### 2.5 Collection Summary (Résumés)

**Rôle**: Résumés LLM de chapitres/sections pour recherche hiérarchique

**Propriétés vectorisées**:
```python
text: TEXT (VECTORISÉ)            # Résumé généré par LLM
concepts: TEXT_ARRAY (VECTORISÉ)  # ["réminiscence", "anamnèse", "connaissance innée"]
```

**Propriétés de filtrage**:
```python
sectionPath: TEXT [skip_vec]      # "Livre I > Chapitre 2"
title: TEXT [skip_vec]            # "La réminiscence et la connaissance"
level: INT                        # 1=chapitre, 2=section, 3=subsection
chunksCount: INT                  # 15 (nombre de chunks dans cette section)
```

---

## 3. Focus: Œuvre, Document, Chunk - La Hiérarchie Centrale

### 3.1 Modèle de Données

L'architecture suit un modèle **normalisé avec dénormalisation stratégique** :

```
┌──────────────────────────────────────────────────────────────┐
│                      MODÈLE NORMALISÉ                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Work (Source de vérité unique)                             │
│    title: "Ménon ou de la vertu"                            │
│    author: "Platon"                                          │
│    year: -380                                                │
│    language: "gr"                                            │
│    genre: "dialogue"                                         │
│                                                              │
│    ├─► Document 1 (trad. Cousin)                            │
│    │     sourceId: "platon_menon_cousin"                    │
│    │     edition: "trad. Cousin, 1844"                      │
│    │     language: "fr"                                      │
│    │     pages: 120                                          │
│    │     chunksCount: 338                                    │
│    │     work: {title, author} ← DÉNORMALISÉ                │
│    │                                                          │
│    │     ├─► Chunk 1                                         │
│    │     │     text: "Peux-tu me dire, Ménon..."            │
│    │     │     work: {title, author} ← DÉNORMALISÉ          │
│    │     │     document: {sourceId, edition} ← DÉNORMALISÉ  │
│    │     │                                                   │
│    │     ├─► Chunk 2...                                      │
│    │     └─► Chunk 338                                       │
│    │                                                          │
│    │     ├─► Summary 1 (chapitre 1)                         │
│    │     │     text: "Cette section explore..."             │
│    │     │     level: 1                                      │
│    │     │     document: {sourceId} ← DÉNORMALISÉ           │
│    │     │                                                   │
│    │     └─► Summary N...                                    │
│    │                                                          │
│    └─► Document 2 (Loeb Classical Library)                  │
│          sourceId: "plato_meno_loeb"                         │
│          edition: "Loeb Classical Library"                   │
│          language: "en"                                       │
│          ... (même structure)                                │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

### 3.2 Pourquoi Nested Objects au lieu de Cross-References ?

**Avantages**:
1. ✅ **Requête unique** - Récupération en une seule requête sans joins
2. ✅ **Performance** - Pas de jointures complexes côté application
3. ✅ **Simplicité** - Logique de requête plus simple
4. ✅ **Cache-friendly** - Toutes les métadonnées dans un seul objet

**Trade-off**:
- Pour 5,404 chunks: ~200 KB de duplication
- Économie de temps: ~50-100ms par requête (évite 2 roundtrips Weaviate)

---

## 4. Stratégie de Recherche: Résumés → Chunks

### 4.1 Pourquoi Deux Collections Vectorisées ?

**Problème**: Chercher directement dans 5,404 chunks peut manquer le contexte global

**Solution**: Architecture à deux niveaux

```
┌─────────────────────────────────────────────────────────────┐
│              RECHERCHE À DEUX NIVEAUX                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Niveau 1: MACRO (Summary - 8,425 objets)                   │
│    "Quels chapitres parlent de la réminiscence?"            │
│    └─► Identifie: Chapitre 2, Section 3                     │
│                                                              │
│  Niveau 2: MICRO (Chunk - 5,404 objets)                     │
│    "Quelle est la définition exacte de l'anamnèse?"         │
│    └─► Trouve: Chunk #42 dans la section identifiée         │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

**Avantages**:
1. ✅ Meilleure précision (contexte chapitres + détails chunks)
2. ✅ Performance optimale (filtrer chunks par section identifiée)
3. ✅ Hiérarchie exploitée (level 1=chapitre, 2=section, 3=subsection)

### 4.2 Stratégies de Recherche Implémentables

#### Stratégie 1: Sequential Search (Résumés puis Chunks)

**Cas d'usage**: Recherche approfondie avec contexte

```python
# 1. Chercher dans Summary (macro)
summaries = client.collections.get("Summary")
summary_results = summaries.query.near_text(
    query="théorie de la réminiscence",
    limit=5,
    filters=Filter.by_property("level").equal(1)  # Chapitres uniquement
)

# 2. Extraire sections pertinentes
relevant_sections = [
    s.properties['sectionPath']
    for s in summary_results.objects
]

# 3. Chercher chunks dans ces sections (micro)
chunks = client.collections.get("Chunk")
chunk_results = chunks.query.near_text(
    query="qu'est-ce que l'anamnèse?",
    limit=10,
    filters=Filter.by_property("sectionPath").like(f"{relevant_sections[0]}*")
)
```

**Performance**: 2 requêtes (~50ms chacune) = 100ms total

#### Stratégie 2: Hybrid Two-Stage avec Score Boosting

**Algorithme recommandé pour production**:

```python
def hybrid_search(query: str, limit: int = 10) -> List[ChunkResult]:
    """Recherche hybride résumés → chunks avec boosting."""

    # Stage 1: Summary search (macro)
    summaries = client.collections.get("Summary")
    summary_results = summaries.query.near_text(
        query=query,
        limit=3,  # Top 3 chapitres
        filters=Filter.by_property("level").less_or_equal(2),
        return_metadata=wvq.MetadataQuery(distance=True)
    )

    # Stage 2: Chunk search avec boost par section
    chunks = client.collections.get("Chunk")
    all_chunks = []

    for summary in summary_results.objects:
        section_path = summary.properties['sectionPath']
        summary_score = 1 - summary.metadata.distance

        # Chercher chunks dans cette section
        chunk_results = chunks.query.near_text(
            query=query,
            limit=5,
            filters=Filter.by_property("sectionPath").like(f"{section_path}*"),
            return_metadata=wvq.MetadataQuery(distance=True)
        )

        # Booster le score des chunks
        for chunk in chunk_results.objects:
            chunk_score = 1 - chunk.metadata.distance
            boosted_score = (chunk_score * 0.7) + (summary_score * 0.3)

            all_chunks.append({
                'chunk': chunk,
                'score': boosted_score,
                'context_chapter': section_path
            })

    # Trier par score boosted
    all_chunks.sort(key=lambda x: x['score'], reverse=True)
    return all_chunks[:limit]
```

**Impact**: +15-20% précision, ~120ms latence

---

## 5. Outils Weaviate: Utilisés vs Non-Utilisés

### 5.1 Outils Actuellement Utilisés ✅

1. **Semantic Search (near_text)** - Recherche sémantique principale
2. **Filters (Nested Objects)** - Filtrage par author, work, language
3. **Fetch Objects** - Récupération par ID
4. **Batch Insertion** - Insertion groupée adaptative (10-100 objets)
5. **Delete Many** - Suppression en masse

### 5.2 Outils Weaviate NON Utilisés ❌

#### 1. Hybrid Search (Sémantique + BM25) ⚠️ **HAUTE PRIORITÉ**

**Qu'est-ce que c'est?**
Combine recherche vectorielle (sémantique) + BM25 (mots-clés exacts)

**Exemple d'implémentation**:
```python
result = chunks.query.hybrid(
    query="qu'est-ce que la vertu?",
    alpha=0.75,  # 75% vectoriel, 25% BM25
    limit=10,
    filters=filters,
)
```

**Impact attendu**: +10-15% précision sur requêtes factuelles

#### 2. Generative Search (RAG natif) 🚨 **HAUTE PRIORITÉ**

**Qu'est-ce que c'est?**
Weaviate génère directement une réponse synthétique à partir des chunks

**Exemple**:
```python
result = chunks.generate.near_text(
    query="qu'est-ce que la réminiscence chez Platon?",
    limit=5,
    grouped_task="Réponds à la question en utilisant ces 5 passages",
)

# Résultat contient:
# - result.objects: chunks trouvés
# - result.generated: réponse LLM générée
```

**Impact**: Réduction 50% latence end-to-end (RAG complet en une requête)

#### 3. Reranking (Cohere, Voyage AI) ⚠️ **MOYENNE PRIORITÉ**

Re-score les résultats avec un modèle spécialisé

**Impact**: +15-20% précision top-3, +50-100ms latence

#### 4. RAG Fusion (Multi-Query Search) ⚠️ **MOYENNE PRIORITÉ**

Génère N variantes de la requête et fusionne les résultats

**Impact**: +20-25% recall

### 5.3 Matrice Priorités

| Outil | Priorité | Difficulté | Impact Précision | Impact Latence | Coût |
|-------|----------|------------|------------------|----------------|------|
| **Hybrid Search** | 🔴 Haute | Faible (1h) | +10-15% | +5ms | Gratuit |
| **Generative Search** | 🔴 Haute | Moyenne (3h) | +30% (RAG E2E) | -50% E2E | LLM API |
| **Reranking** | 🟡 Moyenne | Faible (2h) | +15-20% top-3 | +50-100ms | $0.001/req |
| **RAG Fusion** | 🟡 Moyenne | Moyenne (4h) | +20-25% recall | x3 requêtes | Gratuit |

---

## 6. Recommandations pour Exploiter Weaviate à 100%

### 6.1 Quick Wins (1-2 jours d'implémentation)

#### Quick Win #1: Activer Hybrid Search

**Fichier à modifier**: `schema.py`

```python
# Ajouter index BM25
wvc.Property(
    name="text",
    data_type=wvc.DataType.TEXT,
    index_searchable=True,  # ← Active BM25
)
```

**Fichier à modifier**: `mcp_tools/retrieval_tools.py`

```python
# Remplacer near_text par hybrid
result = chunks.query.hybrid(
    query=input_data.query,
    alpha=0.75,  # 75% vectoriel, 25% BM25
    limit=input_data.limit,
    filters=filters,
)
```

**Impact**: +10% précision, <5ms surcoût

#### Quick Win #2: Implémenter Two-Stage Search

Créer `utils/two_stage_search.py` avec l'algorithme hybrid boosting (voir section 4.2)

**Impact**: +15-20% précision, ~120ms latence

### 6.2 High-Impact Features (1 semaine d'implémentation)

#### Feature #1: Generative Search (RAG Natif)

**Étape 1**: Activer module dans docker-compose.yml

```yaml
services:
  weaviate:
    environment:
      GENERATIVE_ANTHROPIC_APIKEY: ${ANTHROPIC_API_KEY}
```

**Étape 2**: Endpoint Flask

```python
@app.route("/search/generative", methods=["GET"])
def search_generative():
    query = request.args.get("q", "")

    chunks = client.collections.get("Chunk")
    result = chunks.generate.near_text(
        query=query,
        limit=5,
        grouped_task=f"Réponds à: {query}. Utilise les passages fournis.",
    )

    return jsonify({
        "answer": result.generated,
        "sources": [...]
    })
```

**Impact**: RAG complet en une requête, -50% latence E2E

---

## 7. Annexes Techniques

### 7.1 Exemple de Requête Complète

```python
import weaviate
from weaviate.classes.query import Filter

client = weaviate.connect_to_local()
chunks = client.collections.get("Chunk")

# Recherche: "vertu" chez Platon en français
result = chunks.query.near_text(
    query="qu'est-ce que la vertu?",
    limit=10,
    filters=(
        Filter.by_property("work").by_property("author").equal("Platon") &
        Filter.by_property("language").equal("fr")
    ),
    return_metadata=wvq.MetadataQuery(distance=True)
)

for obj in result.objects:
    props = obj.properties
    similarity = 1 - obj.metadata.distance

    print(f"Similarité: {similarity:.3f}")
    print(f"Texte: {props['text'][:100]}...")
    print(f"Œuvre: {props['work']['title']}")
    print(f"Référence: {props['canonicalReference']}")
    print("---")

client.close()
```

### 7.2 Glossaire Weaviate

| Terme | Définition |
|-------|------------|
| **Collection** | Équivalent d'une "table" en SQL |
| **Object** | Une entrée dans une collection |
| **Vector** | Représentation numérique (1024-dim pour BGE-M3) |
| **near_text** | Recherche sémantique par similarité |
| **hybrid** | Recherche combinée (vectorielle + BM25) |
| **Nested Object** | Objet imbriqué (ex: `work: {title, author}`) |
| **HNSW** | Index vectoriel performant |
| **RQ** | Rotational Quantization (-75% RAM) |

---

## Conclusion

### Points Clés

1. **Architecture solide** - 4 collections avec nested objects
2. **13,829 vecteurs** - Base de production opérationnelle
3. **Ratio 1.56 Summary/Chunk** - Excellent pour recherche hiérarchique
4. **Utilisation 30%** - Beaucoup de potentiel non exploité

### Roadmap Recommandée

**Q1 2026** (Quick Wins):
1. Hybrid Search (1 jour)
2. Two-Stage Search (3 jours)
3. Métriques/monitoring (2 jours)

**Q2 2026** (High Impact):
1. Generative Search (1 semaine)
2. Reranking (3 jours)
3. Semantic caching (3 jours)

---

**Dernière mise à jour**: 2026-01-03
**Version**: 1.0