Ontology Module

semantica.ontology provides the full lifecycle for knowledge graph schemas:

Auto-generate ontologies from KG data via a 5-stage pipeline (Semantic Network → YAML → Types → Hierarchy → TTL)
LLM-powered ontology generation for complex domains via LLMOntologyGenerator
SHACL validation: generate shapes, validate graphs, and get violation reports
OWL/RDF export in Turtle, RDF/XML, and JSON-LD formats
Ontology Hub visual editor available in semantica.explorer (v0.5.0)

Exported Classes

Class	Role
`OntologyEngine`	Unified facade orchestrating the full ontology lifecycle
`OntologyGenerator`	Auto-generate ontologies from KG data (5-stage pipeline)
`LLMOntologyGenerator`	LLM-powered ontology generation for complex domains
`SHACLGenerator`	Generate SHACL shapes from an ontology or KG schema
`OntologyValidator`	Validate any graph against SHACL shapes: returns `SHACLValidationReport`
`OntologyQualityGate`	Run deterministic ontology/KG quality checks for CI
`OWLGenerator`	Serialize ontologies to Turtle, RDF/XML, JSON-LD
`NamespaceManager`	IRI generation, prefix management, and namespace binding
`OntologyEvaluator`	Coverage, completeness, and granularity quality metrics
`ClassInferrer`	Infer classes from entity type patterns
`PropertyGenerator`	Generate properties from entity attributes and relationships
`AssociativeClassBuilder`	Model N-ary relationships as intermediate OWL classes

Getting Started

OntologyEngine is your main entry point for the complete ontology workflow:

from semantica.ontology import OntologyEngine

# Initialize with base URI for your domain
engine = OntologyEngine(base_uri="https://example.org/ontology/")

# Generate ontology from your knowledge graph data
ontology = engine.from_data({"entities": entities, "relationships": relationships})

# Validate a graph against the generated SHACL shapes
report = engine.validate_graph(kg, ontology=ontology)
if not report.conforms:
    for v in report.violations:
        print(f"{v.severity}: {v.message} on {v.focus_node}")

# Export to OWL Turtle
engine.export_owl(ontology, "ontology.ttl", format="turtle")

OntologyEngine (Unified Facade)

OntologyEngine orchestrates the full ontology lifecycle: generation, validation, export, and evaluation:

from semantica.ontology import OntologyEngine

engine = OntologyEngine(base_uri="https://example.org/ontology/")

# Generate ontology from KG data
ontology = engine.from_data({"entities": entities, "relationships": relationships})

# Validate a graph against the generated SHACL shapes
report = engine.validate_graph(kg, ontology=ontology)
if not report.conforms:
    for v in report.violations:
        print(f"{v.severity}: {v.message} on {v.focus_node}")

# Export to OWL Turtle
engine.export_owl(ontology, "ontology.ttl", format="turtle")

OntologyEngine Methods

Method	Description
`from_data(data)`	Run the 5-stage pipeline on entity/relationship data
`validate_graph(kg, ontology=...)`	Check a knowledge graph against generated SHACL shapes
`quality_check(ontology, graph_data=...)`	Return a deterministic quality report and CI-friendly pass/fail result
`export_owl(ontology, path, format)`	Serialize to `"turtle"`, `"xml"`, or `"json-ld"`
`evaluate(ontology, kg)`	Compute coverage, completeness, and granularity metrics

Ontology Quality Gate

Use the quality gate before export or deployment to catch structural issues without adding a runtime dependency:

from semantica.ontology import ontology_quality_check

report = ontology_quality_check(
    ontology,
    graph_data=kg,
    thresholds={"min_coverage": 0.8},
)

if not report.passed:
    for issue in report.issues:
        print(issue.code, issue.message)

The report checks class/property coverage, orphan schema elements, domain and range references, and unresolved KG relationship endpoints. It includes machine-readable issue codes, severity, counts, metrics, and threshold failures. The first version reports findings only; it does not auto-fix data.

Thresholds

min_coverage (default 0.0) sets the minimum required coverage score, the average of class and property coverage from 0.0 to 1.0; the gate fails below it. max_errors (default 0.0) caps how many error/critical issues are allowed before the gate fails. max_warnings (default None) caps warning issues the same way, and None means warnings alone never fail the gate. fail_on_warnings is a separate parameter, not a thresholds key, passed to OntologyQualityGate(...) or .check(...) directly; when True, a single warning fails the gate regardless of max_warnings.

OntologyGenerator (5-Stage Pipeline)

OntologyGenerator auto-generates a formal ontology from your knowledge graph entities and relationships:

from semantica.ontology import OntologyGenerator

generator = OntologyGenerator(base_uri="https://example.org/ontology/")
ontology  = generator.generate_ontology({
    "entities":      entities,
    "relationships": relationships,
})

Semantic Network Parsing

Extract concepts and patterns from entity types and relationship structures in the source data.

YAML-to-Definition

Transform the extracted patterns into intermediate class and property definitions.

Definition-to-Types

Map definitions to OWL constructs: owl:Class, owl:ObjectProperty, owl:DatatypeProperty.

Hierarchy Generation

Build taxonomy trees using transitive closure and cycle detection: produces rdfs:subClassOf chains.

TTL Generation

Serialize the final ontology to Turtle format using rdflib. Also available: RDF/XML and JSON-LD.

SHACL Validation

Generate SHACL shapes from an ontology and validate any graph against them:

from semantica.ontology import SHACLGenerator, OntologyValidator, SHACLValidationReport, SHACLViolation

# Generate shapes from ontology
generator  = SHACLGenerator()
shapes     = generator.generate(ontology)
shapes_ttl = shapes.serialize(format="turtle")

# Validate a graph against the shapes
validator = OntologyValidator()
report: SHACLValidationReport = validator.validate_graph(kg, ontology=ontology)

if not report.conforms:
    violation: SHACLViolation
    for violation in report.violations:
        print(f"{violation.severity}: {violation.message}")
        print(f"  Node: {violation.focus_node}")
        print(f"  Path: {violation.result_path}")

Validation Report Fields

Field	Type	Description
`conforms`	`bool`	`True` if the graph passes all SHACL constraints
`violations`	`List[SHACLViolation]`	Detailed failure records
`focus_node`	`str`	IRI of the violating graph node
`result_path`	`str`	IRI of the violating property path
`severity`	`str`	`"Violation"`, `"Warning"`, or `"Info"`
`message`	`str`	Human-readable constraint failure description

LLM-Powered Ontology Generation

For complex or novel domains where schema patterns are hard to infer statistically:

from semantica.ontology import LLMOntologyGenerator

# Initialize with your preferred LLM provider
generator = LLMOntologyGenerator(provider="openai")  # or "anthropic", "groq", etc.
ontology  = generator.generate_ontology_from_text(
    text="A biomedical ontology for clinical trial protocols involving patients, trials, interventions, and outcomes."
)

OWL / RDF Export

from semantica.ontology import OWLGenerator

generator = OWLGenerator()
generator.export_owl(ontology, path="ontology.ttl",  format="turtle")
generator.export_owl(ontology, path="ontology.owl",  format="xml")
generator.export_owl(ontology, path="ontology.json", format="json-ld")

Namespace Management

from semantica.ontology import NamespaceManager

ns = NamespaceManager(base_uri="https://example.org/")
ns.register("ex",     "https://example.org/")
ns.register("schema", "https://schema.org/")
ns.register("owl",    "http://www.w3.org/2002/07/owl#")

# Generate IRIs for classes and properties
class_iri    = ns.generate_class_iri("Person")
property_iri = ns.generate_property_iri("worksFor")

Ontology Evaluation

Measure coverage, completeness, and granularity of a generated ontology:

from semantica.ontology import OntologyEvaluator

evaluator = OntologyEvaluator()
result    = evaluator.evaluate_ontology(ontology, kg)

print(f"Class coverage:    {result.class_coverage:.2f}")
print(f"Property coverage: {result.property_coverage:.2f}")
print(f"Completeness:      {result.completeness:.2f}")
print(f"Granularity:       {result.granularity:.2f}")

for gap in result.gaps:
    print(f"Gap: {gap.description}")

Common Workflows

Quick Start
LLM-Powered Generation
Export and Integration

Generate and validate an ontology in 3 steps:

from semantica.ontology import OntologyEngine

# 1. Initialize engine
engine = OntologyEngine(base_uri="https://yourcompany.com/ontology/")

# 2. Generate from your data
ontology = engine.from_data({"entities": entities, "relationships": relationships})

# 3. Validate against a knowledge graph
report = engine.validate_graph(kg, ontology=ontology)
if report.conforms:
    print("✓ Graph conforms to ontology")
else:
    print(f"✗ Found {len(report.violations)} violations")

Generate ontologies from text descriptions:

from semantica.ontology import LLMOntologyGenerator

generator = LLMOntologyGenerator(provider="openai")
ontology = generator.generate_ontology_from_text("""
    Create an e-commerce ontology with products, customers, orders, 
    categories, reviews, and payment methods.
""")

# Refine with additional constraints
engine = OntologyEngine()
validated = engine.validate(ontology)

Export ontologies in multiple formats:

from semantica.ontology import OntologyEngine

engine = OntologyEngine()

# Export as OWL/Turtle for Protégé
engine.export_owl(ontology, "schema.ttl", format="turtle")

# Export as JSON-LD for web applications
engine.export_owl(ontology, "schema.jsonld", format="json-ld")

# Generate SHACL shapes for validation
engine.export_shacl(ontology, "shapes.ttl")

Ingest an Existing Ontology

Load and parse an ontology file for downstream use:

from semantica.ontology import ingest_ontology

ontology_data = ingest_ontology("schema.ttl")     # Turtle
ontology_data = ingest_ontology("schema.owl")     # OWL/XML
ontology_data = ingest_ontology("schema.jsonld")  # JSON-LD

Ontology versioning (VersionManager, OntologyVersion) has moved to semantica.change_management. Import from there: from semantica.change_management import VersionManager.

Reasoning — Apply inference rules over ontology axioms.
Knowledge Graph — The graph being modeled by the ontology.
Export — Export ontologies as RDF, OWL, or JSON-LD.
Conflicts — Detect ontology constraint violations.

Context & Intelligence

Storage

Data Pipeline

Quality & Provenance

Output

Utilities

Exported Classes

Getting Started

OntologyEngine (Unified Facade)

OntologyEngine Methods

Ontology Quality Gate

Thresholds

OntologyGenerator (5-Stage Pipeline)

SHACL Validation

Validation Report Fields

LLM-Powered Ontology Generation

OWL / RDF Export

Namespace Management

Ontology Evaluation

Common Workflows

Ingest an Existing Ontology

​Exported Classes

​Getting Started

​OntologyEngine (Unified Facade)

​OntologyEngine Methods

​Ontology Quality Gate

​Thresholds

​OntologyGenerator (5-Stage Pipeline)

​SHACL Validation

​Validation Report Fields

​LLM-Powered Ontology Generation

​OWL / RDF Export

​Namespace Management

​Ontology Evaluation

​Common Workflows

​Ingest an Existing Ontology

Exported Classes

Getting Started

OntologyEngine (Unified Facade)

OntologyEngine Methods

Ontology Quality Gate

Thresholds

OntologyGenerator (5-Stage Pipeline)

SHACL Validation

Validation Report Fields

LLM-Powered Ontology Generation

OWL / RDF Export

Namespace Management

Ontology Evaluation

Common Workflows

Ingest an Existing Ontology