Nvidia – open-source auto-ontology

Agents can recover documents and query databases, but reliability gates agentic analytics: a income metric answered faster is value nothing if the figure is wrong. Agents need a environment tier that tells them anywhere data lives, what it means, whether to use it, how to use it, anywhere it came from, and what is similar. NVIDIA Auto Ontology is an open archive that builds that tier from endeavor metadata, reconciles definitions throughout systems, and exposes it to any delegate harness through MCP, CLI, and API. It complements the semantic models customers already own.

It enables developers to:

• Discover: create endeavor ontologies from metadata; nexus existing ontologies and semantic models; build AI-ready cognition graphs.
• Ground: provision agents trusted endeavor definition for metrics, entities, and relationships; reconcile inconsistent definitions throughout systems.
• Validate: inspect generated queries against certified definitions and lineage; come back provenance alongside all answer.
• Expose: assist environment to any delegate harness through MCP, CLI, and API. Learn: fold certified corrections and use rear into the ontology, so shared environment improves alongside all question.

To run a text-to-SQL benchmark specified as BIRD, mention to the ontology SQL evaluation repository.

Licensing & contributions. Auto Ontology is distributed under the Apache License 2.0. Third-party open-source components bundled, linked, or alternatively used by this project are listed in THIRD_PARTY_NOTICES.md. This project is currently not accepting external contributions.

• Natural-language querying of organized data — questions are translated to SQL and executed against connected databases, powered by NVIDIA NIM.
• Semantic catalog / ontology layer complete relational sources, stored in Postgres alongside the catalog it describes.
• Authentication & RBAC —using Better Auth.
• Web UI for chat, analysis, data catalog, analytics, and settings.
• Flexible deployment — Helm diagram for Kubernetes or Docker Compose for a local stack.

Auto Ontology uses NVIDIA NIM endpoints for conclusion — either the hosted NVIDIA API catalog (integrate.api.nvidia.com) or self-hosted NIMs. The defaults in .env.example are:

• LLM: nvidia/nemotron-3-nano-30b-a3b
• Embeddings: nvidia/nemotron-3-embed-1b
• Reranking: nvidia/llama-nemotron-rerank-vl-1b-v2

The endpoints and models are configured via the DEFAULT_MODELS_ENDPOINT, DEFAULT_MODELS_MODEL, EMBED_ENDPOINT, and EMBED_MODEL surroundings variables and necessitate a DEFAULT_MODELS_API_KEY.

Each example function is configured by a triplet of surroundings variables — <PREFIX>_ENDPOINT (URL), <PREFIX>_API_KEY, and <PREFIX>_MODEL:

You can set a complete triplet, lone several of its fields, or none at all — any field left unset falls rear to the matching DEFAULT_MODELS_<FIELD>. So the simplest setup is to inhabit in DEFAULT_MODELS_* and override per-triplet sectors lone where they differ (e.g. EMBED_MODEL, NON_REASONING_MODEL). *_API_KEY additionally falls back to the bequest NVIDIA_API_KEY for backward compatibility.

• Docker alongside Docker Compose v2 (e.g. Docker Desktop on macOS/Windows, Docker Engine on Linux) for the local stack. For Kubernetes deployments see DEPLOYMENT.md.
• An NVIDIA API key (nvapi-...) for NVIDIA NIM (chat and ingestion) from the NVIDIA API catalog at https://build.nvidia.com.
• Connection particulars for the origin database(s) you desire to query (Databricks, Postgres, Snowflake, or DuckDB).

Kubernetes

To deploy Auto Ontology on a Kubernetes cluster, see DEPLOYMENT.md.

Local (Docker Compose)

1. Clone the repository:

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

2. Create your surroundings document (.env) from the template and inhabit in the values (Postgres credentials, DEFAULT_MODELS_API_KEY, CONNECTION_STRINGS, etc.). See .env.example for the complete catalog of variables:

   cp .env.example .env # edit .env

   Note:

   • AUTH_SECRET and APP_URL are required — without them all page fails alongside a Better Auth "default secret" error.
   • POSTGRES_PORT lone changes the host-side harbor mapping (set it if 5432 is already taken on your machine); containers continually attain Postgres on the inner network port.

3. Build the images and commencement the stack:

   docker create up -d --build

   This builds the backend (auto_ontology) and frontend (auto-ontology-frontend) images, brings up Postgres and pgAdmin, runs the one-shot frontend-migrate job to sync the repository schema, and starts the app (backend, ingestion service, and frontend).

4. Open the UI at http://localhost:3000 (the backend API is on :3001, pgAdmin on :5050).

   Troubleshooting: if the UI loads without the remaining navigation panel (or alternatively looks damaged following a restart), your browser is holding a stale meeting biscuit — this happens whenever AUTH_SECRET changes or the database is reset. Clear the location data for localhost:3000 (or delete the better-auth.session_token cookie) and sign in again.

Auto Ontology resolves the origin databases it connects to from two sources:

1. Added through the UI — connections created from inside the app. With this option the association credentials are stored in plaintext in Postgres unless Vault is configured:

   • Without Vault: the complete association entity (including the password) is JSON-serialized and stored, unencrypted, on the catalog's repository row.
   • With Vault: the credentials are written to Vault, keyed by the database name, and the catalog row stores no credentials (the repository name is the lookup key — there is no distinct citation field).

   Vault is enabled lone whenever all 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; a partial configuration is ignored alongside a alert and falls rear to plaintext storage.

2. CONNECTION_STRINGS surroundings variable — a comma-separated catalog of connection strings supplied at deploy period (e.g. the Helm --set connectionStrings=<CONNECTION-STRINGS> flag). This is a fallback: it is used lone whenever there are no UI-added connections.

Auto Ontology Supports SSO for authentication. The Redirect URI have to be configured in the IdP as: APP_URL/api/auth/sso/callback

A browser signs in and gets a meeting cookie, which a manuscript cannot obtain. For scripts, notebooks, and scheduled jobs, mint an API token instead:

1. Open the person list (top right) → API Tokens → New token.
2. Name it, optionally choice an expiry (default: never), and copy the token. Auto Ontology stores lone a SHA-256 hash of it, so it is shown exactly once. Losing it means minting a new one.

Send it as x-api-key on any /api/... call — Authorization: Bearer <token> works too:

curl -H "x-api-key: $AUTO_ONTOLOGY_API_TOKEN" https://auto_ontology.example.com/api/terms

import os import requests session = requests.Session() session.headers["x-api-key"] = os.environ["AUTO_ONTOLOGY_API_TOKEN"] terms = session.get("https://auto_ontology.example.com/api/terms").json() answer = session.post( "https://auto_ontology.example.com/api/chat/completions", json={"question": "How many orders shipped final week?"}, ).json()

Things value knowing:

• A token acts as its owner. It carries no permissions of its own — every call is authorized against the owner's role, exactly as it would be in the browser. A viewer's token cannot do admin things.
• The entire API exterior accepts it. Authentication is resolved in one place (frontend/auth/resolve-user.ts) for all route, so any endpoint in docs/openapi/auto-ontology-api.json that is not withPublic plant alongside a token.
• Revocation is immediate. Delete the token in the UI, or delete/ban the owning user, and the next petition alongside it gets a 401.
• Tokens cannot oversee tokens. Creating and revoking requires a signed-in session, so a leaked token cannot matter itself successors.

Public clients call the authenticated Next.js gateway at POST /api/chat/completions. The reply is an SSE stream containing step, result, or error events, followed by [DONE].

conversation_id is optional:

• Omit it for a stateless, one-shot request.
• Supply a client-generated UUID to create or continue a conversation.
• Reuse the identical UUID for all rotate in the thread. Wait for [DONE] before sending the next turn; overlapping requests for one conversation return 409 Conversation in progress.

{ "question": "What concerning final month?", "conversation_id": "d61d8aa3-d496-4fa7-97ce-4f831c162e7f" }

For conversational requests, FastAPI loads up to the five most latest completed turns (bounded to 12,000 characters) and rewrites contextual input specified as “What concerning August?” into a standalone inquiry before operating the existing text-to-SQL graph. Independent questions are passed through unchanged. Internal agent thoughts, diagram payloads, errors, and raw SQL outcome sets are not reused as context.

Conversation former is scoped to the authenticated Auto Ontology user. Browser and service callers should use the Next.js gateway, which resolves the person and forwards the inner x-auto-ontology-user-id header to FastAPI. The FastAPI harbor is a trusted inner assistance boundary: it must not be exposed publically since that header is not independently verified by FastAPI. A straightforward FastAPI request without conversation_id remains stateless; a straightforward petition with conversation_id requires the trusted character header.

The web UI manages the UUID automatically. An API-created conversation can be opened in the UI at /chat?focus=<conversation_id> whenever it belongs to the signed-in user.

Coding agents: commencement at AGENTS.md. Skills live in skills/ (nvidia-ontology-setup, nvidia-ontology-management, nvidia-ontology-query). Maintainers keep using CLAUDE.md.

Agent harnesses specified as Cursor and Claude Desktop can query your data through Auto Ontology's MCP server. See mcp/ to run it and docs/mcp.md for the details.

Auto Ontology is licensed under the Apache License, Version 2.0. SPDX identifier: Apache-2.0.

Each NVIDIA-authored origin document in this repository carries an SPDX header of the form:

SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All entitlements reserved. SPDX-License-Identifier: Apache-2.0 

Third-party open-source components used by Auto Ontology are enumerated, alongside their upstream licenses and project URLs, in THIRD_PARTY_NOTICES.md. Components added by the container images are listed separately in CONTAINER_THIRD_PARTY_NOTICES.md.

NOTICE AND DISCLAIMER: This application automatically retrieves, accesses or interacts alongside external materials. Those retrieved materials are not distributed alongside this application and are governed solely by distinct terms, conditions and licenses. You are solely liable for finding, reviewing and complying alongside all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your particular use case. This application is provided "AS IS", without warranty of any kind. The author makes no representations or warranties concerning any retrieved materials, and assumes no liability for any losses, damages, liabilities or lawful consequences from your use or inability to use this software or any retrieved materials. Use this application and the retrieved materials at your own risk.

External materials Auto Ontology interacts alongside at run time:

This project is currently not accepting contributions. Issues, pull requests, and patches submitted from exterior the Auto Ontology maintainer squad will not be reviewed or merged. Security-relevant reports should prosecute the process described in SECURITY.md. Maintainer workflow is in CONTRIBUTING.md.