GitHub – NVIDIA/auto-ontology : Auto Ontology est un framework Python permettant de créer des couches de raisonnement sémantique basées sur des graphiques sur des données. Il permet une génération de requêtes déterministes, une meilleure récupération du contexte et une IA plus explicable pour les flux de travail LLM et des agents.

Les agents peuvent récupérer des documents et interroger des bases de données, mais la fiabilité bloque l’analyse agent : une mesure de revenus traitée plus rapidement ne vaut rien si le chiffre est erroné. Les agents ont besoin d’une couche de contexte qui leur indique où se trouvent les données, ce qu’elles signifient, s’il faut les utiliser, comment les utiliser, d’où elles viennent et ce qui est similaire. NVIDIA Auto Ontology est une bibliothèque ouverte qui construit cette couche à partir de métadonnées d’entreprise, réconcilie les définitions entre les systèmes et l’expose à n’importe quel ensemble d’agents via MCP, CLI et API. Il complète les modèles sémantiques que les clients possèdent déjà.

Il permet aux développeurs de :

• Découvrir : générer des ontologies d’entreprise à partir de métadonnées ; connecter les ontologies et les modèles sémantiques existants ; créez des graphiques de connaissances prêts pour l’IA.
• Ground : donnez aux agents une signification commerciale fiable pour les métriques, les entités et les relations ; concilier les définitions incohérentes entre les systèmes.
• Valider : vérifier les requêtes générées par rapport aux définitions et au lignage certifiés ; renvoyer la provenance avec chaque réponse.
• Exposez : servez le contexte à n’importe quel harnais d’agent via MCP, CLI et API. Apprenez : intégrez les corrections et l’utilisation certifiées dans l’ontologie, afin que le contexte partagé s’améliore à chaque question.

Pour exécuter un test de référence texte vers SQL tel que BIRD, reportez-vous au référentiel d’évaluation de l’ontologie SQL.

Licences et cotisations. Auto Ontology est distribué sous la licence Apache 2.0. Les composants open source tiers regroupés, liés ou autrement utilisés par ce projet sont répertoriés dans
THIRD_PARTY_NOTICES.md. Ce projet n’accepte actuellement pas de contributions externes.

• Requête en langage naturel de données structurées : les questions sont traduites en SQL et exécutées sur des bases de données connectées, optimisées par NVIDIA NIM.
• Catalogue sémantique / couche ontologie sur des sources relationnelles, stockées dans Postgres à côté du catalogue qu’il décrit.
• Authentification et RBAC -en utilisant une meilleure authentification.
• Interface utilisateur Web pour le chat, l’analyse, le catalogue de données, l’analyse et les paramètres.
• Déploiement flexible — Graphique Helm pour Kubernetes ou Docker Compose pour une pile locale.

Auto Ontology utilise les points de terminaison NVIDIA NIM pour l’inférence : soit le catalogue d’API NVIDIA hébergé (integrate.api.nvidia.com) ou des NIM auto-hébergés. Les valeurs par défaut dans .env.example sont:

• LLM : nvidia/nemotron-3-nano-30b-a3b
• Intégrations : nvidia/nemotron-3-embed-1b
• Reclassement : nvidia/llama-nemotron-rerank-vl-1b-v2

Les points de terminaison et les modèles sont configurés via le DEFAULT_MODELS_ENDPOINT, DEFAULT_MODELS_MODEL,
EMBED_ENDPOINTet EMBED_MODEL variables d’environnement et nécessitent un
DEFAULT_MODELS_API_KEY.

Chaque rôle de modèle est configuré par un triolet de variables d’environnement –

You can set a full triplet, only some of its fields, or none at all — any field left unset falls back to the matching DEFAULT_MODELS_. So the simplest setup is to fill in DEFAULT_MODELS_* and override per-triplet fields only where they differ (e.g. EMBED_MODEL, NON_REASONING_MODEL). *_API_KEY also falls back to the legacy NVIDIA_API_KEY for backward compatibility.

• Docker with Docker Compose v2 (e.g. Docker Desktop on macOS/Windows, Docker Engine on Linux) for the local stack. For Kubernetes deployments see DEPLOYMENT.md.
• An NVIDIA API key (nvapi-...) for NVIDIA NIM (chat and ingestion) from the NVIDIA API catalog at
• Connection details for the source database(s) you want to query (Databricks, Postgres, Snowflake, or DuckDB).

Kubernetes

To deploy Auto Ontology on a Kubernetes cluster, see DEPLOYMENT.md.

Local (Docker Compose)

1. Clone the repository:

   git clone <repo-url> auto_ontology && cd auto_ontology

2. Créez votre fichier d’environnement (.env) à partir du modèle et renseignez les valeurs (identifiants Postgres, DEFAULT_MODELS_API_KEY, CONNECTION_STRINGSetc.). Voir .env.example pour la liste complète des variables :

   cp .env.example .env
   # edit .env

   Note:

   • AUTH_SECRET et APP_URL sont requis – sans eux, chaque page échoue avec une erreur “secret par défaut” Better Auth.
   • POSTGRES_PORT ne change que le côté hôte mappage de port (définissez-le si 5432 est déjà pris sur votre machine) ; les conteneurs atteignent toujours Postgres sur le port réseau interne.

3. Construisez les images et démarrez la pile :

   docker compose up -d --build

   Cela construit le backend (auto_ontology) et l’interface (auto-ontology-frontend) images, affiche Postgres et pgAdmin, exécute le one-shot frontend-migrate travail pour synchroniser le schéma de base de données et démarre l’application (backend, service d’ingestion et frontend).

4. Ouvrez l’interface utilisateur à (l’API backend est activée :3001pgAdmin sur :5050).

   Dépannage : si l’interface utilisateur se charge sans le panneau de navigation de gauche (ou semble cassée après un redémarrage), votre navigateur contient un cookie de session obsolète – cela se produit lorsque AUTH_SECRET modifications ou la base de données est réinitialisée. Effacer les données du site pour localhost:3000 (ou supprimez le better-auth.session_token cookie) et reconnectez-vous.

Auto Ontology résout les bases de données sources auxquelles elle se connecte à partir de deux sources :

1. Ajouté via l’interface utilisateur – connexions créées à partir de l’application. Avec cette option, les identifiants de connexion sont stocké en texte brut dans Postgres sauf si Vault est configuré:

   • Sans coffre-fort : l’objet de connexion complet (y compris le mot de passe) est sérialisé en JSON et stocké, non chiffré, sur la ligne de la base de données du catalogue.
   • Avec coffre-fort : les informations d’identification sont écrites dans Vault, saisies par le nom de la base de données, et la ligne du catalogue ne stocke aucune information d’identification (le nom de la base de données est la clé de recherche — il n’y a pas de champ de référence distinct).

   Vault est activé uniquement lorsque tous VAULT_ADDR, VAULT_NAMESPACE,
   VAULT_ROLE_IDet VAULT_SECRET_ID sont définis (VAULT_AUTH_MOUNT et
   VAULT_KV_MOUNT sont des remplacements facultatifs). Il est désactivé par défaut ; une configuration partielle est ignorée avec un avertissement et revient au stockage en texte brut.

2. CONNECTION_STRINGS variable d’environnement — une liste de chaînes de connexion séparées par des virgules fournies au moment du déploiement (par exemple le Helm
   --set connectionStrings= drapeau). Il s’agit d’une solution de secours : elle est utilisée uniquement lorsqu’il n’y a aucune connexion ajoutée à l’interface utilisateur.

Ontologie automatique Prend en charge SSO pour l’authentification. L’URI de redirection doit être configuré dans l’IdP comme : APP_URL/api/auth/sso/callback

Un navigateur se connecte et obtient un cookie de session, qu’un script ne peut pas obtenir. Pour les scripts, les blocs-notes et les tâches planifiées, créez un Jeton API plutôt:

1. Ouvrez le menu utilisateur (en haut à droite) → Jetons API → Nouveau jeton.
2. Nommez-le, choisissez éventuellement une date d’expiration (par défaut : jamais) et copier le jeton. Auto Ontology n’en stocke qu’un hachage SHA-256, il est donc affiché exactement une fois. Le perdre signifie en créer un nouveau.

Envoyez-le comme x-api-key sur n’importe quel /api/... appel – Authorization: Bearer
ça marche aussi :

curl -H "x-api-key: $AUTO_ONTOLOGY_API_TOKEN" 

import os
import requests

session = requests.Session()
session.headers["x-api-key"] = os.environ["AUTO_ONTOLOGY_API_TOKEN"]

terms = session.get("").json()

answer = session.post(
    "https://auto_ontology.example.com/api/chat/completions",
    json={"question": "How many orders shipped last week?"},
).json()

Choses à savoir :

• Un jeton agit en tant que propriétaire. Il ne comporte aucune autorisation propre : chaque appel est autorisé en fonction du rôle du propriétaire, exactement comme il le serait dans le navigateur. Le jeton d’un spectateur ne peut pas effectuer de tâches d’administration.
• Toute la surface de l’API l’accepte. L’authentification est résolue en un seul endroit (frontend/auth/resolve-user.ts) pour chaque itinéraire, donc tout point de terminaison dans
  docs/openapi/auto-ontology-api.json ce n’est pas
  withPublic fonctionne avec un jeton.
• La révocation est immédiate. Supprimez le jeton dans l’interface utilisateur, ou supprimez/bannissez l’utilisateur propriétaire, et la requête suivante avec celui-ci obtient un 401.
• Les jetons ne peuvent pas gérer les jetons. La création et la révocation nécessitent une session de connexion, de sorte qu’un jeton divulgué ne peut pas se donner de successeurs.

Les clients publics appellent la passerelle Next.js authentifiée à l’adresse
POST /api/chat/completions. La réponse est un flux SSE contenant step,
resultou error événements, suivis de [DONE].

conversation_id est facultatif :

• Omettez-le pour une demande unique et apatride.
• Fournissez un UUID généré par le client pour créer ou poursuivre une conversation.
• Réutilisez le même UUID pour chaque tour du thread. Attendre [DONE] avant d’envoyer le prochain tour ; demandes qui se chevauchent pour un retour de conversation
  409 Conversation in progress.

{
  "question": "What about last month?",
  "conversation_id": "d61d8aa3-d496-4fa7-97ce-4f831c162e7f"
}

Pour les requêtes conversationnelles, FastAPI charge jusqu’aux cinq tours terminés les plus récents (limités à 12 000 caractères) et réécrit les entrées contextuelles telles que « Et août ? en une question autonome avant d’exécuter le graphique texte-vers-SQL existant. Les questions indépendantes sont transmises sans modification. Les réflexions des agents internes, les charges utiles des graphiques, les erreurs et les jeux de résultats SQL bruts ne sont pas réutilisés comme contexte.

L’historique des conversations est limité à l’utilisateur authentifié d’Auto Ontology. Les appelants du navigateur et du service doivent utiliser la passerelle Next.js, qui résout le problème de l’utilisateur et transmet le message interne. x-auto-ontology-user-id en-tête vers FastAPI. Le port FastAPI est une limite de service interne de confiance : il ne doit pas être exposé publiquement car cet en-tête n’est pas vérifié de manière indépendante par FastAPI. Une requête FastAPI directe sans conversation_id reste apatride ; une demande directe avec
conversation_id nécessite l’en-tête d’identité approuvée.

L’interface utilisateur Web gère automatiquement l’UUID. Une conversation créée par l’API peut être ouverte dans l’interface utilisateur à l’adresse /chat?focus= lorsqu’il appartient à l’utilisateur connecté.

Agents de codage : commencez à AGENTS.md. Les compétences vivent dans
skills/ (nvidia-ontology-setup, nvidia-ontology-management, nvidia-ontology-query). Les responsables continuent d’utiliser CLAUDE.md.

Les harnais d’agents tels que Cursor et Claude Desktop peuvent interroger vos données via le serveur MCP d’Auto Ontology. Voir
mcp/ pour l’exécuter et docs/mcp.md pour les détails.

Auto Ontology est sous licence Apache, version 2.0. Identifiant SPDX : Apache-2.0.

Chaque fichier source créé par NVIDIA dans ce référentiel comporte un en-tête SPDX du formulaire :

SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES.
All rights reserved.
SPDX-License-Identifier: Apache-2.0

Les composants open source tiers utilisés par Auto Ontology sont répertoriés, avec leurs licences en amont et les URL de projet, dans
THIRD_PARTY_NOTICES.md. Les composants ajoutés par les images du conteneur sont répertoriés séparément dans
CONTAINER_THIRD_PARTY_NOTICES.md.

AVIS ET AVERTISSEMENT : Ce logiciel récupère, accède ou interagit automatiquement avec des documents externes. Les documents récupérés ne sont pas distribués avec ce logiciel et sont régis uniquement par des termes, conditions et licences distincts. Vous êtes seul responsable de la recherche, de l’examen et du respect de tous les termes, conditions et licences applicables, ainsi que de la vérification de la sécurité, de l’intégrité et de l’adéquation de tout matériel récupéré à votre cas d’utilisation spécifique. Ce logiciel est fourni « TEL QUEL », sans garantie d’aucune sorte. L’auteur ne fait aucune déclaration ou garantie concernant les documents récupérés et n’assume aucune responsabilité pour les pertes, dommages, responsabilités ou conséquences juridiques résultant de votre utilisation ou de votre incapacité à utiliser ce logiciel ou tout matériel récupéré. Utilisez ce logiciel et les documents récupérés à vos propres risques.

Matériaux externes avec lesquels Auto Ontology interagit au moment de l’exécution :

Ce projet n’accepte actuellement aucune contribution. Les problèmes, les demandes d’extraction et les correctifs soumis en dehors de l’équipe de maintenance d’Auto Ontology ne seront ni examinés ni fusionnés. Les rapports relatifs à la sécurité doivent suivre le processus décrit dans SECURITY.md. Le workflow du responsable est en cours
CONTRIBUTING.md.