Skip to content

1.6 Tropy Integration Guide

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

Guide d'intégration Tropy

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

Vue d'ensemble

ClioDeck intègre Tropy, le logiciel de gestion de sources primaires développé par le Roy Rosenzweig Center for History and New Media. Cette intégration permet d'inclure vos archives photographiées et transcrites dans le système RAG, aux côtés de vos sources secondaires (PDFs bibliographiques).

Fonctionnalités principales

  • Import de projets Tropy : Lecture des fichiers .tropy (packages) et .tpy (bases SQLite)
  • Synchronisation des métadonnées : Titre, date, créateur, archive, collection, tags
  • Import des transcriptions : Notes Tropy, Transkribus, OCR Tesseract (par ordre de priorité)
  • Recherche unifiée : Les sources primaires sont interrogeables via le chat RAG
  • Surveillance automatique : Détection des modifications du fichier Tropy

Prérequis

Logiciels requis

  1. Tropy installé sur votre machine (téléchargement)
  2. Un projet Tropy existant avec des items

Formats supportés

Format Extension Description
Tropy Package .tropy Dossier contenant project.tpy et assets/
Base SQLite .tpy Fichier de base de données direct

Configuration initiale

1. Ouvrir un projet Tropy

  1. Dans ClioDeck, ouvrez votre projet
  2. Accédez au panneau Sources Primaires (icône archive dans la barre latérale)
  3. Cliquez sur Ouvrir un projet Tropy
  4. Sélectionnez votre fichier .tropy ou .tpy

2. Synchroniser les données

Une fois le projet ouvert, cliquez sur Synchroniser pour importer :

  • Les métadonnées de chaque item (titre, date, créateur, etc.)
  • Les tags associés
  • Les notes (transcriptions) de l'item, des photos et des sélections
  • Les chemins vers les photos

Options de synchronisation

Option Description Défaut
Effectuer l'OCR Lancer Tesseract sur les images sans transcription Désactivé
Langue OCR Langue pour la reconnaissance de caractères Français

Structure des données Tropy

Hiérarchie des items

Item (source primaire)
├── Métadonnées (titre, date, créateur, archive, collection)
├── Tags
├── Notes (transcriptions au niveau item)
└── Photos
    ├── Notes (transcriptions au niveau photo)
    └── Sélections
        └── Notes (transcriptions au niveau sélection)

Métadonnées importées

ClioDeck extrait automatiquement les propriétés Dublin Core et Tropy :

Propriété Utilisation
title Titre affiché et indexé
date Date du document
creator Auteur/créateur
archive Institution de conservation
collection Collection ou fonds
type Type de document

Transcriptions

Sources de transcription

ClioDeck supporte plusieurs sources de transcription, par ordre de priorité :

  1. Notes Tropy : Transcriptions saisies directement dans Tropy
  2. Transkribus : Import de fichiers PAGE XML ou ALTO (cherché avant l'OCR)
  3. OCR Tesseract : Reconnaissance optique via Tesseract.js, seulement si rien d'autre n'a produit de transcription
  4. Import de fichier : Transcription PAGE/ALTO XML importée via TranscriptionImportModal. Une quatrième voie existe côté code — relancer l'OCR manuellement sur une seule source (performOCR dans primarySourcesStore.ts, qui appelle updateTranscription(..., source: 'manual')) — mais aucun composant de l'interface ne déclenche cette action aujourd'hui. Filé en issue #23.

Import depuis Tropy

Les notes de Tropy sont automatiquement importées comme transcriptions :

  • Notes de l'item → Transcription principale
  • Notes des photos → Concaténées à la transcription
  • Notes des sélections → Concaténées avec contexte

OCR avec Tesseract

Pour les images sans transcription, ClioDeck peut effectuer l'OCR :

  1. Activez Effectuer l'OCR dans les options de synchronisation
  2. Sélectionnez la Langue OCR appropriée
  3. Lancez la synchronisation

Langues supportées (15 au total) : Français, Anglais, Allemand, Espagnol, Italien, Latin, Portugais, Néerlandais, Polonais, Russe, Grec ancien, Hébreu, Arabe, Moyen français, Allemand Fraktur

Import de transcriptions externes

ClioDeck supporte plusieurs formats d'import de transcriptions :

Format Extension Description
PAGE XML .xml Format Transkribus standard
ALTO XML .xml Format d'OCR structuré
Plain Text .txt Texte brut simple

Procédure d'import :

  1. Exportez depuis Transkribus au format PAGE XML ou ALTO
  2. Dans ClioDeck, utilisez Importer une transcription
  3. Sélectionnez le fichier exporté
  4. Associez-le à la source primaire correspondante

Le système détecte automatiquement le format et extrait le texte avec les métadonnées de confiance si disponibles.

Recherche et RAG

Indexation vectorielle

Les sources primaires sont indexées dans brain.db (le store partagé avec les PDF et l'historique de recherche) avec :

  • Chunking optimisé : Découpage intelligent du texte (300 mots, overlap 50)
  • Filtrage qualité : Suppression des chunks de faible qualité (entropie, mots uniques)
  • Dédoublonnage : Élimination des chunks similaires
  • Embeddings : via le provider d'embeddings configuré (Ollama, embarqué, ou un provider cloud) — pas un choix figé sur nomic-embed-text

Recherche hybride

La recherche dans les sources primaires utilise le même système hybride que les PDFs :

  • HNSW : Recherche sémantique rapide
  • BM25 : Recherche par mots-clés
  • RRF : Fusion des résultats (Reciprocal Rank Fusion)

Utilisation dans le chat

Les sources primaires sont automatiquement incluses dans les recherches RAG :

Question : "Que dit la correspondance de 1914 sur la mobilisation ?"

→ ClioDeck recherche dans :
  - PDFs indexés (sources secondaires)
  - Sources Tropy (sources primaires)

→ Les résultats pertinents des deux sources alimentent la réponse

Collections

Le nom de la collection s'affiche sur chaque source (carte primaire) et dans les statistiques agrégées, mais il n'existe aucun filtre de recherche par collection accessible depuis l'interface. Une action setCollectionFilter existe bien côté store (primarySourcesStore.ts), mais elle est orpheline — aucun composant sous PrimarySources/ ne l'appelle, et RAGConfigSection.tsx n'y fait aucune référence. Filé en issue #21 (même lacune que le filtrage par collection du Similarity Finder).

Réinitialiser l'index

Paramètres → Actions → Purge Primary Sources Database (ActionsSection.tsx, tropy:purge) supprime toutes les sources Tropy indexées et leurs embeddings — une resynchronisation complète du projet Tropy est ensuite nécessaire. Contrairement au bug d'Unlink du carnet Obsidian (issue #27), cette purge est correctement cantonnée : elle ne supprime que les tables préfixées tropy_* dans brain.db (PrimarySourcesVectorStore.purgeAll() — des DROP TABLE IF EXISTS ciblés, pas une suppression du fichier), sans toucher aux vecteurs PDF, aux notes Obsidian ni à l'historique de recherche. Un second bouton, séparé, purge les sources secondaires (PDF) via pdf:purge — les deux actions sont indépendantes.

Surveillance automatique

Watcher de fichier

ClioDeck peut surveiller votre fichier .tpy pour détecter les modifications :

  1. Activez Auto-sync dans les paramètres du projet Tropy
  2. ClioDeck détectera les changements lorsque vous sauvegardez dans Tropy
  3. La resynchronisation se déclenche automatiquement et silencieusement — il n'y a pas de notification ni de choix à faire, contrairement à ce qu'une version antérieure de cette page laissait entendre (vérifié dans tropy-service.ts et primarySourcesStore.ts : le gestionnaire de changement de fichier relance directement syncTPY(), sans aucune alerte affichée).

Une erreur du watcher est journalisée côté processus principal (tropy-service.ts), mais n'a aujourd'hui aucun affichage côté interface — pas d'alerte visible si le watcher échoue silencieusement.

⚠️ Risque de concurrence, vérifié dans le code (pas encore reproduit comme plantage) : cette resynchronisation automatique écrit dans brain.db via PrimarySourcesVectorStore, qui n'active ni le mode WAL ni de busy_timeout sur sa connexion — comme trois des quatre classes qui écrivent dans ce fichier partagé. Si elle se déclenche pendant une réindexation Obsidian ou un import PDF en cours, l'une des deux opérations peut échouer avec une erreur SQLITE_BUSY non rattrapée. Détail complet dans le guide Obsidian.

⚠️ Bug réel, vérifié dans le code : changer de projet ClioDeck ne désactive jamais un watcher actif de l'ancien projet. TropyService.init() (tropy-service.ts) remplace inconditionnellement this.watcher par une nouvelle instance à chaque changement de projet, sans jamais appeler .unwatch() sur l'ancienne — contrairement au registre LLM/embeddings, qui a son propre disposePreviousRegistry() explicite juste à côté. Le gestionnaire 'change' de l'ancien watcher lit this.vectorStore au moment où l'événement se déclenche, pas au moment où il a été enregistré — et this désigne le service singleton, donc cette référence pointe déjà vers le nouveau projet. Si le fichier .tpy de l'ancien projet change après le changement de projet (l'app Tropy peut très bien rester ouverte dessus), cela déclenche une resynchronisation superflue du projet actuellement ouvert, sans rapport avec le fichier qui a réellement changé. Filé comme issue #34.

Bonnes pratiques

Organisation dans Tropy

  1. Utilisez des tags cohérents : Ils sont importés et permettent le filtrage
  2. Renseignez les métadonnées : Titre, date, archive facilitent la citation
  3. Transcrivez dans les notes : Les notes Tropy sont la source privilégiée

Workflow recommandé

  1. Photographiez et organisez vos archives dans Tropy
  2. Transcrivez les documents importants (notes Tropy ou Transkribus)
  3. Synchronisez avec ClioDeck
  4. Utilisez le chat RAG pour interroger vos sources primaires

Performance

  • Gros projets : La première synchronisation peut être longue (génération des embeddings)
  • Re-synchronisation : Seuls les items modifiés sont traités
  • OCR : Désactivez-le si vous avez déjà des transcriptions

Dépannage

Le projet Tropy ne s'ouvre pas

Causes possibles :

  • Chemin incorrect vers le fichier .tropy ou .tpy
  • Fichier corrompu ou incompatible

Solutions :

  • Vérifiez que le fichier existe et est accessible
  • Essayez d'ouvrir le projet dans Tropy pour valider son intégrité

Les transcriptions n'apparaissent pas

Causes possibles :

  • Notes non enregistrées dans Tropy
  • Synchronisation incomplète

Solutions :

  • Sauvegardez votre projet dans Tropy
  • Relancez la synchronisation dans ClioDeck

La recherche ne trouve pas mes sources

Causes possibles :

  • Embeddings non générés
  • Transcription vide ou trop courte

Solutions :

  • Vérifiez que la source a une transcription (> 50 caractères)
  • Consultez les logs pour les erreurs d'embedding

Performances lentes

Causes possibles :

  • Le provider d'embeddings configuré n'est pas disponible (Ollama non démarré, modèle embarqué non téléchargé, ou clé cloud manquante — selon ce que vous utilisez)
  • Trop d'items à synchroniser

Solutions :

  • Vérifiez que votre provider d'embeddings configuré (Settings → LLM) est bien disponible avant de synchroniser
  • Synchronisez par lots si vous avez beaucoup d'items

Aucun raccourci clavier dédié n'existe pour la synchronisation Tropy — utilisez le bouton Sync du panneau.

API technique

Service Tropy

Le service Tropy (tropy-service.ts) expose les méthodes suivantes :

Méthode Description
openProject(path) Ouvre un projet Tropy
sync(options) Synchronise les données
search(query, options) Recherche dans les sources
getAllSources() Récupère toutes les sources
getStatistics() Statistiques du corpus

Vector Store

Les sources primaires utilisent PrimarySourcesVectorStore :

  • Base de données : {projet}/.cliodeck/brain.db (store partagé, pas un fichier dédié)
  • Index HNSW : {projet}/.cliodeck/primary-hnsw.index
  • Index BM25 : En mémoire, reconstruit au chargement

Références

Clone this wiki locally