Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix: resolve code review feedback for diff engine and report format

ZohaibHassan169a2b2b9cd19e
diff --git a/docs/reference/change_management.md b/docs/reference/change_management.md
index d03df6da..cdb85106 100644
--- a/docs/reference/change_management.md
+++ b/docs/reference/change_management.md
@@ -416,3 +416,54 @@ report = engine.compare_versions(
print(f"Total changes detected: {report['summary']['total_changes']}")
```
+---
+
+### Understanding the Report Format
+
+The `compare_versions` method returns a comprehensive dictionary containing both a machine-readable diff and a human-readable impact analysis.
+
+
+
+Here is the exact structure of the returned report:
+
+```json
+{
+ "summary": {
+ "total_changes": 12
+ },
+ "impact_classification": {
+ "breaking": [
+ {
+ "entity_uri": "[http://example.org/Person](http://example.org/Person)",
+ "severity": "critical",
+ "description": "Class Person removed.",
+ "mitigation": "Migrate orphaned instances."
+ }
+ ],
+ "potentially_breaking": [],
+ "safe": []
+ },
+ "recommendations": [
+ "✘✘✘ BREAKING: Schedule downtime or validate existing data."
+ ],
+ "diff": {
+ "added_classes": [],
+ "removed_classes": [],
+ "changed_classes": [],
+ "added_properties": [],
+ "removed_properties": [],
+ "changed_properties": []
+ },
+ "validation_results": {
+ "valid": true,
+ "consistent": true,
+ "satisfiable": true,
+ "errors": [],
+ "warnings": []
+ },
+ "graph_validation": {
+ "valid": false,
+ "errors": ["Instance data violates new domain constraint"],
+ "warnings": []
+ }
+}
diff --git a/semantica/change_management/change_log.py b/semantica/change_management/change_log.py
index 822f6928..6ecb7b37 100644
--- a/semantica/change_management/change_log.py
+++ b/semantica/change_management/change_log.py
@@ -152,9 +152,10 @@ class ChangeLogAnalyzer:
STRUCTURAL_FIELDS = {'subclasses', 'superclasses', 'equivalent_to', 'disjoint_with'}
def __init__(self):
- self.report = ImpactReport()
+ pass
def analyze(self, diff: Dict[str, Any]) -> ImpactReport:
+ self.report = ImpactReport()
if not diff:
self.report.summary = {"error": "Empty diff provided"}
return self.report
diff --git a/semantica/change_management/ontology_version_manager.py b/semantica/change_management/ontology_version_manager.py
index 19ee7f28..ad124add 100644
--- a/semantica/change_management/ontology_version_manager.py
+++ b/semantica/change_management/ontology_version_manager.py
@@ -304,15 +304,19 @@ class VersionManager:
base_map = {}
for item in base_list:
- if isinstance(item, dict) and (item.get("uri") or item.get("name")):
- base_map[item.get("uri", item.get("name"))] = item
+ if isinstance(item, dict):
+ key = item.get("uri") or item.get("name")
+ if key:
+ base_map[key] = item
elif isinstance(item, str):
base_map[item] = {"uri": item}
target_map = {}
for item in target_list:
- if isinstance(item, dict) and (item.get("uri") or item.get("name")):
- target_map[item.get("uri", item.get("name"))] = item
+ if isinstance(item, dict):
+ key = item.get("uri") or item.get("name")
+ if key:
+ target_map[key] = item
elif isinstance(item, str):
target_map[item] = {"uri": item}
@@ -343,8 +347,8 @@ class VersionManager:
if changes:
changed.append({
- "uri": t_item.get("uri", key),
- "name": t_item.get("name", key),
+ "uri": t_item.get("uri") or key,
+ "name": t_item.get("name") or key,
"changes": changes
})
diff --git a/semantica/ontology/engine.py b/semantica/ontology/engine.py
index 2a7b1b36..4044ba97 100644
--- a/semantica/ontology/engine.py
+++ b/semantica/ontology/engine.py
@@ -90,9 +90,11 @@ class OntologyEngine:
base_id: Version ID of the old ontology
target_id: Version ID of the new ontology
**options: Can pass 'base_dict' and 'target_dict' directly to bypass loading.
+ Can pass 'run_validation=True' to validate schema.
+ Can pass 'graph_data' to validate instances against new schema.
Returns:
- A structured ImpactReport dictionary containing breaking/safe changes.
+ A structured dictionary containing the impact report and machine-readable diff.
"""
tracking_id = self.progress.start_tracking(
@@ -104,22 +106,46 @@ class OntologyEngine:
try:
from ..change_management.change_log import generate_change_report
- base_dict = options.get("base_dict") or self.get_ontology_version_dict(base_id)
- target_dict = options.get("target_dict") or self.get_ontology_version_dict(target_id)
+
+ base_dict = options["base_dict"] if "base_dict" in options else self.get_ontology_version_dict(base_id)
+ target_dict = options["target_dict"] if "target_dict" in options else self.get_ontology_version_dict(target_id)
diff_result = self.version_manager.diff_ontologies(base_dict, target_dict)
-
report = generate_change_report(diff_result)
+ report["diff"] = diff_result
+
if options.get("run_validation"):
self.progress.update_tracking(tracking_id, message="Running validation on target schema...")
- validation_results = self.validate(target_dict, **options)
+
+ val_res = self.validate(target_dict, **options)
+ report["validation_results"] = {
+ "valid": getattr(val_res, "valid", getattr(val_res, "is_valid", False)),
+ "consistent": getattr(val_res, "consistent", True),
+ "satisfiable": getattr(val_res, "satisfiable", True),
+ "errors": getattr(val_res, "errors", []),
+ "warnings": getattr(val_res, "warnings", [])
+ }
- report["validation_results"] = validation_results
+
+ if "graph_data" in options:
+ try:
+ from ..kg.graph_validator import GraphValidator
+ kg_validator = GraphValidator(**self.config)
+
+ self.progress.update_tracking(tracking_id, message="Running graph data validation...")
+ kg_res = kg_validator.validate(options["graph_data"], ontology=target_dict, **options)
+
+ report["graph_validation"] = {
+ "valid": getattr(kg_res, "valid", getattr(kg_res, "is_valid", False)),
+ "errors": getattr(kg_res, "errors", []),
+ "warnings": getattr(kg_res, "warnings", [])
+ }
+ except ImportError:
+ self.logger.warning("GraphValidator module not found, skipping KG validation.")
self.progress.stop_tracking(tracking_id, status="completed", message="Comparison complete")
-
return report
except Exception as e: