NVIDIA Auto Ontology: An Open Source Context Layer for Enterprise Data Agents

An agent that answers a revenue question in four seconds is a liability if it summed the wrong column. NVIDIA’s Auto Ontology repository puts it bluntly: “a revenue metric answered faster is worth nothing if the number is wrong.” Reliability, the project argues, is what gates agentic analytics, not speed and not SQL syntax.

The hard part of text-to-SQL is meaning. Which table actually holds revenue, whether two systems define it the same way, whether a dataset should be used at all and where a figure came from. Auto Ontology is NVIDIA’s open source answer: a Python framework that builds a semantic, graph-based context layer from enterprise metadata, reconciles definitions across systems, and serves the result to any agent harness through MCP, a CLI and an API.

It is also more than a library. The repository ships a web UI, an ontology stored in Postgres, role-based access control, a Helm chart and a Docker Compose stack. It also ships a credential default that every team should read about before connecting a production warehouse.

Six questions a schema cannot answer

The README lists what an agent needs from a context layer: where data lives, what it means, whether to use it, how to use it, where it came from, and what is similar. A database schema handles the first of those, and only partly. Column names and foreign keys say nothing about whether a metric in a Snowflake warehouse matches a similarly named one in a Postgres replica, or which of two near-identical tables the business has actually signed off on.

Auto Ontology’s response is a semantic catalog, an ontology layer over relational sources stored in Postgres alongside the catalog it describes. It can be generated from metadata, but it can also connect to ontologies and semantic models a company already maintains. NVIDIA frames the project as complementing those existing models rather than replacing them, which matters for any organisation that has already invested years in a metrics layer.

The output is what the project calls an AI-ready knowledge graph: entities, metrics and relationships an agent consults before it writes a query, with provenance attached to whatever it returns.

Discover, ground, validate, expose, learn

The project organises its capabilities into five verbs, and they read as a pipeline more than a feature list:

• Discover: generate enterprise ontologies from metadata, connect existing ontologies and semantic models, and build knowledge graphs.
• Ground: give agents trusted business meaning for metrics, entities and relationships, and reconcile inconsistent definitions across systems.
• Validate: check generated queries against certified definitions and lineage, and return provenance with every answer.
• Expose: serve context to any agent harness through MCP, CLI and API.
• Learn: fold certified corrections and usage back into the ontology, so shared context improves with every question.

Validate is the step that separates this from ordinary retrieval-augmented generation. Fetching a few relevant table descriptions into a prompt helps a model guess better; checking the finished query against certified definitions and lineage, and attaching provenance to the answer, gives a human something to audit. That is the explainability claim in the project’s own description.

The word doing the heavy lifting is “certified”. Both validation and learning depend on definitions and corrections that someone has approved. The software can reconcile and record, but which definition of a metric wins is still a governance decision an organisation has to make and keep current.

Nemotron by default, any NIM endpoint in practice

The user-facing feature is natural-language querying: a question is translated to SQL and executed against connected databases, powered by NVIDIA NIM. Inference can go to the hosted NVIDIA API catalog at integrate.api.nvidia.com or to self-hosted NIMs. The defaults in .env.example assign a Nemotron model to each of three roles:

The hosted route needs an API key beginning nvapi-, issued through the catalog at build.nvidia.com, and the README uses it for both chat and ingestion. That is the quickest way to try the stack without any local GPUs. Teams handling sensitive schemas should check exactly what metadata and question text the ingestion and chat paths send to the hosted endpoint before choosing it over a self-hosted NIM.

One triplet per model role

Model configuration follows a pattern worth understanding before editing the environment file. Each model role is set by a triplet of variables: <PREFIX>_ENDPOINT for the URL, <PREFIX>_API_KEY and <PREFIX>_MODEL. Any field left unset falls back to the matching DEFAULT_MODELS_<FIELD>. Every *_API_KEY also falls back to the legacy NVIDIA_API_KEY for backward compatibility.

The practical upshot is that the minimal setup fills in the defaults once and overrides only what differs, such as EMBED_MODEL or NON_REASONING_MODEL:

DEFAULT_MODELS_ENDPOINT=<NIM endpoint URL>
DEFAULT_MODELS_API_KEY=nvapi-...
DEFAULT_MODELS_MODEL=nvidia/nemotron-3-nano-30b-a3b
EMBED_MODEL=nvidia/nemotron-3-embed-1b

The fallback is convenient and also a source of quiet surprises. A role whose model you forgot to override does not fail; it inherits the default model. When a deployment behaves oddly, checking which variables are actually set for each prefix is the first debugging step.

From git clone to localhost:3000

The local stack needs Docker with Docker Compose v2, an NVIDIA API key, and connection details for at least one source database. Supported sources are Databricks, Postgres, Snowflake and DuckDB. Kubernetes deployments go through a Helm chart documented separately in DEPLOYMENT.md.

1. Clone the repository

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

2. Create the environment file

   Run cp .env.example .env and fill in Postgres credentials, DEFAULT_MODELS_API_KEY, CONNECTION_STRINGS and the rest. AUTH_SECRET and APP_URL are mandatory: without them every page fails with a Better Auth “default secret” error. Set POSTGRES_PORT only if 5432 is taken on the host; it changes the host-side mapping, not how containers reach the database.

3. Build and start

   docker compose up -d --build builds the auto_ontology backend and auto-ontology-frontend images, starts Postgres and pgAdmin, runs the one-shot frontend-migrate job to sync the schema, then starts the backend, the ingestion service and the frontend.

4. Open the UI

   The web app is at http://localhost:3000, the backend API on port 3001 and pgAdmin on 5050. The UI covers chat, analysis, the data catalog, analytics and settings.

One troubleshooting note from the README saves real time. If the UI loads without its left navigation panel, or looks broken after a restart, the browser is holding a stale session cookie. That happens whenever AUTH_SECRET changes or the database is reset. Clear site data for localhost:3000, or delete the better-auth.session_token cookie, and sign in again.

The credential default to change first

Auto Ontology resolves source databases from two places. The first is the CONNECTION_STRINGS environment variable, a comma-separated list supplied at deploy time. The second is connections created inside the app, and that is where the security trade-off lives.

For UI-created connections, Vault is off by default. Without it, the full connection object, password included, is JSON-serialised and stored unencrypted on the catalog’s database row in Postgres. Anyone with read access to that database, including through the bundled pgAdmin, can read every warehouse credential the app has been given.

Turning Vault on requires all four of VAULT_ADDR, VAULT_NAMESPACE, VAULT_ROLE_ID and VAULT_SECRET_ID. VAULT_AUTH_MOUNT and VAULT_KV_MOUNT are optional overrides. Keying secrets by database name also means renaming a database in the catalog is not a cosmetic change: it changes the key the app looks up.

Open source licence, closed contribution door

Auto Ontology is distributed under the Apache License 2.0, with bundled and linked third-party components listed in THIRD_PARTY_NOTICES.md. Apache 2.0 is permissive: companies can run, modify and embed it in commercial products. Authentication and role-based access control come from the Better Auth library, and the whole thing can run on Kubernetes through the Helm chart or locally through Compose.

There is a catch for anyone hoping to shape the project: it is “currently not accepting external contributions.” The code is open, but the roadmap is NVIDIA’s. Teams that need a missing connector or a fix can fork, but carrying a fork against an actively developed upstream is its own maintenance cost. Whether contributions open later is worth watching before building heavily on top of it.

On accuracy, the repository points to a separate ontology SQL evaluation repository for running text-to-SQL benchmarks such as BIRD. No headline scores sit in the README itself, so anyone comparing Auto Ontology with a plain schema-in-prompt approach should run that evaluation against their own schemas, where ambiguous metric definitions actually live.

Limits and what to watch

The design depends on certified definitions. Validation and the learning loop are only as good as the corrections and approvals fed into them, and the README does not settle who certifies a metric when finance and sales disagree. That is organisational work no library can do, and it is where many semantic-layer projects stall.

The model stack leans on NVIDIA. The triplet system makes endpoints configurable, but the defaults, the API key format and the documentation all assume NIM. Teams standardised on another inference provider should test whether their endpoints behave as drop-in replacements before committing. The security defaults, meanwhile, favour getting started over safe operation: plaintext credentials, fail-open Vault and a bundled pgAdmin are fine on a laptop and risky anywhere else.

What to watch next is whether external contributions open, whether published benchmark results appear, and how well the MCP interface holds up across agent harnesses beyond NVIDIA’s own.

This article draws on Open Source Alternatives to Reflector? and answers to it (1, 2), on the Stack Exchange network, licensed under CC BY-SA 4.0.