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
Add deterministic temporal reasoning engine
KaifAhmad1c6dc9d87aa44
diff --git a/semantica/kg/__init__.py b/semantica/kg/__init__.pyindex 54f1f373..bcb35622 100644--- a/semantica/kg/__init__.py+++ b/semantica/kg/__init__.py@@ -127,6 +127,7 @@ from .temporal_query import (TemporalVersionManager,)from .temporal_model import BiTemporalFact, TemporalBound+from ..reasoning.temporal_reasoning import IntervalRelation, TemporalInterval, TemporalReasoningEngine__all__ = [# Core Classes@@ -140,6 +141,9 @@ __all__ = ["TemporalVersionManager","TemporalBound","BiTemporalFact",+ "TemporalInterval",+ "IntervalRelation",+ "TemporalReasoningEngine","AlgorithmTrackerWithProvenance","ProvenanceTracker",# Enhanced Graph Algorithmsdiff --git a/semantica/kg/temporal_query.py b/semantica/kg/temporal_query.pyindex e60c010f..f1ba16c6 100644--- a/semantica/kg/temporal_query.py+++ b/semantica/kg/temporal_query.py@@ -21,6 +21,7 @@ from .temporal_model import (serialize_temporal_value,temporal_structure_to_json_ready,)+from ..reasoning.temporal_reasoning import IntervalRelation, TemporalInterval, TemporalReasoningEnginefrom ..utils.exceptions import ProcessingError, TemporalValidationError@@ -101,6 +102,7 @@ class TemporalGraphQuery:self.pattern_detector = TemporalPatternDetector(**kwargs.get("pattern_detection", {}))+ self.reasoning_engine = TemporalReasoningEngine()def query_at_time(self,@@ -395,8 +397,13 @@ class TemporalGraphQuery:self.logger.info(f"Querying graph in time range: {start_time} to {end_time}")# Parse times- start = self._parse_time(start_time)- end = self._parse_time(end_time)+ normalized_range = self.reasoning_engine.normalize_interval(+ start_time,+ end_time,+ self.temporal_granularity,+ )+ start = normalized_range.start+ end = normalized_range.end if isinstance(normalized_range.end, datetime) else None# Filter relationships valid in time rangerelationships = []@@ -701,7 +708,7 @@ class TemporalGraphQuery:def _parse_time(self, time_value):"""Parse time value into a UTC-normalized datetime."""- if time_value in (TemporalBound.OPEN, TemporalBound.OPEN.value):+ if time_value in (None, TemporalBound.OPEN, TemporalBound.OPEN.value):return Nonetry:return parse_temporal_value(time_value)@@ -723,22 +730,7 @@ class TemporalGraphQuery:def _truncate_to_granularity(self, value: datetime) -> datetime:granularity = getattr(self, "temporal_granularity", "second")- if granularity == "second":- return value.replace(microsecond=0)- if granularity == "minute":- return value.replace(second=0, microsecond=0)- if granularity == "hour":- return value.replace(minute=0, second=0, microsecond=0)- if granularity == "day":- return value.replace(hour=0, minute=0, second=0, microsecond=0)- if granularity == "week":- start_of_week = value - timedelta(days=value.weekday())- return start_of_week.replace(hour=0, minute=0, second=0, microsecond=0)- if granularity == "month":- return value.replace(day=1, hour=0, minute=0, second=0, microsecond=0)- if granularity == "year":- return value.replace(month=1, day=1, hour=0, minute=0, second=0, microsecond=0)- return value+ return self.reasoning_engine.normalize_timestamp(value, granularity)def _get_axis_bounds(self, relationship: Dict[str, Any], axis: str):normalized = deserialize_relationship_temporal_fields(relationship)@@ -750,25 +742,39 @@ class TemporalGraphQuery:raise ValueError(f"Unsupported time axis: {axis}")def _is_point_in_bounds(self, point: datetime, start: Optional[datetime], end: Optional[datetime | TemporalBound]) -> bool:- if start and self._compare_times(point, start) < 0:- return False- if isinstance(end, datetime) and self._compare_times(point, end) >= 0:- return False- return True+ if start is None:+ start = datetime.min.replace(tzinfo=timezone.utc)+ return self.reasoning_engine.active_at(+ TemporalInterval(start=start, end=end or TemporalBound.OPEN),+ point,+ )def _range_overlaps_bounds(self, query_start: datetime, query_end: datetime, start: Optional[datetime], end: Optional[datetime | TemporalBound]) -> bool:- if start and self._compare_times(query_end, start) < 0:+ if query_end < query_start:return False- if isinstance(end, datetime) and self._compare_times(query_start, end) > 0:+ if isinstance(end, datetime) and start is not None and end < start:return False- return True+ candidate = TemporalInterval(+ start=start or datetime.min.replace(tzinfo=timezone.utc),+ end=end or TemporalBound.OPEN,+ )+ query_interval = TemporalInterval(start=query_start, end=query_end)+ relation = self.reasoning_engine.relation(candidate, query_interval)+ return relation not in {+ IntervalRelation.BEFORE,+ IntervalRelation.AFTER,+ }def _range_covered_by_bounds(self, query_start: datetime, query_end: datetime, start: Optional[datetime], end: Optional[datetime | TemporalBound]) -> bool:- if start and self._compare_times(start, query_start) > 0:+ if query_end < query_start:return False- if isinstance(end, datetime) and self._compare_times(end, query_end) < 0:+ if isinstance(end, datetime) and start is not None and end < start:return False- return True+ candidate = TemporalInterval(+ start=start or datetime.min.replace(tzinfo=timezone.utc),+ end=end or TemporalBound.OPEN,+ )+ return self.reasoning_engine.contains(candidate, TemporalInterval(start=query_start, end=query_end))def _relationship_active_at_time(self, relationship: Dict[str, Any], query_time: datetime, *, time_axis: str) -> bool:axes = ["valid", "transaction"] if time_axis == "both" else [time_axis]@@ -826,12 +832,6 @@ class TemporalGraphQuery: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:diff --git a/semantica/kg/temporal_reasoning.py b/semantica/kg/temporal_reasoning.pynew file mode 100644index 00000000..90cb2782--- /dev/null+++ b/semantica/kg/temporal_reasoning.py@@ -0,0 +1,9 @@+"""+Backward-compatible import shim for temporal reasoning.++Canonical implementation lives in ``semantica.reasoning.temporal_reasoning``.+"""++from ..reasoning.temporal_reasoning import IntervalRelation, TemporalInterval, TemporalReasoningEngine++__all__ = ["TemporalInterval", "IntervalRelation", "TemporalReasoningEngine"]diff --git a/semantica/reasoning/__init__.py b/semantica/reasoning/__init__.pyindex a72da515..54665576 100644--- a/semantica/reasoning/__init__.py+++ b/semantica/reasoning/__init__.py@@ -27,6 +27,7 @@ from .rete_engine import (from .sparql_reasoner import SPARQLQueryResult, SPARQLReasonerfrom .datalog_reasoner import DatalogReasoner, DatalogFact, DatalogRule+from .temporal_reasoning import IntervalRelation, TemporalInterval, TemporalReasoningEngine__all__ = [# Reasoner facade@@ -50,10 +51,13 @@ __all__ = ["DatalogReasoner","DatalogFact","DatalogRule",+ "TemporalInterval",+ "IntervalRelation",+ "TemporalReasoningEngine",# Explanation"ExplanationGenerator","Explanation","ReasoningStep","ReasoningPath","Justification",-]\ No newline at end of file+]diff --git a/semantica/reasoning/temporal_reasoning.py b/semantica/reasoning/temporal_reasoning.pynew file mode 100644index 00000000..5ab7e1d7--- /dev/null+++ b/semantica/reasoning/temporal_reasoning.py@@ -0,0 +1,326 @@+"""+Deterministic temporal reasoning primitives for Semantica.++This module is the single source of truth for interval math across temporal KG+features. It must remain free of LLM calls: extraction may happen upstream, but+all temporal reasoning here is pure Python and fully deterministic.+"""++from __future__ import annotations++import calendar+from dataclasses import dataclass+from datetime import datetime, timedelta, timezone+from enum import Enum+from typing import Any, Dict, Iterable, List, Optional++from ..kg.temporal_model import BiTemporalFact, TemporalBound, parse_temporal_bound, parse_temporal_value+++@dataclass(frozen=True)+class TemporalInterval:+ start: datetime+ end: datetime | TemporalBound+ label: Optional[str] = None+++class IntervalRelation(Enum):+ BEFORE = "before"+ AFTER = "after"+ MEETS = "meets"+ MET_BY = "met_by"+ OVERLAPS = "overlaps"+ OVERLAPPED_BY = "overlapped_by"+ STARTS = "starts"+ STARTED_BY = "started_by"+ DURING = "during"+ CONTAINS = "contains"+ FINISHES = "finishes"+ FINISHED_BY = "finished_by"+ EQUALS = "equals"+++class TemporalReasoningEngine:+ """Pure-Python temporal reasoning engine with Allen interval algebra."""++ SUPPORTED_GRANULARITIES = {"second", "minute", "hour", "day", "week", "month", "year"}++ def relation(self, a: TemporalInterval, b: TemporalInterval) -> IntervalRelation:+ self._validate_interval(a)+ self._validate_interval(b)++ a_end = self._end_value(a.end)+ b_end = self._end_value(b.end)++ if a_end < b.start:+ return IntervalRelation.BEFORE+ if a.start > b_end:+ return IntervalRelation.AFTER+ if a_end == b.start:+ return IntervalRelation.MEETS+ if a.start == b_end:+ return IntervalRelation.MET_BY+ if a.start == b.start and a_end == b_end:+ return IntervalRelation.EQUALS+ if a.start == b.start and a_end < b_end:+ return IntervalRelation.STARTS+ if a.start == b.start and a_end > b_end:+ return IntervalRelation.STARTED_BY+ if a_end == b_end and a.start > b.start:+ return IntervalRelation.FINISHES+ if a_end == b_end and a.start < b.start:+ return IntervalRelation.FINISHED_BY+ if a.start < b.start and a_end > b.start and a_end < b_end:+ return IntervalRelation.OVERLAPS+ if a.start > b.start and a.start < b_end and a_end > b_end:+ return IntervalRelation.OVERLAPPED_BY+ if a.start > b.start and a_end < b_end:+ return IntervalRelation.DURING+ return IntervalRelation.CONTAINS++ def overlaps(self, a: TemporalInterval, b: TemporalInterval) -> bool:+ relation = self.relation(a, b)+ return relation not in {+ IntervalRelation.BEFORE,+ IntervalRelation.AFTER,+ IntervalRelation.MEETS,+ IntervalRelation.MET_BY,+ }++ def contains(self, outer: TemporalInterval, inner: TemporalInterval) -> bool:+ self._validate_interval(outer)+ self._validate_interval(inner)+ return outer.start <= inner.start and self._end_value(outer.end) >= self._end_value(inner.end)++ def active_at(self, interval: TemporalInterval, timestamp: Any) -> bool:+ self._validate_interval(interval)+ point = parse_temporal_value(timestamp)+ return interval.start <= point and (+ interval.end is TemporalBound.OPEN or point < self._coerce_datetime(interval.end)+ )++ def merge_intervals(self, intervals: Iterable[TemporalInterval]) -> List[TemporalInterval]:+ ordered = sorted((self._validated_copy(i) for i in intervals), key=lambda item: item.start)+ if not ordered:+ return []++ merged: List[TemporalInterval] = [ordered[0]]+ for interval in ordered[1:]:+ current = merged[-1]+ if self._touches_or_overlaps(current, interval):+ new_end = self._max_end(current.end, interval.end)+ merged[-1] = TemporalInterval(start=current.start, end=new_end, label=current.label)+ else:+ merged.append(interval)+ return merged++ def gap_analysis(+ self,+ intervals: Iterable[TemporalInterval],+ domain_start: Any,+ domain_end: Any,+ ) -> List[TemporalInterval]:+ domain = self._make_interval(domain_start, domain_end, label="domain")+ clipped = self._clip_to_domain(intervals, domain)+ merged = self.merge_intervals(clipped)++ gaps: List[TemporalInterval] = []+ cursor = domain.start+ for interval in merged:+ if cursor < interval.start:+ gaps.append(TemporalInterval(start=cursor, end=interval.start, label="gap"))+ cursor = self._max_datetime(cursor, self._end_as_datetime(interval.end, domain.end))+ if cursor < self._coerce_datetime(domain.end):+ gaps.append(TemporalInterval(start=cursor, end=self._coerce_datetime(domain.end), label="gap"))+ return gaps++ def coverage_percentage(+ self,+ intervals: Iterable[TemporalInterval],+ domain_start: Any,+ domain_end: Any,+ ) -> float:+ domain = self._make_interval(domain_start, domain_end, label="domain")+ domain_duration = (self._coerce_datetime(domain.end) - domain.start).total_seconds()+ if domain_duration <= 0:+ return 0.0+ covered = 0.0+ for interval in self.merge_intervals(self._clip_to_domain(intervals, domain)):+ covered += (self._end_as_datetime(interval.end, domain.end) - interval.start).total_seconds()+ return max(0.0, min(1.0, covered / domain_duration))++ def timeline_of(self, entity_id: Any, graph: Dict[str, Any]) -> List[Dict[str, Any]]:+ entity_key = str(entity_id)+ events: List[Dict[str, Any]] = []++ for fact in graph.get("entities", []):+ if str(fact.get("id", fact.get("name", ""))) != entity_key:+ continue+ events.extend(self._events_for_fact(fact))++ for fact in graph.get("relationships", []):+ if str(fact.get("source")) != entity_key and str(fact.get("target")) != entity_key:+ continue+ events.extend(self._events_for_fact(fact))++ return sorted(events, key=lambda item: (item["timestamp"], item["change_type"]))++ def retroactive_coverage(+ self,+ revision: BiTemporalFact | Dict[str, Any],+ original_facts: Iterable[BiTemporalFact | Dict[str, Any]],+ ) -> Dict[str, List[BiTemporalFact | Dict[str, Any]]]:+ revision_fact = self._coerce_fact(revision)+ revision_interval = self._fact_interval(revision_fact)+ result = {"affected": [], "partial": [], "unaffected": []}++ for fact in original_facts:+ coerced = self._coerce_fact(fact)+ original_interval = self._fact_interval(coerced)+ if self.contains(original_interval, revision_interval):+ result["affected"].append(fact)+ elif self.overlaps(original_interval, revision_interval):+ result["partial"].append(fact)+ else:+ result["unaffected"].append(fact)+ return result++ def normalize_timestamp(self, timestamp: Any, granularity: str) -> datetime:+ granularity = self._validate_granularity(granularity)+ value = parse_temporal_value(timestamp)+ if granularity == "second":+ return value.replace(microsecond=0)+ if granularity == "minute":+ return value.replace(second=0, microsecond=0)+ if granularity == "hour":+ return value.replace(minute=0, second=0, microsecond=0)+ if granularity == "day":+ return value.replace(hour=0, minute=0, second=0, microsecond=0)+ if granularity == "week":+ start_of_week = value - timedelta(days=value.weekday())+ return start_of_week.replace(hour=0, minute=0, second=0, microsecond=0)+ if granularity == "month":+ return value.replace(day=1, hour=0, minute=0, second=0, microsecond=0)+ return value.replace(month=1, day=1, hour=0, minute=0, second=0, microsecond=0)++ def normalize_interval(self, start: Any, end: Any, granularity: str) -> TemporalInterval:+ granularity = self._validate_granularity(granularity)+ normalized_start = self.normalize_timestamp(start, granularity)+ parsed_end = parse_temporal_bound(end, default=TemporalBound.OPEN)+ if parsed_end is TemporalBound.OPEN:+ return TemporalInterval(start=normalized_start, end=TemporalBound.OPEN)+ end_dt = parse_temporal_value(parsed_end)+ normalized_end = self._expand_end(end_dt, granularity)+ return TemporalInterval(start=normalized_start, end=normalized_end)++ def _events_for_fact(self, fact: Dict[str, Any]) -> List[Dict[str, Any]]:+ events: List[Dict[str, Any]] = []+ start = parse_temporal_value(fact.get("valid_from")) if fact.get("valid_from") is not None else None+ end = parse_temporal_bound(fact.get("valid_until"), default=TemporalBound.OPEN)+ recorded_at = parse_temporal_value(fact.get("recorded_at")) if fact.get("recorded_at") is not None else None+ superseded_at = parse_temporal_bound(fact.get("superseded_at"), default=TemporalBound.OPEN)++ if start is not None:+ events.append({"timestamp": start, "change_type": "added", "fact": fact})+ if isinstance(recorded_at, datetime) and (start is None or recorded_at != start):+ events.append({"timestamp": recorded_at, "change_type": "modified", "fact": fact})+ if isinstance(superseded_at, datetime):+ events.append({"timestamp": superseded_at, "change_type": "modified", "fact": fact})+ if isinstance(end, datetime):+ events.append({"timestamp": end, "change_type": "removed", "fact": fact})+ return events++ def _coerce_fact(self, fact: BiTemporalFact | Dict[str, Any]) -> BiTemporalFact:+ if isinstance(fact, BiTemporalFact):+ return fact+ return BiTemporalFact.from_relationship(dict(fact))++ def _fact_interval(self, fact: BiTemporalFact) -> TemporalInterval:+ start = fact.valid_from or datetime.min.replace(tzinfo=timezone.utc)+ end = fact.valid_until if fact.valid_until is not None else TemporalBound.OPEN+ return TemporalInterval(start=start, end=end)++ def _clip_to_domain(+ self,+ intervals: Iterable[TemporalInterval],+ domain: TemporalInterval,+ ) -> List[TemporalInterval]:+ clipped: List[TemporalInterval] = []+ domain_end = self._coerce_datetime(domain.end)+ for interval in intervals:+ candidate = self._validated_copy(interval)+ if not self.overlaps(candidate, domain) and candidate.end != domain.start and candidate.start != domain_end:+ continue+ start = max(candidate.start, domain.start)+ end_dt = min(self._end_as_datetime(candidate.end, domain.end), domain_end)+ if start < end_dt:+ clipped.append(TemporalInterval(start=start, end=end_dt, label=candidate.label))+ return clipped++ def _touches_or_overlaps(self, left: TemporalInterval, right: TemporalInterval) -> bool:+ left_end = self._end_value(left.end)+ return right.start <= left_end++ def _make_interval(self, start: Any, end: Any, *, label: Optional[str] = None) -> TemporalInterval:+ interval = TemporalInterval(+ start=parse_temporal_value(start),+ end=parse_temporal_bound(end, default=TemporalBound.OPEN),+ label=label,+ )+ return self._validated_copy(interval)++ def _validated_copy(self, interval: TemporalInterval) -> TemporalInterval:+ normalized = TemporalInterval(+ start=parse_temporal_value(interval.start),+ end=parse_temporal_bound(interval.end, default=TemporalBound.OPEN),+ label=interval.label,+ )+ self._validate_interval(normalized)+ return normalized++ def _validate_interval(self, interval: TemporalInterval) -> None:+ if isinstance(interval.end, datetime) and interval.start > interval.end:+ raise ValueError("Temporal intervals must satisfy start <= end.")++ def _end_value(self, value: datetime | TemporalBound) -> datetime:+ if value is TemporalBound.OPEN:+ return datetime.max.replace(tzinfo=timezone.utc)+ return self._coerce_datetime(value)++ def _end_as_datetime(self, value: datetime | TemporalBound, fallback: datetime | TemporalBound) -> datetime:+ if value is TemporalBound.OPEN:+ return self._coerce_datetime(fallback)+ return self._coerce_datetime(value)++ def _coerce_datetime(self, value: Any) -> datetime:+ return parse_temporal_value(value)++ def _max_end(self, left: datetime | TemporalBound, right: datetime | TemporalBound) -> datetime | TemporalBound:+ if left is TemporalBound.OPEN or right is TemporalBound.OPEN:+ return TemporalBound.OPEN+ return max(self._coerce_datetime(left), self._coerce_datetime(right))++ def _max_datetime(self, left: datetime, right: datetime) -> datetime:+ return left if left >= right else right++ def _validate_granularity(self, granularity: str) -> str:+ if granularity not in self.SUPPORTED_GRANULARITIES:+ raise ValueError(f"Unsupported temporal granularity: {granularity}")+ return granularity++ def _expand_end(self, value: datetime, granularity: str) -> datetime:+ floor = self.normalize_timestamp(value, granularity)+ if granularity == "second":+ return floor + timedelta(seconds=1) - timedelta(microseconds=1)+ if granularity == "minute":+ return floor + timedelta(minutes=1) - timedelta(microseconds=1)+ if granularity == "hour":+ return floor + timedelta(hours=1) - timedelta(microseconds=1)+ if granularity == "day":+ return floor + timedelta(days=1) - timedelta(microseconds=1)+ if granularity == "week":+ return floor + timedelta(weeks=1) - timedelta(microseconds=1)+ if granularity == "month":+ _, days = calendar.monthrange(floor.year, floor.month)+ return floor.replace(day=days, hour=23, minute=59, second=59, microsecond=999999)+ return floor.replace(month=12, day=31, hour=23, minute=59, second=59, microsecond=999999)diff --git a/tests/kg/test_temporal_reasoning.py b/tests/kg/test_temporal_reasoning.pynew file mode 100644index 00000000..c68df8e1--- /dev/null+++ b/tests/kg/test_temporal_reasoning.py@@ -0,0 +1,129 @@+from datetime import datetime, timezone++from semantica.kg import BiTemporalFact, TemporalBound, TemporalGraphQuery+from semantica.reasoning import IntervalRelation, TemporalInterval, TemporalReasoningEngine+++def dt(value: str) -> datetime:+ return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)+++def interval(start: str, end, label: str | None = None) -> TemporalInterval:+ return TemporalInterval(start=dt(start), end=TemporalBound.OPEN if end is TemporalBound.OPEN else dt(end), label=label)+++class TestTemporalReasoningEngine:+ def setup_method(self):+ self.engine = TemporalReasoningEngine()++ def test_allen_relations_cover_all_thirteen_cases(self):+ base = interval("2024-01-03T00:00:00Z", "2024-01-05T00:00:00Z")+ cases = {+ IntervalRelation.BEFORE: interval("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z"),+ IntervalRelation.AFTER: interval("2024-01-06T00:00:00Z", "2024-01-07T00:00:00Z"),+ IntervalRelation.MEETS: interval("2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z"),+ IntervalRelation.MET_BY: interval("2024-01-05T00:00:00Z", "2024-01-06T00:00:00Z"),+ IntervalRelation.OVERLAPS: interval("2024-01-01T00:00:00Z", "2024-01-04T00:00:00Z"),+ IntervalRelation.OVERLAPPED_BY: interval("2024-01-04T00:00:00Z", "2024-01-06T00:00:00Z"),+ IntervalRelation.STARTS: interval("2024-01-03T00:00:00Z", "2024-01-04T00:00:00Z"),+ IntervalRelation.STARTED_BY: interval("2024-01-03T00:00:00Z", "2024-01-06T00:00:00Z"),+ IntervalRelation.DURING: interval("2024-01-03T12:00:00Z", "2024-01-04T12:00:00Z"),+ IntervalRelation.CONTAINS: interval("2024-01-02T00:00:00Z", "2024-01-06T00:00:00Z"),+ IntervalRelation.FINISHES: interval("2024-01-04T00:00:00Z", "2024-01-05T00:00:00Z"),+ IntervalRelation.FINISHED_BY: interval("2024-01-02T00:00:00Z", "2024-01-05T00:00:00Z"),+ IntervalRelation.EQUALS: interval("2024-01-03T00:00:00Z", "2024-01-05T00:00:00Z"),+ }++ assert {self.engine.relation(candidate, base) for candidate in cases.values()} == set(cases.keys())+ for expected, candidate in cases.items():+ assert self.engine.relation(candidate, base) is expected++ def test_merge_intervals_and_active_at_open_bound(self):+ merged = self.engine.merge_intervals(+ [+ interval("2024-01-01T00:00:00Z", "2024-01-03T00:00:00Z", "A"),+ interval("2024-01-02T00:00:00Z", "2024-01-04T00:00:00Z", "B"),+ interval("2024-01-10T00:00:00Z", "2024-01-11T00:00:00Z", "C"),+ ]+ )++ assert len(merged) == 2+ assert merged[0].start == dt("2024-01-01T00:00:00Z")+ assert merged[0].end == dt("2024-01-04T00:00:00Z")+ assert self.engine.active_at(+ TemporalInterval(start=dt("2024-01-01T00:00:00Z"), end=TemporalBound.OPEN),+ "2026-01-01T00:00:00Z",+ )++ def test_gap_analysis_and_coverage_percentage(self):+ gaps = self.engine.gap_analysis(+ [+ interval("2020-01-01T00:00:00Z", "2021-01-01T00:00:00Z"),+ interval("2022-01-01T00:00:00Z", "2023-01-01T00:00:00Z"),+ ],+ "2020-01-01T00:00:00Z",+ "2023-01-01T00:00:00Z",+ )++ assert len(gaps) == 1+ assert gaps[0].start == dt("2021-01-01T00:00:00Z")+ assert gaps[0].end == dt("2022-01-01T00:00:00Z")+ assert self.engine.coverage_percentage(+ [interval("2020-01-01T00:00:00Z", "2023-01-01T00:00:00Z")],+ "2020-01-01T00:00:00Z",+ "2023-01-01T00:00:00Z",+ ) == 1.0++ def test_timeline_of_orders_events_and_handles_open_intervals(self):+ graph = {+ "entities": [{"id": "supplier-1", "valid_from": "2020-01-01T00:00:00Z", "valid_until": TemporalBound.OPEN}],+ "relationships": [+ {"id": "r1", "source": "supplier-1", "target": "cert", "type": "certified", "valid_from": "2021-01-01T00:00:00Z", "valid_until": "2022-01-01T00:00:00Z"},+ {"id": "r2", "source": "supplier-1", "target": "renewal", "type": "certified", "valid_from": "2023-01-01T00:00:00Z", "valid_until": TemporalBound.OPEN},+ ],+ }++ events = self.engine.timeline_of("supplier-1", graph)++ assert [event["change_type"] for event in events] == ["added", "added", "removed", "added"]+ assert events == sorted(events, key=lambda item: (item["timestamp"], item["change_type"]))++ def test_retroactive_coverage_classifies_affected_partial_and_unaffected(self):+ revision = BiTemporalFact(+ valid_from=dt("2021-01-01T00:00:00Z"),+ valid_until=dt("2023-01-01T00:00:00Z"),+ recorded_at=dt("2024-01-01T00:00:00Z"),+ )+ originals = [+ {"id": "affected", "valid_from": "2020-01-01T00:00:00Z", "valid_until": "2023-01-01T00:00:00Z"},+ {"id": "unaffected", "valid_from": "2019-01-01T00:00:00Z", "valid_until": "2020-01-01T00:00:00Z"},+ {"id": "partial", "valid_from": "2022-01-01T00:00:00Z", "valid_until": "2024-01-01T00:00:00Z"},+ ]++ result = self.engine.retroactive_coverage(revision, originals)++ assert [fact["id"] for fact in result["affected"]] == ["affected"]+ assert [fact["id"] for fact in result["unaffected"]] == ["unaffected"]+ assert [fact["id"] for fact in result["partial"]] == ["partial"]++ def test_normalization_is_idempotent_and_used_by_temporal_graph_query(self):+ month_point = self.engine.normalize_timestamp("2024-06-15T14:32:10Z", "month")+ assert month_point == dt("2024-06-01T00:00:00Z")++ normalized = self.engine.normalize_interval("2024-06-15T00:00:00Z", "2024-08-20T00:00:00Z", "month")+ assert normalized.start == dt("2024-06-01T00:00:00Z")+ assert normalized.end == dt("2024-08-31T23:59:59.999999Z")+ assert self.engine.normalize_interval(normalized.start, normalized.end, "month") == normalized++ query = TemporalGraphQuery(temporal_granularity="month")+ graph = {+ "relationships": [+ {"id": "jan", "source": "A", "target": "B", "type": "rel", "valid_from": "2024-01-10T00:00:00Z", "valid_until": "2024-01-20T00:00:00Z"},+ {"id": "feb", "source": "A", "target": "C", "type": "rel", "valid_from": "2024-02-05T00:00:00Z", "valid_until": "2024-02-10T00:00:00Z"},+ ]+ }++ result = query.query_time_range(graph, "", "2024-01-15T12:00:00Z", "2024-02-01T00:00:00Z")+ assert result["start_time"] == dt("2024-01-01T00:00:00Z")+ assert result["end_time"] == dt("2024-02-29T23:59:59.999999Z")+ assert {rel["id"] for rel in result["relationships"]} == {"jan", "feb"}