Ontologies

Ontologies are a NAMS (hosted backend) capability. On the bolt backend the client.ontology methods raise NotSupportedError; define a custom schema with SchemaModel.CUSTOM instead. See Backends.

What is an ontology?

An ontology is a typed, versioned, validated schema for your knowledge graph. Where the base POLE+O model gives you five coarse entity categories (Person, Organization, Location, Event, Object), an ontology refines them into a concrete domain vocabulary:

Entity types — each carries a pole_type (one of the POLE+O categories), an optional subtype, display metadata (color, icon), and a list of typed properties.
Properties — a name, a type (string, datetime, date, float, integer), and optional required, unique, and enum constraints.
Relationships — a typed edge (UPPER_SNAKE) with source and target entity labels.

NAMS ships ~28 system templates (healthcare, legal, cybersecurity, financial-services, software-engineering, and more). Activating one makes server-side extraction produce a clean, predictable graph — Patient, Provider, Diagnosis with enforced fields and enumerations — instead of generic, loosely-typed nodes.

Templates vs. workspace-owned ontologies

System templates are read-only (is_system = true). To customize one you clone it into a workspace-owned copy, which you can then revise. A workspace also has exactly one active ontology at a time; until you activate one, the nams-default template is implicitly bound.

Versioning and immutability

Every change produces a new immutable revision. clone yields revision 1; each update yields revision n+1. A version records its revision, validation_mode, a schema_hash, and provenance. You activate a specific version (by its ov_… id) — activation is what binds a schema to the workspace and starts validating writes against it.

Validation modes

Each version has a validation_mode:

Mode Behavior

Mode	Behavior
`permissive`	(default) Non-conforming entity writes are accepted and recorded.
`strict`	Writes that violate the schema are rejected. The SDK surfaces the rejection as `ValidationError`.

permissive

(default) Non-conforming entity writes are accepted and recorded.

strict

Writes that violate the schema are rejected. The SDK surfaces the rejection as ValidationError.

permissive favors ingestion tolerance; strict favors graph cleanliness. You choose per version, and get_active() reports the active mode.

Relationship to server-side extraction

Ontologies shape the server-side GraphRAG extraction pipeline. Once a version is active, entities extracted from stored messages — and entities you write directly with add_entity — are validated against the active schema. Extraction is asynchronous; use wait_for_extraction when you need to observe the result deterministically.