Ontology Foundation

Overview

The foundation includes storage-independent ontology models, relationship validation for ontology v1 relationships, an ontology graph repository protocol, an in-memory repository for unit tests, a Neo4j Community Edition repository adapter, graph schema initialization, and an ontology service for validated writes and traversal.

Existing prompt, model, dataset, experiment, evaluation, job, and MCP services do not depend on Neo4j. The separate synchronization layer projects their authoritative state through OntologyService without making the graph a system of record.

In simple terms, the foundation gives the platform one reliable map of its AI work. Nodes are the things on the map, such as a model or policy; relationships are the labelled lines that explain how those things are connected. The graph helps people investigate a decision without changing the original domain records that produced it.

Domain Models

• OntologyEntity — represents a first-class ontology node. Stores stable entity identity, entity type, ontology version, owner, lifecycle, creation timestamp, immutable attributes, mutable attributes, and metadata.
• OntologyRelationship — represents a directed ontology edge. Stores source and target entity IDs and types, relationship type, ontology version, creation metadata, and relationship metadata.
• OntologyEvent — represents semantic temporal facts such as Created, EvaluationCompleted, or DriftDetected. Events are records, not graph relationships, because high-volume event logs should not redefine the decision topology.

Explorer Views

The Ontology Explorer provides two ways to look at this same foundation. Explore is the default, human-oriented view: search for a model, dataset, policy, decision, prompt, or experiment, then follow the labelled relationships around it. Technical exposes the exact entity type and ID, raw relationship names, graph depth and direction, properties, and schema metadata for engineering and support work.

These are not separate graphs. Selecting an entity in Explore and switching to Technical preserves the same canonical entity, relationships, permissions, tenant/project scope, and graph context. Read the Governance Ontology and Decision Graph guide for a visual walkthrough.

Relationship Validation

RelationshipValidator is the central registry for relationship rules. It rejects unknown relationship types, unsupported source or target entity types, invalid relationship direction, and self-relationships unless a rule explicitly allows them.

service.create_relationship(
    source_type="Candidate",
    source_id="candidate-1",
    relationship_type="USES",
    target_type="PromptVersion",
    target_id="prompt-v1",
    created_by="governance-admin",
)

# Invalid: Candidate -[:HAS_VERSION]-> PromptVersion
# HAS_VERSION is valid from Prompt -> PromptVersion only

Neo4j Local Development

Start Neo4j Community Edition:

docker compose up -d neo4j

Configure the repository:

export AI_GOVERNANCE_GRAPH_URI=bolt://localhost:7687
export AI_GOVERNANCE_GRAPH_USER=neo4j
export AI_GOVERNANCE_GRAPH_PASSWORD=<your-neo4j-password>
export AI_GOVERNANCE_GRAPH_DATABASE=neo4j

The Neo4j adapter imports the Neo4j Python driver only when constructed. Install the project dependencies before running the adapter:

uv sync

Schema Initialization

The adapter creates a tenant-scoped composite uniqueness constraint on (organization_id, project_id, entity_type, entity_id), plus indexes for tenant lookup and graph traversal. Relationship-ID uniqueness is enforced per canonical relationship type because Neo4j constraints must name a relationship type. Schema initialization is automatic in the supported local and Docker workflows; see Neo4j Operations for verification and recovery guidance.

Use the Compose startup path when provisioning or recreating Neo4j. The one-shot deployment schema service runs after Neo4j is healthy and before Platform starts. It creates only idempotent constraints and indexes; it does not rewrite nodes, normalize tenants, or deduplicate relationships.

docker compose up -d --build

Entity Search Index

ontology_entity_searchis a Neo4j full-text index used by the Explorer's type-ahead entity search. It indexes existing canonical entity properties, so Neo4j populates it normally when the index is first created. The deployment schema service waits until the index is ONLINE before allowing Platform to start.

SHOW INDEXES YIELD name, type, state
WHERE name = 'ontology_entity_search'
RETURN name, type, state;

A healthy result is one FULLTEXT index with state ONLINE. Starting only the Platform container bypasses the Compose schema dependency, so use Compose for a fresh graph volume.

Running Tests

# Unit tests without Neo4j
uv run pytest tests/unit/ontology

# Integration tests with Neo4j
AI_GOVERNANCE_RUN_NEO4J_TESTS=true uv run pytest tests/integration/ontology tests/integration/ontology_sync

Guardrails

• Ontology writes go through OntologyService.
• Existing domain services do not depend on Neo4j.
• Neo4j-specific APIs stay inside Neo4jOntologyGraphRepository.
• Every graph relationship must conform to the ontology taxonomy.
• Graph topology represents semantic decision structure, not high-volume event or audit logs.