agrag.ingestion.community.compute_communities

compute_communities(edges:list[WeightedEdge], *, max_cluster_size:int = 10, resolution:float = 1.0, seed:int | None = 3735928559) -> list[Community]

Run hierarchical Leiden and return level-0 communities.

CPU-bound and synchronous; callers on the event loop should run this via asyncio.to_thread (see Graph._chunk_documents for the same pattern with chunking). Only level 0 is kept -- higher levels are computed for max_cluster_size capping but never persisted.

After clustering, one extra pass over the same edge list computes a structural-importance signal, entirely from data already in memory -- no new dependency (graspologic exposes no general centrality function; see the follow-up research this refinement is based on), no new query:

• Each community's internal_weight (total weight of edges where both endpoints are its members) -- signal for which communities get a real LLM report instead of a heuristic one.
• Each member's local weight (weight of its own internal edges) -- used to order member_ids highest-first, so the "most representative" members lead the list for both a large qualifying community's (token-budget-truncated) LLM prompt and a heuristic report's few-name summary.

Parameters:

• edges (list[WeightedEdge]) – The weighted edge list from fetch_relation_edges, as (source_id, target_id, weight, relation_type) tuples.
• max_cluster_size (int) – The size ceiling a cluster is split past, at every level.
• resolution (float) – Leiden's resolution parameter.
• seed (int | None) – Random seed for reproducibility. None uses the native default.

Returns:

• list[Community] – One Community per level-0 cluster with two or more members, with
• list[Community] – member_ids ordered by local weight descending and internal_weight
• list[Community] – set. Reports (title/summary/rating/findings) are left empty; report
• list[Community] – generation fills them.

Raises:

• CommunityDetectionMissingExtraError – graspologic-native is not installed.