Requêtes ancrées à Auto Ontology

Objectif

Interroger l'implémentation Auto Ontology actuelle à partir d'un agent sans prescrire de harnais, SDK ou template LangGraph. Les artefacts de workflow typés, les statuts, les gates et les handoffs sont dans runtime-contract.yaml.

Prérequis

Utilisez un déploiement Auto Ontology opérationnel et un client MCP ou REST authentifié. Si Auto Ontology n'est pas en cours d'exécution, utilisez d'abord nvidia-ontology-setup.

Limitations

Cette skill lit et valide les réponses. Elle n'expose pas FastAPI directement, n'écrit pas de définitions sémantiques, ne publie pas de résultats gouvernés et ne fournit pas de navigateur de schéma brut. Confiez les mutations et la publication à nvidia-ontology-management.

Instructions

Appelez readiness avant de poser une question.
Découvrez les termes et confirmez l'answerability via la couche sémantique.
Posez la question via MCP, ou utilisez la gateway REST Next.js authentifiée comme solution de secours.
Validez l'intention matérielle, le SQL, les lignes, la troncature et la prose avant de présenter une réponse porteuse de réclamation.

Préférez MCP pour les lectures

Quand le harnais parle MCP, utilisez-le. La liste des outils du handshake est la source de vérité en direct (mcp/auto_ontology_mcp/tools.py). Ne copiez pas de table d'outils dans la session ; si le handshake et cette skill divergent, faites confiance au handshake.

Séquence (le serveur annonce aussi ceci pour que les modèles ne passent pas directement à ask_question) :

check_readiness — couche sémantique compilée et connexion DB en direct.
search_terms — ce que signifient les noms ici.
check_answerable — vérification de couverture bon marché.
ask_question — texte-to-SQL complet ; quelques dizaines de secondes ; réponse + SQL + lignes (limité à 100 lignes, avec row_count / truncated).
Pour une réponse porteuse de réclamation, validez l'intention matérielle, le SQL généré, les lignes retournées, la troncature et la prose en utilisant query-validation.md.

Tout sur MCP lit. Il n'existe pas d'outil MCP pour les bases de données brutes, les schémas ou les colonnes à dessein. describe_table est la vue de table légitime : les termes et les attributs SQL auxquels participe la table.

Connectez-vous : AUTO_ONTOLOGY_API_URL est l'application web. Exécutez auto-ontology-mcp, pointez le client vers …/mcp, l'utilisateur se connecte. Aucun token sur le serveur MCP. Détails : repository mcp/README.md et docs/mcp.md.

Fallback REST et handoff d'écriture

Quand MCP est indisponible, les clients publics appellent la gateway Next.js authentifiée, pas FastAPI :3001. FastAPI fait confiance à x-auto-ontology-user-id et ne doit pas être exposé. Une requête FastAPI directe sans conversation_id est apatride ; avec conversation_id elle nécessite cet en-tête interne.

Auth (l'un de ces éléments ; résolu en un seul endroit) :

Cookie de session navigateur
Jeton API : x-api-key: $AUTO_ONTOLOGY_API_TOKEN (Authorization: Bearer fonctionne aussi pour les tokens auto_ontology_…). Le jeton agit comme son propriétaire.
Bearer OAuth émis par Auto Ontology (connexion MCP)
Jeton id SSO (Authorization: Bearer <jwt>), p. ex. AI-Q — voir stack.md

Formes : docs/openapi/auto-ontology-api.json. Ne grattez pas les ~87 opérations. Une requête d'écriture remet à nvidia-ontology-management ; cette skill ne transforme pas une question en lecture seule en mutation.

Chat

POST /api/chat/completions — SSE step / result / error / charts, puis [DONE]. Permission chat:use ; une requête avec conversation_id a aussi besoin de conversation:write, ou elle obtient 403.

Omettez conversation_id pour un one-shot (pas d'historique, pas de step de graphique).
Fournissez un UUID généré par le client pour créer ou poursuivre un thread (nécessite chat:use et conversation:write).
Attendez [DONE] avant le prochain tour ; les requêtes qui se chevauchent retournent 409 Conversation in progress.
Un 404 sur un id de conversation signifie qu'il appartient à un autre utilisateur.

Python (du README Auto Ontology ; pas d'SDK supplémentaire) :

import os
import requests

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

terms = session.get("https://ontology.example.com/api/terms").json()

answer = session.post(
    "https://ontology.example.com/api/chat/completions",
    json={"question": "How many orders shipped last week?"},
)
# response is SSE, not a single JSON object

Ouvrez un thread créé par API dans l'UI à /chat?focus=<conversation_id> quand il appartient à l'utilisateur connecté.

Découverte (couche sémantique, pas un navigateur de catalogue)

MCP d'abord. Fallback REST :

GET /api/terms (query, skip, limit)
GET /api/terms/{term_id}
GET /api/exploration/tables/{table_id}/details
GET /api/exploration/graph

Écritures et réinitialisation de compilation : nvidia-ontology-management.

Validez les réponses porteuses de réclamation

Ne traitez pas l'exécution réussie comme preuve suffisante. Avant de présenter un résultat décisionnel, appliquez query-validation.md pour vérifier la population, la mesure, l'unité, le grain, les jointures, la lignée, le statut, la validité, les lignes, la troncature et la prose de réponse. Si une contrainte matérielle ne peut être vérifiée, retournez l'écart plutôt qu'une réclamation plus forte.

Réponses vides ou échouées

ask_question / chat n'a rien retourné d'utile → check_readiness (ou GET /api/semantic-compilation/status) avant de réécrire la question. Une base de données nommée n'est pas la preuve que le SQL peut s'exécuter. Voir nvidia-ontology-setup dépannage.

Exemples

Pour un décompte ancré, exécutez check_readiness, search_terms, check_answerable, puis ask_question.
Si une réponse est tronquée ou viole le grain de mesure, refusez la réclamation complète et suivez query-validation.md.

Dépannage

Pour les réponses vides ou échouées, vérifiez la readiness et le statut de compilation avant de reformuler. Pour les erreurs REST, vérifiez l'origine web publique, l'authentification et la propriété de la conversation avant de réessayer.

Voir aussi

stack.md — AI-Q, Nemotron, cuOpt (ce qui existe vs ce que les partenaires câblent)
query-validation.md — intention matérielle, SQL, lignes et vérifications de réponse
nvidia-ontology-management — modéliser, modifier et publier via la couche
nvidia-ontology-setup — lancement et découverte OAuth MCP

nvidia-ontology-query