Skip to content

FEATURE_SIMILARITY_FINDER

Jump to bottom
Frédéric Clavert edited this page Jul 20, 2026 · 13 revisions

Feature: Similarity Finder - Recommandations bibliographiques contextuelles

Version: 1.0.0-rc.3 (re-verified) Status: Implémenté Dernière mise à jour: 2026-07-20

Vue d'ensemble

La fonctionnalité Similarity Finder permet à l'historien·ne de comparer son texte en cours de rédaction avec les PDFs indexés dans sa base vectorielle. Le système analyse chaque segment du texte (section, paragraphe ou phrase selon le choix) et recommande des sources pertinentes pour approfondir chaque partie.

Philosophie : Analyse asynchrone à la demande, adaptée aux contraintes d'un environnement local avec Ollama.

Cas d'usage principal

  1. L'utilisateur·rice rédige son article dans ClioDeck (document.md)
  2. À un moment opportun (pause, fin de session), il/elle clique sur "Trouver des similarités" dans la barre d'outils de l'éditeur
  3. Une barre de progression indique l'avancement de l'analyse
  4. Une fois terminé, l'utilisateur·rice peut cliquer sur n'importe quel segment de son texte
  5. Un panneau latéral affiche les PDFs recommandés pour ce segment
  6. L'utilisateur·rice peut ouvrir le PDF ou insérer une citation

Spécifications fonctionnelles

1. Découpage du texte

L'utilisateur·rice choisit la granularité d'analyse :

Granularité Découpage Cas d'usage
Section Titres Markdown (#, ##, ###) Vue d'ensemble, textes longs
Paragraphe Blocs séparés par lignes vides Équilibre précision/performance
Phrase Segmentation par ponctuation Analyse fine, textes courts

Défaut recommandé : Paragraphe

2. Options configurables

Option Type Valeur par défaut Description
granularity enum paragraph Niveau de découpage (section, paragraph, sentence)
maxResults number 5 Nombre max de PDFs par segment (1-20)
similarityThreshold number 0.6 Seuil minimum de similarité (0-1)
collectionFilter string[] null Restriction à certaines collections Zotero
sourceType enum both Type de sources à rechercher (secondary, primary, both)
useReranking boolean false Activer le reranking pour améliorer la pertinence
useContextualEmbedding boolean false Utiliser des embeddings contextuels

3. Affichage des résultats

Interaction : Au clic sur un segment analysé, un panneau latéral s'affiche avec :

  • Titre du segment (premiers mots ou numéro)
  • Score de similarité global
  • Liste des PDFs recommandés :
    • Titre de la source
    • Auteur(s)
    • Score de similarité (%)
    • Bouton "Ouvrir le PDF"
    • Bouton "Insérer citation"

4. Persistance et cache

Stratégie de cache intelligent :

Hash du segment = hash(contenu_texte)
Hash de la BDD = hash(dernière_modification_vectorstore)

Si segment_hash + bdd_hash existe en cache :
    → Utiliser les résultats cachés
Sinon :
    → Recalculer les embeddings
    → Sauvegarder en cache

Stockage : Fichier JSON dans le dossier projet (.cliodeck/similarity_cache.json)

5. Actions sur les recommandations

Action Comportement
Ouvrir le PDF Ouvre le PDF dans le lecteur ClioDeck
Insérer citation Insère une référence Markdown au curseur (format configurable)

Architecture technique

Composants

┌─────────────────────────────────────────────────────────────────┐
│                         RENDERER                                │
├─────────────────────────────────────────────────────────────────┤
│  EditorToolbar                                                  │
│    └── [Bouton "Trouver des similarités"]                       │
│                                                                 │
│  SimilarityPanel                                                │
│    ├── SimilarityProgress (barre de progression)                │
│    ├── SimilarityResults (panneau latéral)                      │
│    │     └── SimilarityCard (carte par PDF recommandé)          │
│    └── SimilarityOptions (modal de configuration)               │
│                                                                 │
│  useSimilarityStore (Zustand)                                   │
│    ├── results: Map<segmentId, SimilarityResult[]>              │
│    ├── isAnalyzing: boolean                                     │
│    ├── progress: { current: number, total: number }             │
│    └── options: SimilarityOptions                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ IPC
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                           MAIN                                  │
├─────────────────────────────────────────────────────────────────┤
│  similarity-handlers.ts                                         │
│    ├── similarity:analyze                                       │
│    ├── similarity:get-results                                   │
│    └── similarity:clear-cache                                   │
│                                                                 │
│  SimilarityService                                              │
│    ├── analyzeDocument(text, options)                           │
│    ├── segmentText(text, granularity)                           │
│    ├── findSimilarPDFs(segment, options)                        │
│    ├── loadCache() / saveCache()                                │
│    └── computeHashes()                                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                          BACKEND                                │
├─────────────────────────────────────────────────────────────────┤
│  VectorStoreManager (existant)                                  │
│    └── searchSimilar(embedding, options)                        │
│                                                                 │
│  OllamaClient (existant)                                        │
│    └── generateEmbedding(text)                                  │
└─────────────────────────────────────────────────────────────────┘

Structures de données

// Types principaux
interface SimilarityOptions {
  granularity: 'section' | 'paragraph' | 'sentence';
  maxResults: number;
  similarityThreshold: number;
  collectionFilter: string[] | null;
  sourceType: 'secondary' | 'primary' | 'both';
  useReranking: boolean;
  useContextualEmbedding: boolean;
}

interface TextSegment {
  id: string;           // Hash unique
  content: string;      // Contenu textuel
  startLine: number;    // Position dans le document
  endLine: number;
  type: 'section' | 'paragraph' | 'sentence';
}

interface SimilarityResult {
  segmentId: string;
  recommendations: PDFRecommendation[];
  analyzedAt: number;   // Timestamp
}

interface PDFRecommendation {
  pdfId: string;
  title: string;
  authors: string[];
  similarity: number;   // 0-1
  chunkPreview: string; // Extrait pertinent du PDF
  zoteroKey?: string;   // Pour insertion citation
}

Dépendances existantes réutilisées

Composant existant Utilisation
VectorStoreManager Recherche de similarité
OllamaClient Génération d'embeddings
PDFService Métadonnées des PDFs
ZoteroService Collections et citations
editorStore Gestion du document

Utilisation

Accès

  1. Dans l'éditeur, cliquez sur "Trouver des similarités" dans la barre d'outils

Configuration

Avant l'analyse, vous pouvez configurer :

  • Granularité : Section, Paragraphe, ou Phrase
  • Nombre de résultats : Maximum de sources par segment
  • Seuil de similarité : Filtrer les résultats peu pertinents
  • Collection : Limiter à une collection Zotero

Interprétation des résultats

  • Score élevé (> 0.8) : Source très pertinente pour ce segment
  • Score moyen (0.5-0.8) : Source potentiellement intéressante
  • Score faible (< 0.5) : Source marginalement liée

Bonnes pratiques

  1. Indexez vos PDFs avant d'utiliser le Similarity Finder
  2. Choisissez la bonne granularité selon la longueur de votre texte
  3. Utilisez le filtrage par collection pour des résultats plus ciblés
  4. Relancez l'analyse après avoir modifié significativement votre texte

Limitations

  • Nécessite Ollama pour générer les embeddings
  • Performance dépend de la taille du corpus et du texte analysé
  • Cache invalidé si l'index vectoriel change

Clone this wiki locally