LRP-148: Add user guide documentation for works filter
- WORKS_FILTER.md: Complete user documentation in French - Feature overview and location - Selection/deselection instructions - Quick action buttons (Tout/Aucun) - Badge counter explanation - Collapse functionality - Default behavior and localStorage persistence - Impact on semantic search - Recommended use cases (comparative study, focus, exclusion) - Responsive mobile support - API Reference section: - GET /api/get-works endpoint documentation - POST /chat/send selected_works parameter - Error codes and validation - Troubleshooting guide: - No works displayed - Filter not working - How to reset selection - Chunks count explanation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
214
generations/library_rag/WORKS_FILTER.md
Normal file
214
generations/library_rag/WORKS_FILTER.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Filtrage par oeuvres - Guide utilisateur
|
||||
|
||||
Ce guide explique comment utiliser la fonctionnalité de filtrage par oeuvres dans la page de conversation RAG.
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
La fonctionnalité de filtrage permet de restreindre la recherche sémantique à certaines oeuvres spécifiques de votre bibliothèque. C'est particulièrement utile lorsque vous souhaitez :
|
||||
|
||||
- Comparer les perspectives de différents auteurs sur un même sujet
|
||||
- Vous concentrer sur un corpus précis (ex: uniquement Platon)
|
||||
- Exclure temporairement des textes non pertinents pour votre recherche
|
||||
|
||||
## Localisation
|
||||
|
||||
La section "Filtrer par oeuvres" se trouve dans la **sidebar droite** de la page `/chat`, au-dessus de la section "Contexte RAG".
|
||||
|
||||
## Fonctionnalités
|
||||
|
||||
### 1. Liste des oeuvres disponibles
|
||||
|
||||
Chaque oeuvre affiche :
|
||||
- **Titre** : Le titre de l'oeuvre
|
||||
- **Auteur** : Le nom de l'auteur
|
||||
- **Nombre de passages** : Le nombre de chunks indexés pour cette oeuvre
|
||||
|
||||
### 2. Sélection / Désélection
|
||||
|
||||
- **Cliquer sur une oeuvre** : Toggle (active/désactive) la sélection
|
||||
- **Cliquer sur la checkbox** : Même comportement
|
||||
|
||||
### 3. Boutons d'action rapide
|
||||
|
||||
| Bouton | Action |
|
||||
|--------|--------|
|
||||
| **Tout** | Sélectionne toutes les oeuvres |
|
||||
| **Aucun** | Désélectionne toutes les oeuvres |
|
||||
|
||||
### 4. Badge compteur
|
||||
|
||||
Le badge dans l'en-tête affiche le nombre d'oeuvres sélectionnées :
|
||||
- `10/10` = Toutes les oeuvres sélectionnées
|
||||
- `3/10` = 3 oeuvres sur 10 sélectionnées
|
||||
- `0/10` = Aucune oeuvre sélectionnée
|
||||
|
||||
### 5. Section collapsible
|
||||
|
||||
Cliquez sur le chevron (▼/▲) pour réduire ou développer la section. Le badge reste visible même quand la section est réduite.
|
||||
|
||||
## Comportement par défaut
|
||||
|
||||
- **Au premier chargement** : Toutes les oeuvres sont sélectionnées
|
||||
- **Lors des visites suivantes** : La dernière sélection est restaurée (persistance localStorage)
|
||||
|
||||
## Impact sur la recherche
|
||||
|
||||
Lorsque vous posez une question :
|
||||
|
||||
1. **Toutes les oeuvres sélectionnées** : La recherche s'effectue sur l'ensemble de la bibliothèque
|
||||
2. **Certaines oeuvres sélectionnées** : Seuls les passages des oeuvres cochées sont retournés
|
||||
3. **Aucune oeuvre sélectionnée** : La recherche s'effectue sur toutes les oeuvres (équivalent à "Tout")
|
||||
|
||||
## Cas d'usage recommandés
|
||||
|
||||
### Étude comparative
|
||||
> Je veux comparer ce que disent Peirce et Tiercelin sur la notion de signe.
|
||||
|
||||
1. Cliquez sur "Aucun"
|
||||
2. Sélectionnez uniquement les oeuvres de Peirce et Tiercelin
|
||||
3. Posez votre question
|
||||
|
||||
### Focus sur un auteur
|
||||
> Je ne veux que les textes de Platon pour ma recherche sur la vertu.
|
||||
|
||||
1. Cliquez sur "Aucun"
|
||||
2. Cochez uniquement les oeuvres de Platon
|
||||
3. Effectuez vos recherches
|
||||
|
||||
### Exclusion temporaire
|
||||
> Le corpus de Peirce est trop volumineux et noie mes résultats.
|
||||
|
||||
1. Cliquez sur "Tout"
|
||||
2. Décochez les oeuvres de Peirce
|
||||
3. Continuez vos recherches
|
||||
|
||||
## Persistance des préférences
|
||||
|
||||
Votre sélection est automatiquement sauvegardée dans le **localStorage** de votre navigateur. Elle sera restaurée lors de vos prochaines visites sur la page.
|
||||
|
||||
Pour **réinitialiser** vos préférences :
|
||||
1. Cliquez sur "Tout" pour tout sélectionner
|
||||
2. La nouvelle sélection sera sauvegardée automatiquement
|
||||
|
||||
## Responsive (Mobile)
|
||||
|
||||
Sur les écrans de moins de 992px de large :
|
||||
- La section de filtrage apparaît en dessous de la zone de conversation
|
||||
- Elle reste entièrement fonctionnelle
|
||||
- La section peut être réduite pour économiser de l'espace
|
||||
|
||||
---
|
||||
|
||||
# API Reference (Développeurs)
|
||||
|
||||
## GET /api/get-works
|
||||
|
||||
Retourne la liste de toutes les oeuvres disponibles.
|
||||
|
||||
**Requête :**
|
||||
```http
|
||||
GET /api/get-works
|
||||
```
|
||||
|
||||
**Réponse (200 OK) :**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"title": "Ménon",
|
||||
"author": "Platon",
|
||||
"chunks_count": 127
|
||||
},
|
||||
{
|
||||
"title": "La logique de la science",
|
||||
"author": "Charles Sanders Peirce",
|
||||
"chunks_count": 12
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Erreur (500) :**
|
||||
```json
|
||||
{
|
||||
"error": "Weaviate connection failed",
|
||||
"message": "Cannot connect to Weaviate database"
|
||||
}
|
||||
```
|
||||
|
||||
## POST /chat/send (paramètre selected_works)
|
||||
|
||||
Le paramètre `selected_works` permet de filtrer la recherche par oeuvres.
|
||||
|
||||
**Requête :**
|
||||
```json
|
||||
{
|
||||
"question": "Qu'est-ce que la vertu ?",
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o-mini",
|
||||
"limit": 5,
|
||||
"selected_works": ["Ménon", "La pensée-signe"]
|
||||
}
|
||||
```
|
||||
|
||||
**Comportement :**
|
||||
- `selected_works: []` (liste vide) : Recherche dans toutes les oeuvres
|
||||
- `selected_works: ["Ménon"]` : Recherche uniquement dans Ménon
|
||||
- `selected_works` absent : Équivalent à liste vide (toutes les oeuvres)
|
||||
|
||||
**Erreurs de validation (400) :**
|
||||
```json
|
||||
{"error": "selected_works must be a list of work titles"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"error": "selected_works must contain only strings"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## Aucune oeuvre n'est affichée
|
||||
|
||||
**Causes possibles :**
|
||||
1. Weaviate n'est pas démarré
|
||||
2. Aucun document n'a été ingéré
|
||||
|
||||
**Solutions :**
|
||||
```bash
|
||||
# Vérifier que Weaviate est démarré
|
||||
docker compose ps
|
||||
|
||||
# Démarrer Weaviate si nécessaire
|
||||
docker compose up -d
|
||||
|
||||
# Vérifier qu'il y a des documents
|
||||
# Aller sur http://localhost:5000/documents
|
||||
```
|
||||
|
||||
## Le filtre ne semble pas fonctionner
|
||||
|
||||
**Vérifications :**
|
||||
1. Vérifiez le badge compteur (combien d'oeuvres sont sélectionnées ?)
|
||||
2. Ouvrez les DevTools (F12) > Network
|
||||
3. Envoyez une question
|
||||
4. Vérifiez que le POST `/chat/send` contient `selected_works`
|
||||
|
||||
**Si le problème persiste :**
|
||||
1. Rafraîchissez la page (Ctrl+F5)
|
||||
2. Videz le localStorage : DevTools > Application > Local Storage > Supprimer `selectedWorks`
|
||||
|
||||
## Comment réinitialiser la sélection ?
|
||||
|
||||
**Méthode 1 - Via l'interface :**
|
||||
1. Cliquez sur le bouton "Tout"
|
||||
2. La sélection est sauvegardée automatiquement
|
||||
|
||||
**Méthode 2 - Via DevTools :**
|
||||
1. Ouvrez DevTools (F12)
|
||||
2. Allez dans Application > Local Storage > localhost:5000
|
||||
3. Supprimez la clé `selectedWorks`
|
||||
4. Rafraîchissez la page
|
||||
|
||||
## Le nombre de passages ne correspond pas
|
||||
|
||||
Le nombre de passages (`chunks_count`) représente le nombre de **chunks** indexés, pas le nombre de pages du document original. Un document de 50 pages peut générer 100+ chunks selon le découpage sémantique.
|
||||
Reference in New Issue
Block a user