# Guide d'intégration Tropy

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

---

## Vue d'ensemble

ClioDeck intègre [Tropy](https://tropy.org/), 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](https://tropy.org/))
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](./1.14-Obsidian-Vault-Guide.md#storage-and-migration).
> 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

- [Tropy - Documentation officielle](https://docs.tropy.org/)
- [Dublin Core Metadata](https://www.dublincore.org/specifications/dublin-core/)
- [Transkribus](https://readcoop.eu/transkribus/)
- [Tesseract OCR](https://tesseract-ocr.github.io/)