nvidia-ontology-management

Files (9)

• BENCHMARK.md
• SKILL.md
• runtime-contract.yaml · assets/
• evals.json · evals/
• modeling.md · references/
• publication.md · references/
• write-api.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

<!--
SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# Auto Ontology management and modeling

## Purpose

Inspect and change Auto Ontology's semantic layer without confusing a successful API call
with correct business meaning or durable publication. The machine-readable
inputs, outputs, statuses, gates, and handoffs are in
[runtime-contract.yaml](assets/runtime-contract.yaml).

Choose the focused workflow before acting:

- routine inspection or metadata edits: continue below and use
  [write-api.md](references/write-api.md);
- concepts, relationships, measures, units, grain, or policies: use
  [modeling.md](references/modeling.md);
- model promotion or reusable analytical results: use
  [publication.md](references/publication.md).

MCP tools only **read**. Create, patch, import, and compile-reset go through
the Next.js `/api/...` gateway. Governed result rows require an approved source
writer; Auto Ontology has no generic result-row writeback endpoint. Request bodies and
field types live in `docs/openapi/auto-ontology-api.json`; this skill names operations and
permissions only.

## Prerequisites

Use a running, authenticated Auto Ontology deployment. Use `nvidia-ontology-setup` when
the deployment or semantic layer is not ready.

## Limitations

MCP is read-only, Auto Ontology has no generic result-row writeback endpoint, and current
model import and certification APIs do not prove atomic promotion. Follow the
publication gates below and fail closed when exact readback is unavailable.

## Auth

Scripts use an API token (`x-api-key` or `Authorization: Bearer`). Mint it in
the UI (user menu → API Tokens). A token **acts as its owner** — a viewer's
token cannot do admin things. Creating and revoking tokens requires a signed-in
session; a token cannot mint another token.

Writes below need `catalog:edit` unless noted. `403` means the owner's role
lacks that permission, not that the path is wrong.

## Instructions

1. **Discover current meaning** via MCP (`search_terms`, `get_term`,
   `get_term_columns`, `get_term_sql_attributes`, `describe_table`) or REST
   if MCP is absent (`GET /api/terms`, `GET /api/terms/{term_id}`,
   `GET /api/exploration/tables/{table_id}/details`).
2. **Resolve the semantic contract** when meaning changes. Record source
   binding, identity, population, relationship cardinality, measure expression,
   unit, grain, denominator, time, validity, and counterexamples; see
   [modeling.md](references/modeling.md).
3. **State the proposed change** to the user (term rename, new SQL attribute,
   import, and so on). Do not silently rewrite the glossary.
4. **Validate SQL** before create/update: `POST /api/sql-attributes/validate`.
   A parse failure is **HTTP 422**, not `valid: false`.
5. **Apply** the smallest write that matches the request (see
   [write-api.md](references/write-api.md)).
6. **Compilation is not a hidden side effect.** Check
   `GET /api/semantic-compilation/status`. Do **not** call
   `POST /api/semantic-compilation/reset` as cleanup — it is an asynchronous,
   destructive rebuild of every database's compiled layer, returns 202, and
   requires `semanticCompilation:manage`.
7. **Verify the persisted change**, not merely request success. Model imports
   require a scoped backup and exact re-export comparison; see
   [publication.md](references/publication.md). Then use MCP
   `check_answerable` / `ask_question` (or REST
   `POST /api/question-entity-coverage` and `POST /api/chat/completions`) for
   positive and negative behavior checks.

## Semantic relationships and "what does this dataset mean"

Stay on the semantic layer. Do not browse raw schemas to answer meaning.

- Term → columns: MCP `get_term_columns` or
  `GET /api/terms/{term_id}/column-attributes`
- Term → derived SQL: MCP `get_term_sql_attributes`
- Table → terms and SQL attributes: MCP `describe_table` or
  `GET /api/exploration/tables/{table_id}/details`
- Semantic hop chain between two terms:
  `GET /api/exploration/terms/{term_id}/path/{other_term_id}`
- Semantic graphs: `GET /api/exploration/graph`,
  `GET /api/exploration/semantic-graph`

These are semantic relationship paths, not generation provenance, source
revision, certification history, or version lineage.

## Bulk import / export

- `POST /api/model/export` — YAML of catalog + semantic layer.
  Permission `modelInterchange:export`. Body may set catalog database **IDs**
  in `databases` (empty = all) and `format` (`auto_ontology` or `ossie`).
- `POST /api/model/import` — multipart YAML; native Auto Ontology
  (`data_layer` / `semantic_layer`) or Apache Ossie (`version`, `name`,
  `datasets` at the root).
  Query `replace` (default true) and `embed` (default true). Permission
  `modelInterchange:import`. Can replace existing data — confirm with the
  user before `replace=true`, apply first in isolation, and use the exact
  readback workflow in [publication.md](references/publication.md).

## Examples

- To define a run-grain measure, follow the evidence and counterexample workflow
  in [modeling.md](references/modeling.md).
- To revise and promote a model, back up the exact scope and follow the staged
  readback workflow in [publication.md](references/publication.md).

## Troubleshooting

For write failures, verify the authenticated owner's permission, distinguish

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills