Voir aussi : Guide RaggableTree · Retour à l'index
ADR — Graphe sémantique RaggableTree comme substrat de contexte des agents
Statut : Accepté · Date : 2026-04 · Portée : Orkeon.Analysis + Orkeon.Tools.Analysis
Contexte
Les agents Orkeon raisonnent sur des bases de code réelles dépassant fréquemment les centaines de milliers de lignes sur plusieurs langages (TypeScript, C#, Python, Go, Rust). Trois contraintes matérielles :
- Budget tokens — Le contexte LLM (même 1M tokens) ne peut pas absorber un monorepo ; il faut un index compact qui réponde à « quel symbole est affecté par X ? » sans recharger les sources.
- Granularité variable — Un agent peut avoir besoin d'une vue package, d'un extrait de méthode, d'une chaîne d'appels ou d'une mesure de complexité selon la tâche. Une seule représentation (AST brut, embeddings plats, documents Markdown) ne couvre pas tous ces cas.
- Coût d'itération — Un projet évolue en continu ; reconstruire l'index complet à chaque commit est inacceptable (mesuré : 20× plus lent qu'une réindexation incrémentale ciblée).
Les solutions naïves disponibles (lecture fichier via file_read, grep plein-texte, recherche RAG sur chunks arbitraires) ont été évaluées et considérées insuffisantes : elles ne préservent pas les relations sémantiques (imports, appels, héritage) et forcent l'agent à redécouvrir la structure à chaque requête.
Décision
Construire un graphe sémantique stratifié — cinq NodeLevel plus la couche d'arêtes — alimenté par Tree-sitter, exposé aux agents via 13 tools structurels.
Les cinq niveaux (NodeLevel) et les arêtes :
- L0 Monorepo — racine du projet indexé
- L1 Package — unité de build détectée par marker (
package.json,*.csproj, ...) - L2 Module — fichier source
- L3 Symbol — classe, interface, fonction, méthode, enum, property, constant
- L4 Statement — if/try/loop/return extraits pour les requêtes de flow et de CFG
- Edges — Imports, Calls, Extends, Implements, Contains
Sept composants-clés implémentent le pipeline :
ILanguageAdapter— adaptation par langage (queries Tree-sitter + heuristiques d'import)RaggableTreeBuilder— construction initiale (6 phases)IncrementalReindexEngine— réindexation diff (changed files only)IRaggableStore— requêtes sur le graphe construitIEmbeddingProvider+IEmbeddingTextComposer— recherche sémantiqueIFrameworkFingerprinter— tagging des nœuds par framework (Angular, NestJS, ASP.NET, Flask, FastAPI)ICodebaseWatcher+IRaggableTreeEventBus— synchronisation temps réel
Alternatives rejetées
LSP (Language Server Protocol) complet
Intégrer un serveur LSP par langage (tsserver, OmniSharp, pylsp, ...) donne des informations très précises sur les symboles et les références.
- Rejeté car : nécessite un runtime par langage (Node.js pour tsserver, MSBuild pour OmniSharp, Python venv pour pylsp) et une orchestration de processus longue-durée. Impraticable pour un pipeline d'indexation batch sur CI ou sur un serveur sans les SDK installés.
Roslyn-only (C# uniquement)
Roslyn donne un AST parfait et un graphe de symboles résolus pour C#.
- Rejeté car : le portage Python/JavaScript/Go/Rust est une perte fonctionnelle majeure. La cible est un framework multi-langage par défaut.
Recherche plein-texte + embeddings plats
Découper chaque fichier en chunks de 500 tokens, vectoriser, stocker dans un vector store, et laisser les agents faire uniquement de la recherche sémantique.
- Rejeté car : perd les relations structurelles (qui appelle quoi, qui hérite de quoi, quels imports). Les tools
flow_trace,impact_analysis,sub_graphdeviennent impossibles. La qualité des réponses chute sur les questions typées « si je modifie X, qu'est-ce qui casse ? ».
Regex/ctags over AST
Option la plus rapide à implémenter mais la plus fragile : ne distingue pas les vrais appels des mentions en commentaire, ne résout pas les imports, rate les constructions modernes (async/await, decorators, spread).
- Rejeté car : la dette technique grandit avec chaque nouveau langage ou framework. Tree-sitter offre une grammaire officielle maintenue pour 40+ langages.
Conséquences
Positives
- Contexte compact —
ICodebaseContextProviderproduit un résumé < 500 tokens (markdown) ou < 200 tokens (compact) injectable dans tous les agents. - Requêtes typées — Les 13 tools remplacent des dizaines de lignes de prompting « lis ce fichier et dis-moi... » par des appels déterministes.
- Réindexation incrémentale — Le moteur ne re-parse que les fichiers changés (objectif mesuré : < 5% du coût initial).
- Multi-langage par construction — Ajouter un langage = implémenter un
ILanguageAdapter, pas étendre un pipeline C#-only.
Négatives
- Surface API importante — 7 interfaces + 5 adaptateurs + 13 tools = 25 points d'extension à comprendre avant d'étendre le système. Atténué par les docs
docs/architecture/raggable-tree.mdet l'ADR présent. - Tree-sitter en dépendance native — Les parsers sont compilés en C ; les builds musl ou ARM32 peuvent nécessiter du travail. Atténué par
TreeSitter.DotNetqui wrappe la compilation pour la plupart des plateformes cibles. - Coût mémoire — Un monorepo de 100k symboles avec embeddings 1536-dim pèse ~600 MB en mémoire. Atténué par la possibilité d'utiliser un vector store externe (Redis/LanceDB) plutôt que
InMemoryRaggableStore. - Provider embedding optionnel mais stratégique — Sans embedding,
codebase_searchetsemantic_searchsont désactivés. Le pipeline reste utile pour les tools structurels (map, detail, graph, flow) mais perd sa composante sémantique.
Risques acceptés
- Les re-exports TypeScript (
export { Foo } from './bar') et les imports Python dynamiques peuvent produire desUnresolvedRef. Décision : documenter la limite plutôt que construire un résolveur lourd en V1. - Le cache JSON est non versionné et donc invalide aux changements d'adapter. Décision : recalculer à la demande, sans migration automatique.
Amendement — 2026-08-18
La surface d'outils est passée depuis des 13 tools décrits ici à 15
(Orkeon.Tools.Analysis) ; le chiffre dérivé « 25 points d'extension » est
désormais 27. Les comptes ci-dessus sont conservés tels quels — cet ADR est un
enregistrement de décision gelé ; le guide RaggableTree
est l'inventaire de référence, maintenu.
Amendement — 2026-09-30 (état de l'implémentation)
La décision tient ; trois des mécanismes qu'elle nomme ont été livrés autrement, et le texte ci-dessus est conservé tel quel :
- Synchronisation temps réel —
ICodebaseWatcher+IRaggableTreeEventBusont été remplacés comme mécanisme de synchronisation par la passe de fraîcheur paresseuse (IndexFreshnessService: marquage « sale » à l'écriture + sonde du working tree git + réindexation incrémentale avant la réponse de chaque tool de lecture). Le bus d'événements transporte les notifications de rafraîchissement (RaggableTreeUpdated) ; l'implémentation du watcher (FileSystemWatcherCodebaseWatcher) existe mais aucun hôte livré ne l'enregistre. - Vector store externe comme atténuation mémoire — non réalisé : le graphe et
toutes les requêtes vivent dans
InMemoryRaggableStore; unIVectorStoreProviderenregistré (p. ex.MemoryProviderVectorStoreAdaptersur Redis/LanceDB) ne reçoit qu'un miroir en écriture seule des embeddings. - Recherche sans embeddings — n'est plus désactivée :
codebase_searchest hybride (embedding + BM25 fusionnés par RRF) et dégrade vers le BM25 lexical quand aucun embedder n'est câblé. Le runner host livré prend par défaut des embeddings on-device (LocalSmartComponents, sans clé d'API). Le cache JSON cité dans les risques acceptés (RaggableTreeCache) n'est câblé par aucun hôte livré.
Amendement 2026-10-29
Six affirmations de l'enregistrement et de ses amendements ci-dessus sont périmées ; l'enregistrement ci-dessus est conservé tel quel.
- Tools :
AddRaggableTreeToolsenregistre 29 tools, et non 15 (amendement du 2026-08-18) ; les « 27 points d'extension » qui en étaient dérivés ne tiennent pas. Le guide RaggableTree les liste. - Adapters : douze adapters de langage intégrés, et non cinq.
- Cache d'index : le cache des risques acceptés est une base SQLite versionnée
(
RaggableTreeCache,PRAGMA user_version), enregistrée parAddRaggableTreeet utilisée parindex_codebasedans chaque hôte livré ; voir Cache d'index. - Arêtes :
EdgeKinda huit valeurs, et non les cinq nommées sous Décision :Imports,Calls,Extends,Implements,Contains, plusTests,DocumentsetProjectDepends. - Tools de recherche :
semantic_searchn'est pas un tool RaggableTree ; le tool de recherche estcodebase_search. - Taille du résumé : le guide donne le budget du résumé de contexte à environ
300 tokens (
markdown, le défaut) et environ 150 (compact), et non les 500 et 200 des Conséquences.
Voir aussi : Guide RaggableTree · Retour à l'index