ktx : une couche de contexte exécutable pour les agents qui interrogent un entrepôt de données

Le problème visé : un agent qui redécouvre l'entrepôt à chaque question

Le README décrit un échec précis : un agent généraliste explore l'entrepôt de zéro à chaque question, invente sa propre logique de métrique et renvoie des nombres qui ne correspondent pas aux définitions validées. Ce n'est pas un problème de modèle, c'est un problème de contexte manquant. L'agent ne sait pas que le chiffre d'affaires net se calcule d'une certaine façon chez vous, ni quelles colonnes se joignent proprement. Le projet s'adresse donc à deux populations. D'abord les équipes data qui ont déjà un entrepôt et des définitions qui font autorité, mais qui voient les agents produire des chiffres divergents. Ensuite les équipes dont la connaissance est éparpillée entre dbt, Looker, Metabase, Notion et un wiki interne. Le README est explicite sur le cas inverse : sans entrepôt SQL, ktx n'a rien sur quoi se poser, et pour une requête ad hoc unique, psql ou un notebook suffisent. Cette franchise sur le hors-cible est plus utile que la liste habituelle de fonctionnalités.

Deux flux distincts : l'ingestion qui construit, le MCP qui sert

L'architecture visible dans le dépôt se lit en deux temps. Le premier est l'ingestion : des connecteurs de source alimentent un moteur de contexte composé d'un constructeur, d'une étape de réconciliation et d'une étape de validation, qui produisent deux artefacts, des pages wiki en Markdown et une couche sémantique en YAML. Le second est le service : un agent interroge ktx via MCP, qui cherche à la fois dans le wiki et dans la couche sémantique, renvoie les métriques approuvées et les compile en SQL exécuté en lecture seule contre l'entrepôt. Le point de conception qui compte est le graph de jointures. Le README indique qu'il résout automatiquement les chasm traps et les fan traps, ces deux pièges où une jointure multiple les lignes et gonfle un agrégat sans que personne ne s'en aperçoive. C'est là que se joue la différence avec un agent qui écrit son propre SQL : la métrique est récupérée de façon déclarative, pas réécrite à chaque prompt. La réconciliation, elle, est présentée comme automatique pour l'organisation et la déduplication, mais les contradictions entre sources sont signalées pour revue humaine. C'est un choix : l'outil ne tranche pas à votre place sur un désaccord entre deux définitions.

Mise en route : trois commandes, puis une vérification qui décide de tout

L'installation tient en une ligne : npm install -g @kaelio/ktx. Ensuite ktx setup crée ou reprend un projet local, configure les fournisseurs et les connexions, construit le contexte et installe l'intégration avec l'agent. Puis ktx status affiche l'état. L'exemple du README montre ce que doit contenir cette sortie : le chemin du projet, Project ready, LLM ready avec un modèle nommé, Embeddings ready, Databases configured, Context sources configured, ktx context built, et enfin Agent integration ready avec un mode comme codex:project. Si une de ces lignes manque, l'agent travaillera sur un contexte partiel. Le README insiste sur un point qui se rate facilement : si ktx status imprime ktx mcp start --project-dir ..., il faut lancer cette commande avant d'ouvrir le client d'agent. Les commandes de travail quotidien sont ktx ingest pour reconstruire le contexte de chaque connexion, ktx sl "revenue" pour chercher dans les sources sémantiques, ktx wiki "refund policy" pour chercher dans les pages locales, et ktx mcp start pour le serveur MCP. Une variante existe pour les utilisateurs déjà équipés d'un agent : demander à Claude Code, Codex, Cursor ou OpenCode d'exécuter npx skills add Kaelio/ktx --skill ktx depuis le répertoire du projet. Sur l'authentification, le README précise que ktx tourne avec vos propres clés d'API LLM ou avec une connexion d'agent locale (abonnement Claude Pro/Max via Claude Code, ou authentification Codex locale), sans facturation d'usage supplémentaire de la part de ktx.

La couche sémantique n'est pas gratuite à maintenir

Le README présente la réconciliation comme automatique, et c'est en partie vrai : l'organisation du wiki et la déduplication sont prises en charge. Mais l'étape de validation existe pour une raison, et les contradictions entre sources sont explicitement renvoyées à une revue humaine. Cela signifie qu'une équipe qui ingère plusieurs sources de vérité concurrentes, par exemple un modèle dbt et un tableau de bord Looker qui ne s'accordent pas, devra arbitrer. Le coût de maintenance ne disparaît pas, il se déplace : au lieu d'écrire des définitions, on valide des réconciliations. Autre contrainte, le projet s'appuie sur un LLM et sur des embeddings, donc sur des coûts et une latence qui dépendent de votre fournisseur. La liste des sources supportées est large (PostgreSQL, Snowflake, BigQuery, ClickHouse, MySQL, SQL Server, SQLite, DuckDB, Amazon Athena, MongoDB) et celle des intégrations aussi (dbt, MetricFlow, LookML, Looker, Metabase, Sigma, Notion, Google Drive), mais le README ne documente pas la profondeur de chaque connecteur. Impossible de savoir depuis ce matériau si un connecteur donné capture les métadonnées aussi finement qu'un autre. C'est le premier point à tester soi-même sur sa propre pile.

Face à une couche sémantique classique : automatiser la construction plutôt que la déclaration

Le tableau comparatif du README résume la position : une couche sémantique traditionnelle fournit des définitions de métriques approuvées et réutilisables, mais la détection des colonnes joignables et la résolution des fan et chasm traps y sont manuelles. ktx revendique l'automatisation de ces deux points, plus l'absorption de la connaissance wiki. La différence d'approche est donc moins dans le résultat final, une couche sémantique interrogeable, que dans le mode de construction. Une couche classique suppose que quelqu'un déclare les jointures et les métriques ; ktx les déduit en échantillonnant les tables, en capturant les métadonnées et les schémas d'usage, puis en annotant les sources. Le pari est que la déduction à partir de l'usage réel produit un contexte plus proche de la pratique que la déclaration exhaustive. Le revers est symétrique : une couche déclarative est déterministe et auditable ligne par ligne, alors qu'un contexte inféré doit être vérifié, ce que le mécanisme de signalement des contradictions reconnaît implicitement. Aucun des deux n'est meilleur dans l'absolu, mais si votre organisation exige une traçabilité complète de chaque définition, la construction automatique ajoute une étape de contrôle.

Licence, mises à jour et ce que le dépôt ne dit pas

Le projet est publié sous Apache-2.0, une licence permissive qui autorise l'usage commercial et la modification, avec les obligations habituelles de conservation des mentions de licence et d'attribution, et une clause de brevets. Ce paragraphe n'est pas un conseil juridique : pour un usage en entreprise, la conformité se vérifie avec vos propres règles. Côté mises à jour, le README donne une seule procédure : npm install -g @kaelio/ktx@latest. Le rythme de publication est rapide, trois versions mineures entre le 30 juin et le 3 juillet 2026 selon les notes de version, ce qui suggère une phase active de développement plutôt qu'une API figée. Le dépôt n'est pas archivé et le dernier envoi date du 3 septembre 2026. Le README tronqué s'arrête au début de l'arborescence de projet, avec ktx.y, donc la structure exacte des fichiers de configuration n'est pas entièrement visible dans ce matériau. De même, aucune information sur le nombre d'utilisateurs, la performance des requêtes ou la couverture de tests n'est fournie ici, et je ne peux pas en produire.

Conclusion éditoriale

ktx convient aux équipes qui possèdent déjà un entrepôt SQL et dont la connaissance métier est dispersée entre dbt, Looker, Metabase et un wiki. Il ne convient pas à qui n'a pas d'entrepôt SQL, ni à qui cherche une réponse ponctuelle. Avant d'adopter, vérifier une chose précise : que la sortie de ktx status affiche bien les quatre lignes de préparation (projet, LLM, embeddings, contexte), et que la commande ktx mcp start --project-dir ... qu'il imprime est lancée avant l'ouverture du client d'agent, sinon l'agent ne verra rien.

Sources officielles

1. Kaelio/ktx on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases