NVIDIA Auto Ontology: A Verifiable Semantic Layer for Agent Harnesses

How the semantic catalog is compiled

The catalog is not produced in one unconstrained prompt. Compilation begins with database metadata, then samples table contents under a controlled limit. By default, it reads up to 1,000 rows per table to discover common values, candidate enums, and possible relationships. Low-cardinality text columns can be examined with a capped DISTINCT query so high-cardinality identifiers are not mistaken for categorical values. The resulting catalog reflects the sampled evidence, not a statistical guarantee about the entire database.

At the structural level, the compiler collects tables, columns, keys, and constraints, attempts to infer foreign-key relationships, and detects bridge tables. Similar names do not automatically create a trusted join. Candidate relationships enter the catalog for later review or query planning. Bridge-table detection is particularly important for many-to-many paths that have no direct foreign key link and are difficult to infer from names alone.

At the explanatory level, three workers can run expensive language-model extraction tasks concurrently. Each extraction operation is also constrained by SEMANTIC_LLM_MAX_INFLIGHT, which defaults to 6. This value limits simultaneous model requests, not database connections or worker processes. Capacity planning must account for provider quotas, sampling load, and queue growth rather than assuming three workers determine the total concurrency.

Compilation produces terms, descriptions, relationships, and SQL attributes. Terms normalize business concepts to columns, relationships preserve traceable join paths, and SQL attributes make metrics or filters explicit and reviewable. Writes follow canonical table order to reduce nondeterminism between concurrent compilation tasks. If one table fails, the compiler logs the failure and continues with the remaining tables. That behavior preserves partial progress, but an administrator still needs to inspect failures rather than treating a finished job as proof that every table completed.

Certification turns definitions into commitments

Automation can expand coverage, but it cannot assign business responsibility. Auto Ontology lets a person edit and certify term names, descriptions, and SQL attributes. A certified definition becomes a commitment that an agent may rely on: the metric expression, mapped columns, and reviewed relationship can be inspected instead of inferred from probabilistic confidence.

This shifts the question from whether a model sounds certain to whether an answer is supported by an auditable catalog. Which semantic definitions did the answer use? Were they certified? Did the readiness check confirm a compiled catalog? Is the source connection still reachable? Certification does not make a definition correct by itself, but it makes quality an explicit engineering responsibility.

Generated definitions should remain provisional until reviewed. A model can merge similar columns incorrectly or overgeneralize from a small sample of enum values. Important terms, ambiguous status fields, and cross-table joins deserve review first. Migration changes, new business rules, and newly added tables should trigger recompilation and review of affected certified assets. Certification records describe a decision at a point in time, not permanent truth.

The bounded text-to-SQL path

A question does not pass directly from natural language to database execution. The query pipeline identifies intent, extracts entities, retrieves relevant terms and semantic attributes, prepares candidate tables and join paths, and only then constructs SQL. Validation and prechecks run before execution.

If SQL generation fails, repair is bounded. An attempt that cannot produce SQL at all receives one restart from the immutable request state instead of continuing to modify an increasingly distorted intermediate result. If construction still fails, the service returns the explicit message SQL cannot be constructed. That refusal is safer than sending plausible-looking SQL with no semantic support to the source database.

An empty result also receives one repair opportunity based on the original request state. This addresses source-side surprises such as join conditions, filters, or field choices that produce no rows. The protection comes from the stopping rules: the request state is recoverable, repair is limited, execution has prechecks, and failure has a recognizable representation rather than being hidden inside a polished answer.

Entity coverage is easy to misread. It is the number of covered extracted entities divided by the total number of extracted entities. Only column-attribute matches count as coverage. SQL attributes and custom analyses do not increase the score by themselves. A high coverage value therefore does not prove that every business claim is grounded. Reviewers should confirm that the important entities in the question have concrete column mappings; a successful complex analysis can still contain an unsupported entity.

Nine curated MCP tools

MCP is a primary agent interface, but Auto Ontology deliberately avoids exposing the whole database browsing surface. The server provides nine read-only tools: check_readiness, search_terms, get_term, get_term_columns, get_term_sql_attributes, get_sql_attribute, describe_table, check_answerable, and ask_question.

The first eight tools let an agent inspect catalog readiness, search business terms, retrieve mapped columns and SQL attributes, and understand a relevant table. They do not provide arbitrary schema enumeration, raw column scanning, or a database execution endpoint. ask_question sends a natural-language request through the full controlled pipeline, caps output at 100 rows, and returns row_count and truncated so the caller can detect an incomplete result.

That tool surface is narrower than giving an agent a SQL executor, but it makes the boundary easier to enforce. Agents express information needs through terms and relationships, while the service applies validation, bounded repair, row limits, and structured failures consistently. Custom SQL and analysis workflows can use the HTTP API, but the MCP server is focused on discoverable, answerable, traceable read-only questions.

check_readiness examines whether the semantic catalog is compiled, the live connection is available, and the catalog can be read. A viewer may receive a 403 when attempting an admin-only connection read. That result is unverified, not a statement that the service is not ready. Insufficient permission means the current identity cannot confirm the connection state; it does not prove that the database connection has failed.

Connectors, model roles, and portability

Connectors cover PostgreSQL, MySQL, Databricks, Snowflake, ClickHouse, Trino, Apache Kyuubi, HeavyDB, DuckDB, and SQLite. These systems differ in their metadata queries, type systems, SQL dialects, and connection constraints, so a connector name is not a substitute for testing a supported database version and permission model. Read-only accounts, network allowlists, query timeouts, and resource limits should be enforced by the deployment rather than left to model behavior.

Models have four roles: REASONING, NON_REASONING, EMBED, and RERANK. Reasoning models handle semantic extraction and query planning, non-reasoning models perform more mechanical generation steps, embedding models support catalog retrieval, and rerankers improve candidate ordering. The default configuration targets NVIDIA NIM and Nemotron, while OpenAI-compatible endpoints are supported.

Embedding changes require special care. Vectors written during compilation must match the embedding model and dimensions used during retrieval. Replacing only the query-side embedding model can make catalog search unreliable or unusable. A model migration should define which assets need re-embedding and verify term retrieval and representative questions after the switch.

Deployment boundaries and limits

Auto Ontology supports Apache Ossie semantic-model import and export, which helps place definitions under version control or move them into compatible tooling. The optional KumoRFM feature uploads connected tables to a hosted prediction service and defaults to a maximum of 20 tables. Enabling it introduces a separate data flow that must be checked against classification, table scope, hosting region, and organizational policy. It is not required for local text-to-SQL operation.

The repository does not provide a single benchmark result suitable for claiming a general performance improvement. It links an external evaluation project, but a real assessment still needs the deployment's own database, terminology, models, and question set. Useful measures include certified coverage, key-entity match rate, unconstructable-request rate, empty-result repair success, query latency, and human correction cost. Architectural intent alone is not a performance result.

A sensible first deployment is one data domain with clear permissions, stable terminology, and recurring questions. Certify the important tables, enum meanings, and join paths before connecting a small set of agents through MCP. Study unsuccessful questions, improve the semantic definitions, and expand coverage deliberately. The outcome is a maintainable semantic asset that can be reviewed and traced, not a one-time schema summary that nobody owns.

The project does not accept external pull requests, so downstream changes should follow the Apache-2.0 terms through local branches and integrations. Its role is not to replace a database or a BI platform. It is a system for making the agent's basis for understanding data explicit enough to compile, retrieve, certify, query, and inspect.