Knowledge Graph Nexus

Le Knowledge Graph Nexus ajoute une couche relationnelle au-dessus des données déjà stockées dans Postgres : applications appelantes, sources, workspaces, projets, documents, requêtes, conversations et citations. Il ne remplace pas Qdrant et ne change pas le modèle de permissions documentaire.

TL;DR

• Le KG est stocké dans Postgres via les tables knowledge_graph_versions, knowledge_nodes et knowledge_edges.
• La page UI est disponible dans l'administration Nexus via le dashboard Knowledge Graph.
• Les endpoints API sont sous /api/knowledge-graph/*.
• Le rebuild KG est manuel et réservé aux administrateurs.
• Le retrieval RAG reste Qdrant-first ; le scoring KG est optionnel et désactivé par défaut.
• L'expansion KG est préparée, mais pas active par défaut.
• Nexus distingue le KG documentaire du Code KG / Meta KG applicatif; les deux graphes n'ont pas les mêmes usages ni les mêmes connecteurs MCP.

Périmètre actuel

Le lot livré met en place un KG structurel, en observation :

KG documentaire vs Code KG / Meta KG

Nexus maintient deux surfaces de graphe complémentaires :

Le KG documentaire ne remplace pas Qdrant et ne contourne jamais les droits source_app / workspace / project. Le Code KG ne sert pas à répondre à un utilisateur final sur ses documents; il sert à orienter un agent développeur vers les fichiers, risques et relations de code à vérifier.

Ponts possibles entre les deux graphes :

document REFERENCES_FILE code:file
document DOCUMENTS_ENDPOINT code:api_endpoint
document DOCUMENTS_TABLE data:postgres_table
document DOCUMENTS_COLLECTION vector:qdrant_collection

Ces ponts sont des relations d'analyse. Ils ne modifient pas le modèle de permissions documentaire.

Connecteurs MCP

Deux MCP doivent rester distincts :

nexus-doc-kg accepte les filtres documentaires caller_app, source_app, workspace et project. Si un graphe documentaire est absent ou inaccessible, il doit retourner une alerte explicite plutôt que lancer une mutation.

Modèle de données

Versions

knowledge_graph_versions trace chaque reconstruction :

• tenant_id
• scope_type, scope_key
• status : building, ready, failed
• node_count, edge_count
• metadata
• created_at, completed_at

Nœuds

knowledge_nodes contient les entités relationnelles :

Relations

knowledge_edges relie les nœuds :

API

Les endpoints exigent une authentification Nexus. Les filtres source_app, workspace et project respectent la hiérarchie existante : un workspace nécessite source_app, un project nécessite source_app et workspace.

GET /api/knowledge-graph/overview

Retourne l'état du dernier graphe prêt :

• enabled
• graph_version_id
• status
• node_count
• edge_count
• dates de création et de complétion

Si KG_ENABLED=false, l'endpoint retourne enabled=false.

GET /api/knowledge-graph/subgraph

Retourne un sous-graphe filtré.

Paramètres principaux :

GET /api/knowledge-graph/neighbors/{node_id}

Retourne les voisins d'un nœud. Le résultat est limité par les permissions de lecture sur les sources autorisées.

POST /api/knowledge-graph/rebuild

Reconstruit le graphe structurel pour le tenant par défaut.

Contraintes :

• accès admin requis ;
• KG_ENABLED=true requis ;
• le nombre de requêtes historiques prises en compte est borné par KG_REBUILD_MAX_QUERY_ROWS.

UI

Le dashboard Knowledge Graph est intégré à l'administration Nexus. Il affiche :

• les métriques du graphe ;
• les filtres par source, workspace, projet et types ;
• une visualisation relationnelle ECharts ;
• un panneau de détail sur le nœud sélectionné ;
• une action de rebuild pour les administrateurs.

Variables d'environnement

En production, laisser KG_RETRIEVAL_SCORE_ENABLED=false et KG_RETRIEVAL_EXPAND_ENABLED=false tant que le scoring et l'expansion relationnels n'ont pas été validés sur vos corpus.

Ces réglages sont aussi exposés dans l'admin UI, section Paramètres → Knowledge Graph. La section est volontairement séparée des paramètres RAG classiques pour éviter d'activer un comportement expérimental en pensant modifier uniquement le retrieval standard.

Intégration RAG

Le pipeline RAG reste :

question
-> retrieval Qdrant
-> expansion KG optionnelle et bornée
-> scoring KG optionnel
-> génération LLM avec citations

Le scoring KG reste optionnel. Quand KG_RETRIEVAL_SCORE_ENABLED=true, le reranking combine un score de rang Qdrant dominant avec un score KG minoritaire basé sur le scope, les citations du même thread, l'historique de citations, les requêtes historiques similaires, les co-citations et une centralité bornée.

Quand KG_RETRIEVAL_EXPAND_ENABLED=true, le KG peut proposer quelques documents voisins absents des candidats initiaux. Ces documents doivent rester dans le même tenant/source_app/workspace/project; Nexus récupère ensuite des chunks Qdrant pour ces documents et les soumet au même reranking. L'expansion reste bornée par KG_RETRIEVAL_MAX_EXTRA_DOCS et ne contourne pas les filtres de permissions.

Benchmark RAG vs RAG + KG

Le script ops/kg_rag_compare.py permet de comparer deux exécutions de /api/query :

python ops/kg_rag_compare.py questions --output tmp/kg_rag_cases.json
python ops/kg_rag_compare.py run --api-url http://127.0.0.1:18500 --mode baseline --cases docs/benchmark/kg_tests/cases.json --output tmp/kg_rag_baseline.json
python ops/kg_rag_compare.py run --api-url http://127.0.0.1:18500 --mode kg --cases docs/benchmark/kg_tests/cases.json --output tmp/kg_rag_kg.json
python ops/kg_rag_compare.py compare --baseline tmp/kg_rag_baseline.json --kg tmp/kg_rag_kg.json --report tmp/kg_rag_report.md --json-report tmp/kg_rag_report.json

Le corpus de test versionné vit dans docs/benchmark/kg_tests/ :

• manifest.json décrit source_app=kg_tests, les workspaces, projets et documents ;
• fixtures/ contient les documents Markdown de test ;
• cases.json contient les questions progressives utilisées par le benchmark.

Préparation locale du corpus :

python ops/kg_tests_prepare.py
python ops/kg_tests_prepare.py --apply
python ops/kg_tests_prepare.py --index --reset --rebuild-kg

Le premier appel est un dry-run. --apply écrit uniquement Postgres. --index écrit Postgres et Qdrant; il nécessite les variables d'embedding disponibles. --reset ne purge que les documents et points Qdrant de source_app=kg_tests.

Le rebuild lancé par ce script est scoped à source_app=kg_tests; il n'écrase pas le graphe global. Au retrieval, Nexus privilégie un graphe scoped disponible pour la source_app, puis retombe sur le dernier graphe global prêt.

Dernier constat local connu :

• qualité RAG normal : 100/100 ;
• qualité RAG + KG : 100/100 ;
• influence KG : 0/100 ;
• citations identiques sur les cas testés.

Interprétation : le KG ne dégrade pas le retrieval, mais le scoring actuel est encore trop faible pour améliorer l'ordre des citations. L'amélioration attendue porte sur les relations du graphe, les voisins fiables et les historiques de citations.

Sécurité et limites

• caller_app est une dimension d'observabilité, pas une permission documentaire.
• Les permissions de lecture restent portées par source_app.
• Le KG ne doit jamais exposer un document hors scope utilisateur.
• Une erreur KG ne doit pas faire échouer une requête RAG.
• Le rebuild KG ne modifie pas Qdrant.
• Le KG ne remplace pas les citations : une réponse doit rester fondée sur les documents récupérés.

Prochaines améliorations prévues

1. Ajouter un scoring relationnel basé sur les chemins query -> cited -> document, thread -> query et les voisins proches.
2. Activer une expansion KG contrôlée uniquement quand Qdrant est faible ou ambigu.
3. Ajouter des tests benchmark plus discriminants : questions multi-documents, follow-up, documents lexicalement éloignés mais reliés.
4. Exposer des métriques d'influence KG dans les traces de retrieval.