Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
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.mdindex 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.pyindex 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()+ passdef analyze(self, diff: Dict[str, Any]) -> ImpactReport:+ self.report = ImpactReport()if not diff:self.report.summary = {"error": "Empty diff provided"}return self.reportdiff --git a/semantica/change_management/ontology_version_manager.py b/semantica/change_management/ontology_version_manager.pyindex 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] = itemelif 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] = itemelif 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.pyindex 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 ontologytarget_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 reportexcept Exception as e: