Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

Implement temporal point-in-time correctness (#397)

KaifAhmad13c863e860eab
diff --git a/semantica/kg/temporal_query.py b/semantica/kg/temporal_query.py
index d482845a..c49b0e1b 100644
--- a/semantica/kg/temporal_query.py
+++ b/semantica/kg/temporal_query.py
@@ -4,8 +4,10 @@ Temporal Query Module
import copy
import warnings
+from collections import defaultdict
+from dataclasses import asdict, dataclass
from datetime import datetime, timedelta, timezone
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Literal, Optional
from uuid import uuid4
from ..utils.progress_tracker import get_progress_tracker
@@ -22,6 +24,19 @@ from .temporal_model import (
from ..utils.exceptions import ProcessingError, TemporalValidationError
+@dataclass
+class TemporalConsistencyIssue:
+ message: str
+ fact_id: str
+ issue_type: str
+
+
+@dataclass
+class TemporalConsistencyReport:
+ errors: List[Dict[str, str]]
+ warnings: List[Dict[str, str]]
+
+
class TemporalGraphQuery:
"""
Temporal knowledge graph query engine.
@@ -126,16 +141,15 @@ class TemporalGraphQuery:
# Parse time
query_time = self._parse_time(at_time)
-
- # Filter relationships valid at query time
- relationships = []
- if "relationships" in graph:
- for rel in graph.get("relationships", []):
- if self._relationship_active_at_time(rel, query_time, time_axis=time_axis):
- relationships.append(rel)
+ reconstructed_graph = self.reconstruct_at_time(
+ graph,
+ query_time,
+ time_axis=time_axis,
+ )
# Get entities
- entities = graph.get("entities", [])
+ entities = reconstructed_graph.get("entities", [])
+ relationships = reconstructed_graph.get("relationships", [])
# Include history if requested
if include_history:
@@ -151,6 +165,154 @@ class TemporalGraphQuery:
"num_relationships": len(relationships),
}
+ def reconstruct_at_time(
+ self,
+ graph: Any,
+ at_time: Any,
+ *,
+ time_axis: str = "valid",
+ ) -> Dict[str, Any]:
+ """Return a self-consistent subgraph for a single point in time."""
+ query_time = at_time if isinstance(at_time, datetime) else self._parse_time(at_time)
+ reconstructed = copy.deepcopy(graph)
+ entity_list = graph.get("entities", [])
+
+ if not entity_list:
+ reconstructed["entities"] = []
+ reconstructed["relationships"] = [
+ copy.deepcopy(relationship)
+ for relationship in graph.get("relationships", [])
+ if self._relationship_active_at_time(relationship, query_time, time_axis=time_axis)
+ ]
+ return reconstructed
+
+ entity_index = {
+ self._entity_id(entity): entity
+ for entity in entity_list
+ if self._entity_active_at_time(entity, query_time, time_axis=time_axis)
+ }
+
+ relationships = []
+ for relationship in graph.get("relationships", []):
+ if not self._relationship_active_at_time(relationship, query_time, time_axis=time_axis):
+ continue
+ source = relationship.get("source")
+ target = relationship.get("target")
+ if source not in entity_index or target not in entity_index:
+ continue
+ relationships.append(copy.deepcopy(relationship))
+
+ reconstructed["entities"] = list(entity_index.values())
+ reconstructed["relationships"] = relationships
+ return reconstructed
+
+ def validate_temporal_consistency(self, graph: Any) -> TemporalConsistencyReport:
+ errors: List[Dict[str, str]] = []
+ warnings_list: List[Dict[str, str]] = []
+
+ entities = {
+ self._entity_id(entity): entity
+ for entity in graph.get("entities", [])
+ }
+ rel_groups: Dict[tuple[str, str, str], List[Dict[str, Any]]] = defaultdict(list)
+
+ for relationship in graph.get("relationships", []):
+ rel_id = relationship.get("id") or self._relationship_key(relationship)
+ rel_groups[
+ (
+ relationship.get("source", ""),
+ relationship.get("type", relationship.get("relationship", "")),
+ relationship.get("target", ""),
+ )
+ ].append(relationship)
+
+ start, end = self._get_axis_bounds(relationship, "valid")
+ if start and isinstance(end, datetime) and self._compare_times(start, end) > 0:
+ errors.append(
+ asdict(
+ TemporalConsistencyIssue(
+ message="Relationship has an inverted validity interval.",
+ fact_id=rel_id,
+ issue_type="inverted_interval",
+ )
+ )
+ )
+
+ for endpoint in ("source", "target"):
+ entity = entities.get(relationship.get(endpoint))
+ if entity is None:
+ errors.append(
+ asdict(
+ TemporalConsistencyIssue(
+ message=f"Relationship references missing {endpoint} entity.",
+ fact_id=rel_id,
+ issue_type=f"missing_{endpoint}_entity",
+ )
+ )
+ )
+ continue
+ if not self._window_within_entity_lifetime(entity, start, end):
+ errors.append(
+ asdict(
+ TemporalConsistencyIssue(
+ message=f"Relationship validity falls outside {endpoint} entity lifetime.",
+ fact_id=rel_id,
+ issue_type=f"{endpoint}_lifetime_mismatch",
+ )
+ )
+ )
+ for relationships in rel_groups.values():
+ ordered = sorted(
+ relationships,
+ key=lambda rel: self._sort_key(self._get_axis_bounds(rel, "valid")[0]),
+ )
+ for index, current in enumerate(ordered):
+ current_id = current.get("id") or self._relationship_key(current)
+ current_start, current_end = self._get_axis_bounds(current, "valid")
+ if index > 0:
+ previous_start, previous_end = self._get_axis_bounds(ordered[index - 1], "valid")
+ if self._range_overlaps_bounds(
+ current_start or datetime.min.replace(tzinfo=timezone.utc),
+ current_end if isinstance(current_end, datetime) else datetime.max.replace(tzinfo=timezone.utc),
+ previous_start,
+ previous_end,
+ ):
+ warnings_list.append(
+ asdict(
+ TemporalConsistencyIssue(
+ message="Relationship overlaps another relationship with the same edge and type.",
+ fact_id=current_id,
+ issue_type="overlapping_same_edge",
+ )
+ )
+ )
+ elif (
+ isinstance(previous_end, datetime)
+ and current_start
+ and self._compare_times(current_start, previous_end) > 0
+ ):
+ warnings_list.append(
+ asdict(
+ TemporalConsistencyIssue(
+ message="Relationship restarts after a temporal gap.",
+ fact_id=current_id,
+ issue_type="gap_after_restart",
+ )
+ )
+ )
+ elif current_start and previous_start and self._compare_times(current_start, previous_start) == 0:
+ warnings_list.append(
+ asdict(
+ TemporalConsistencyIssue(
+ message="Relationship interval overlaps another interval on the same edge.",
+ fact_id=current_id,
+ issue_type="overlapping_same_edge",
+ )
+ )
+ )
+
+ return TemporalConsistencyReport(errors=errors, warnings=warnings_list)
+
def query_time_range(
self,
graph: Any,
@@ -390,6 +552,8 @@ class TemporalGraphQuery:
end_time: Optional[Any] = None,
max_path_length: Optional[int] = None,
temporal_constraints: Optional[Dict[str, Any]] = None,
+ enforce_causal_ordering: bool = True,
+ ordering_strategy: Literal["strict", "overlap", "loose"] = "strict",
**options,
) -> Dict[str, Any]:
"""
@@ -477,7 +641,13 @@ class TemporalGraphQuery:
for neighbor, rel in adjacency.get(node, []):
if neighbor not in path: # Avoid cycles
- queue.append((neighbor, path + [neighbor], edges + [rel]))
+ next_edges = edges + [rel]
+ if self._path_respects_causal_order(
+ next_edges,
+ enforce_causal_ordering=enforce_causal_ordering,
+ ordering_strategy=ordering_strategy,
+ ):
+ queue.append((neighbor, path + [neighbor], next_edges))
return {
"source": source,
@@ -578,10 +748,118 @@ class TemporalGraphQuery:
for axis in axes
)
+ def _entity_id(self, entity: Dict[str, Any]) -> str:
+ return str(entity.get("id", entity.get("name", "")))
+
+ def _entity_active_at_time(self, entity: Dict[str, Any], query_time: datetime, *, time_axis: str) -> bool:
+ relationship_like = {
+ "valid_from": entity.get("valid_from"),
+ "valid_until": entity.get("valid_until", TemporalBound.OPEN),
+ "recorded_at": entity.get("recorded_at", entity.get("valid_from")),
+ "superseded_at": entity.get("superseded_at", TemporalBound.OPEN),
+ }
+ return self._relationship_active_at_time(relationship_like, query_time, time_axis=time_axis)
+
+ def _window_within_entity_lifetime(
+ self,
+ entity: Dict[str, Any],
+ rel_start: Optional[datetime],
+ rel_end: Optional[datetime | TemporalBound],
+ ) -> bool:
+ entity_start = self._parse_time(entity.get("valid_from")) if entity.get("valid_from") is not None else None
+ entity_end = parse_temporal_bound(entity.get("valid_until"), default=TemporalBound.OPEN)
+ if rel_start and entity_start and self._compare_times(rel_start, entity_start) < 0:
+ return False
+ if isinstance(entity_end, datetime):
+ if rel_start and self._compare_times(rel_start, entity_end) > 0:
+ return False
+ if isinstance(rel_end, datetime) and self._compare_times(rel_end, entity_end) > 0:
+ return False
+ if rel_end is TemporalBound.OPEN:
+ return False
+ return True
+
+ def _sort_key(self, value: Optional[datetime]) -> datetime:
+ return value or datetime.min.replace(tzinfo=timezone.utc)
+
+ def _period_floor(self, value: datetime) -> datetime:
+ if self.temporal_granularity == "week":
+ return (value - timedelta(days=value.weekday())).replace(hour=0, minute=0, second=0, microsecond=0)
+ if self.temporal_granularity == "month":
+ return value.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+ if self.temporal_granularity == "year":
+ return value.replace(month=1, day=1, hour=0, minute=0, second=0, microsecond=0)
+ return self._truncate_to_granularity(value)
+
+ def _next_period(self, value: datetime) -> datetime:
+ if self.temporal_granularity == "day":
+ return value + timedelta(days=1)
+ if self.temporal_granularity == "week":
+ return value + timedelta(weeks=1)
+ if self.temporal_granularity == "month":
+ if value.month == 12:
+ return value.replace(year=value.year + 1, month=1)
+ return value.replace(month=value.month + 1)
+ if self.temporal_granularity == "year":
+ return value.replace(year=value.year + 1)
+ return value + timedelta(days=1)
+
+ def _period_label(self, value: datetime) -> str:
+ if self.temporal_granularity == "week":
+ return f"{value.isocalendar().year}-W{value.isocalendar().week:02d}"
+ if self.temporal_granularity == "month":
+ return value.strftime("%Y-%m")
+ if self.temporal_granularity == "year":
+ return value.strftime("%Y")
+ return value.strftime("%Y-%m-%d")
+
+ def _path_respects_causal_order(
+ self,
+ edges: List[Dict[str, Any]],
+ *,
+ enforce_causal_ordering: bool,
+ ordering_strategy: Literal["strict", "overlap", "loose"],
+ ) -> bool:
+ if not enforce_causal_ordering or ordering_strategy == "loose" or len(edges) < 2:
+ return True
+
+ previous = edges[-2]
+ current = edges[-1]
+ previous_start, previous_end = self._get_axis_bounds(previous, "valid")
+ current_start, _ = self._get_axis_bounds(current, "valid")
+
+ if ordering_strategy == "strict":
+ if previous_start and current_start and self._compare_times(current_start, previous_start) < 0:
+ return False
+ return True
+ if ordering_strategy == "overlap":
+ if current_start is None:
+ return True
+ if isinstance(previous_end, datetime):
+ return self._compare_times(current_start, previous_end) <= 0
+ return True
+ return True
+
def _group_by_time_periods(self, relationships, start, end):
- """Group relationships by time periods."""
- # Simplified grouping
- return relationships
+ """Group relationships into calendar-aligned buckets."""
+ buckets: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
+ current = self._period_floor(start)
+ end_bound = self._period_floor(end)
+
+ while current <= end_bound:
+ bucket_end = self._next_period(current)
+ label = self._period_label(current)
+ for relationship in relationships:
+ if self._relationship_overlaps_range(
+ relationship,
+ current,
+ bucket_end,
+ time_axis="valid",
+ ):
+ buckets[label].append(relationship)
+ current = bucket_end
+
+ return dict(buckets)
class TemporalPatternDetector:
@@ -650,6 +928,8 @@ class TemporalPatternDetector:
list: List of detected pattern dictionaries
"""
self.logger.info(f"Detecting temporal patterns: {pattern_type}")
+ if "gap_tolerance" in options:
+ self.config["gap_tolerance"] = options["gap_tolerance"]
relationships = graph.get("relationships", [])
@@ -669,13 +949,137 @@ class TemporalPatternDetector:
def _find_sequences(self, relationships, min_frequency):
"""Find sequential patterns."""
- # Simplified sequence detection
- return []
+ gap_tolerance = self._resolve_gap_tolerance()
+ outgoing: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
+ for relationship in relationships:
+ outgoing[relationship.get("source")].append(relationship)
+
+ occurrences = defaultdict(list)
+ for relationship in relationships:
+ sequence = [relationship]
+ current = relationship
+ while True:
+ next_candidates = []
+ _, current_end = self._get_axis_bounds(current)
+ for candidate in outgoing.get(current.get("target"), []):
+ if candidate is current:
+ continue
+ candidate_start, _ = self._get_axis_bounds(candidate)
+ if current_end is None or candidate_start is None:
+ continue
+ gap = candidate_start - current_end
+ if gap < timedelta(0) or gap > gap_tolerance:
+ continue
+ next_candidates.append((candidate_start, candidate))
+ if not next_candidates:
+ break
+ next_candidates.sort(key=lambda item: item[0])
+ current = next_candidates[0][1]
+ sequence.append(current)
+
+ if len(sequence) < 2:
+ continue
+
+ signature = tuple(
+ [sequence[0].get("source")] + [edge.get("target") for edge in sequence]
+ )
+ occurrences[signature].append(
+ {
+ "nodes": list(signature),
+ "edges": [copy.deepcopy(edge) for edge in sequence],
+ "start_time": serialize_temporal_value(self._get_axis_bounds(sequence[0])[0]),
+ "end_time": serialize_temporal_value(self._sequence_end(sequence)),
+ }
+ )
+
+ return [
+ {
+ "pattern_type": "sequence",
+ "signature": signature,
+ "frequency": len(items),
+ "occurrences": items,
+ }
+ for signature, items in occurrences.items()
+ if len(items) >= min_frequency
+ ]
def _find_cycles(self, relationships, min_frequency):
"""Find cyclic patterns."""
- # Simplified cycle detection
- return []
+ outgoing: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
+ for relationship in relationships:
+ outgoing[relationship.get("source")].append(relationship)
+
+ occurrences = defaultdict(list)
+ for relationship in relationships:
+ start_node = relationship.get("source")
+ path_edges = [relationship]
+ visited_nodes = [start_node, relationship.get("target")]
+ current = relationship
+
+ while len(path_edges) <= 6:
+ if visited_nodes[-1] == start_node:
+ signature = tuple(visited_nodes)
+ occurrences[signature].append(
+ {
+ "nodes": visited_nodes[:],
+ "edges": [copy.deepcopy(edge) for edge in path_edges],
+ "start_time": serialize_temporal_value(self._get_axis_bounds(path_edges[0])[0]),
+ "end_time": serialize_temporal_value(self._sequence_end(path_edges)),
+ }
+ )
+ break
+
+ next_candidates = []
+ _, current_end = self._get_axis_bounds(current)
+ for candidate in outgoing.get(visited_nodes[-1], []):
+ candidate_start, _ = self._get_axis_bounds(candidate)
+ if current_end and candidate_start and self._compare_times(candidate_start, current_end) < 0:
+ continue
+ next_candidates.append((self._sort_key(candidate_start), candidate))
+ if not next_candidates:
+ break
+ next_candidates.sort(key=lambda item: item[0])
+ current = next_candidates[0][1]
+ next_target = current.get("target")
+ if next_target in visited_nodes[1:-1] and next_target != start_node:
+ break
+ path_edges.append(current)
+ visited_nodes.append(next_target)
+
+ return [
+ {
+ "pattern_type": "cycle",
+ "signature": signature,
+ "frequency": len(items),
+ "occurrences": items,
+ }
+ for signature, items in occurrences.items()
+ if len(items) >= min_frequency
+ ]
+
+ def _resolve_gap_tolerance(self) -> timedelta:
+ gap_tolerance = self.config.get("gap_tolerance", timedelta(days=0))
+ if isinstance(gap_tolerance, timedelta):
+ return gap_tolerance
+ if isinstance(gap_tolerance, (int, float)):
+ return timedelta(days=gap_tolerance)
+ return timedelta(days=0)
+
+ def _sequence_end(self, edges: List[Dict[str, Any]]) -> Optional[datetime]:
+ last_start, last_end = self._get_axis_bounds(edges[-1])
+ if isinstance(last_end, datetime):
+ return last_end
+ return last_start
+
+ def _get_axis_bounds(self, relationship: Dict[str, Any]) -> tuple[Optional[datetime], Optional[datetime | TemporalBound]]:
+ normalized = deserialize_relationship_temporal_fields(relationship)
+ fact = BiTemporalFact.from_relationship(normalized)
+ return fact.valid_from, fact.valid_until
+
+ def _compare_times(self, time1: Optional[datetime], time2: Optional[datetime]) -> int:
+ if time1 is None or time2 is None:
+ return 0
+ return (time1 > time2) - (time1 < time2)
class TemporalVersionManager:
diff --git a/tests/kg/test_kg.py b/tests/kg/test_kg.py
index db8fb5cc..11c968a0 100644
--- a/tests/kg/test_kg.py
+++ b/tests/kg/test_kg.py
@@ -11,6 +11,7 @@ sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../.
from semantica.kg.graph_builder import GraphBuilder
from semantica.kg.graph_analyzer import GraphAnalyzer
from semantica.kg.temporal_model import TemporalBound, deserialize_relationship_temporal_fields
+from semantica.kg.temporal_query import TemporalConsistencyReport
from semantica.utils.exceptions import TemporalValidationError
class TestGraphBuilder(unittest.TestCase):
@@ -431,5 +432,166 @@ class TestTemporalGraphQuery(unittest.TestCase):
)
self.assertIs(relationship["valid_until"], TemporalBound.OPEN)
+ def test_reconstruct_at_time_removes_dangling_edges_and_does_not_mutate_input(self):
+ graph = {
+ "entities": [
+ {"id": "1", "valid_from": "2020-01-01", "valid_until": "2023-01-01"},
+ {"id": "2", "valid_from": "2020-01-01", "valid_until": TemporalBound.OPEN},
+ {"id": "3", "valid_from": "2025-01-01", "valid_until": TemporalBound.OPEN},
+ ],
+ "relationships": [
+ {"id": "r1", "source": "1", "target": "2", "type": "rel", "valid_from": "2022-01-01", "valid_until": TemporalBound.OPEN},
+ {"id": "r2", "source": "2", "target": "3", "type": "rel", "valid_from": "2024-01-01", "valid_until": TemporalBound.OPEN},
+ ],
+ }
+ original = {
+ "entities": [dict(entity) for entity in graph["entities"]],
+ "relationships": [dict(rel) for rel in graph["relationships"]],
+ }
+
+ reconstructed = self.query_engine.reconstruct_at_time(graph, "2024-06-01")
+
+ self.assertEqual([entity["id"] for entity in reconstructed["entities"]], ["2"])
+ self.assertEqual(reconstructed["relationships"], [])
+ self.assertEqual(graph, original)
+
+ def test_query_at_time_uses_self_consistent_reconstruction(self):
+ graph = {
+ "entities": [
+ {"id": "1", "valid_from": "2020-01-01", "valid_until": "2023-01-01"},
+ {"id": "2", "valid_from": "2020-01-01", "valid_until": TemporalBound.OPEN},
+ ],
+ "relationships": [
+ {"source": "1", "target": "2", "type": "rel", "valid_from": "2022-01-01", "valid_until": TemporalBound.OPEN},
+ ],
+ }
+
+ result = self.query_engine.query_at_time(graph, "", "2024-06-01")
+
+ self.assertEqual(result["num_entities"], 1)
+ self.assertEqual(result["num_relationships"], 0)
+
+ def test_validate_temporal_consistency_reports_errors_and_warnings(self):
+ graph = {
+ "entities": [
+ {"id": "A", "valid_from": "2020-01-01", "valid_until": TemporalBound.OPEN},
+ {"id": "B", "valid_from": "2020-01-01", "valid_until": "2022-01-01"},
+ ],
+ "relationships": [
+ {"id": "bad-range", "source": "A", "target": "B", "type": "rel", "valid_from": "2023-01-01", "valid_until": "2022-01-01"},
+ {"id": "outside-life", "source": "A", "target": "B", "type": "rel", "valid_from": "2021-06-01", "valid_until": "2023-06-01"},
+ {"id": "gap-1", "source": "A", "target": "B", "type": "same", "valid_from": "2020-01-01", "valid_until": "2020-06-01"},
+ {"id": "gap-2", "source": "A", "target": "B", "type": "same", "valid_from": "2020-07-01", "valid_until": "2020-12-01"},
+ {"id": "overlap-1", "source": "A", "target": "B", "type": "dup", "valid_from": "2021-01-01", "valid_until": "2021-06-01"},
+ {"id": "overlap-2", "source": "A", "target": "B", "type": "dup", "valid_from": "2021-05-01", "valid_until": "2021-08-01"},
+ ],
+ }
+
+ report = self.query_engine.validate_temporal_consistency(graph)
+
+ self.assertIsInstance(report, TemporalConsistencyReport)
+ self.assertTrue(any(issue["fact_id"] == "bad-range" for issue in report.errors))
+ self.assertTrue(any(issue["fact_id"] == "outside-life" for issue in report.errors))
+ self.assertTrue(any(issue["fact_id"] == "gap-2" for issue in report.warnings))
+ self.assertTrue(any(issue["fact_id"] == "overlap-2" for issue in report.warnings))
+
+ def test_validate_temporal_consistency_clean_graph(self):
+ graph = {
+ "entities": [
+ {"id": "A", "valid_from": "2020-01-01", "valid_until": TemporalBound.OPEN},
+ {"id": "B", "valid_from": "2020-01-01", "valid_until": TemporalBound.OPEN},
+ ],
+ "relationships": [
+ {"id": "ok", "source": "A", "target": "B", "type": "rel", "valid_from": "2020-02-01", "valid_until": "2020-05-01"},
+ ],
+ }
+
+ report = self.query_engine.validate_temporal_consistency(graph)
+
+ self.assertEqual(report.errors, [])
+ self.assertEqual(report.warnings, [])
+
+ def test_query_temporal_pattern_sequence_returns_patterns(self):
+ graph = {
+ "relationships": [
+ {"id": "s1", "source": "A", "target": "B", "type": "rel", "valid_from": "2024-01-01", "valid_until": "2024-01-02"},
+ {"id": "s2", "source": "B", "target": "C", "type": "rel", "valid_from": "2024-01-02", "valid_until": "2024-01-03"},
+ ]
+ }
+
+ result = self.query_engine.query_temporal_pattern(graph, "sequence")
+
+ self.assertGreaterEqual(result["num_patterns"], 1)
+ self.assertEqual(result["patterns"][0]["pattern_type"], "sequence")
+
+ def test_query_temporal_pattern_sequence_supports_gap_tolerance(self):
+ query_engine = __import__("semantica.kg.temporal_query", fromlist=["TemporalGraphQuery"]).TemporalGraphQuery(
+ pattern_detection={"gap_tolerance": 1}
+ )
+ graph = {
+ "relationships": [
+ {"id": "s1", "source": "A", "target": "B", "type": "rel", "valid_from": "2024-01-01", "valid_until": "2024-01-02"},
+ {"id": "s2", "source": "B", "target": "C", "type": "rel", "valid_from": "2024-01-03", "valid_until": "2024-01-04"},
+ ]
+ }
+
+ result = query_engine.query_temporal_pattern(graph, "sequence")
+
+ self.assertGreaterEqual(result["num_patterns"], 1)
+
+ def test_query_temporal_pattern_cycle_returns_single_node_cycle(self):
+ graph = {
+ "relationships": [
+ {"id": "c1", "source": "A", "target": "A", "type": "loop", "valid_from": "2024-01-01", "valid_until": "2024-01-02"},
+ ]
+ }
+
+ result = self.query_engine.query_temporal_pattern(graph, "cycle")
+
+ self.assertGreaterEqual(result["num_patterns"], 1)
+ self.assertEqual(result["patterns"][0]["pattern_type"], "cycle")
+
+ def test_query_time_range_evolution_buckets_by_granularity(self):
+ query_engine = __import__("semantica.kg.temporal_query", fromlist=["TemporalGraphQuery"]).TemporalGraphQuery(
+ temporal_granularity="month"
+ )
+ graph = {
+ "relationships": [
+ {"id": "jan", "source": "A", "target": "B", "type": "rel", "valid_from": "2024-01-10", "valid_until": "2024-01-20"},
+ {"id": "feb", "source": "B", "target": "C", "type": "rel", "valid_from": "2024-02-05", "valid_until": "2024-02-10"},
+ ]
+ }
+
+ result = query_engine.query_time_range(
+ graph,
+ "",
+ "2024-01-01",
+ "2024-02-28",
+ temporal_aggregation="evolution",
+ )
+
+ self.assertIsInstance(result["relationships"], dict)
+ self.assertIn("2024-01", result["relationships"])
+ self.assertIn("2024-02", result["relationships"])
+
+ def test_find_temporal_paths_respects_strict_and_loose_causal_ordering(self):
+ graph = {
+ "relationships": [
+ {"source": "A", "target": "B", "type": "ab", "valid_from": "2020-01-01", "valid_until": "2022-01-01"},
+ {"source": "B", "target": "C", "type": "bc", "valid_from": "2019-01-01", "valid_until": "2021-01-01"},
+ ]
+ }
+
+ strict_result = self.query_engine.find_temporal_paths(graph, "A", "C")
+ loose_result = self.query_engine.find_temporal_paths(
+ graph,
+ "A",
+ "C",
+ ordering_strategy="loose",
+ )
+
+ self.assertEqual(strict_result["num_paths"], 0)
+ self.assertEqual(loose_result["num_paths"], 1)
+
if __name__ == "__main__":
unittest.main()