NVIDIA Auto Ontology Review: A Semantic Layer for Agents

TL;DR

NVIDIA Auto Ontology (NVIDIA/auto-ontology) reads the schemas and sample values of your databases and drafts an ontology from them: business terms such as Customer or Invoice Line, the columns that hold them, reviewed SQL formulas for measures, and the joins between tables. People correct and certify that draft. An agent then answers questions in plain English by writing SQL from the certified definitions. Each answer comes back with its SQL and the steps that produced it. The same layer is served to Cursor, Claude Desktop and other MCP clients, and through a REST API.

Last verified: November 9, 2026. Facts as of that date:

10,746 GitHub stars and 882 forks. It topped GitHub’s weekly trending page on November 9, 2026, with 9,327 stars gained in seven days.
56 open issues (issues only; GitHub’s combined counter shows 96 because it also counts 40 open pull requests).
No tagged GitHub release yet. The package version was bumped to 1.2.0 on November 5, 2026.
License: Apache-2.0. NVIDIA maintains the code and says it does not accept external pull requests; issues and integration requests are welcome.

Not run by us: our hands-on lab, a throwaway GitHub Actions container, would not start today because GitHub refused the job over an account billing problem. A real run would also need Docker Compose and an NVIDIA API key, or your own OpenAI-compatible model endpoint. This review is based on the README, the docs folder, .env.example, pyproject.toml, the companion evaluation repository, the issue tracker and the Hacker News discussion.

Our verdict: Auto Ontology tackles the right problem. Text-to-SQL agents usually fail because they don’t know what “revenue” or “active customer” means in your company, not because they write bad SQL. Its draft-then-certify workflow, the answerability check, and returning SQL with every answer are good design. It is also a young, NVIDIA-flavoured stack: the defaults run on NVIDIA-hosted Nemotron models, and an open issue reports that the README quick-start fails against those hosted models. Some security defaults also need care before the stack is safe to deploy. Pilot it on one well-understood database. Don’t hand it your warehouse yet.

Quick Reference

Field	Value
What it is	Ontology / semantic layer generated from database metadata, used to ground an NL-to-SQL agent
Stack	Next.js 16 frontend, FastAPI + LangChain backend, an ingestion service, FastMCP server, Postgres 17 + pgvector, optional HashiCorp Vault
Interfaces	Web UI (chat, catalog, ontology graph), REST API (SSE stream), read-only MCP server, three agent skills
Databases	PostgreSQL, MySQL, Databricks, Snowflake, ClickHouse, Trino, Apache Kyuubi, HeavyDB, DuckDB, SQLite
Models	Four roles (reasoning, non-reasoning, embedding, reranking); NVIDIA NIM by default, any OpenAI-compatible endpoint allowed
Deploy	Docker Compose for local use, Helm chart for Kubernetes
Interchange	Import and export via Apache Ossie YAML
Price	Free; you pay for model inference and your own infrastructure
License	Apache-2.0

What Auto Ontology actually does

The README describes three stages: generate, certify and answer.

Generate. The ingestion service pulls schemas from the connected databases, profiles the columns and samples their values. It then extracts business terms table by table, infers joins (bridge tables included) from keys and from the data, and suggests SQL attributes based on query history. Everything is stored in Postgres, with embeddings in pgvector. On Microsoft’s Wide World Importers sample database, the project reports that a single compilation produced 31 terms.

The ontology contains three kinds of definition:

Terms: business concepts with a description and synonyms, mapped to columns.
SQL attributes: reviewed expressions under a term, such as a margin or a rolling total. The agent reuses these, so a measure is computed the same way every time.
Relationships: how tables join.

Certify. People test the draft with real questions, fix descriptions and SQL attributes in the UI or through the API, and mark definitions as certified once they’re correct. This step is what separates Auto Ontology from “point an LLM at the schema”. The README frames the whole project around reliability: “a revenue metric answered faster is worth nothing if the number is wrong.”

Answer. For each question, the agent classifies the intent and extracts the entities the question names. It retrieves candidate terms, columns and SQL attributes by embedding search, then writes SQL from them. Before running the query, it checks the filter values and the SQL against the database and repairs the SQL when a check fails. It returns the answer together with the SQL and its steps. If the candidates can’t support a query, it says the question can’t be answered from this data.

In the README’s example, a revenue question for one product in Pennsylvania in June 2015 returns $588.80 from three invoice lines, with the full five-join SQL attached. Ask about return on ad spend instead and check_answerable reports coverage of 0.5 because no term covers “ad spend”, so the agent asks you what to do rather than inventing a number. That refusal path matters more than the happy path.

Getting started

The documented quick-start uses Docker Compose with Compose v2, uv and an NVIDIA API key (nvapi-...) from build.nvidia.com:

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, AUTO_ONTOLOGY_ADMIN_PASSWORD, PGADMIN_PASSWORD

docker compose up -d --wait postgres

# the sample-database seed script lives in the companion eval repo
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='<the same password>' \
  uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)

docker compose up -d --build

Next, open http://localhost:3000, sign in as the admin, and turn on Settings → Semantic Compilation. Ingestion runs at startup, and compilation starts as soon as you switch it on. The README notes that Compose publishes Postgres, pgAdmin and the web app on the host, so replace every default password before you start the stack.

Model configuration uses one triplet per role: <ROLE>_ENDPOINT, <ROLE>_API_KEY and <ROLE>_MODEL. Any field you leave unset falls back to DEFAULT_MODELS_*. As of today, .env.example sets nvidia/nemotron-3.5-lightning-30b-a3b for both the reasoning and non-reasoning roles, nvidia/nemotron-3.5-embed-1b for embeddings and nvidia/nemotron-3.5-rerank-8b for reranking. The README’s quick-start section still names older embedding and reranking models in one place, so treat .env.example as the source of truth. To use a self-hosted NIM or any OpenAI-compatible endpoint, override the triplets. The project asks for models that support structured output, and the same embedding model must be used for ingestion and queries.

Using it from an agent: MCP, API and skills

The MCP server is a separate, small Python package with four dependencies (FastMCP, httpx, pydantic, python-dotenv). It talks to your deployment over HTTP and holds no database credentials. Its tools are read-only:

Job	Tools
Readiness	`check_readiness`
Terms	`search_terms`, `get_term`, `get_term_columns`, `get_term_sql_attributes`, `get_sql_attribute`, `describe_table`
Answerability	`check_answerable`
Questions	`ask_question` (the answer, the SQL and the rows)

AUTO_ONTOLOGY_API_URL=http://localhost:3000 \
  uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcp

{
  "mcpServers": {
    "auto-ontology": { "url": "http://localhost:3003/mcp" }
  }
}

Users sign in through Auto Ontology in a browser, and every MCP call runs with that user’s permissions. The package is not on PyPI yet, so a plain uvx auto-ontology-mcp does not resolve. Issue #403 points out that docs/mcp.md still calls the repository NVIDIA-internal and says you need GitHub credentials, which is no longer true. A maintainer replied that they will fix it.

For applications, POST /api/chat/completions accepts a question with an x-api-key token, minted under the user menu. It returns a server-sent event stream: a result event carries answer.response and answer.sql_code, and data: [DONE] ends the stream. Three bundled skills (setup, management, query) teach a coding agent how to install, curate and query the ontology, starting from AGENTS.md.

How good is it? What the project does and doesn’t claim

The README makes no headline accuracy claim. Instead, NVIDIA publishes a separate repository, auto-ontology-eval, that measures what the ontology adds over the same model given only the schema. Each run asks the same questions twice: once with a schema dump in a single prompt, once through Auto Ontology’s agent. A deterministic verifier then runs both SQL answers and the gold SQL. Scoring uses BIRD execution accuracy, or BEAVER’s ex_acc for BEAVER, and no LLM judge. Supported datasets include BIRD (1,534 Dev questions, 500 Mini-Dev), a 100-question BEAVER sample, FDABench-Lite, 41 Wide World Importers questions and BIRD-Interact.

The methodology is honest: the eval withholds its headline number when more than 5% of questions got no model output, and warns that BIRD’s optional “extra prompts” help only the treatment arm. You won’t find a single “X% better” figure to quote, and you shouldn’t trust one from a third party either. Run the eval on your own schema. That is the number that matters for your decision.

Community reactions

The Hacker News thread from November 3 reached 291 points and 139 comments. Commenters split into three camps:

Skeptics. The most-replied comment called it “fixing unreliable agents by adding more unreliable agents.” Others answered that the point is to shrink the space the model works in: it chooses among certified definitions instead of reinterpreting raw tables on every question.
People who got the point. Several commenters described ontologies as a way to write down tribal knowledge. One example: “exclude test accounts whenever you count customers” is a rule every analyst follows and almost nobody writes down, and an agent that doesn’t know it will count the test accounts.
The API-key worry. “Was interested… but then realized it needs an NVIDIA api key?” Replies pointed out that the models can be self-hosted. That’s correct, but the defaults, docs and tested paths are all NVIDIA’s.

The thread also produced alternatives: the maker of GetCassis/ontology-skills (MIT, 31 stars) pitched agent skills that keep the ontology in reviewable Git changes and run on your own LLM key.

Honest limitations

The hosted-model path is fragile right now. Issue #440, opened November 6, reports that every structured-output call to integrate.api.nvidia.com fails with a 400 (unknown field guided_json). According to the reporter, SQL generation then returns nothing and the agent loops in repair, so the README quick-start question “never gets a complete answer.” A second user confirmed the 400 on November 7 and posted a workaround: route the endpoint through LangChain’s ChatOpenAI with thinking turned off. That user reports SQL for 97 of 98 questions across seven eval runs with the change. Until a fix lands, expect to patch code to get through the default quick-start.
Security needs deliberate configuration. In the README’s words, FastAPI “trusts the user identity the frontend forwards in the x-auto-ontology-user-id header”, and the ingestion service’s ingest, delete, reset and compile endpoints “have no authentication of their own”. Keep ports 3001 and 3002 on a private network. Without Vault, connection passwords are stored as unencrypted JSON on a Postgres row (docs/connections.md). Configure Vault for anything beyond a laptop.
Predictions send your data out. Set KUMO_RFM_API_KEY and predictive questions go to KumoRFM, a hosted service. The agent uploads the connected tables, capped at 20 tables by default with no row limit unless you set one. The README tells you to complete a data review first. Take that seriously.
Certification is real work. The generated draft is a starting point. Its value comes from people reviewing terms and SQL attributes, and that’s the same tribal-knowledge work the HN skeptic said he simply wouldn’t do.
Closed contribution model. NVIDIA doesn’t accept external pull requests (40 are open anyway). Bug fixes from users arrive as issue reports and depend on NVIDIA’s priorities.
Young project, heavy stack. Five services plus Postgres, roughly 450 backend packages by the MCP package’s own estimate, and no tagged release.

Auto Ontology vs the alternatives

If you…	Consider
Live in Snowflake or Databricks	The platform’s own semantic layer (Cortex Analyst semantic views, Genie). It’s governed, billed with your warehouse, and needs no extra services
Want an open-source text-to-SQL product with semantic modelling on Postgres, BigQuery or MySQL	WrenAI
Already maintain dbt or a metrics layer	Keep it as the source of truth. Auto Ontology says it “complements the semantic models customers already own”, and Ossie import/export is the bridge
Want the ontology as files in Git, curated by your coding agent	GetCassis/ontology-skills (tiny and new)
Have many sources, no semantic layer, and want one drafted for you and served over MCP	Auto Ontology

For the wider field, see our best text-to-SQL tools comparison, the guide to building an agent knowledge layer, and text-to-SQL for complex enterprise databases.

FAQ

What is NVIDIA Auto Ontology?

It’s an Apache-2.0 open-source library from NVIDIA that builds a semantic layer, or ontology, over your databases. It drafts business terms, SQL formulas and joins from metadata. People certify them, and an agent uses them to write SQL and answer questions with the query and its steps attached. It’s exposed through a web UI, a REST API and an MCP server.

Does Auto Ontology require an NVIDIA API key or GPU?

No GPU is needed on your side, because the default models run on NVIDIA’s hosted API catalog, and that does require an nvapi- key. You can point every model role at a self-hosted NIM or any OpenAI-compatible endpoint instead. The models must support structured output, and the documented and tested path is NVIDIA’s.

Can I use it with Claude Code, Cursor or Claude Desktop?

Yes, through its read-only MCP server. Cursor connects to http://localhost:3003/mcp directly. Claude Desktop needs the mcp-remote bridge. Each user signs in through Auto Ontology, and calls run with that user’s permissions.

How accurate is Auto Ontology’s text-to-SQL?

NVIDIA doesn’t publish a headline number in the README. Its auto-ontology-eval repository measures the gain over a schema-only baseline with the same model on BIRD, BEAVER, FDABench-Lite and Wide World Importers, using deterministic execution scoring. Run it on your own data before you trust any figure.

Is it production-ready?

Not without work. There’s no tagged release yet, an open issue reports the hosted-model quick-start failing, internal services trust a forwarded user header, and credentials sit unencrypted unless you configure Vault. It’s a solid base for a pilot on one database.

Bottom line

Auto Ontology is the most complete open-source attempt so far to give data agents a certified meaning layer instead of a raw schema. Expect NVIDIA-first defaults, a heavy stack, an open quick-start bug and security settings you must lock down yourself. Run the eval on your own schema, keep the internal ports private, and treat certification as the actual project.