NVIDIA Auto Ontology: An Open-Source Semantic Layer for Reliable Agentic Analytics
NVIDIA Auto Ontology is an Apache-2.0 licensed Python framework that builds a semantic, graph-based ontology layer over enterprise data so that LLM and agent workflows can generate deterministic, validated SQL queries with provenance instead of guessing. NVIDIA published it as an open-source repository at github.com/NVIDIA/auto-ontology, and it reached 206 points and 70 comments on Hacker News.
The repository frames its own motivation around reliability rather than speed: "Agents can retrieve documents and query databases, but reliability gates agentic analytics: a revenue metric answered faster is worth nothing if the number is wrong." Auto Ontology is positioned as the context layer that answers, for an agent, where data lives, what it means, whether to use it, how to use it, where it came from, and what is similar. NVIDIA states that it complements the semantic models customers already own rather than replacing them.
What problem the ontology layer solves
The core claim is that agents need certified business meaning, not just database access. Auto Ontology builds its layer from existing enterprise metadata, reconciles definitions across systems, and exposes the result to any agent harness through MCP, a CLI, and an HTTP API.
Five capabilities are listed in the repository:
- Discover: generate enterprise ontologies from metadata, connect existing ontologies and semantic models, and build AI-ready 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.
Software components and default ports
Auto Ontology ships as a multi-service stack. The frontend is a Next.js 16 application (React 19, TypeScript, Tailwind CSS 4) using Better Auth and Prisma, serving the web UI, authentication, and the API gateway on port 3000. The backend is FastAPI on Python 3.12+ with LangChain, handling chat and natural-language-to-SQL, catalog, and datasource APIs on port 3001. A separate FastAPI ingestion worker ingests tabular data and writes embeddings on port 3002. Postgres with pgvector on port 5432 stores application metadata, the catalog and ontology, and the vector store. HashiCorp Vault is optional and has no assigned port in the component table.
The web UI covers chat, analysis, a data catalog, analytics, and settings. Deployment is supported either through a Helm chart for Kubernetes or Docker Compose for a local stack.
Inference is configured through NVIDIA NIM and model triplets
Auto Ontology uses NVIDIA NIM endpoints for inference, either the hosted NVIDIA API catalog at integrate.api.nvidia.com or self-hosted NIMs. The defaults in the repository's .env.example are:
- LLM: nvidia/nemotron-3-nano-30b-a3b
- Embeddings: nvidia/nemotron-3-embed-1b
- Reranking: nvidia/llama-nemotron-rerank-vl-1b-v2
Each model role is configured by a triplet of environment variables: a PREFIX_ENDPOINT URL, a PREFIX_API_KEY, and a PREFIX_MODEL. The roles are DEFAULT_MODELS (shared default that everything else falls back to), REASONING (the main chat and NL-to-SQL model), NON_REASONING (a lighter model used for entity extraction), EMBED (the text-embedding model, which must match between ingest and query), and RERANK (the reranker used by the retrieval flow). Any unset field falls back to the matching DEFAULT_MODELS_ field, and any *_API_KEY also falls back to the legacy NVIDIA_API_KEY variable for backward compatibility.
Deployment prerequisites
A local stack requires Docker with Docker Compose v2, an NVIDIA API key in the nvapi-... format obtained from build.nvidia.com, and connection details for the source databases to be queried. The supported source systems named in the repository are Databricks, Postgres, Snowflake, and DuckDB.
Installation is a clone of the repository, copying .env.example to .env and filling in values such as Postgres credentials, DEFAULT_MODELS_API_KEY, and CONNECTION_STRINGS, then running docker compose up -d --build. That build produces the backend (auto_ontology) and frontend (auto-ontology-frontend) images, brings up Postgres and pgAdmin, runs a one-shot frontend-migrate job to sync the database schema, and starts the app. The UI is served at http://localhost:3000, the backend API on port 3001, and pgAdmin on port 5050.
The repository flags two configuration traps. AUTH_SECRET and APP_URL are required, and without them every page fails with a Better Auth "default secret" error. POSTGRES_PORT only changes the host-side port mapping, since containers always reach Postgres on the internal network port. It also documents a troubleshooting case where the UI loads without its left navigation panel after a restart because the browser holds a stale session cookie, which happens when AUTH_SECRET changes or the database is reset; clearing site data for localhost:3000 or deleting the better-auth.session_token cookie resolves it.
Credential storage defaults to plaintext unless Vault is configured
This is the most operationally significant security detail in the repository. Connections added through the UI have their credentials stored in plaintext in Postgres unless Vault is configured. Without Vault, the full connection object, including the password, is JSON-serialized and stored unencrypted on the catalog's database row. With Vault, credentials are written to Vault keyed by the database name and the catalog row stores no credentials, because the database name itself is the lookup key and there is no separate reference field.
Vault is enabled only when all four of VAULT_ADDR, VAULT_NAMESPACE, VAULT_ROLE_ID, and VAULT_SECRET_ID are set; VAULT_AUTH_MOUNT and VAULT_KV_MOUNT are optional overrides. It is off by default, and a partial configuration is ignored with a warning and falls back to plaintext storage.
A second source of connection definitions is the CONNECTION_STRINGS environment variable, a comma-separated list supplied at deploy time, for example through the Helm --set connectionStrings=
Agent API, API tokens, and the FastAPI trust boundary
Public clients call an authenticated Next.js gateway at POST /api/chat/completions. The response is an SSE stream carrying step, result, or error events followed by [DONE]. The conversation_id field is optional: omit it for a stateless one-shot request, or supply a client-generated UUID to create or continue a conversation and reuse the same UUID for every turn. Callers must wait for [DONE] before sending the next turn, because overlapping requests for one conversation return 409 Conversation in progress.
For conversational requests, FastAPI loads up to the five most recent completed turns, bounded to 12,000 characters, and rewrites contextual input such as "What about August?" into a standalone question before running the existing text-to-SQL graph. Independent questions pass through unchanged. Internal agent thoughts, chart payloads, errors, and raw SQL result sets are not reused as context. Conversation history is scoped to the authenticated Auto Ontology user.
The repository draws an explicit security boundary around FastAPI. It states that the FastAPI port is a trusted internal service boundary that must not be exposed publicly, because FastAPI does not independently verify the internal x-auto-ontology-user-id header that the Next.js gateway forwards. A direct FastAPI request without conversation_id remains stateless; a direct request with conversation_id requires the trusted identity header. API-created conversations can be opened in the UI at /chat?focus=
API tokens exist for scripts, notebooks, and scheduled jobs that cannot hold a browser session cookie. They are minted from the user menu under API Tokens, and Auto Ontology stores only a SHA-256 hash, so the token is shown exactly once and losing it means minting a new one. Tokens are sent as the x-api-key header on any /api/... call, and Authorization: Bearer
Four token behaviors are documented:
- A token acts as its owner and carries no permissions of its own, so every call is authorized against the owner's role exactly as it would be in the browser, and a viewer's token cannot perform admin actions.
- The whole API surface accepts a token, because authentication is resolved in one place (frontend/auth/resolve-user.ts) for every route, so any endpoint in docs/openapi/auto-ontology-api.json that is not marked withPublic works with a token.
- Revocation is immediate: deleting the token in the UI, or deleting or banning the owning user, causes the next request with it to receive a 401.
- Tokens cannot manage tokens, because creating and revoking tokens requires a signed-in session, so a leaked token cannot issue itself successors.
SSO is supported for authentication, with the redirect URI configured in the identity provider as APP_URL/api/auth/sso/callback.
MCP server and coding-agent skills
Agent harnesses such as Cursor and Claude Desktop can query data through Auto Ontology's MCP server, documented in the mcp/ directory and docs/mcp.md. Coding agents are directed to start at AGENTS.md, and three skills ship in the skills/ directory: nvidia-ontology-setup, nvidia-ontology-management, and nvidia-ontology-query. Maintainers of the project continue to use CLAUDE.md.
Benchmarks are referenced but not published in the repository
The repository points developers to a separate ontology SQL evaluation repository at github.com/NVIDIA/ontology-sql-eval to run a text-to-SQL benchmark such as BIRD. Auto Ontology's own README does not publish accuracy, latency, or cost numbers, so any performance claim about the project has to be reproduced against that evaluation harness rather than quoted from the repository.
Licensing, contributions, and external dependencies
Auto Ontology is licensed under the Apache License, Version 2.0, with SPDX identifier Apache-2.0. NVIDIA-authored source files carry an SPDX header reading "SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved." with "SPDX-License-Identifier: Apache-2.0". Third-party open-source components are enumerated with upstream licenses and project URLs in THIRD_PARTY_NOTICES.md, and components added by the container images are listed separately in CONTAINER_THIRD_PARTY_NOTICES.md.
Despite the open-source license, the project is currently not accepting external contributions: "Issues, pull requests, and patches submitted from outside the Auto Ontology maintainer team will not be reviewed or merged." Security-relevant reports are routed through SECURITY.md, and the maintainer workflow lives in CONTRIBUTING.md.
The repository also includes a notice that the software retrieves and interacts with external materials that are not distributed with it and are governed by separate terms. The listed runtime external materials are NVIDIA-hosted model APIs at build.nvidia.com and integrate.api.nvidia.com for LLM, embedding, and reranking during chat, ingestion, and semantic compilation; any other OpenAI-compatible model endpoint a user configures through the *_ENDPOINT and *_MODEL variables; the KumoRFM predictive-query service, used only when KUMO_RFM_API_KEY is set, under Kumo's terms; and the user's own source databases during ingestion, profiling, and query execution.
How the Hacker News discussion reacted
The reaction split between people who see enterprise ontology work as the real bottleneck for AI and people who are skeptical that adding another LLM-driven layer fixes agent unreliability.
The sharpest technical objection came from grey-area, who argued the architecture adds uncertainty rather than removing it:
Fixing unreliable agents by adding more unreliable agents. It's a shame we can't do something about the tendency of LLMs to give more weight to their weights than to the data they're analysing. I guess it all comes back to the fact that they don't have a clear division between data they have learned about the world, instructions and data under analysis. You can ask them only to consider the 5 facts in front of them, but they won't do that, and cannot do that.
HexDecOctBin raised the symbolic-AI question that the ontology framing invites: why not use LLMs to write as many symbolic rules as needed to fit the data while keeping the ruleset reviewable and maintainable. That question points directly at the tension in Auto Ontology's design, which uses LLMs (via NIM) to generate and maintain a symbolic, reviewable catalog rather than to answer questions directly.
Several commenters questioned where the product stops and the surrounding complexity begins. podocarp asked what distinguishes this from a memory system plus skills that collect an enterprise's APIs and CLIs. bbor found the README written for enterprise project managers and asked what philosophy or academic ontology work, if any, the project ties to, saying the specifics were hard to follow. dstu had a visceral reaction to the word "gates" in the opening sentence and argued that a tool worth building is worth describing in the author's own plain words.
Adoption friction was raised as a practical objection. igleria expressed interest but was put off on realizing the project requires an NVIDIA API key. That matches the repository, where the NVIDIA API key is a listed prerequisite and the default model endpoints point at build.nvidia.com.
On the demand side, monkeydust described spending a small fortune getting ontology right because it is critical to real-world success of enterprise AI, and said they were curious whether this could help. The original poster, campervans, summarized the value proposition bluntly: "Game changer for entreprise (technical) debt."
A separate thread of skepticism targeted NVIDIA's open-source posture more broadly. einpoklum wrote:
Open Source? How about we start by open-sourcing the NVIDIA user-space libraries: libcuda, libcudart, libOpenCL, libnvtx, as well as nvidia-smi and the CUDA and OpenCL profilers.
That criticism is about upstream driver and toolchain components, not about the license of Auto Ontology itself, which is Apache-2.0.
What to verify before adopting Auto Ontology
Three things in the repository are worth checking against a specific deployment. First, credential storage defaults to plaintext in Postgres for UI-added connections unless all four Vault variables are set, so Vault configuration is not optional for any deployment handling production database passwords. Second, the FastAPI port must not be exposed publicly, because identity headers are trusted rather than verified at that boundary. Third, the project does not publish its own benchmark results; the README only directs readers to the separate ontology-sql-eval repository for running a text-to-SQL benchmark such as BIRD. Potential adopters should also weigh that external contributions are currently closed, so the roadmap is controlled entirely by NVIDIA's maintainer team.