Skip to content
Back to search

auto-ontology

Auto Ontology is a Python framework for building semantic, graph-based reasoning layers over data. It enables deterministic query generation, better context retrieval, and more explainable AI for LLM and agent workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/NVIDIA/auto-ontology with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/NVIDIA/auto-ontology'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nvidia--auto-ontology/badge.svg)](/listings/nvidia--auto-ontology)

HTML

<a href="/listings/nvidia--auto-ontology"><img src="/api/listings/nvidia--auto-ontology/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This runs Auto-Ontology with Docker Compose against Wide World Importers, Microsoft's sample sales database. You need Docker with Compose v2, [uv](https://docs.astral.sh/uv/), and an NVIDIA API key (`nvapi-...`) from [build.nvidia.com](https://build.nvidia.com).

1. Clone the repository and create `.env`:

   git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
   cp .env.example .env

Then set these values in `.env`:

   DEFAULT_MODELS_API_KEY=nvapi-...
   AUTH_SECRET=<a long random string, e.g. from openssl rand -base64 32>
   APP_URL=http://localhost:3000
   POSTGRES_PASSWORD=<a new password>
   CONNECTION_STRINGS=postgresql://postgres:<the same password>@postgres:5432/wideworldimporters
   AUTO_ONTOLOGY_ADMIN_PASSWORD=<a new password>
   PGADMIN_PASSWORD=<a new password>

Compose publishes Postgres, pgAdmin, and the web app on the host, so replace each default password before you start it. `.env.example` also sets an API key per model role: replace each `nvapi-your-api-key-here` with your key, or delete those lines so they fall back to `DEFAULT_MODELS_API_KEY`.

2. Start Postgres and load the sample database. The seed script lives in auto-ontology-eval; pass it the Postgres password you set:

   docker compose up -d --wait postgres
   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)

3. Build and start the rest of the stack:

   docker compose up -d --build

4. Open <http://localhost:3000> and sign in with `AUTO_ONTOLOGY_ADMIN_EMAIL` and `AUTO_ONTOLOGY_ADMIN_PASSWORD` from `.env`. Go to **Settings → Semantic Compilation** and turn it on. Ingestion runs at startup; compilation starts immediately and reports **Semantic compilation is ready** when it finishes.

5. Ask a question in **Chat**:

> What was revenue for the USB food flash drive - sushi roll in Pennsylvania > in June 2015?

The agent resolves *revenue*, *product*, and *state* to terms in the ontology, follows their relationships to the joins it needs, and runs the query. The answer comes back with its SQL and the steps that produced it, so you can check the result against the source:

   Answer:  Revenue for USB food flash drive - sushi roll in Pennsylvania in
            June 2015 was $588.80, from 3 invoice lines.

   SQL:     SELECT SUM(il.extendedprice) AS revenue, COUNT(*) AS invoice_lines
            FROM sales.invoicelines il
            JOIN sales.invoices i             ON il.invoiceid = i.invoiceid
            JOIN warehouse.stockitems si      ON il.stockitemid = si.stockitemid
            JOIN sales.customers c            ON i.customerid = c.customerid
            JOIN application.cities ct        ON c.deliverycityid = ct.cityid
            JOIN application.stateprovinces sp ON ct.stateprovinceid = sp.stateprovinceid
            WHERE si.stockitemname = 'USB food flash drive - sushi roll'
              AND sp.stateprovincename = 'Pennsylvania'
              AND i.invoicedate >= '2015-06-01' AND i.invoicedate < '2015-07-01'

   Steps:   Resolved terms: Invoice Line (revenue), Stock Item, State Province, Invoice
            Joined: invoice line -> invoice -> customer -> city -> state province
            Validated the filter values against the data, then executed

6. Ask something the data can't answer. Wide World Importers has no advertising data, so a question about ad spend has nothing to resolve against. An agent connected through [MCP](#mcp-server) checks answerability first and asks you to clarify:

   You:    What was return on ad spend for the sushi roll flash drive in June 2015?

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 518 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!--
  2. SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
  3. All rights reserved.
  4. SPDX-License-Identifier: Apache-2.0
  5. -->
  6. # Auto Ontology
  7. [![#1 on the BEAVER leaderboard](https://img.shields.io/badge/BEAVER_leaderboard-%231-76b900)](https://beaverbench.github.io/#leaderboard)
  8. [![#2 on the BIRD-Interact leaderboard](https://img.shields.io/badge/BIRD--Interact_leaderboard-%232-76b900)](https://bird-interact.github.io/)
  9. 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. Agents need context to answer accurately: what each business concept means, where it lives, how it connects, how to calculate it, where it comes from, and whether to trust it. An ontology holds that context: a shared, governed map from the concepts people ask about to the data behind them. NVIDIA Auto Ontology is an open library that builds that ontology automatically from enterprise metadata, reconciles definitions across systems, and exposes it to any agent harness through MCP, CLI, and API. It complements the semantic models customers already own, and [Apache Ossie](https://ossie.apache.org/) keeps it portable.
  10. It enables developers to:
  11. - **Discover:** generate enterprise ontologies from metadata; connect existing ontologies and semantic models; build AI-ready knowledge graphs.
  12. - **Ground:** give agents trusted business meaning for metrics, entities, and relationships; reconcile inconsistent definitions across systems.
  13. - **Validate:** test a draft with real questions before experts certify it; check generated queries against the catalog and the definitions retrieval surfaced; return the SQL and steps with every answer.
  14. - **Expose:** serve context to any agent harness through MCP, CLI, and API.
  15. - **Learn:** fold certified corrections and usage back into the ontology, so shared context improves with use.
  16. An ontology matters most when:
  17. - questions are varied, open-ended, and ambiguous;
  18. - data spans many disparate sources with overlapping or conflicting
  19. definitions;
  20. - meanings must be reused and governed across runs, teams, and agents;
  21. - the model or its context budget can't hold the full documentation;
  22. - users ask in business terms and need routing to the right source and grain.
  23. With one well-modeled source and a fixed set of questions, direct SQL may be
  24. enough.
  25. ## Quickstart
  26. This runs Auto Ontology with Docker Compose against Wide World Importers,
  27. Microsoft's sample sales database. You need Docker with Compose v2,
  28. [uv](https://docs.astral.sh/uv/), and an NVIDIA API key (`nvapi-...`) from
  29. [build.nvidia.com](https://build.nvidia.com).
  30. 1. Clone the repository and create `.env`:
  31. ```bash
  32. git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
  33. cp .env.example .env
  34. ```
  35. Then set these values in `.env`:
  36. ```dotenv
  37. DEFAULT_MODELS_API_KEY=nvapi-...
  38. AUTH_SECRET=<a long random string, e.g. from openssl rand -base64 32>
  39. APP_URL=http://localhost:3000
  40. POSTGRES_PASSWORD=<a new password>
  41. CONNECTION_STRINGS=postgresql://postgres:<the same password>@postgres:5432/wideworldimporters
  42. AUTO_ONTOLOGY_ADMIN_PASSWORD=<a new password>
  43. PGADMIN_PASSWORD=<a new password>
  44. ```
  45. Compose publishes Postgres, pgAdmin, and the web app on the host, so replace
  46. each default password before you start it. `.env.example` also sets an API
  47. key per model role: replace each `nvapi-your-api-key-here` with your key, or
  48. delete those lines so they fall back to `DEFAULT_MODELS_API_KEY`.
  49. 2. Start Postgres and load the sample database. The seed script lives in
  50. auto-ontology-eval; pass it the Postgres password you set:
  51. ```bash
  52. docker compose up -d --wait postgres
  53. git clone https://github.com/NVIDIA/auto-ontology-eval.git ../auto-ontology-eval
  54. (cd ../auto-ontology-eval && uv sync && cp .env.example .env && \
  55. POSTGRES_PASSWORD='<the same password>' \
  56. uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)
  57. ```
  58. 3. Build and start the rest of the stack:
  59. ```bash
  60. docker compose up -d --build
  61. ```
  62. 4. Open <http://localhost:3000> and sign in with `AUTO_ONTOLOGY_ADMIN_EMAIL` and
  63. `AUTO_ONTOLOGY_ADMIN_PASSWORD` from `.env`. Go to **Settings → Semantic
  64. Compilation** and turn it on. Ingestion runs at startup; compilation starts
  65. immediately and reports **Semantic compilation is ready** when it finishes.
  66. 5. Ask a question in **Chat**:
  67. > What was revenue for the USB food flash drive - sushi roll in Pennsylvania
  68. > in June 2015?
  69. The agent resolves *revenue*, *product*, and *state* to terms in the
  70. ontology, follows their relationships to the joins it needs, and runs the
  71. query. The answer comes back with its SQL and the steps that produced it,
  72. so you can check the result against the source:
  73. ```text
  74. Answer: Revenue for USB food flash drive - sushi roll in Pennsylvania in
  75. June 2015 was $588.80, from 3 invoice lines.
  76. SQL: SELECT SUM(il.extendedprice) AS revenue, COUNT(*) AS invoice_lines
  77. FROM sales.invoicelines il
  78. JOIN sales.invoices i ON il.invoiceid = i.invoiceid
  79. JOIN warehouse.stockitems si ON il.stockitemid = si.stockitemid
  80. JOIN sales.customers c ON i.customerid = c.customerid
  81. JOIN application.cities ct ON c.deliverycityid = ct.cityid
  82. JOIN application.stateprovinces sp ON ct.stateprovinceid = sp.stateprovinceid
  83. WHERE si.stockitemname = 'USB food flash drive - sushi roll'
  84. AND sp.stateprovincename = 'Pennsylvania'
  85. AND i.invoicedate >= '2015-06-01' AND i.invoicedate < '2015-07-01'
  86. Steps: Resolved terms: Invoice Line (revenue), Stock Item, State Province, Invoice
  87. Joined: invoice line -> invoice -> customer -> city -> state province
  88. Validated the filter values against the data, then executed
  89. ```
  90. 6. Ask something the data can't answer. Wide World Importers has no
  91. advertising data, so a question about ad spend has nothing to resolve
  92. against. An agent connected through [MCP](#mcp-server) checks answerability
  93. first and asks you to clarify:
  94. ```text
  95. You: What was return on ad spend for the sushi roll flash drive in June 2015?
  96. Agent: check_answerable -> coverage 0.5; no term covers "ad spend"
  97. Agent: I can find revenue for that product, but this data has no
  98. advertising spend, so I can't compute return on ad spend. Do you
  99. want June 2015 revenue instead, or is ad spend tracked in another
  100. source I should connect?
  101. ```
  102. If the UI loads without its left navigation after a restart, the browser is
  103. holding a stale session cookie. Clear site data for `localhost:3000` and sign in
  104. again. For other setup failures, see the
  105. [setup skill's troubleshooting guide](./skills/nvidia-ontology-setup/references/troubleshooting.md).
  106. ## How it works
  107. Auto Ontology works in two stages: it generates an ontology that people
  108. certify, and the agent answers questions from it.
  109. The ontology answers six questions, each with its own element:
  110. | Question | Element | In Auto Ontology |
  111. | ------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------- |
  112. | What does it mean? | Concept | A term, such as *Customer* or *Invoice Line*, with a description and synonyms |
  113. | Where is it? | Mapping | Column attributes tie each term to the tables and columns that hold it |
  114. | What's connected? | Relationship | Joins between tables, including bridge tables: declared keys, plus inferred links confirmed against the data |
  115. | How do I calculate it? | Metric | SQL attributes: reviewed SQL under a term, such as a margin, reused so answers compute each measure the same way |
  116. | Where does it come from? | Lineage | Each term and attribute links to its source tables and columns, and each answer returns its SQL |
  117. | Should I use it? | Certification | Experts certify names, descriptions, and attributes, and certified elements are marked as reviewed |
  118. **Generate:** the ingestion service builds a first draft from the source
  119. databases, and people refine it. Semantic compilation starts once you turn it
  120. on in **Settings → Semantic Compilation**.
  121. - **Catalog ingest:** read tables, columns, keys, views, and query history; tag
  122. PII if you turn on PII detection; embed tables and columns in pgvector.
  123. - **Per table:** profile values with SQL. A model finds foreign key candidates
  124. and junction tables, writes column descriptions, and names the terms.
  125. - **Across tables:** group copies of a schema into term families, and link
  126. foreign keys to the terms they reference, keeping an inferred link only when
  127. the data confirms it. A model attaches foreign key columns left unlinked,
  128. suggests SQL attributes from query history and for bridge tables, and
  129. describes each column attribute.
  130. - **Output:** the ontology in Postgres with embeddings in pgvector, which you
  131. can import or export as Ossie YAML.
  132. - **Certify:** test the draft with real questions in Chat, or with
  133. `check_answerable` and `ask_question` over MCP. Refine terms, descriptions,
  134. and SQL attributes in the UI or through the API, and certify them once
  135. they're correct. Edits are re-embedded right away, and the next compilation
  136. keeps them, except which semantic foreign key each join uses, which every
  137. compilation re-selects.
  138. The [Generate tool flow](./docs/architecture.md#generate-an-ontology) shows
  139. which steps call a model and which are SQL or rules.
  140. The result is a semantic graph you can explore in the UI. In this example, one
  141. compilation of Wide World Importers produced 31 terms; selecting **Order** shows
  142. its description, related terms, mapped columns, and SQL attributes:
  143. <p>
  144. <img src="./docs/assets/ontology-graph.png" alt="Semantic graph of the Wide World Importers ontology, with the Order term selected" width="800">
  145. </p>
  146. **Answer:** the reasoning model answers each question in a loop, choosing one
  147. tool at a time:
  148. - **`retrieve`:** search the semantic layer by meaning and by name for business
  149. concepts, column meanings, and named calculations. Results come back as
  150. tables and columns with their descriptions and stored values, definitions
  151. with their SQL, and join paths. The model searches again whenever something
  152. is missing.
  153. - **`run_sql`:** look at stored values or test a draft. Before the query runs,
  154. table and column names are checked against the catalog, and tables against
  155. what `retrieve` showed.
  156. - **`submit`:** give the final query and an explanation. The query is checked
  157. and run, and an error goes back to the model to fix. A question about the
  158. data itself, such as which tables exist or what a term means, is answered in
  159. words: `retrieve` looks it up with `purpose=information`, and `submit` returns
  160. the answer without SQL.
  161. - **Result:** the answer comes back with its SQL and the steps it took, and a
  162. chart in Chat.
  163. No tool calls a language model except `predict`, which answers predictive
  164. questions when `KUMO_RFM_API_URL` is set; see [Predictions](#predictions). If
  165. the model reaches its tool-call limit without an accepted query, the agent
  166. reports that the question can't be answered from this data. The
  167. [Answer tool flow](./docs/architecture.md#answer-a-question) shows the loop,
  168. its tools, and its limits.
  169. In Chat, each answer shows its SQL, and you can view the rows, download them as
  170. CSV, or read them as a chart:
  171. <p>
  172. <img src="./docs/assets/qa-example.png" alt="Chat answering which products drive the most revenue and highest customer count, with the generated SQL and a revenue chart" width="550">
  173. </p>
  174. Auto Ontology is compatible with [Apache Ossie](https://ossie.apache.org/), the
  175. open standard for exchanging semantic models. Ossie includes a
  176. [converter for Auto Ontology](https://github.com/apache/ossie-converters/tree/main/nvidia),
  177. which Auto Ontology uses to import and export model definitions as Ossie YAML.
  178. Use **Settings → Import / Export**, or `POST /api/model/import` and
  179. `POST /api/model/export`.
  180. The services behind both stages, and how clients reach them:
  181. ```mermaid
  182. flowchart LR
  183. subgraph clients["Clients"]
  184. direction TB
  185. ui["Browser: web UI"]
  186. rest["Scripts: REST API with API tokens"]
  187. mcpc["MCP clients: Cursor, Claude Desktop, agents"]
  188. end
  189. mcp["MCP server: read-only tools (FastMCP, port 3003)"]
  190. fe["Web app, auth, API gateway (Next.js, port 3000)"]
  191. subgraph private["Private network"]
  192. direction TB
  193. be["Backend: text-to-SQL agent, catalog and ontology APIs (FastAPI, port 3001)"]
  194. ing["Ingestion and semantic compilation (FastAPI, port 3002)"]
  195. pg[("Postgres + pgvector: app data, catalog, ontology, embeddings")]
  196. end
  197. src[("Source databases: 10 connectors")]
  198. models["Model endpoints: NVIDIA NIM or OpenAI-compatible (reasoning, non-reasoning, embed, rerank)"]
  199. vault["Vault (optional): connection credentials"]
  200. kumo["KumoRFM (optional): predictions"]
  201. ui --> fe
  202. rest --> fe
  203. mcpc --> mcp
  204. mcp -- "public API" --> fe
  205. fe --> be
  206. fe -- "users, sessions, settings" --> pg
  207. be -- "trigger ingest and compile" --> ing
  208. be --> pg
  209. ing --> pg
  210. be -- "run SQL" --> src
  211. ing -- "read schema, sample values" --> src
  212. be --> models
  213. ing --> models
  214. be -.-> vault
  215. ing -.-> vault
  216. be -.-> kumo
  217. ```
  218. | Component | Technology | Role | Port |
  219. | ------------------- | --------------------------------- | ------------------------------------------------------------------------------------ | ---- |
  220. | Frontend | Next.js, Better Auth, Prisma | Web UI for chat, catalog, analytics, and settings; auth and RBAC; public API gateway | 3000 |
  221. | Backend | FastAPI (Python 3.12+), LangChain | Text-to-SQL agent, catalog, ontology APIs | 3001 |
  222. | Ingestion service | FastAPI (Python 3.12+) | Ingestion and semantic compilation | 3002 |
  223. | MCP server | FastMCP | Read-only agent tools over the public API | 3003 |
  224. | Postgres + pgvector | PostgreSQL 17 | Catalog, ontology, app data, vector store | 5432 |
  225. | HashiCorp Vault | Optional | Connection credential storage | n/a |
  226. Browser and API clients go through the web app on port 3000, and MCP clients
  227. through the MCP server on port 3003, which calls the same public API. Keep
  228. ports 3001 and 3002 on a private network: FastAPI trusts the user identity the
  229. frontend forwards in the `x-auto-ontology-user-id` header, and the ingestion
  230. service's endpoints (ingest, delete, reset, compile) have no authentication of
  231. their own.
  232. Full pipeline detail, with tool-flow diagrams for generating an ontology and
  233. answering a question: [docs/architecture.md](./docs/architecture.md).
  234. ## Use it from your agent
  235. ### MCP server
  236. The [MCP](https://modelcontextprotocol.io) server gives any MCP client read-only
  237. tools over the ontology. Each user signs in through Auto Ontology, and every
  238. call runs with that user's permissions.
  239. | Job | Tools |
  240. | ------------- | ------------------------------------------------------------- |
  241. | Readiness | `check_readiness`: can this deployment answer anything at all |
  242. | Terms | `search_terms`, `get_term`, `get_term_columns`, `get_term_sql_attributes`, `get_sql_attribute`, `describe_table` |
  243. | Answerability | `check_answerable`: does the ontology cover this question |
  244. | Questions | `ask_question`: the answer, the SQL, and the rows |
  245. Run the server against your deployment:
  246. ```bash
  247. AUTO_ONTOLOGY_API_URL=http://localhost:3000 \
  248. uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcp
  249. ```
  250. Cursor (`~/.cursor/mcp.json`):
  251. ```json
  252. {
  253. "mcpServers": {
  254. "auto-ontology": { "url": "http://localhost:3003/mcp" }
  255. }
  256. }
  257. ```
  258. Claude Desktop (`claude_desktop_config.json`), bridged with
  259. [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
  260. ```json
  261. {
  262. "mcpServers": {
  263. "auto-ontology": {
  264. "command": "npx",
  265. "args": ["mcp-remote", "http://localhost:3003/mcp"]
  266. }
  267. }
  268. }
  269. ```
  270. Restart the client after editing its config, then sign in when it prompts.
  271. Sign-in, configuration, and troubleshooting are in [docs/mcp.md](./docs/mcp.md).
  272. ### Agent skills
  273. Three skills teach a coding agent to work with Auto Ontology. Start at
  274. [AGENTS.md](./AGENTS.md).
  275. | Skill | Covers |
  276. | -------------------------------------------------------------------- | ---------------------------------------------------- |
  277. | [`nvidia-ontology-setup`](./skills/nvidia-ontology-setup/) | Install, connect sources, compile, prove readiness |
  278. | [`nvidia-ontology-management`](./skills/nvidia-ontology-management/) | Inspect, model, certify, import/export, and publish |
  279. | [`nvidia-ontology-query`](./skills/nvidia-ontology-query/) | Ask questions and validate the SQL, rows, and answer |
  280. ### REST API
  281. Ask a question with `POST /api/chat/completions` on the web app's origin. Mint
  282. an API token under the user menu → **API Tokens**. The response is a
  283. server-sent event stream: a `result` event carries the answer, and
  284. `data: [DONE]` ends the stream.
  285. ```bash
  286. curl -N http://localhost:3000/api/chat/completions \
  287. -H "x-api-key: $AUTO_ONTOLOGY_API_TOKEN" \
  288. -H "Content-Type: application/json" \
  289. -d '{"question": "How many orders shipped last week?"}'
  290. ```
  291. ```python
  292. import json
  293. import os
  294. import requests
  295. response = requests.post(
  296. "http://localhost:3000/api/chat/completions",
  297. headers={"x-api-key": os.environ["AUTO_ONTOLOGY_API_TOKEN"]},
  298. json={"question": "How many orders shipped last week?"},
  299. stream=True,
  300. timeout=900,
  301. )
  302. response.raise_for_status()
  303. for line in response.iter_lines(decode_unicode=True):
  304. if not line or not line.startswith("data:"):
  305. continue
  306. payload = line.removeprefix("data:").strip()
  307. if payload == "[DONE]":
  308. break
  309. event = json.loads(payload)
  310. if event["type"] == "result":
  311. print(event["answer"]["response"])
  312. print(event["answer"]["sql_code"])
  313. elif event["type"] == "error":
  314. raise RuntimeError(event["message"])
  315. ```
  316. Event types, multi-turn conversations, and the gateway trust boundary are in
  317. [docs/conversation-api.md](./docs/conversation-api.md). Every other operation is
  318. in the [OpenAPI spec](./docs/openapi/auto-ontology-api.json).
  319. ## Connectors, models, and predictions
  320. ### Sources
  321. Auto Ontology connects to ten engines:
  322. - PostgreSQL
  323. - MySQL
  324. - Databricks
  325. - Snowflake
  326. - ClickHouse
  327. - Trino
  328. - Apache Kyuubi
  329. - HeavyDB
  330. - DuckDB
  331. - SQLite
  332. Add connections under **Settings → Connections**, or list them in
  333. `CONNECTION_STRINGS`. DuckDB and SQLite are connection-string only. See
  334. [docs/connections.md](./docs/connections.md) for URL schemes, scoping, and
  335. credential storage.
  336. ### Models
  337. Auto Ontology uses four model roles. With an `nvapi-` key, each defaults to an
  338. NVIDIA NIM on [build.nvidia.com](https://build.nvidia.com):
  339. | Role | Default model | What it does |
  340. | --------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
  341. | `REASONING` | `nvidia/nemotron-3.5-lightning-30b-a3b` | Runs the answering agent and `check_answerable`, builds the ontology, and detects PII |
  342. | `NON_REASONING` | `nvidia/nemotron-3.5-lightning-30b-a3b` | Rewrites follow-up questions, plans charts, writes PQL for predictions, and runs the quick steps of interactive analysis |
  343. | `EMBED` | `nvidia/nemotron-3.5-embed-1b` | Indexes tables, columns, terms, and SQL attributes in pgvector, and matches each question to them |
  344. | `RERANK` | `nvidia/nemotron-3.5-rerank-8b` | Picks the term that owns each bridge-table SQL attribute during compilation; not used to answer questions |
  345. To use self-hosted NIM or any OpenAI-compatible endpoint, set
  346. `<ROLE>_ENDPOINT`, `<ROLE>_API_KEY`, and `<ROLE>_MODEL`. Any field you leave
  347. unset falls back to `DEFAULT_MODELS_<FIELD>`, so the simplest setup fills in
  348. `DEFAULT_MODELS_*` and overrides only what differs; `*_API_KEY` also falls back
  349. to the legacy `NVIDIA_API_KEY`. Use models
  350. that support structured output, and keep the embedding model the same for
  351. ingestion and queries. [`.env.example`](./.env.example) documents every
  352. variable.
  353. ### Predictions
  354. Set `KUMO_RFM_API_URL` (and `KUMO_RFM_API_KEY` if your endpoint requires
  355. one) and the agent routes predictive questions to KumoRFM.
  356. KumoRFM is a hosted service: to answer, the agent uploads the connected tables
  357. to it, capped by `KUMO_MAX_TABLES` (20 by default) and
  358. `KUMO_MAX_ROWS_PER_TABLE` (unlimited unless set). Review what that sends, and
  359. complete your organization's data review, before you enable it.
  360. ## Benchmarks
  361. To run a text-to-SQL benchmark such as BIRD, refer to
  362. [auto-ontology-eval](https://github.com/NVIDIA/auto-ontology-eval), which
  363. scores the same model with and without the ontology on
  364. [NeMo Gym](https://github.com/NVIDIA-NeMo/Gym).
  365. ## Contributing
  366. We welcome contributions: bug fixes, connectors, documentation, and examples.
  367. Please read the
  368. [Contributing Guidelines](https://github.com/NVIDIA/auto-ontology/blob/main/CONTRIBUTING.md)
  369. before submitting pull requests.
  370. To integrate an agent platform, application, or storage provider with
  371. Auto Ontology,
  372. [open an integration request](https://github.com/NVIDIA/auto-ontology/issues/new?template=integration.yml).
  373. ## Reference
  374. | Topic | Doc |
  375. | --------------------------------------- | ---------------------------------------------------- |
  376. | Kubernetes deployment with Helm | [DEPLOYMENT.md](./DEPLOYMENT.md) |
  377. | Architecture and pipeline steps | [docs/architecture.md](./docs/architecture.md) |
  378. | Connections, scoping, and Vault | [docs/connections.md](./docs/connections.md) |
  379. | Authentication, SSO, and API tokens | [docs/authentication.md](./docs/authentication.md) |
  380. | Conversation API | [docs/conversation-api.md](./docs/conversation-api.md) |
  381. | MCP server | [docs/mcp.md](./docs/mcp.md) |
  382. | REST API | [docs/openapi/auto-ontology-api.json](./docs/openapi/auto-ontology-api.json) |
  383. ## License
  384. Auto Ontology is licensed under the [Apache License, Version 2.0](./LICENSE).
  385. SPDX identifier: `Apache-2.0`.
  386. Each NVIDIA-authored source file in this repository carries an SPDX header
  387. of the form:
  388. ```text
  389. SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES.
  390. All rights reserved.
  391. SPDX-License-Identifier: Apache-2.0
  392. ```
  393. Third-party open-source components used by Auto Ontology are enumerated, with their
  394. upstream licenses and project URLs, in
  395. [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md). Components added by the
  396. container images are listed separately in
  397. [`CONTAINER_THIRD_PARTY_NOTICES.md`](./CONTAINER_THIRD_PARTY_NOTICES.md).
  398. ## Notice and Disclaimer
  399. NOTICE AND DISCLAIMER: This software automatically retrieves, accesses or
  400. interacts with external materials. Those retrieved materials are not
  401. distributed with this software and are governed solely by separate terms,
  402. conditions and licenses. You are solely responsible for finding, reviewing and
  403. complying with all applicable terms, conditions, and licenses, and for
  404. verifying the security, integrity and suitability of any retrieved materials
  405. for your specific use case. This software is provided "AS IS", without warranty
  406. of any kind. The author makes no representations or warranties regarding any
  407. retrieved materials, and assumes no liability for any losses, damages,
  408. liabilities or legal consequences from your use or inability to use this
  409. software or any retrieved materials. Use this software and the retrieved
  410. materials at your own risk.
  411. External materials Auto Ontology interacts with at run time:
  412. - Model endpoints you configure, by default the NVIDIA API catalog
  413. (`integrate.api.nvidia.com`, `ai.api.nvidia.com`), under each provider's and
  414. model's terms.
  415. - The KumoRFM service, only when `KUMO_RFM_API_URL` is set, under Kumo's terms.
  416. - Your source databases, under your agreements for those systems.
  417. ## Security
  418. Report security vulnerabilities as described in [SECURITY.md](./SECURITY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.