图谱构建与双时态事实

30class GraphBuilder:31    """32    Knowledge graph builder with temporal support.3334    • Constructs knowledge graphs from entities and relationships35    • Supports temporal knowledge graphs with time-aware edges36    • Manages node and edge creation with temporal annotations37    • Handles graph structure optimization38    • Supports incremental graph building39    • Enables temporal versioning and snapshots4041    Attributes:42        • merge_entities: Whether to merge duplicate entities43        • entity_resolution_strategy: Strategy for entity resolution44        • resolve_conflicts: Whether to resolve conflicts45        • enable_temporal: Enable temporal knowledge graph features46        • temporal_granularity: Time granularity (second, minute, hour, day, etc.)47        • track_history: Track historical changes48        • version_snapshots: Create version snapshots4950    Methods:51        • build(): Build knowledge graph from sources52        • add_temporal_edge(): Add edge with temporal validity53        • create_temporal_snapshot(): Create temporal snapshot54        • query_temporal(): Query graph at specific time point55    """

57    def __init__(58        self,59        merge_entities=False,60        entity_resolution_strategy="fuzzy",61        resolve_conflicts=True,62        enable_temporal=False,63        temporal_granularity="day",64        track_history=False,65        version_snapshots=False,66        graph_store=None,67        **kwargs,68    ):69        """70        Initialize graph builder.7172        Args:73            merge_entities: Whether to merge duplicate entities (default: False, set to True to enable)74                          Note: Entity resolution is typically done in conflict resolution step75            entity_resolution_strategy: Strategy for entity resolution ("fuzzy", "exact", "ml-based")76            resolve_conflicts: Whether to resolve conflicts77            enable_temporal: Enable temporal knowledge graph features78            temporal_granularity: Time granularity ("second", "minute", "hour", "day", "week", "month", "year")79            track_history: Track historical changes to entities/relationships80            version_snapshots: Create version snapshots at intervals81            graph_store: Optional GraphStore instance for persistence82            **kwargs: Additional configuration options83        """84        self.merge_entities = merge_entities85        self.entity_resolution_strategy = entity_resolution_strategy86        self.resolve_conflicts = resolve_conflicts87        self.enable_temporal = enable_temporal88        self.temporal_granularity = temporal_granularity89        self.track_history = track_history90        self.version_snapshots = version_snapshots91        self.graph_store = graph_store92        self.config = kwargs  # Store additional config for extractors93        # Extractors are reused across texts: NERExtractor loads its spaCy model94        # eagerly in __init__, so constructing one per text would reload the95        # model on every source in a multi-document build.96        self._extractor_cache: Dict[Tuple[str, Any], Any] = {}97        # build() resets these per run; seed them here so _extract_from_text98        # is usable on its own instead of raising an AttributeError that the99        # broad except in the extraction path silently swallows.100        self._extraction_stats: Dict[str, int] = {101            "extracted_entities": 0,102            "extracted_relations": 0,103            "extracted_triplets": 0,104        }

116        # Initialize entity resolver if entity merging is enabled117        # This helps deduplicate and merge similar entities118        if self.merge_entities:119            from .entity_resolver import EntityResolver120121            entity_resolution_config = kwargs.get("entity_resolution", {})122            self.entity_resolver = EntityResolver(123                strategy=self.entity_resolution_strategy, **entity_resolution_config124            )125            self.logger.debug(126                f"Entity resolver initialized with strategy: {self.entity_resolution_strategy}"127            )128        else:129            self.entity_resolver = None130            self.logger.debug("Entity merging disabled, skipping entity resolver")131132        # Initialize conflict detector if conflict resolution is enabled133        # This helps detect and resolve conflicting information in the graph134        if self.resolve_conflicts:135            from ..conflicts.conflict_detector import ConflictDetector136137            conflict_detection_config = kwargs.get("conflict_detection", {})138            self.conflict_detector = ConflictDetector(**conflict_detection_config)139            self.logger.debug("Conflict detector initialized")140        else:141            self.conflict_detector = None142            self.logger.debug("Conflict resolution disabled")

144    def _process_item(self, item: Any, all_entities: List[Any], all_relationships: List[Any], **options):145        """Helper to process a single item and add to entities or relationships list."""146        if isinstance(item, str):147            # Treat string as text for extraction148            self._extract_from_text(item, all_entities, all_relationships, **options)149            return150151        if hasattr(item, "text") and (hasattr(item, "label") or hasattr(item, "type")):152            # It's likely an Entity object153            entity_dict = {154                "id": getattr(item, "id", getattr(item, "entity_id", item.text)),155                "name": item.text,156                "type": getattr(item, "label", getattr(item, "type", "UNKNOWN")),157                "confidence": getattr(item, "confidence", 1.0),158                "metadata": getattr(item, "metadata", {})159            }160            all_entities.append(entity_dict)161        elif hasattr(item, "subject") and hasattr(item, "predicate") and hasattr(item, "object"):162            # It's likely a Relation object163            subj = item.subject164            obj = item.object165            subj_id = getattr(subj, "id", getattr(subj, "text", str(subj))) if not isinstance(subj, str) else subj166            obj_id = getattr(obj, "id", getattr(obj, "text", str(obj))) if not isinstance(obj, str) else obj167            rel_dict = {168                "source": subj_id,169                "target": obj_id,170                "type": item.predicate,171                "confidence": getattr(item, "confidence", 1.0),172                "metadata": getattr(item, "metadata", {})173            }174            all_relationships.append(rel_dict)175        elif isinstance(item, dict):

493        source_dict = None494        if isinstance(sources, dict) and ("entities" in sources or "relationships" in sources):495            source_dict = sources496            sources = [sources]  # Normalize for tracking497        elif isinstance(sources, list) and len(sources) > 0:498            # Check if first item is a dict with entities/relationships499            first_item = sources[0]500            if isinstance(first_item, dict) and ("entities" in first_item or "relationships" in first_item):501                # If all items are dicts with entities/relationships, merge them502                if all(isinstance(item, dict) and ("entities" in item or "relationships" in item) for item in sources):503                    # Merge all sources into one dict504                    source_dict = {505                        "entities": [],506                        "relationships": []507                    }508                    for item in sources:509                        if "entities" in item:510                            if isinstance(item["entities"], list):511                                source_dict["entities"].extend(item["entities"])512                            else:513                                source_dict["entities"].append(item["entities"])514                        if "relationships" in item:515                            if isinstance(item["relationships"], list):516                                source_dict["relationships"].extend(item["relationships"])517                            else:518                                source_dict["relationships"].append(item["relationships"])519        elif not isinstance(sources, list):520            sources = [sources]

588                    # Check if entities are already in dictionary format589                    sample_entity = entities_list[0] if entities_list else None590                    is_dict_format = isinstance(sample_entity, dict) and (591                        "id" in sample_entity or "entity_id" in sample_entity or 592                        "name" in sample_entity or "text" in sample_entity593                    ) and not hasattr(sample_entity, "__dict__") # Ensure it's not a class instance594                    595                    if is_dict_format:596                        # Fast path: directly append dictionaries after normalizing597                        batch_size = max(100, len(entities_list) // 20)598                        for i in range(0, len(entities_list), batch_size):599                            batch = entities_list[i:i + batch_size]600                            for item in batch:601                                # Normalize entity dict format602                                if isinstance(item, dict):603                                    # Ensure required fields exist604                                    entity_dict = item.copy()605                                    if "text" in entity_dict and "name" not in entity_dict:606                                        entity_dict["name"] = entity_dict["text"]607                                    if "id" not in entity_dict and "entity_id" not in entity_dict:608                                        entity_dict["id"] = entity_dict.get("name") or entity_dict.get("text") or str(hash(str(item)))609                                    all_entities.append(entity_dict)610                                else:611                                    # Fallback to _process_item for non-dict items612                                    self._process_item(item, all_entities, all_relationships, **options)613                            614                            processed = min(i + batch_size, len(entities_list))615                            616                            # Update progress with ETA617                            self.progress_tracker.update_progress(618                                entity_tracking_id,619                                processed=processed,620                                total=len(entities_list),621                                message=f"Processing entities... {processed}/{len(entities_list)}"622                            )623                    else:624                        # Slow path: use _process_item for complex objects

764                resolved_entities = resolver_to_use.resolve_entities(all_entities)765                resolution_time = time.time() - resolution_start766                self.logger.info(767                    "Resolved to %d unique entities (%.2fs)",768                    len(resolved_entities),769                    resolution_time,770                )771                self.logger.info(772                    f"Entity resolution complete: {len(all_entities)} -> {len(resolved_entities)} unique entities"773                )774775            # Relationships were collected before entity resolution. Rewrite776            # endpoints only when resolution produced merged entity IDs.777            if resolver_to_use:778                has_merged_entities = any(779                    isinstance(entity, dict) and entity.get("merged_from")780                    for entity in resolved_entities781                )782                if has_merged_entities:783                    self._remap_relationship_endpoints(resolved_entities, all_relationships)784785            if input_relationships_count > 0 and len(all_relationships) == 0:786                warning_msg = (787                    f"All relationships were dropped during graph building: "788                    f"{input_relationships_count} input relationships, 0 in final graph"789                )790                self.logger.warning(warning_msg)791792            # Build graph structure793            self.logger.debug("Building graph structure...")794            structure_start = time.time()795            graph = {796                "entities": resolved_entities,797                "relationships": all_relationships,798                "metadata": {799                    "num_entities": len(resolved_entities),800                    "num_relationships": len(all_relationships),801                    "temporal_enabled": self.enable_temporal,802                    "timestamp": self._get_timestamp(),803                    "entity_resolution_applied": resolver_to_use is not None,804                },805            }

265    def _remap_relationship_endpoints(266        self,267        entities: List[Dict[str, Any]],268        relationships: List[Dict[str, Any]],269    ) -> int:270        """Rewrite relationship endpoints after entity resolution.271272        Entity merging keeps the canonical entity ID and records the IDs of all273        merged inputs in ``merged_from``.  Relationships are collected before274        resolution, so without this remapping they can continue to reference an275        entity that is no longer present in the graph.276277        Returns:278            The number of relationship endpoints that were remapped.279        """280        endpoint_map: Dict[Any, Any] = {}281282        for entity in entities:283            if not isinstance(entity, dict):284                continue285286            canonical_id = entity.get("id")287            if canonical_id is None:288                canonical_id = entity.get("entity_id")289            if canonical_id is None:290                continue291292            # Keep canonical IDs stable and map every source ID retained by the293            # merge operation to the surviving entity.294            try:295                endpoint_map[canonical_id] = canonical_id296            except TypeError:297                # Invalid/unhashable IDs are left for graph validation to report298                # rather than making graph construction fail here.299                continue300301            merged_from = entity.get("merged_from") or []302            if isinstance(merged_from, (list, tuple, set)):303                for source_id in merged_from:304                    if source_id is not None:305                        try:306                            endpoint_map[source_id] = canonical_id307                        except TypeError:308                            # Skip invalid aliases while preserving valid ones.309                            continue310311        remapped_count = 0312        for relationship in relationships:313            if not isinstance(relationship, dict):314                continue315316            for endpoint, endpoint_alias in (317                ("source", "source_id"),318                ("target", "target_id"),319            ):320                endpoint_id = relationship.get(endpoint)321                try:322                    canonical_id = endpoint_map.get(endpoint_id)323                except TypeError:324                    # Invalid/unhashable endpoints are left for graph validation325                    # to report rather than making graph construction fail here.326                    continue327328                if canonical_id is None:329                    continue330331                remapped = canonical_id != endpoint_id332                if remapped:333                    relationship[endpoint] = canonical_id334335                if (336                    endpoint_alias in relationship337                    and relationship[endpoint_alias] != canonical_id338                ):339                    relationship[endpoint_alias] = canonical_id340                    remapped = True341342                if remapped:343                    remapped_count += 1344345        if remapped_count:346            self.logger.info(347                "Remapped %d relationship endpoint(s) after entity resolution",348                remapped_count,349            )350        return remapped_count

32class EntityResolver:33    """34    Entity resolver for knowledge graph construction.3536    This class provides entity disambiguation and resolution by detecting37    duplicate entities and merging them based on similarity. It supports38    multiple resolution strategies and configurable similarity thresholds.3940    Resolution Strategies:41        - "fuzzy": Fuzzy string matching (default)42        - "exact": Exact string matching43        - "semantic": Semantic similarity matching4445    Example Usage:46        >>> resolver = EntityResolver(strategy="fuzzy", similarity_threshold=0.8)47        >>> entities = [{"id": "1", "name": "Apple Inc."}, {"id": "2", "name": "Apple"}]48        >>> resolved = resolver.resolve_entities(entities)49    """

136        try:137            # Step 1: Detect duplicate groups138            # Groups entities that are similar enough to be considered duplicates139            self.logger.debug(140                f"Detecting duplicate groups with threshold {self.similarity_threshold}"141            )142            duplicate_groups = self._detect_duplicate_groups(entities)143144            self.logger.debug(f"Found {len(duplicate_groups)} duplicate group(s)")145146            self.progress_tracker.update_tracking(147                tracking_id, message=f"Found {len(duplicate_groups)} duplicate group(s)"148            )149            # Step 2: Merge duplicates in each group150            merged_entities = []151            processed_entity_ids = set()  # Track which entities have been merged152            processed_entity_objects = set()153154            for group in duplicate_groups:155                # Skip groups with less than 2 entities (not duplicates)156                if len(group.entities) < 2:157                    continue158159                # Merge the duplicate group into a single canonical entity160                if self.resolution_strategy == "exact":161                    merge_operations = [162                        self.entity_merger.merge_entity_group(163                            group.entities, **self.config164                        )165                    ]166                else:167                    merge_operations = self.entity_merger.merge_duplicates(168                        group.entities, **self.config169                    )170171                # Process each merge operation172                for operation in merge_operations:173                    merged_entity = operation.merged_entity174                    merged_entities.append(merged_entity)175176                    # Mark all source entities as processed177                    for source_entity in operation.source_entities:178                        entity_id = self._get_entity_id(source_entity)179                        if entity_id is None:180                            processed_entity_objects.add(id(source_entity))181                            continue182                        try:183                            processed_entity_ids.add(entity_id)184                        except TypeError:185                            processed_entity_objects.add(id(source_entity))186187            # Step 3: Add non-duplicate entities (entities not in any duplicate group)188            for entity in entities:189                entity_id = self._get_entity_id(entity)190                if entity_id is None:191                    is_unprocessed = id(entity) not in processed_entity_objects192                else:193                    try:194                        is_unprocessed = entity_id not in processed_entity_ids195                    except TypeError:196                        is_unprocessed = id(entity) not in processed_entity_objects197                if is_unprocessed:198                    # This entity was not merged, add it as-is199                    merged_entities.append(entity)200201            # Log resolution statistics202            original_count = len(entities)203            resolved_count = len(merged_entities)204            reduction = original_count - resolved_count205206            self.logger.info(207                f"Entity resolution complete: {original_count} -> {resolved_count} "208                f"({reduction} duplicate(s) merged)"209            )210211            return merged_entities

27@dataclass28class BiTemporalFact:29    """30    Backward-compatible wrapper around existing relationship dictionaries.3132    Design note:33    Facts continue to live as plain relationship dicts in the graph. This wrapper34    is only used internally for normalization so existing callers can keep35    reading and writing `valid_from` / `valid_until` directly.36    """3738    valid_from: Optional[datetime]39    valid_until: Optional[datetime | TemporalBound]40    recorded_at: datetime = field(default_factory=_default_recorded_at)41    superseded_at: datetime | TemporalBound = TemporalBound.OPEN4243    @classmethod44    def from_relationship(cls, relationship: Dict[str, Any]) -> "BiTemporalFact":45        valid_until_raw = relationship.get("valid_until", TemporalBound.OPEN)46        if valid_until_raw is None:47            valid_until_raw = TemporalBound.OPEN4849        valid_from = parse_temporal_value(relationship.get("valid_from"))50        recorded_at_raw = relationship.get("recorded_at")51        superseded_at_raw = relationship.get("superseded_at", TemporalBound.OPEN)5253        return cls(54            valid_from=valid_from,55            valid_until=parse_temporal_bound(valid_until_raw),56            recorded_at=parse_temporal_value(recorded_at_raw) if recorded_at_raw is not None else (valid_from or _default_recorded_at()),57            superseded_at=parse_temporal_bound(superseded_at_raw, default=TemporalBound.OPEN),58        )5960    def to_relationship_fields(self) -> Dict[str, Any]:61        return {62            "valid_from": serialize_temporal_value(self.valid_from),63            "valid_until": serialize_temporal_bound(self.valid_until),64            "recorded_at": serialize_temporal_value(self.recorded_at),65            "superseded_at": serialize_temporal_bound(self.superseded_at),66        }

17class TemporalBound(Enum):18    """Sentinel bounds for open-ended temporal intervals."""1920    OPEN = "OPEN"

83def parse_temporal_value(value: Any) -> Optional[datetime]:84    if value is None:85        return None86    if isinstance(value, datetime):87        dt = value88    elif isinstance(value, (int, float)):89        dt = datetime.fromtimestamp(value, timezone.utc)90    elif isinstance(value, str):91        normalized = _coerce_iso_like_string(value)92        if normalized.endswith("Z"):93            normalized = normalized[:-1] + "+00:00"94        try:95            dt = datetime.fromisoformat(normalized)96        except ValueError as exc:97            raise TemporalValidationError(98                "Invalid temporal value",99                temporal_context={"value": value},100            ) from exc101    else:102        raise TemporalValidationError(103            "Unsupported temporal value type",104            temporal_context={"value": value, "type": type(value).__name__},105        )106107    if dt.tzinfo is None:108        dt = dt.replace(tzinfo=timezone.utc)109    return dt.astimezone(timezone.utc)

980            # Parse temporal information981            valid_from = self._parse_time(valid_from) or self._get_timestamp()982            valid_until = self._parse_time(valid_until) if valid_until else None983984            # Create edge with temporal information985            edge = {986                "source": source,987                "target": target,988                "type": relationship,989                "valid_from": valid_from,990                "valid_until": valid_until,991                "temporal_metadata": temporal_metadata or {},992                **kwargs,993            }994995            # Add to graph996            if "relationships" not in graph:997                graph["relationships"] = []998            graph["relationships"].append(edge)

1065            # Filter relationships valid at snapshot time1066            if "relationships" in graph:1067                for rel in graph["relationships"]:1068                    valid_from = self._parse_time(rel.get("valid_from"))1069                    valid_until = self._parse_time(rel.get("valid_until"))10701071                    # Check if relationship is valid at snapshot time1072                    if (1073                        valid_from1074                        and self._compare_times(snapshot_time, valid_from) < 01075                    ):1076                        continue1077                    if (1078                        valid_until1079                        and self._compare_times(snapshot_time, valid_until) > 01080                    ):1081                        continue10821083                    relationships.append(rel)

41class TemporalGraphQuery:42    """43    Temporal knowledge graph query engine.4445    This class provides time-aware querying capabilities for knowledge graphs46    with temporal information, enabling queries at specific time points, within47    time ranges, and temporal pattern detection.4849    Features:50        - Time-point queries (filter relationships valid at specific time)51        - Time-range queries (filter relationships valid within range)52        - Temporal pattern detection (sequences, cycles, trends)53        - Graph evolution analysis54        - Temporal path finding (paths considering temporal validity)5556    Example Usage:57        >>> query_engine = TemporalGraphQuery()58        >>> result = query_engine.query_at_time(graph, query, at_time="2024-01-01")59        >>> range_result = query_engine.query_time_range(graph, query, start_time, end_time)60        >>> evolution = query_engine.analyze_evolution(graph)61    """

107    def query_at_time(108        self,109        graph: Any,110        query: str,111        at_time: Any,112        include_history: bool = False,113        temporal_precision: Optional[str] = None,114        time_axis: str = "valid",115        **options,116    ) -> Dict[str, Any]:117        """118        Query graph at specific time point.119120        This method filters the knowledge graph to only include relationships121        that are valid at the specified time point, based on valid_from and122        valid_until fields in relationships.123124        Args:125            graph: Knowledge graph to query (dict with "entities" and "relationships")126            query: Query string (currently unused, reserved for future query parsing)127            at_time: Time point (datetime object, timestamp, or ISO format string)128            include_history: Whether to include all relationships with temporal129                           information (default: False, only valid relationships)130            temporal_precision: Precision for time matching (optional, unused)131            **options: Additional query options (unused)132133        Returns:134            dict: Query results containing:135                - query: Original query string136                - at_time: Parsed time point137                - entities: All entities (not filtered by time)138                - relationships: Relationships valid at specified time139                - num_entities: Number of entities140                - num_relationships: Number of valid relationships141        """142        self.logger.info(f"Querying graph at time: {at_time}")143144        # Parse time145        query_time = self._parse_time(at_time)146        reconstructed_graph = self.reconstruct_at_time(147            graph,148            query_time,149            time_axis=time_axis,150        )151152        # Get entities153        entities = reconstructed_graph.get("entities", [])154        relationships = reconstructed_graph.get("relationships", [])155156        # Include history if requested157        if include_history:158            # Add all relationships with temporal information159            relationships = graph.get("relationships", [])160161        return {162            "query": query,163            "at_time": query_time,164            "entities": entities,165            "relationships": relationships,166            "num_entities": len(entities),167            "num_relationships": len(relationships),168        }

170    def reconstruct_at_time(171        self,172        graph: Any,173        at_time: Any,174        *,175        time_axis: str = "valid",176    ) -> Dict[str, Any]:177        """Return a self-consistent subgraph for a single point in time."""178        query_time = at_time if isinstance(at_time, datetime) else self._parse_time(at_time)179        reconstructed = copy.deepcopy(graph)180        entity_list = graph.get("entities", [])181182        if not entity_list:183            reconstructed["entities"] = []184            reconstructed["relationships"] = [185                copy.deepcopy(relationship)186                for relationship in graph.get("relationships", [])187                if self._relationship_active_at_time(relationship, query_time, time_axis=time_axis)188            ]189            return reconstructed190191        entity_index = {192            self._entity_id(entity): entity193            for entity in entity_list194            if self._entity_active_at_time(entity, query_time, time_axis=time_axis)195        }196197        relationships = []198        for relationship in graph.get("relationships", []):199            if not self._relationship_active_at_time(relationship, query_time, time_axis=time_axis):200                continue201            source = self._entity_id({"id": relationship.get("source")})202            target = self._entity_id({"id": relationship.get("target")})203            if source not in entity_index or target not in entity_index:204                continue205            relationships.append(copy.deepcopy(relationship))206207        reconstructed["entities"] = list(entity_index.values())208        reconstructed["relationships"] = relationships209        return reconstructed

211    def validate_temporal_consistency(self, graph: Any) -> TemporalConsistencyReport:212        errors: List[Dict[str, str]] = []213        warnings_list: List[Dict[str, str]] = []214215        entities = {216            self._entity_id(entity): entity217            for entity in graph.get("entities", [])218        }219        rel_groups: Dict[tuple[str, str, str], List[Dict[str, Any]]] = defaultdict(list)220221        for relationship in graph.get("relationships", []):222            rel_id = relationship.get("id") or self._relationship_key(relationship)223            rel_groups[224                (225                    relationship.get("source", ""),226                    relationship.get("type", relationship.get("relationship", "")),227                    relationship.get("target", ""),228                )229            ].append(relationship)230231            try:232                start, end = self._get_axis_bounds(relationship, "valid")233            except TemporalValidationError as exc:234                errors.append(235                    asdict(236                        TemporalConsistencyIssue(237                            message=f"Unable to parse temporal fields: {exc}",238                            fact_id=rel_id,239                            issue_type="invalid_temporal_fields",240                        )241                    )242                )243                continue244            if start and isinstance(end, datetime) and self._compare_times(start, end) > 0:245                errors.append(246                    asdict(247                        TemporalConsistencyIssue(248                            message="Relationship has an inverted validity interval.",249                            fact_id=rel_id,250                            issue_type="inverted_interval",251                        )252                    )253                )254255            for endpoint in ("source", "target"):256                entity = entities.get(relationship.get(endpoint))257                if entity is None:258                    errors.append(259                        asdict(260                            TemporalConsistencyIssue(261                                message=f"Relationship references missing {endpoint} entity.",262                                fact_id=rel_id,263                                issue_type=f"missing_{endpoint}_entity",264                            )265                        )266                    )267                    continue

1"""2Deterministic temporal reasoning primitives for Semantica.34This module is the single source of truth for interval math across temporal KG5features. It performs zero LLM calls: extraction may happen upstream, but all6temporal reasoning here is pure Python and fully deterministic.7"""

20@dataclass(frozen=True)21class TemporalInterval:22    start: datetime23    end: datetime | TemporalBound24    label: Optional[str] = None252627class IntervalRelation(Enum):28    BEFORE = "before"29    AFTER = "after"30    MEETS = "meets"31    MET_BY = "met_by"32    OVERLAPS = "overlaps"33    OVERLAPPED_BY = "overlapped_by"34    STARTS = "starts"35    STARTED_BY = "started_by"36    DURING = "during"37    CONTAINS = "contains"38    FINISHES = "finishes"39    FINISHED_BY = "finished_by"40    EQUALS = "equals"

43class TemporalReasoningEngine:44    """Pure-Python temporal reasoning engine with Allen interval algebra."""4546    SUPPORTED_GRANULARITIES = {"second", "minute", "hour", "day", "week", "month", "year"}4748    def relation(self, a: TemporalInterval, b: TemporalInterval) -> IntervalRelation:49        self._validate_interval(a)50        self._validate_interval(b)5152        a_end = self._end_value(a.end)53        b_end = self._end_value(b.end)5455        if a_end < b.start:56            return IntervalRelation.BEFORE57        if a.start > b_end:58            return IntervalRelation.AFTER59        if a_end == b.start:60            return IntervalRelation.MEETS61        if a.start == b_end:62            return IntervalRelation.MET_BY63        if a.start == b.start and a_end == b_end:64            return IntervalRelation.EQUALS65        if a.start == b.start and a_end < b_end:66            return IntervalRelation.STARTS67        if a.start == b.start and a_end > b_end:68            return IntervalRelation.STARTED_BY69        if a_end == b_end and a.start > b.start:70            return IntervalRelation.FINISHES71        if a_end == b_end and a.start < b.start:72            return IntervalRelation.FINISHED_BY73        if a.start < b.start and a_end > b.start and a_end < b_end:74            return IntervalRelation.OVERLAPS75        if a.start > b.start and a.start < b_end and a_end > b_end:76            return IntervalRelation.OVERLAPPED_BY77        if a.start > b.start and a_end < b_end:78            return IntervalRelation.DURING79        return IntervalRelation.CONTAINS8081    def overlaps(self, a: TemporalInterval, b: TemporalInterval) -> bool:82        relation = self.relation(a, b)83        return relation not in {84            IntervalRelation.BEFORE,85            IntervalRelation.AFTER,86            IntervalRelation.MEETS,87            IntervalRelation.MET_BY,88        }8990    def contains(self, outer: TemporalInterval, inner: TemporalInterval) -> bool:91        self._validate_interval(outer)92        self._validate_interval(inner)93        return outer.start <= inner.start and self._end_value(outer.end) >= self._end_value(inner.end)9495    def active_at(96        self,97        interval: TemporalInterval,98        timestamp: Any,99        *,100        granularity: Optional[str] = None,101    ) -> bool:102        self._validate_interval(interval)103        point = parse_temporal_value(timestamp)104        start = interval.start105        end = interval.end106107        if granularity is not None:108            point = self.normalize_timestamp(point, granularity)109            start = self.normalize_timestamp(start, granularity)110            if isinstance(end, datetime):111                end = self.normalize_timestamp(end, granularity)112113        return start <= point and (end is TemporalBound.OPEN or point < self._coerce_datetime(end))

844            # Detect and resolve conflicts if conflict detector is available845            if self.conflict_detector:846                self.logger.debug("Detecting conflicts in graph")847                # Pass only entities to detect_conflicts as it expects List[Dict]848                detected_conflicts = self.conflict_detector.detect_conflicts(graph["entities"])849850                if detected_conflicts:851                    conflict_count = len(detected_conflicts)852                    self.logger.warning(853                        f"Detected {conflict_count} conflict(s) in graph"854                    )855856                    # Attempt to resolve conflicts857                    resolution_result = self.conflict_detector.resolve_conflicts(858                        detected_conflicts859                    )860                    resolved_count = resolution_result.get("resolved_count", 0)

118def _merge_relationships(relationship_dfs) -> pd.DataFrame:119    all_relationships = pd.concat(relationship_dfs, ignore_index=False)120    return (121        all_relationships122        .groupby(["source", "target"], sort=False)123        .agg(124            description=("description", list),125            text_unit_ids=("source_id", list),126            weight=("weight", "sum"),127        )128        .reset_index()129    )

20def cluster_graph(21    edges: pd.DataFrame,22    max_cluster_size: int,23    use_lcc: bool,24    seed: int | None = None,25) -> Communities:26    """Apply a hierarchical clustering algorithm to a relationships DataFrame."""27    node_id_to_community_map, parent_mapping = _compute_leiden_communities(28        edges=edges,29        max_cluster_size=max_cluster_size,30        use_lcc=use_lcc,31        seed=seed,32    )3334    levels = sorted(node_id_to_community_map.keys())3536    clusters: dict[int, dict[int, list[str]]] = {}37    for level in levels:38        result: dict[int, list[str]] = defaultdict(list)39        clusters[level] = result40        for node_id, community_id in node_id_to_community_map[level].items():41            result[community_id].append(node_id)4243    results: Communities = []44    for level in clusters:45        for cluster_id, nodes in clusters[level].items():46            results.append((level, cluster_id, parent_mapping[cluster_id], nodes))47    return results

11def hierarchical_leiden(12    edges: list[tuple[str, str, float]],13    max_cluster_size: int = 10,14    random_seed: int | None = 0xDEADBEEF,15) -> list[gn.HierarchicalCluster]:16    """Run hierarchical leiden on an edge list."""17    return gn.hierarchical_leiden(18        edges=edges,19        max_cluster_size=max_cluster_size,20        seed=random_seed,21        starting_communities=None,22        resolution=1.0,23        randomness=0.001,24        use_modularity=True,25        iterations=1,26    )

104def _merge_entities(entity_dfs) -> pd.DataFrame:105    all_entities = pd.concat(entity_dfs, ignore_index=True)106    return (107        all_entities108        .groupby(["title", "type"], sort=False)109        .agg(110            description=("description", list),111            text_unit_ids=("source_id", list),112            frequency=("source_id", "count"),113        )114        .reset_index()115    )

93    title_to_entity_id: dict[str, str] = {}94    async for row in entities_table:95        title_to_entity_id[row["title"]] = row["id"]9697    communities = pd.DataFrame(98        clusters, columns=pd.Index(["level", "community", "parent", "title"])99    ).explode("title")100    communities["community"] = communities["community"].astype(int)101102    # aggregate entity ids for each community103    entity_map = communities[["community", "title"]].copy()104    entity_map["entity_id"] = entity_map["title"].map(title_to_entity_id)105    entity_ids = (106        entity_map107        .dropna(subset=["entity_id"])108        .groupby("community")109        .agg(entity_ids=("entity_id", list))110        .reset_index()111    )112113    # aggregate relationship ids per community, limited to114    # intra-community edges (source and target in the same community).115    # Process one hierarchy level at a time to keep intermediate116    # DataFrames small, then concat the grouped results once at the end.117    level_results = []118    for level in communities["level"].unique():119        level_comms = communities[communities["level"] == level]120        with_source = relationships.merge(121            level_comms, left_on="source", right_on="title", how="inner"122        )123        with_both = with_source.merge(124            level_comms, left_on="target", right_on="title", how="inner"125        )126        intra = with_both[with_both["community_x"] == with_both["community_y"]]127        if intra.empty:128            continue129        grouped = (130            intra131            .explode("text_unit_ids")132            .groupby(["community_x", "parent_x"])133            .agg(134                relationship_ids=("id", list),135                text_unit_ids=("text_unit_ids", list),136            )