Auto Ontology – NVIDIA's Open-Source Semantic Graph Reasoning Framework

Auto Ontology is an open-source semantic layer library from NVIDIA. It builds ontologies from enterprise metadata and exposes them to agent harnesses through three interfaces: MCP, CLI, and API. The workflow has three phases: automatic ontology generation, manual verification, and agents answering natural-language questions based on the ontology. In short, it inserts a semantic translator between the database and the LLM, converting table names, field names, and SQL relationships into terms an agent can understand.

This makes it a good fit for teams validating text-to-SQL prototypes or needing a unified semantic data layer for agents. It is not a fit for teams that expect an out-of-the-box solution and are unwilling to put manual effort into semantic modeling, nor for production environments that require deep customization or community support—the project currently does not accept external contributions, and its reasoning depends on the NVIDIA NIM endpoint.

What Problem Does It Solve

The problem Auto Ontology addresses is that LLMs interacting directly with a database don't understand business terminology. An LLM may not know what a FactInternetSales table represents or how it relates to DimCustomer. Auto Ontology solves this by generating an ontology layer with three kinds of definitions: terminology, SQL attributes (the semantic meaning of fields), and relationships (how tables connect).

A key design choice is that the ontology requires manual verification. The system-generated ontology is only a draft; a human must confirm or correct the definitions. Separating automation from manual review keeps the pipeline from relying entirely on model output.

The workflow is divided into three phases:

1. Generation Phase: Scans the connected database and automatically generates the ontology, extracting business terminology (e.g., which table corresponds to "customer"), SQL attributes (semantic meanings of fields), and relationships (how tables are connected).
2. Manual Verification Phase: A human reviews the generated ontology, confirming or correcting definitions. This is the critical checkpoint for semantic quality.
3. Answering Phase: Agents use the verified ontology to answer natural-language questions and generate SQL queries.

The MCP server exposes four read-only tools that map to the typical usage flow:

• check_readiness: checks whether the ontology is ready
• search_terms: searches term definitions
• check_answerable: determines whether a question can be answered with the current ontology
• ask_question: asks the agent a question and returns an answer

The calling order follows the standard integration path: confirm readiness, search for terms, check whether the question is answerable, then ask.

Getting Started Quickly: Running Wide World Importers with Docker Compose

To run it locally you need Docker Compose v2, the uv package manager, and an NVIDIA API key. The example uses Microsoft's Wide World Importers sample sales database, a public SQL Server sample dataset that demonstrates the full workflow.

Two deployment options are available: Kubernetes via a Helm chart, and local development via Docker Compose. The Helm chart suits teams with existing Kubernetes infrastructure; Docker Compose is better for a quick trial.

The Web UI includes chat, analysis, data catalog, and settings. You can open a browser and start a conversation immediately, without writing any integration code.

Three Integration Methods

Auto Ontology is meant to provide a semantic layer for any agent harness, not to act as a standalone tool. There are three integration paths:

MCP (Model Context Protocol): Any MCP client can integrate with Auto Ontology. MCP is an open protocol introduced by Anthropic; clients such as Claude Desktop and Cursor can use the semantic query capabilities directly. The server exposes read-only tools, so agents cannot modify the ontology or database directly. Integration configuration lives in the mcp subdirectory of the repository (link at the end of the article).

CLI: For scripted use, such as checking ontology status or running batch queries in CI/CD workflows.

REST API: Exposes POST /api/chat/completions with API-token authentication and streaming output via server-sent events. The interface is compatible with OpenAI's chat completions API, so teams already using OpenAI SDKs can connect with minimal changes.

Auto Ontology is also compatible with Apache Ossie, supporting import and export of model definitions in Ossie YAML format. Ontology definitions can be treated as code and stored in a Git repository, which helps with version control and migration across environments.

Database Coverage and Model Configuration

Ten data engines are supported: PostgreSQL, MySQL, Databricks, Snowflake, ClickHouse, Trino, Apache Kyuubi, HeavyDB, DuckDB, and SQLite. This covers mainstream OLTP and OLAP systems, from lightweight SQLite to cloud data warehouses such as Snowflake and Databricks.

Inference runs through the NVIDIA NIM endpoint. Model configuration follows a triplet environment-variable pattern: each model has three variables (_ENDPOINT, _API_KEY, _MODEL), and unset fields fall back to the DEFAULT_MODELS_* defaults. The default LLM is nvidia/nemotron-3.5-lightning-30b-a3b; embeddings and rerank have their own defaults as well.

The official documentation contains some inconsistencies in model naming. The NVIDIA NIM section lists embeddings as nvidia/nemotron-3-embed-1b and rerank as nvidia/llama-nemotron-rerank-vl-1b-v2, while the Models section lists EMBED as nvidia/nemotron-3.5-embed-1b and RERANK as nvidia/nemotron-3.5-rerank-8b. The default models for REASONING and NON_REASONING are also identical (nemotron-3.5-lightning-30b-a3b), which contradicts the documentation's description of the latter as a "lighter model." When configuring environment variables, it's safer to specify the model name explicitly rather than rely on defaults.

Predictive questions (for example, "Predict which customers will churn") can be routed to the KumoRFM service, configured via KUMO_RFM_API_KEY; there is a limit on how much table data can be uploaded. This adds predictive-analytics capabilities beyond text-to-SQL.

Security Boundary: Do Not Expose Ports 3001/3002

The official documentation warns explicitly that ports 3001 and 3002 should stay on a private network. Two reasons are given:

1. FastAPI trusts the x-auto-ontology-user-id header forwarded by the frontend. If the service is exposed to the public internet, an attacker can forge request headers and impersonate any user.
2. The ingestion service endpoints have no authentication of their own. The data ingestion service lacks access control and relies on network isolation for security.

This design works for internal network or VPN deployment, but not for direct internet exposure. To serve external traffic, you need an authentication gateway (API gateway or reverse proxy) in front. Auto Ontology itself should not be relied on for authentication.

Effect Validation: auto-ontology-eval

A separate repository, auto-ontology-eval, measures how much Auto Ontology improves text-to-SQL accuracy. It supports benchmarks including BIRD, BEAVER, FDABench-Lite, and Wide World Importers. The choice of standard benchmarks suggests NVIDIA is validating the semantic layer against established datasets.

NVIDIA has not yet published specific accuracy numbers. The evaluation repository makes it possible to replicate the results yourself; the only way to get performance data is to run it.

Limitations and Selection Considerations

Auto Ontology is released under Apache License 2.0, so you can use and modify it freely, but the project explicitly does not accept external contributions. Even if you find a bug or want to add a feature, you can't contribute it back through a pull request. It works well for internal enterprise use, but not for developers who want to participate in an open-source project.

Inference depends on the NVIDIA NIM endpoint, so you must use NVIDIA's model services, and the overall design is tied to the NIM ecosystem. The model endpoint can be configured through environment variables, but a dependency on NVIDIA's cloud services remains.

Before adopting it, note a few information gaps: the project has no official release date or version number, and production performance, stability, community activity, and maintenance frequency can only be assessed through hands-on testing. If your workload includes Chinese-language queries, validate it in a test environment first. The long-term maintenance schedule is uncertain, so keep a close eye on it for core business scenarios with longer lifecycles.

Auto Ontology sits as a semantic middle layer in the text-to-SQL pipeline, addressing the problem of models not understanding the data model. It does not handle database connections or query execution. If you use MCP as your agent access protocol and need a unified semantic layer for enterprise data, a prototype validation is worthwhile. It offers out-of-the-box support for three usage modes—Web UI, MCP tools, and API—plus a separate evaluation repository for quantifying the accuracy gains from the semantic layer.

Before production deployment, settle two questions: whether the NIM endpoint dependency is acceptable, and whether an additional gateway can compensate for the missing authentication on ports 3001/3002. And since the project does not accept external contributions, if its development direction diverges from your internal needs, you won't be able to influence upstream evolution.

Sources and Project Links

• Product Repository: https://github.com/NVIDIA/auto-ontology.git
• Evaluation Repository: https://github.com/NVIDIA/auto-ontology-eval.git
• MCP Server Documentation: https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp