Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

feat: implement Datalog Reasoner

ZohaibHassan1638ec33362613
diff --git a/semantica/reasoning/__init__.py b/semantica/reasoning/__init__.py
index 2096d86a..a72da515 100644
--- a/semantica/reasoning/__init__.py
+++ b/semantica/reasoning/__init__.py
@@ -3,7 +3,8 @@ Reasoning Module
This module provides reasoning and inference capabilities for knowledge graph
analysis and query answering, supporting multiple reasoning strategies including
-rule-based inference via Rete, SPARQL reasoning, abductive and deductive reasoning.
+rule-based inference via Rete, SPARQL reasoning, abductive and deductive reasoning,
+and native Datalog evaluation.
"""
from .reasoner import Reasoner, InferenceResult, Rule, Fact, RuleType
@@ -25,6 +26,8 @@ from .rete_engine import (
)
from .sparql_reasoner import SPARQLQueryResult, SPARQLReasoner
+from .datalog_reasoner import DatalogReasoner, DatalogFact, DatalogRule
+
__all__ = [
# Reasoner facade
"Reasoner",
@@ -43,10 +46,14 @@ __all__ = [
# SPARQL reasoning
"SPARQLReasoner",
"SPARQLQueryResult",
+ # Datalog reasoning
+ "DatalogReasoner",
+ "DatalogFact",
+ "DatalogRule",
# Explanation
"ExplanationGenerator",
"Explanation",
"ReasoningStep",
"ReasoningPath",
"Justification",
-]
+]
\ No newline at end of file
diff --git a/semantica/reasoning/datalog_reasoner.py b/semantica/reasoning/datalog_reasoner.py
new file mode 100644
index 00000000..8e3f5eb8
--- /dev/null
+++ b/semantica/reasoning/datalog_reasoner.py
@@ -0,0 +1,421 @@
+"""
+Datalog reasoner module
+
+This module provides a native Datalog engine using bottom-up semi-naive fixpoint evaluation.
+It supports recursive rules, multi-hop inference, and guarantees termination on finite graphs.
+"""
+
+import re
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Any, Dict, List, NamedTuple, Optional, Set, Tuple, Union
+
+from ..utils.logging import get_logger
+from ..utils.progress_tracker import get_progress_tracker
+
+# data structs
+
+@dataclass(frozen=True)
+class DatalogFact:
+ """Represents a ground truth fact."""
+ predicate: str
+ args: Tuple[str, ...]
+
+class BodyAtom(NamedTuple):
+ """Represents a single predicate condition in a rule's body."""
+ predicate: str
+ args: Tuple[str, ...]
+
+@dataclass
+class DatalogRule:
+ """Represents a Horn clause rule."""
+ head_predicate: str
+ head_args: Tuple[str, ...]
+ body: List[BodyAtom]
+
+
+# datalog reasoner
+
+class DatalogReasoner:
+ """
+ Datalog reasoning engine supporting recursive rule evaluation via semi-naive
+ bottom-up fixpoint computation.
+ """
+
+ def __init__(self, config: Optional[Dict[str, Any]] = None, **kwargs):
+ self.logger = get_logger("datalog_reasoner")
+ self.config = config or {}
+ self.config.update(kwargs)
+
+ self.progress_tracker = get_progress_tracker()
+ if not self.progress_tracker.enabled:
+ self.progress_tracker.enabled = True
+
+ self._fact_index: Dict[str, Set[DatalogFact]] = defaultdict(set)
+ self._all_facts: Set[DatalogFact] = set()
+
+ self._rules: List[DatalogRule] = []
+
+ self._delta_old: Set[DatalogFact] = set()
+ self._delta_new: Set[DatalogFact] = set()
+
+ def clear(self) -> None:
+ """Clear all facts and rules from the engine."""
+ self._fact_index.clear()
+ self._all_facts.clear()
+ self._rules.clear()
+ self._delta_old.clear()
+ self._delta_new.clear()
+
+ def add_fact(self, fact: Any) -> None:
+ """
+ Add a ground fact to the engine.
+ Accepts strings like "parent(tom, bob)" or standard Semantica Dicts.
+ """
+ parsed_fact = None
+
+ if isinstance(fact, str):
+ parsed_fact = self._parse_fact_string(fact)
+ elif isinstance(fact, dict):
+ if "subject" in fact and "predicate" in fact and "object" in fact:
+ parsed_fact = DatalogFact(
+ predicate=str(fact["predicate"]),
+ args=(str(fact["subject"]), str(fact["object"]))
+ )
+ elif "source_id" in fact or "source_name" in fact:
+ source = fact.get("source_name", fact.get("source_id"))
+ target = fact.get("target_name", fact.get("target_id"))
+ rtype = fact.get("type", "relationship")
+ parsed_fact = DatalogFact(
+ predicate=rtype,
+ args=(str(source), str(target))
+ )
+ elif "type" in fact and ("name" in fact or "id" in fact):
+ name = fact.get("name", fact.get("id"))
+ etype = fact.get("type", "Entity")
+ parsed_fact = DatalogFact(
+ predicate=etype,
+ args=(str(name),)
+ )
+
+ if parsed_fact and parsed_fact not in self._all_facts:
+ self._all_facts.add(parsed_fact)
+ self._fact_index[parsed_fact.predicate].add(parsed_fact)
+
+ def add_rule(self, rule_str: str) -> None:
+ """ Add a Datalog rule using Horn clause syntax."""
+ rule = self._parse_rule_string(rule_str)
+ self._rules.append(rule)
+
+ # Parsing helpers
+
+ def _parse_fact_string(self, s: str) -> DatalogFact:
+ """Parse 'predicate(arg1, arg2)' into a DatalogFact."""
+ match = re.match(r'^\s*([a-zA-Z0-9_]+)\s*\(\s*([^)]+)\s*\)\s*\.?\s*$', s.strip())
+ if not match:
+ raise ValueError(f"Invalid fact syntax: {s}")
+
+ predicate = match.group(1)
+ args_str = match.group(2)
+ args = tuple(arg.strip() for arg in args_str.split(','))
+
+ for arg in args:
+ if arg[0].isupper():
+ raise ValueError(f"Facts must be constants only (no variables). Found variable '{arg}' in {s}")
+
+ return DatalogFact(predicate, args)
+
+ def _parse_rule_string(self, s: str) -> DatalogRule:
+ """Parse 'head(X, Y) :- body1(X, Z), body2(Z, Y).' into a DatalogRule."""
+ s = s.strip()
+ if ":-" not in s:
+ raise ValueError(f"Invalid rule syntax (missing ':-'): {s}")
+
+ head_str, body_str = s.split(":-", 1)
+ head_str = head_str.strip()
+ body_str = body_str.strip().rstrip('.')
+
+ # Parse head
+ head_match = re.match(r'^([a-zA-Z0-9_]+)\s*\(\s*([^)]+)\s*\)$', head_str)
+ if not head_match:
+ raise ValueError(f"Invalid rule head syntax: {head_str}")
+
+ head_pred = head_match.group(1)
+ head_args = tuple(arg.strip() for arg in head_match.group(2).split(','))
+
+ # Parse body atoms
+ body = []
+ atom_matches = re.findall(r'([a-zA-Z0-9_]+)\s*\(\s*([^)]+)\s*\)', body_str)
+ if not atom_matches:
+ raise ValueError(f"No valid body atoms found in rule: {s}")
+
+ for pred, args_str in atom_matches:
+ args = tuple(arg.strip() for arg in args_str.split(','))
+ body.append(BodyAtom(pred, args))
+
+ return DatalogRule(head_pred, head_args, body)
+
+ # Unification & Instantiation
+
+
+ def _is_variable(self, term: str) -> bool:
+ """Variables strictly start with an uppercase letter."""
+ return bool(term and term[0].isupper())
+
+ def _unify(
+ self,
+ pattern_args: Tuple[str, ...],
+ fact_args: Tuple[str, ...],
+ bindings: Dict[str, str]
+ ) -> Optional[Dict[str, str]]:
+ """
+ Unifies a rule atom's pattern with a concrete fact.
+ Optimized to prevent unnecessary dictionary allocations.
+ """
+ if len(pattern_args) != len(fact_args):
+ return None
+
+ new_additions = {}
+
+ for p_arg, f_arg in zip(pattern_args, fact_args):
+ if self._is_variable(p_arg):
+ if p_arg in bindings:
+ if bindings[p_arg] != f_arg:
+ return None
+ elif p_arg in new_additions:
+ if new_additions[p_arg] != f_arg:
+ return None
+ else:
+ new_additions[p_arg] = f_arg
+ else:
+ if p_arg != f_arg:
+ return None
+
+ if new_additions:
+ return {**bindings, **new_additions}
+ return bindings
+
+ def _instantiate(self, args: Tuple[str, ...], bindings: Dict[str, str]) -> Optional[Tuple[str, ...]]:
+ """Replaces variables in a tuple with their bound values."""
+ result = []
+ for arg in args:
+ if self._is_variable(arg):
+ if arg not in bindings:
+ return None
+ result.append(bindings[arg])
+ else:
+ result.append(arg)
+
+ return tuple(result)
+
+ def _instantiate_fact(
+ self, predicate: str, args: Tuple[str, ...], bindings: Dict[str, str]
+ ) -> Optional[DatalogFact]:
+ """Creates a concrete DatalogFact from a predicate, arguments, and bindings."""
+ ground_args = self._instantiate(args, bindings)
+ if ground_args is None:
+ return None
+ return DatalogFact(predicate, ground_args)
+
+ # Semi-Naive Fixpoint Evaluation
+
+
+ def derive_all(self) -> List[str]:
+ """
+ Executes bottom-up semi-naive evaluation until fixpoint is reached.
+ Returns a list of all derived facts as strings.
+ """
+ tracking_id = self.progress_tracker.start_tracking(
+ module="reasoning",
+ submodule="DatalogReasoner",
+ message="Starting semi-naive fixpoint evaluation"
+ )
+
+ iteration = 0
+ newly_derived_count = 0
+
+ self._delta_new = self._all_facts.copy()
+
+ while self._delta_new:
+ iteration += 1
+
+ # Shift deltas
+ self._delta_old = self._delta_new
+ self._delta_new = set()
+
+ delta_index = defaultdict(set)
+ for f in self._delta_old:
+ delta_index[f.predicate].add(f)
+
+ for rule in self._rules:
+ new_facts = self._apply_rule_seminaive(rule, delta_index)
+
+ for fact in new_facts:
+ if fact not in self._all_facts:
+ self._delta_new.add(fact)
+ self._all_facts.add(fact)
+ self._fact_index[fact.predicate].add(fact)
+ newly_derived_count += 1
+
+ self.logger.debug(f"Datalog Iteration {iteration}: derived {len(self._delta_new)} new facts")
+
+ self.progress_tracker.stop_tracking(
+ tracking_id,
+ status="completed",
+ message=f"Fixpoint reached in {iteration} iterations. {newly_derived_count} new facts derived."
+ )
+
+ return [f"{f.predicate}({', '.join(f.args)})" for f in self._all_facts]
+
+ def _apply_rule_seminaive(
+ self, rule: DatalogRule, delta_index: Dict[str, Set[DatalogFact]]
+ ) -> Set[DatalogFact]:
+ """
+ Evaluates a single rule using semi-naive strategy.
+ """
+ results = set()
+
+ if not rule.body:
+ fact = self._instantiate_fact(rule.head_predicate, rule.head_args, {})
+ if fact:
+ results.add(fact)
+ return results
+
+ # Evaluate the rule N times, binding the i-th atom strictly to delta_old facts
+ for delta_index_pos in range(len(rule.body)):
+ bindings_list = [{}]
+
+ for i, atom in enumerate(rule.body):
+ new_bindings_list = []
+
+ if i == delta_index_pos:
+ candidate_facts = delta_index.get(atom.predicate, set())
+ else:
+ candidate_facts = self._fact_index.get(atom.predicate, set())
+
+ for bindings in bindings_list:
+ for fact in candidate_facts:
+ merged_bindings = self._unify(atom.args, fact.args, bindings)
+ if merged_bindings is not None:
+ new_bindings_list.append(merged_bindings)
+
+ bindings_list = new_bindings_list
+ if not bindings_list:
+ break
+
+ for final_bindings in bindings_list:
+ head_fact = self._instantiate_fact(rule.head_predicate, rule.head_args, final_bindings)
+ if head_fact:
+ results.add(head_fact)
+
+ return results
+
+
+ # Query & ContextGraph Integration
+
+
+ def query(self, pattern: str, bindings: dict = None) -> List[dict]:
+ """
+ Queries the derived fact set. Automatically runs derive_all() if rules exist.
+ Syntax: "ancestor(tom, ?Y)"
+ Returns: [{"Y": "bob"}, {"Y": "ann"}]
+ """
+ if self._rules:
+ self.derive_all()
+
+ match = re.match(r'^\s*([a-zA-Z0-9_]+)\s*\(\s*([^)]+)\s*\)\s*\.?\s*$', pattern.strip())
+ if not match:
+ raise ValueError(f"Invalid query syntax: {pattern}")
+
+ pred = match.group(1)
+ raw_args = tuple(arg.strip() for arg in match.group(2).split(','))
+
+ query_vars = {}
+ pattern_args = []
+
+ for i, arg in enumerate(raw_args):
+ if arg.startswith('?'):
+ var_name = arg[1:]
+ query_vars[i] = var_name
+ pattern_args.append(var_name)
+ elif self._is_variable(arg):
+ query_vars[i] = arg
+ pattern_args.append(arg)
+ else:
+ pattern_args.append(arg)
+
+ initial_bindings = bindings or {}
+ for i, arg in enumerate(pattern_args):
+ if self._is_variable(arg) and arg in initial_bindings:
+ pattern_args[i] = initial_bindings[arg]
+
+ results = []
+ candidates = self._fact_index.get(pred, set())
+
+ for fact in candidates:
+ match_bindings = self._unify(tuple(pattern_args), fact.args, {})
+ if match_bindings is not None:
+ result_row = {}
+ for idx, var_name in query_vars.items():
+ if var_name in match_bindings:
+ result_row[var_name] = match_bindings[var_name]
+ elif var_name in initial_bindings:
+ result_row[var_name] = initial_bindings[var_name]
+
+ if result_row and result_row not in results:
+ results.append(result_row)
+
+ return results
+
+ def load_from_graph(self, graph: Any) -> int:
+ """
+ Loads a ContextGraph into Datalog facts.
+ Edges become binary facts, nodes become unary facts.
+ """
+ facts_added = 0
+
+ if hasattr(graph, 'edges'):
+ edges = graph.edges() if callable(graph.edges) else graph.edges
+ for edge in edges:
+ if isinstance(edge, dict):
+ source = edge.get('source_id', edge.get('source'))
+ target = edge.get('target_id', edge.get('target'))
+ rel_type = edge.get('type', edge.get('relation', 'connected_to'))
+ else:
+ source = getattr(edge, 'source_id', getattr(edge, 'source', None))
+ target = getattr(edge, 'target_id', getattr(edge, 'target', None))
+ rel_type = getattr(edge, 'type', getattr(edge, 'relation', 'connected_to'))
+
+ if source and target:
+ s_clean = str(source).replace(' ', '_').lower()
+ t_clean = str(target).replace(' ', '_').lower()
+ pred_clean = str(rel_type).replace(' ', '_').lower()
+
+ fact = DatalogFact(pred_clean, (s_clean, t_clean))
+ if fact not in self._all_facts:
+ self._all_facts.add(fact)
+ self._fact_index[pred_clean].add(fact)
+ facts_added += 1
+
+ if hasattr(graph, 'nodes'):
+ nodes = graph.nodes() if callable(graph.nodes) else graph.nodes
+ for node in nodes:
+ if isinstance(node, dict):
+ node_id = node.get('id', node.get('name'))
+ node_type = node.get('type', 'entity')
+ else:
+ node_id = getattr(node, 'id', getattr(node, 'name', None))
+ node_type = getattr(node, 'type', 'entity')
+
+ if node_id:
+ n_clean = str(node_id).replace(' ', '_').lower()
+ t_clean = str(node_type).replace(' ', '_').lower()
+
+ fact = DatalogFact(t_clean, (n_clean,))
+ if fact not in self._all_facts:
+ self._all_facts.add(fact)
+ self._fact_index[t_clean].add(fact)
+ facts_added += 1
+
+ self.logger.info(f"Loaded {facts_added} facts from ContextGraph.")
+ return facts_added
\ No newline at end of file
diff --git a/tests/reasoning/test_datalog_reasoner.py b/tests/reasoning/test_datalog_reasoner.py
new file mode 100644
index 00000000..c7cb3cba
--- /dev/null
+++ b/tests/reasoning/test_datalog_reasoner.py
@@ -0,0 +1,186 @@
+"""
+Test suite for the DatalogReasoner module.
+"""
+
+import pytest
+from typing import List, Dict, Any
+
+from semantica.reasoning.datalog_reasoner import DatalogReasoner, DatalogFact
+
+# fixtures and mocks
+
+def reasoner():
+ """Provides a fresh DatalogReasoner instance for each test."""
+ return DatalogReasoner()
+
+class MockContextGraph:
+ """A simple mock to simulate Semantica's ContextGraph for testing."""
+ def __init__(self, nodes: List[Dict[str, Any]], edges: List[Dict[str, Any]]):
+ self._nodes = nodes
+ self._edges = edges
+
+ def nodes(self):
+ return self._nodes
+
+ def edges(self):
+ return self._edges
+
+# Test suite
+
+class TestBasicFacts:
+ def test_add_string_fact(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ assert len(reasoner._all_facts) == 1
+ fact = list(reasoner._all_facts)[0]
+ assert fact.predicate == "parent"
+ assert fact.args == ("tom", "bob")
+
+ def test_add_dict_fact(self, reasoner):
+ reasoner.add_fact({"subject": "bob", "predicate": "parent", "object": "ann"})
+ assert len(reasoner._all_facts) == 1
+ fact = list(reasoner._all_facts)[0]
+ assert fact.predicate == "parent"
+ assert fact.args == ("bob", "ann")
+
+ def test_duplicate_fact_ignored(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ reasoner.add_fact("parent(tom, bob)")
+ assert len(reasoner._all_facts) == 1
+
+
+class TestRules:
+ def test_single_rule(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ reasoner.add_rule("ancestor(X, Y) :- parent(X, Y).")
+
+ derived = reasoner.derive_all()
+ assert "ancestor(tom, bob)" in derived
+
+ def test_recursive_ancestor(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ reasoner.add_fact("parent(bob, ann)")
+
+ reasoner.add_rule("ancestor(X, Y) :- parent(X, Y).")
+ reasoner.add_rule("ancestor(X, Y) :- parent(X, Z), ancestor(Z, Y).")
+
+ derived = reasoner.derive_all()
+ assert "ancestor(tom, bob)" in derived
+ assert "ancestor(bob, ann)" in derived
+ assert "ancestor(tom, ann)" in derived
+
+ def test_multi_hop_three_levels(self, reasoner):
+ reasoner.add_fact("edge(1, 2)")
+ reasoner.add_fact("edge(2, 3)")
+ reasoner.add_fact("edge(3, 4)")
+
+ reasoner.add_rule("reachable(X, Y) :- edge(X, Y).")
+ reasoner.add_rule("reachable(X, Y) :- edge(X, Z), reachable(Z, Y).")
+
+ derived = reasoner.derive_all()
+ assert "reachable(1, 4)" in derived
+
+ def test_two_body_atoms(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ reasoner.add_fact("parent(bob, ann)")
+
+
+ reasoner.add_rule("grandparent(X, Y) :- parent(X, Z), parent(Z, Y).")
+
+ derived = reasoner.derive_all()
+ assert "grandparent(tom, ann)" in derived
+ assert "grandparent(tom, bob)" not in derived
+
+
+class TestQuery:
+ def test_variable_binding(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ reasoner.add_fact("parent(tom, alex)")
+ reasoner.add_rule("ancestor(X, Y) :- parent(X, Y).")
+
+ results = reasoner.query("ancestor(tom, ?Y)")
+ y_bindings = sorted([res["Y"] for res in results])
+ assert y_bindings == ["alex", "bob"]
+
+ def test_pre_bound_variable(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ reasoner.add_rule("ancestor(X, Y) :- parent(X, Y).")
+
+
+ results_bob = reasoner.query("ancestor(tom, ?Y)", bindings={"Y": "bob"})
+ assert len(results_bob) == 1
+ assert results_bob[0]["Y"] == "bob"
+
+ results_ann = reasoner.query("ancestor(tom, ?Y)", bindings={"Y": "ann"})
+ assert len(results_ann) == 0
+
+ def test_no_match_returns_empty(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ results = reasoner.query("parent(sarah, ?Y)")
+ assert results == []
+
+
+class TestContextGraphIntegration:
+ def test_load_from_graph(self, reasoner):
+ graph = MockContextGraph(
+ nodes=[{"id": "microsoft", "type": "company"}],
+ edges=[{"source": "microsoft", "target": "openai", "type": "invested_in"}]
+ )
+
+ added = reasoner.load_from_graph(graph)
+ assert added == 2
+
+ assert DatalogFact("company", ("microsoft",)) in reasoner._all_facts
+ assert DatalogFact("invested_in", ("microsoft", "openai")) in reasoner._all_facts
+
+ def test_edge_becomes_fact(self, reasoner):
+ graph = MockContextGraph(
+ nodes=[],
+ edges=[{"source_id": "a", "target_id": "b", "relation": "connected_to"}]
+ )
+ reasoner.load_from_graph(graph)
+ assert DatalogFact("connected_to", ("a", "b")) in reasoner._all_facts
+
+ def test_derive_after_load(self, reasoner):
+ graph = MockContextGraph(
+ nodes=[],
+ edges=[
+ {"source": "node_a", "target": "node_b", "type": "linked"},
+ {"source": "node_b", "target": "node_c", "type": "linked"}
+ ]
+ )
+ reasoner.load_from_graph(graph)
+ reasoner.add_rule("path(X, Y) :- linked(X, Y).")
+ reasoner.add_rule("path(X, Y) :- linked(X, Z), path(Z, Y).")
+
+ derived = reasoner.derive_all()
+ assert "path(node_a, node_c)" in derived
+
+
+class TestEdgeCases:
+ def test_empty_program(self, reasoner):
+ derived = reasoner.derive_all()
+ assert derived == []
+
+ def test_derive_all_idempotent(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ reasoner.add_rule("ancestor(X, Y) :- parent(X, Y).")
+
+ first_run = len(reasoner.derive_all())
+ second_run = len(reasoner.derive_all())
+
+ assert first_run == second_run
+ assert first_run == 2
+
+ def test_clear_resets_state(self, reasoner):
+ reasoner.add_fact("parent(tom, bob)")
+ reasoner.add_rule("ancestor(X, Y) :- parent(X, Y).")
+ reasoner.derive_all()
+
+ reasoner.clear()
+
+ assert len(reasoner._all_facts) == 0
+ assert len(reasoner._rules) == 0
+ assert len(reasoner._delta_new) == 0
+ assert len(reasoner._delta_old) == 0
+ assert len(reasoner._fact_index) == 0
\ No newline at end of file