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.

graphiti_core/utils/maintenance/community_operations.py

@@ -85,7 +85,7 @@ 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
@@ -110,7 +110,7 @@ def label_propagation(projection: dict[str, list[Neighbor]]) -> list[list[str]]:
     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
@@ -135,11 +135,12 @@ def label_propagation(projection: dict[str, list[Neighbor]]) -> list[list[str]]:
 
             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:
@@ -152,7 +153,6 @@ def label_propagation(projection: dict[str, list[Neighbor]]) -> list[list[str]]:
             break
 
         # Check for oscillation by comparing with recent history
-        if iteration >= OSCILLATION_CHECK_WINDOW:
         current_state = community_map.copy()
         history.append(current_state)
 
@@ -161,12 +161,19 @@ def label_propagation(projection: dict[str, list[Neighbor]]) -> list[list[str]]:
             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(
@@ -174,7 +181,7 @@ def label_propagation(projection: dict[str, list[Neighbor]]) -> list[list[str]]:
         )
 
     # 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)