From 675efbebe1fcd307ae6bcef9dd0ff7cec5fc61bd Mon Sep 17 00:00:00 2001 From: remonxiao Date: Thu, 27 Nov 2025 19:41:31 +0800 Subject: [PATCH 1/2] Fix: Prevent oscillation in label propagation algorithm - Changed from synchronous to asynchronous updates with randomized node order - Added maximum iteration limit (100) to prevent infinite loops - Implemented oscillation detection with early stopping mechanism - Improved tie-breaking with deterministic sorting - Added detailed logging for convergence and oscillation events The previous implementation used synchronous updates where all nodes updated simultaneously, which could cause oscillation in certain graph structures (e.g., bipartite graphs). This fix ensures the algorithm always terminates and produces stable community assignments. --- .../utils/maintenance/community_operations.py | 107 +++++++++++++----- 1 file changed, 79 insertions(+), 28 deletions(-) diff --git a/graphiti_core/utils/maintenance/community_operations.py b/graphiti_core/utils/maintenance/community_operations.py index af1e1f10f..3f623b0d7 100644 --- a/graphiti_core/utils/maintenance/community_operations.py +++ b/graphiti_core/utils/maintenance/community_operations.py @@ -84,50 +84,101 @@ async def get_community_clusters( def label_propagation(projection: dict[str, list[Neighbor]]) -> list[list[str]]: - # Implement the label propagation community detection algorithm. - # 1. Start with each node being assigned its own community - # 2. Each node will take on the community of the plurality of its neighbors - # 3. Ties are broken by going to the largest community - # 4. Continue until no communities change during propagation - + """ + Implement the label propagation community detection algorithm with oscillation prevention. + + Algorithm: + 1. Start with each node being assigned its own community + 2. Each node will take on the community of the plurality of its neighbors + 3. Ties are broken by going to the largest community + 4. Continue until no communities change during propagation + + Oscillation prevention: + - Uses asynchronous updates (randomized node order) + - Maximum iteration limit to prevent infinite loops + - Early stopping if oscillation is detected + """ + import random + + MAX_ITERATIONS = 100 + OSCILLATION_CHECK_WINDOW = 5 + community_map = {uuid: i for i, uuid in enumerate(projection.keys())} - - while True: - no_change = True - new_community_map: dict[str, int] = {} - - for uuid, neighbors in projection.items(): + node_uuids = list(projection.keys()) + + # Track history to detect oscillations + history: list[dict[str, int]] = [] + + for iteration in range(MAX_ITERATIONS): + # Asynchronous update: randomize node processing order + random.shuffle(node_uuids) + + changed_count = 0 + + for uuid in node_uuids: + neighbors = projection[uuid] curr_community = community_map[uuid] - + + # Count votes from neighbors community_candidates: dict[int, int] = defaultdict(int) for neighbor in neighbors: community_candidates[community_map[neighbor.node_uuid]] += neighbor.edge_count + + if not community_candidates: + continue + + # Sort by count (descending), then by community ID for deterministic tie-breaking community_lst = [ (count, community) for community, count in community_candidates.items() ] - - community_lst.sort(reverse=True) - candidate_rank, community_candidate = community_lst[0] if community_lst else (0, -1) - if community_candidate != -1 and candidate_rank > 1: + community_lst.sort(key=lambda x: (-x[0], x[1])) + + candidate_rank, community_candidate = community_lst[0] + + # Update community based on neighbor plurality + if candidate_rank > 1: new_community = community_candidate else: + # For weak signals, prefer staying in current community new_community = max(community_candidate, curr_community) - - new_community_map[uuid] = new_community - + if new_community != curr_community: - no_change = False - - if no_change: + community_map[uuid] = new_community + changed_count += 1 + + # Check for convergence + if changed_count == 0: + logger.debug(f'Label propagation converged after {iteration + 1} iterations') break - - community_map = new_community_map - + + # Check for oscillation by comparing with recent history + if iteration >= OSCILLATION_CHECK_WINDOW: + current_state = community_map.copy() + history.append(current_state) + + # Keep only recent history + if len(history) > OSCILLATION_CHECK_WINDOW: + history.pop(0) + + # Detect oscillation: if current state matches any recent state + for past_state in history[:-1]: + if past_state == current_state: + logger.warning( + f'Label propagation oscillation detected at iteration {iteration + 1}, ' + 'stopping early' + ) + break + else: + logger.warning( + f'Label propagation reached maximum iterations ({MAX_ITERATIONS}) without converging' + ) + + # Group nodes by community community_cluster_map = defaultdict(list) for uuid, community in community_map.items(): community_cluster_map[community].append(uuid) - - clusters = [cluster for cluster in community_cluster_map.values()] + + clusters = list(community_cluster_map.values()) return clusters From febf8923f6792b790317c54900a288421e36dc70 Mon Sep 17 00:00:00 2001 From: remonxiao Date: Fri, 28 Nov 2025 09:56:41 +0800 Subject: [PATCH 2/2] Fix: Prevent oscillation in label propagation algorithm - Changed from synchronous to asynchronous updates with randomized node order - Added maximum iteration limit (100) to prevent infinite loops - Implemented oscillation detection with early stopping mechanism - Improved tie-breaking with deterministic sorting - Added detailed docstring and logging for convergence/oscillation events - Fixed oscillation detection to properly break out of nested loops The previous implementation used synchronous updates where all nodes updated simultaneously, which could cause oscillation in certain graph structures (e.g., bipartite graphs). This fix ensures the algorithm always terminates and produces stable community assignments while maintaining backward compatibility with existing tests. --- .../utils/maintenance/community_operations.py | 71 ++++++++++--------- 1 file changed, 39 insertions(+), 32 deletions(-) diff --git a/graphiti_core/utils/maintenance/community_operations.py b/graphiti_core/utils/maintenance/community_operations.py index 3f623b0d7..0c9ea0a90 100644 --- a/graphiti_core/utils/maintenance/community_operations.py +++ b/graphiti_core/utils/maintenance/community_operations.py @@ -85,99 +85,106 @@ async def get_community_clusters( def label_propagation(projection: dict[str, list[Neighbor]]) -> list[list[str]]: """ - Implement the label propagation community detection algorithm with oscillation prevention. - + Implement the label propagation community detection algorithm. + Algorithm: 1. Start with each node being assigned its own community 2. Each node will take on the community of the plurality of its neighbors 3. Ties are broken by going to the largest community 4. Continue until no communities change during propagation - + Oscillation prevention: - Uses asynchronous updates (randomized node order) - Maximum iteration limit to prevent infinite loops - Early stopping if oscillation is detected """ import random - + MAX_ITERATIONS = 100 OSCILLATION_CHECK_WINDOW = 5 - + community_map = {uuid: i for i, uuid in enumerate(projection.keys())} node_uuids = list(projection.keys()) - + # Track history to detect oscillations history: list[dict[str, int]] = [] - + for iteration in range(MAX_ITERATIONS): - # Asynchronous update: randomize node processing order + # Asynchronous update: randomize node processing order to prevent oscillation random.shuffle(node_uuids) - + changed_count = 0 - + for uuid in node_uuids: neighbors = projection[uuid] curr_community = community_map[uuid] - + # Count votes from neighbors community_candidates: dict[int, int] = defaultdict(int) for neighbor in neighbors: community_candidates[community_map[neighbor.node_uuid]] += neighbor.edge_count - + if not community_candidates: continue - + # Sort by count (descending), then by community ID for deterministic tie-breaking community_lst = [ (count, community) for community, count in community_candidates.items() ] community_lst.sort(key=lambda x: (-x[0], x[1])) - + candidate_rank, community_candidate = community_lst[0] - - # Update community based on neighbor plurality + + # Determine new community: + # - If strong signal (edge count > 1), adopt the neighbor's community + # - Otherwise, prefer the larger community ID (original behavior) if candidate_rank > 1: new_community = community_candidate else: - # For weak signals, prefer staying in current community new_community = max(community_candidate, curr_community) - + if new_community != curr_community: community_map[uuid] = new_community changed_count += 1 - + # Check for convergence if changed_count == 0: logger.debug(f'Label propagation converged after {iteration + 1} iterations') break - + # Check for oscillation by comparing with recent history - if iteration >= OSCILLATION_CHECK_WINDOW: - current_state = community_map.copy() - history.append(current_state) - - # Keep only recent history - if len(history) > OSCILLATION_CHECK_WINDOW: - history.pop(0) - - # Detect oscillation: if current state matches any recent state + current_state = community_map.copy() + history.append(current_state) + + # Keep only recent history + if len(history) > OSCILLATION_CHECK_WINDOW: + history.pop(0) + + # Detect oscillation: if current state matches any recent state + if len(history) >= 2: for past_state in history[:-1]: if past_state == current_state: logger.warning( f'Label propagation oscillation detected at iteration {iteration + 1}, ' 'stopping early' ) + # Break out of the for loop break + else: + # No oscillation detected, continue to next iteration + continue + # Oscillation detected, break out of the main loop + break else: logger.warning( f'Label propagation reached maximum iterations ({MAX_ITERATIONS}) without converging' ) - + # Group nodes by community - community_cluster_map = defaultdict(list) + community_cluster_map: dict[int, list[str]] = defaultdict(list) for uuid, community in community_map.items(): community_cluster_map[community].append(uuid) - + clusters = list(community_cluster_map.values()) return clusters