Skip to content

1.6 Tropy Integration Guide

Jump to bottom
Frédéric Clavert edited this page Jul 26, 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. 4. OCR manuel par source : depuis la RC4, un bouton sur la fiche de la source relance l'OCR sur celle-ci seule. La RC4 a aussi corrigé deux défauts de ce chemin : le succès était annoncé sans vérifier que l'écriture avait eu lieu, et la transcription n'atteignait jamais le moteur de recherche — la réindexation supprimait les extraits sans les regénérer.

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. Le filtre par collection est accessible depuis l'interface depuis la RC4, ici comme dans le Similarity Finder : l'action setCollectionFilter existait côté store sans qu'aucun composant ne l'appelle.

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 à ce que faisait le détachement du carnet Obsidian avant la RC4 — il supprimait brain.db en entier —, 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 résiduel de concurrence, vérifié dans le code — revu à la baisse après une contre-vérification : cette resynchronisation automatique écrit dans brain.db via PrimarySourcesVectorStore, qui n'active pas le mode WAL sur sa connexion — comme trois des quatre classes qui écrivent dans ce fichier partagé. Une version antérieure de ce encadré affirmait qu'une écriture concurrente échouerait immédiatement en SQLITE_BUSY faute de busy_timeout : c'était faux — better-sqlite3 applique par défaut un timeout de 5000 ms à toute connexion (database.js : 'timeout' in options ? options.timeout : 5000). Le risque qui subsiste est bien plus étroit : seule une transaction d'écriture tenant le verrou plus de 5 secondes (envisageable pendant une grosse réindexation par lot) pourrait encore pousser un écrivain concurrent en SQLITE_BUSY. Détail complet dans le guide Obsidian. Les cinq écrivains de brain.db posent désormais ce délai — le store du manuscrit était le dernier à ne pas le faire, jusqu'à la RC4.

Corrigé en RC4. Changer de projet ne démontait pas le watcher de l'ancien : une modification du .tpy précédent — l'application Tropy pouvant très bien rester ouverte dessus — déclenchait une resynchronisation du projet actuellement ouvert, sans rapport avec le fichier qui avait changé. La RC4 démonte le watcher et son store à la bascule, et purge ses écouteurs : les empiler faisait qu'un seul enregistrement dans Tropy déclenchait autant de synchronisations concurrentes qu'il y avait eu d'activations.

Note de conception, vérifiée, pas un bug distinct : la synchronisation (y compris l'OCR par lot, qui peut prendre du temps sur beaucoup d'images) ne risque pas l'écriture croisée entre projets — TropySync.sync() et processItem() reçoivent vectorStore en paramètre explicite, capturé une fois par tropy-service.ts au moment de l'appel, pas relu en direct sur le singleton pendant l'opération. En revanche, la même init() qui remplace this.watcher sans .unwatch() (ci-dessus) fait la même chose avec this.vectorStore : aucune fermeture de l'ancienne instance avant réassignation. Une synchronisation encore en cours après un changement de projet continue donc d'écrire correctement dans l'ancien projet — mais la connexion better-sqlite3 de cet ancien PrimarySourcesVectorStore n'est jamais explicitement fermée — une fuite de ressource qui laisse un verrou potentiel sur le brain.db de l'ancien projet si l'utilisateur le rouvre pendant que l'ancienne connexion est encore active (le timeout par défaut de 5 s de better-sqlite3 absorbe les contentions courtes, voir l'encadré ci-dessus).

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