Skip to main content
Back

NVIDIA's Auto Ontology Stops AI Agents From Querying the Wrong Data

NVIDIA released Auto Ontology, an open-source Python framework that builds semantic graph layers over enterprise data so agents generate SQL deterministically with provenance.

Repo, Full Access
  • NVIDIA released Auto Ontology, an Apache-2.0 framework for building semantic graph layers over enterprise databases.
  • Agents get grounded SQL with provenance, validated against certified definitions and lineage from existing metadata.
  • Supports Databricks, Postgres, Snowflake, DuckDB sources via Next.js frontend, FastAPI backend, pgvector store.
  • Exposes context through MCP server, CLI, and REST API for Cursor, Claude Desktop, custom agents.
  • Defaults to NVIDIA NIM Nemotron models but accepts any OpenAI-compatible endpoint via environment triplets.
  • Deploys via Docker Compose or Helm; benchmark harness lives in separate ontology-sql-eval repo.

NVIDIA has released Auto Ontology, an open-source Python framework designed to make LLM-generated SQL more reliable. It builds a graph-based semantic layer over enterprise databases, giving analytics agents approved definitions, relationships, and lineage instead of leaving them to infer meaning from column names.

The project uses the Apache 2.0 license and supports local and Kubernetes deployments. At the time of the source page, its GitHub repository had 207 stars.

Why valid SQL still fails

Schema retrieval can help an agent produce SQL that parses and runs, yet the result may still use the wrong revenue field, combine incompatible metrics, or ignore an organization’s reporting rules. A syntactically correct query offers little protection against semantic errors.

Auto Ontology places a semantic layer between the agent and the warehouse. This machine-readable map records where data lives, what fields and metrics mean, how they should be used, where they came from, and which concepts are related. The framework generates that layer from existing metadata, ontologies, and semantic models, then exposes it through the Model Context Protocol, a command-line interface, and a REST API.

From metadata to answer

The framework organizes its workflow into four stages:

  • Discover: Generate ontologies from enterprise metadata, connect existing semantic models, and build an agent-readable knowledge graph.
  • Ground: Map questions to governed metrics, entities, and relationships while reconciling inconsistent definitions across systems.
  • Validate: Check generated queries against certified definitions and lineage, then attach provenance to the result.
  • Learn: Add certified corrections and usage signals to the shared ontology for later requests.

During a typical request, an agent maps the user’s language to concepts in the ontology, generates SQL, executes the query against a connected warehouse, and returns the result with lineage showing its source.

The stack in one view

Component Implementation Responsibility
Web application Next.js 16, Better Auth, Prisma User interface, authentication, and application data access
API FastAPI on Python 3.12 Chat, ontology access, and natural-language-to-SQL requests
Agent orchestration LangChain Question rewriting and text-to-SQL workflow
Ingestion worker Python worker Tabular ingestion and embedding generation
Storage PostgreSQL with pgvector Application state, catalog metadata, ontology data, and vector similarity search

Inference runs through NVIDIA NIM endpoints, which can be hosted by NVIDIA or deployed within the user’s environment. The default model set uses Nemotron-3-nano-30B for reasoning, Nemotron-3-embed-1B for embeddings, and a Llama-Nemotron reranker. Environment variables can point the application to OpenAI-compatible model endpoints.

Built-in database connectors cover Databricks, PostgreSQL, Snowflake, and DuckDB. Database credentials can be stored directly in PostgreSQL or routed through HashiCorp Vault when the required Vault environment variables are configured.

Two paths into agent workflows

The bundled Model Context Protocol server lets compatible tools such as Cursor and Claude Desktop access ontology context and warehouse query capabilities through a standard interface. The repository also includes the nvidia-ontology-setup, nvidia-ontology-management, and nvidia-ontology-query agent skills, plus an AGENTS.md entry point for coding agents.

Scripts and notebooks can call the REST API with a token created in the user interface and supplied through the x-api-key header:

import os
import uuid

import requests

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

response = session.post(
    "https://auto-ontology.example.com/api/chat/completions",
    json={
        "question": "How many orders shipped last week?",
        "conversation_id": str(uuid.uuid4()),
    },
    timeout=60,
)
response.raise_for_status()
answer = response.json()

Passing the same client-generated UUID as conversation_id preserves context across follow-up questions. FastAPI loads as many as five recent completed turns, capped at 12,000 characters, and rewrites contextual prompts such as “What about August?” into standalone questions before invoking the text-to-SQL workflow.

Accuracy needs local proof

NVIDIA provides a separate evaluation repository for text-to-SQL benchmarks such as BIRD. The main repository reports no aggregate accuracy score, so teams must run the evaluation stack against their own schemas, metric definitions, permissions, and baseline models to measure the framework’s effect.

Two limits to plan around

  • External contributions: The maintainers currently do not review issues or pull requests from outside the project team, despite the repository’s open-source license.
  • Backend trust boundary: FastAPI treats the x-auto-ontology-user-id header as trusted and does not independently verify it. A public deployment needs an authenticated gateway that removes client-supplied identity headers and sets the value only after verification.

A common contract for analytics agents

Tools such as dbt metrics and LookML already let data teams encode governed business definitions. Auto Ontology packages the additional machinery needed to ingest those definitions, reconcile them in a graph, apply them during SQL generation, and serve the resulting context through MCP and REST interfaces.

The framework fits teams that already maintain reliable metadata or semantic models and want several analytics agents to share the same definitions and lineage. Its practical value will depend on local benchmark results, the quality of the source metadata, and whether its authentication and contribution constraints match the intended deployment.