Boussole — assistant documentaire interne, sourcé et cloisonné

Un assistant RAG agentique pour les règles internes d'une entreprise : il cherche lui-même dans les documents (Word, PDF, HTML, Markdown), répond avec des citations exactes, respecte les droits d'accès de chaque collaborateur, écarte les versions périmées, et trace le coût de chaque réponse.

EN — Agentic RAG assistant for internal company documents: multi-format ingestion, hybrid BM25 + vector retrieval with RRF, role-based access control enforced before ranking, superseded-version filtering, Claude tool-use agent with native search_result citations, per-request cost ledger and answer cache, FastAPI + web UI, MCP server. Evaluated on a 48-question gold set.

Le problème

Un assistant sur les documents internes est le premier projet d'IA générative de beaucoup d'entreprises. Trois choses le font échouer en production :

1. Il invente quand la réponse n'est pas dans les documents, ou cite une ancienne version d'une règle.
2. Il divulgue : un salarié qui demande « la grille des salaires » ne doit rien obtenir, même indirectement.
3. Il coûte sans que personne ne sache combien, ni par question.

Boussole est construit autour de ces trois risques. La démonstration porte sur Corvelle Énergies, entreprise fictive de 240 salariés, avec 16 documents réalistes : télétravail (avec une ancienne version), notes de frais, congés, sécurité informatique, achats, charte IA, et trois documents confidentiels (grille des salaires pour les RH, guide des augmentations pour les managers, projet de réorganisation pour la direction).

Architecture

flowchart LR
    A[GED<br/>Word · PDF · HTML · Markdown<br/>+ manifeste : droits, version, statut] --> B[Ingestion<br/>sections par titres<br/>passages ~300 tokens]
    B --> C[(Index hybride<br/>BM25 + vecteurs)]
    U[Utilisateur<br/>rôle issu du SSO] --> D[Agent Claude<br/>tool use]
    D -->|search_documents<br/>read_document| E{Filtre droits<br/>+ versions}
    E --> C
    C -->|blocs search_result| D
    D --> F[Réponse avec<br/>citations exactes]
    D --> G[(Journal<br/>tokens · coût · cache)]
    C --> H[Serveur MCP]

Résultats

Recherche (mesurée, sans LLM)

48 questions de référence (eval/questions.yaml) : factuelles, reformulées en langage courant, multi-documents, piégées par une ancienne version, hors des droits du rôle, hors corpus.

Aucune fuite de document confidentiel sur les 8 questions d'accès, y compris la tentative d'injection. Aucune ancienne version remontée.

Le point faible est clair : les questions en langage familier (« mon gamin a de la fièvre », « j'ai perdu mon PC dans le train ») ne partagent presque aucun mot avec les documents. Ici, les vecteurs sont calculés localement (LSA), sans réseau. Deux leviers sont prévus dans le code pour combler l'écart : les vecteurs Voyage AI (--embedder voyage) et surtout l'agent, qui reformule la question en vocabulaire officiel avant de chercher.

Réponses générées (à mesurer avec une clé d'API)

eval/evaluate_answers.py mesure, par modèle : l'exactitude (chiffres attendus présents), la part de réponses sourcées, le bon refus quand l'information n'existe pas ou n'est pas accessible, les fuites, le coût par question et la latence. Il compare par défaut Claude Haiku 5.5 et Claude Sonnet 5.5.

export ANTHROPIC_API_KEY=...
python eval/evaluate_answers.py --models claude-haiku-5-5 claude-sonnet-5-5

Ces chiffres n'ont pas été produits pendant le développement (pas de clé disponible) : lancez la commande et reportez le tableau ici.

Démarrage rapide

pip install -r requirements.txt
make corpus index          # documents de démonstration + index
make test                  # 19 tests
make eval                  # évaluation de la recherche
make serve                 # http://localhost:8000

Sans clé d'API, l'interface fonctionne en mode hors ligne : elle affiche les passages les plus pertinents au lieu d'une réponse rédigée. Avec ANTHROPIC_API_KEY, l'agent répond avec citations. Le sélecteur de rôle de l'interface sert à la démonstration du cloisonnement ; en production, le rôle vient du jeton SSO.

Variables utiles :

Brancher sur Claude Desktop (MCP)

{
  "mcpServers": {
    "boussole": {
      "command": "python",
      "args": ["-m", "boussole.mcp_server"],
      "cwd": "/chemin/vers/boussole",
      "env": { "BOUSSOLE_ROLE": "salarie" }
    }
  }
}

Le rôle est fixé par l'administrateur dans la configuration : la conversation ne peut pas le changer.

Coûts

Chaque requête est journalisée (data/boussole.sqlite) : tokens d'entrée, de sortie, lus et écrits en cache, nombre d'appels au modèle et de recherches, coût en dollars, latence, refus. Les prix sont ceux de la grille publique Anthropic d'octobre 2026 (boussole/ledger.py).

Leviers déjà en place :

• cache de réponses cloisonné par rôle, modèle et version de l'index : une question déjà posée ne coûte rien ;
• mise en cache du prompt (consignes et définitions d'outils) côté API ;
• choix du modèle par variable d'environnement, avec l'évaluation pour arbitrer qualité et coût.

Structure

corpus_src/                 sources des 16 documents (Markdown + métadonnées)
scripts/build_corpus.py     rendu en Word, PDF, HTML, Markdown + manifeste GED
boussole/
├── ingest.py               lecteurs par format, sections, découpage
├── text.py                 normalisation du français (accents, mots vides, racinisation légère)
├── index.py                BM25, vecteurs (LSA locale ou Voyage AI), fusion RRF, filtres
├── access.py               rôles et niveaux de confidentialité
├── engine.py               agent Claude, blocs search_result, citations, mode hors ligne
├── ledger.py               journal des coûts, prix, cache de réponses
├── app.py                  API FastAPI
├── static/index.html       interface (rôles, réponse, sources, traçabilité, coûts)
└── mcp_server.py
eval/                       questions de référence, évaluation recherche et réponses
tests/                      19 tests, dont l'agent avec un client API simulé

Ce qui a été vérifié

• Mesuré : ingestion des 4 formats, recherche (tableau ci-dessus), cloisonnement par rôle et par version, API, interface (bureau et mobile, clair et sombre), serveur MCP avec deux rôles.
• Testé avec un client API simulé : boucle agentique, transmission des blocs search_result, numérotation des citations, calcul du coût, cache. Le format suit la documentation officielle de l'API ; un premier essai avec une vraie clé reste à faire.
• Pas encore mesuré : la qualité des réponses générées et les vecteurs Voyage AI (clés nécessaires).

Pistes

• Reclassement (rerank) des passages avant envoi au modèle
• Synchronisation incrémentale depuis SharePoint ou Google Drive, avec droits hérités de la GED
• Retours utilisateurs (👍/👎) reliés au journal pour enrichir le jeu d'évaluation

Stack

Python · Anthropic SDK (tool use, citations search_result, prompt caching) · scikit-learn · Voyage AI (optionnel) · FastAPI · SQLite · MCP Python SDK · python-docx · pdfplumber · BeautifulSoup · pytest · Playwright

Auteur : Fayçal Boubekri — AI & Data Engineer, Paris. Missions au forfait : agents IA, RAG, pipelines de données.