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.

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.

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=ai-governance-local-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. Schema initialization is automatic in the supported local and Docker workflows; see Neo4j Operations for verification and recovery guidance.

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.