KAVACHKAVACH
v2.0.1

Ontology Foundation

The ontology foundation makes the accepted kavach.governance ontology version 1.0.0 executable without synchronizing existing Kavach domain objects into a graph.

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 this package. Future synchronization epics can project those domain objects into the graph through OntologyService.

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.

python
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:

bash
docker compose up -d neo4j

Configure the repository:

bash
export KAVACH_GRAPH_URI=bolt://localhost:7687
export KAVACH_GRAPH_USER=neo4j
export KAVACH_GRAPH_PASSWORD=kavach-local-password
export KAVACH_GRAPH_DATABASE=neo4j

The Neo4j adapter imports the Neo4j Python driver only when constructed. If the driver is not installed:

bash
uv add neo4j

Schema Initialization

The Neo4j adapter creates a composite uniqueness constraint on (entity_type, entity_id) and indexes on entity_type and ontology_version. Neo4j Community Edition 5.x supports the composite uniqueness constraint.

Running Tests

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

# Integration tests with Neo4j
export KAVACH_RUN_NEO4J_TESTS=true
uv run pytest tests/integration/ontology

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.