ObsiGate/docs/GUIDES/RECHERCHE_PDF_EXCALIDRAW.md

🔍 Guide Recherche, PDF, Excel & Excalidraw

ObsiGate va au-delà de la simple lecture : recherche puissante, rendu des documents riches (PDF, diagrammes) et indexation de leur contenu pour que tout soit retrouvable.

Public : tous les utilisateurs Fiches techniques : features/semantic-search.md · features/pdf.md · features/excalidraw.md

---

1. Recherche plein texte (TF-IDF)

Le moteur d'ObsiGate s'appuie sur un index inversé et un scoring TF-IDF avec :

• Boost titre — une correspondance dans le titre pèse 3× plus.
• Normalisation des accents — resume trouve résumé, elephant trouve éléphant.
• Stemming français — les variantes des mots sont rapprochées.
• Snippets surlignés — les termes trouvés sont mis en <mark> dans l'extrait.
• Facettes — compteurs par vault et par tag sur les résultats.
• Pagination — 50 résultats par page.
• Tri — par pertinence (TF-IDF) ou par date de modification.
• Chips de filtres — les filtres actifs apparaissent sous forme de puces retirables.
• Historique — les 50 dernières recherches sont conservées en localStorage.

La recherche s'effectue sans I/O disque : le contenu est déjà en mémoire.

---

2. Syntaxe de requête

Opérateur	Description	Exemple
tag:<nom>	Filtre par tag	tag:recette docker
#<nom>	Raccourci de tag	#linux serveur
vault:<nom>	Filtre par vault	vault:IT kubernetes
title:<texte>	Filtre par titre	title:pizza
path:<texte>	Filtre par chemin	path:recettes/soupes
ext:<type>	Filtre par type de fichier	ext:md kubernetes
"phrase exacte"	Recherche d'une phrase	tag:"multi mots"

Les opérateurs sont combinables :

tag:linux vault:IT ext:md serveur web

Cette requête cherche « serveur web » dans les fichiers Markdown de la vault IT portant le tag linux.

Filtres par extension

Extension	Contenu
ext:md	Notes Markdown
ext:py, ext:sh, ext:js	Scripts et code
ext:pdf	Documents PDF (texte extrait)
ext:excalidraw	Diagrammes Excalidraw (texte extrait)

---

3. Autocomplétion et suggestions

• /api/suggest — suggère des titres de fichiers.
• /api/tags/suggest — suggère des tags.
• Navigation clavier : ↑ / ↓ puis Entrée ; Échap ferme les suggestions.

Raccourcis de recherche

Raccourci	Action
Ctrl + K / Cmd + K	Focaliser la barre de recherche
/	Focaliser la recherche (hors champ texte)
↑ / ↓	Naviguer dans les suggestions
Entrée	Sélectionner la suggestion active ou lancer la recherche
Échap	Fermer les suggestions / quitter la recherche

Recherches sauvegardées et signets sont disponibles via l'API (/api/saved-searches, /api/bookmarks).

---

4. Recherche sémantique (optionnelle)

Au classement TF-IDF peut s'ajouter un classement par embeddings, fusionné via la méthode RRF (Reciprocal Rank Fusion). Activation : touche ~ (ou Alt + S) dans la recherche.

Deux modes :

1. Sans dépendance — un embedder par hachage fournit une base utilisable immédiatement.
2. Embeddings réels — installez backend/requirements-semantic.txt et/ou renseignez les variables OBSIGATE_EMBEDDING_* pour utiliser all-MiniLM-L6-v2.

Détails et configuration : features/semantic-search.md.

---

5. Support PDF

Lecture

Les fichiers PDF de vos vaults s'affichent en ligne dans le navigateur via le visualiseur PDF natif (iframe + <embed>). Le fichier est streamé en HTTP Range (206 Partial Content) : les gros PDF se chargent progressivement.

Recherche

Le texte est extrait à l'indexation (pypdf / pymupdf), donc le contenu des PDF est recherchable via la recherche plein texte. Utilisez ext:pdf pour limiter les résultats aux PDF.

Métadonnées

GET /api/file/{vault}/pdf/info renvoie les métadonnées (pages, titre, auteur) sans transférer le document.

curl "http://localhost:2020/api/file/Recettes/pdf/info?path=menu.pdf"

Limites

• Pas d'OCR : les PDF scannés (images) ne sont pas recherchables.
• Pas d'annotation ni d'édition du PDF lui-même.

---

6. Tableurs Excel (XLSX)

Affichage et édition

Un fichier .xlsx s'ouvre dans une visionneuse dédiée : un tableau par feuille, des onglets pour naviguer entre elles, les en-têtes A1/B1 et les numéros de ligne. Chaque cellule est modifiable directement (clic), Entrée valide, Échap annule la saisie. Enregistrer envoie les cellules modifiées à PUT /api/file/{vault}/xlsx/save : une sauvegarde par feuille, avec backup automatique du fichier avant écriture, et une écriture atomique (le classeur n'est jamais laissé à moitié écrit).

Avertissement avant enregistrement

Certains classeurs contiennent des éléments qu'ObsiGate ne sait pas réécrire : valeurs calculées mises en cache par Excel, segments (slicers), chronologies, contrôles de formulaire, connexions/requêtes, XML personnalisé, signature numérique, commentaires enrichis, macros. L'ouverture affiche alors un bandeau qui les liste, et la première sauvegarde demande confirmation. Si vous refusez, rien n'est écrit.

Les graphiques, images et tableaux croisés sont, eux, bien conservés.

Formules

Par sécurité, une valeur saisie commençant par = ou @ est stockée comme texte (une formule injectée s'exécuterait à l'ouverture du fichier dans Excel). Le bouton f(x) de la barre d'outils active les vraies formules pour la session en cours.

curl -X PUT "http://localhost:2020/api/file/Recettes/xlsx/save?path=budget.xlsx"   -H "Content-Type: application/json"   -d '{"sheet": "Budget", "cells": {"B1": "250"}, "allow_formula": false, "force": false}'

• allow_formula : true pour écrire une vraie formule (=B1*2).
• force : true pour enregistrer malgré les éléments non préservés (sinon l'API répond 409 xlsx_lossy_content).
• Deux sauvegardes simultanées sur le même fichier : la seconde reçoit 409 conflict au lieu d'écraser la première.

Feuilles volumineuses et lecture par fenêtres

Le rendu est plafonné à 500 lignes × 40 colonnes par feuille. Quand une feuille dépasse ce plafond, un bandeau « Feuille tronquée » l'annonce explicitement (par exemple « 500 lignes affichées sur 520 ») au lieu de présenter une table courte comme complète — le classeur, lui, n'est jamais modifié. La ligne d'en-têtes de colonnes reste visible pendant le défilement vertical.

Côté API, GET /api/file/{vault}/xlsx/sheet sert une feuille par fenêtres de lignes, y compris au-delà du plafond d'affichage — les coordonnées A1 renvoyées sont celles de la feuille réelle :

curl "http://localhost:2020/api/file/Recettes/xlsx/sheet?path=budget.xlsx&sheet=Budget&offset=500&limit=200"

• offset : première ligne renvoyée (0-based) ; limit : nombre de lignes (1 à 1 000 par requête).
• La réponse porte total_rows, truncated et has_more pour paginer.
• Erreurs : 404 si la feuille n'existe pas, 415 si le fichier n'est pas un .xlsx.

Limites

• L'affichage intégré reste plafonné à 500 lignes × 40 colonnes par feuille (le défilement automatique au-delà est en préparation) ; les lignes cachées restent accessibles via l'endpoint ci-dessus.
• Styles, formats de nombre, cellules fusionnées et volets figés ne sont pas rendus.
• Formats non gérés : .xls, .xlsm (macros), .ods.

---

7. Diagrammes Excalidraw

Les fichiers .excalidraw et .excalidraw.md (dont le format compressé du plugin Obsidian Excalidraw) s'ouvrent dans un éditeur visuel Excalidraw complet, dans une iframe sandboxée.

• Dessin et édition sans quitter ObsiGate.
• Sauvegarde automatique (débounce 2 s) ou Ctrl + S.
• Thème clair/sombre suivi automatiquement.
• Texte indexé : le texte des éléments du diagramme est extrait à l'indexation et donc recherchable (ext:excalidraw).

Fiche technique : features/excalidraw.md.

---

8. Autres contenus riches

Mermaid

Les blocs de code ```mermaid sont rendus en diagrammes interactifs (live preview, thèmes, zoom, plein écran, pré-processeur compatible syntaxe Obsidian).

Images Obsidian

Toutes les syntaxes d'images sont supportées avec résolution intelligente en 7 stratégies :

1. chemin absolu ;
2. dossier d'attachements configuré (VAULT_N_ATTACHMENTS_PATH) ;
3. index de démarrage (correspondance unique) ;
4. même répertoire que la note ;
5. racine de la vault ;
6. index de démarrage (correspondance la plus proche) ;
7. repli : [image not found: fichier.ext].

Rescan manuel des attachements :

curl -X POST "http://localhost:2020/api/attachments/rescan/Recettes"

Graphe et backlinks

• Graphe : vue force-directed (Barnes-Hut), filtres (tag, type), profondeur, mode focus, export PNG, aperçu au survol (Ctrl + clic).
• Backlinks : GET /api/file/{vault}/backlinks?path=… liste les notes pointant vers un document.

---

9. Dépannage

Symptôme	Piste
Un PDF ne s'affiche pas	Vérifier la taille (OBSIGATE_PDF_MAX_SIZE_MB, défaut 50 Mo)
Le texte d'un PDF scanné n'est pas trouvé	Pas d'OCR : normal
Une image reste introuvable	Configurer VAULT_N_ATTACHMENTS_PATH, puis rescan
La recherche sémantique ne s'active pas	Vérifier le toggle ~ et OBSIGATE_EMBEDDING_*
Résultats obsolètes	Forcer une réindexation : GET /api/index/reload