One Open Source Project a Day (No. 254): NVIDIA Auto Ontology — A Certified Semantic Layer for Data Agents That Says 'I Can't Answer That' When It Can't

Introduction

"A fast but wrong metric has no value."

This is the 254th article in the "One Open Source Project a Day" series. Today's project is NVIDIA's open-source Auto Ontology.

When an agent queries enterprise data, the usual failure isn't bad SQL syntax; it's bad semantics. Is revenue pre-tax or post-tax? Who defined "active user"? Are two tables both called customer in different systems the same thing? Models will confidently write SQL that runs and returns the wrong number.

Auto Ontology puts a context layer between the agent and the database. It automatically extracts business terms, reusable SQL expressions, and table relationships from metadata; people then test, fix, and certify them; and the agent answers from those certified definitions. The README groups the capabilities into five verbs: Discover, Ground, Validate, Expose, and Learn (certified corrections and usage feed back into the ontology).

What You Will Learn

• What an ontology holds here: terms, SQL attributes, relationships
• The Generate → Certify → Answer flow, and how it refuses to answer when it can't
• Service layout, ports, and security cautions
• How to expose it to agents via MCP / REST
• How it relates to "deterministic query generation," and which limits to watch

Prerequisites

• Familiarity with Text-to-SQL and the metric-definition problems it hits on enterprise data
• Comfort with Docker Compose
• Optional: MCP and vector search (pgvector)

Project Background

What It Is

Officially: a context layer for AI agents built from enterprise metadata, reconciling definitions across systems and exposing the result through MCP, a CLI, and an API. It is meant to sit alongside semantic models a customer already has, not replace them. The GitHub description emphasizes a semantic, graph-based reasoning layer over data for better context retrieval and more explainable LLM and agent workflows.

Project Stats

• ⭐ GitHub Stars: about 5,670
• 🍴 Forks: about 445
• 💻 Language: Python
• 📅 Created: 2026-04-27
• 📄 License: Apache-2.0
• 🤝 No external pull requests accepted, though issues (bugs, integration requests) are welcome
• 🏷️ Maturity: the README states no version or stability status

What It Does

The Problem It Solves

Without a semantic layer:
  The agent sees raw tables and column names
  ↓ guesses definitions from the wording
  ↑ SQL runs, numbers are wrong
 
With Auto Ontology:
  Metadata → terms / SQL attributes / relationships
  ↓ people test and certify them
  ↓ agent retrieves candidates → writes SQL → validates → returns answer and basis
  ↑ if candidates can't support the query, it says so instead of forcing an answer

What the Ontology Stores

The Three-Step Flow

1. Generate: read the sources and profile columns, extract terms table by table, infer relationships and suggest SQL attributes from query history, then write everything to PostgreSQL with embeddings in pgvector
2. Certify: people test with real questions, refine, and certify names, descriptions, and SQL attributes
3. Answer: the agent classifies intent and extracts entities, retrieves candidates by embedding search, writes SQL, validates filter values and the query (repairing on failure), and returns the answer along with its SQL and steps

When candidates fall short, it says it can't answer. Predictive questions can be routed to the third-party KumoRFM if you configure it.

Quick Start

You need Docker (Compose v2), uv, and an NVIDIA API key (nvapi-...). The official walkthrough uses the Wide World Importers sample database:

git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
cp .env.example .env   # set DEFAULT_MODELS_API_KEY, AUTH_SECRET, APP_URL,
                       # POSTGRES_PASSWORD, CONNECTION_STRINGS, admin/pgAdmin passwords
docker compose up -d --wait postgres
 
# Seed the sample data
git clone https://github.com/NVIDIA/auto-ontology-eval.git ../auto-ontology-eval
(cd ../auto-ontology-eval && uv sync && cp .env.example .env && \
  POSTGRES_PASSWORD='<password>' \
  uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)
 
docker compose up -d --build

Then open http://localhost:3000, sign in as admin, enable Settings → Semantic Compilation, and ask a question in Chat.

Two contrasting examples from the docs:

• Answerable: a revenue question for a specific product, state, and month returns $588.80 from 3 invoice lines, with the SQL and resolution steps
• Unanswerable: a return-on-ad-spend question gets a check_answerable coverage of 0.5, and the agent asks for clarification instead of guessing

One compilation of the sample database produced 31 terms.

A Deeper Look

Service Layout

Note that 3001 and 3002 should stay private: the ingestion endpoints have no authentication of their own. Compose publishes services on the host, so every default password must be replaced. A DEPLOYMENT.md in the repo covers Helm deployment to Kubernetes.

Data Sources and Models

• Databases (10): PostgreSQL, MySQL, Databricks, Snowflake, ClickHouse, Trino, Apache Kyuubi, HeavyDB, DuckDB, SQLite (the last two via connection string only)
• Models: NVIDIA NIM (hosted or self-hosted) or any OpenAI-compatible endpoint. Four roles (REASONING, NON_REASONING, EMBED, RERANK) are configured separately with endpoint, key, and model, falling back to DEFAULT_MODELS_*. The default LLM is nvidia/nemotron-3.5-lightning-30b-a3b
• Models must support structured output, and the embedding model must be the same for ingestion and queries

Three Ways to Plug Into an Agent

• MCP (read-only): exposes check_readiness, search_terms, get_term, get_term_columns, get_term_sql_attributes, get_sql_attribute, describe_table, check_answerable, and ask_question. Run it with uvx and configure Cursor or Claude Desktop (via mcp-remote)
• REST: POST /api/chat/completions with an x-api-key header, returning a server-sent event stream
• Skills: nvidia-ontology-setup, -management, and -query

It also imports and exports Apache Ossie YAML, so it can interoperate with existing semantic models.

About "Deterministic Query Generation"

The GitHub repo description mentions deterministic query generation, but the README doesn't describe it that way: it relies on an LLM writing the SQL, plus certified definitions and validation. A more accurate reading is that the definitions are deterministic (a person certified them), while SQL generation is still done by a model and then validated and repaired. If your use case demands fully reproducible results, verify that yourself.

Limits and Cautions

1. No external PRs; the only contribution path is filing issues
2. Predictions through KumoRFM upload connected tables to a hosted service (capped by KUMO_MAX_TABLES, default 20), so review the data exposure before enabling it
3. The software contacts external model endpoints and is provided "AS IS"
4. After a restart, stale session cookies can break UI navigation
5. The README lists inconsistent embedding and rerank defaults in two places, so go by what you actually configure

Project Links and Resources

• 🌟 GitHub: https://github.com/NVIDIA/auto-ontology
• 🧪 Sample and eval data: NVIDIA/auto-ontology-eval
• 📊 Benchmarks: NVIDIA ontology-sql-eval (BIRD-style)
• 📄 License: Apache-2.0

Summary

Key Takeaways

1. Problem: the main risk in agents querying data is wrong definitions, not wrong syntax
2. Approach: generate terms, SQL attributes, and relationships automatically, certify them by hand, then let the agent use them
3. Honest refusal: when candidates are insufficient it says so and reports coverage
4. Integration: MCP (read-only), REST, and Skills; 10 databases and OpenAI-compatible models
5. Cautions: unauthenticated ingestion endpoints, change default passwords, no external PRs, and take "deterministic" with a grain of salt

Who This Is For

• Teams building enterprise data Q&A or analytics agents that struggle with inconsistent definitions
• People with an existing semantic model who want a layer agents can consume
• Developers interested in reliability designs built on human certification, retrieval, and validation

Suggested First Steps

Run the Wide World Importers example first and see how the 31 terms get generated, then deliberately ask something unanswerable and watch how check_answerable reacts. Before pointing it at your own test database, change the default passwords and restrict ports 3001 and 3002 to your internal network.

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage