Skip to content

Curating the catalog

Every document that renders an ontology can add classes and properties to a shared catalog ontology. Some of those terms only ever serve the document that added them. Curation finds them across all the documents processed so far and decides what to do with each one.

What curation reviews

Curation looks only at terms a document added. A term from a seed file or an upload is authored and never changes. OntoCast tells the two apart from the ontology's version history: each version records the document it came from, and a term belongs to the version that first declared it.

A term added by a document is flagged for review when it:

  • is used by the facts of one document only, or of none (counted when the facts store answers SPARQL, as Fuseki and the in-memory store do);
  • has a name that adds one word to another term's (hasOpticalCavity and hasOpticalMicrocavity), or the same words;
  • is one of three or more sibling classes whose labels differ by one word, a value set modelled as subclasses;
  • names an authored term.

Only flagged terms go to the model, in batches. For each one it answers keep, merge_into another term, generalise_to a broader parent, demote_to_property_value (the class becomes a SKOS concept) or drop. OntoCast turns the answers into one change of the ontology without a model, and ignores an answer about an authored term or a term that was not flagged.

Run it

ontocast curate --ontology my_ontology          # report only
ontocast curate --ontology my_ontology --apply  # write a new version

Without --ontology, every catalog ontology is curated. --json report.json writes the full report: each added term, the document that added it, the documents that use it, its flags and the decided action. --no-facts-usage skips the usage counts. A dry run still makes the model calls; only the write is skipped.

From Python:

from ontocast import curate_catalog

reports = await curate_catalog(tools, ontology="my_ontology", apply=False)

--apply writes the change as the ontology's next version, derived from a urn:ontocast:curation:<time> source rather than a document, so later curation runs still attribute each term to the document that added it. Attribution follows each ontology's version history back through owl:priorVersion, so it holds when the catalog is loaded from a triple store that only keeps the latest version in memory.

The calls are charged to the ontology_curation phase in the budget; give it its own model with LLM_MODEL_BY_PHASE.