Skip to main content

agrag.retrieval.community_context.expand_with_communities

expand_with_communities(fused:list[SearchResult], seed_ids:list[UUID], *, graph_store:GraphStore, top_k:int, filters:SearchFilters | None, rrf_k:int, tracer:Tracer | None = None) -> list[SearchResult]

Fuse community reports overlapping seed entities into a result list.

A convenience over community_context. It looks up the communities that overlap seed_ids and fuses whatever comes back into fused under a "community" key, so callers that already have a fused result list do not repeat the fetch-then-fuse pattern (or the error handling below).

A community lookup that raises is recorded on the expansion span and swallowed rather than propagated. Community reports are enrichment on top of results that already exist, so a community-store failure must not discard them.

Parameters:

  • fused (list[SearchResult]) – The already-fused results to enrich. Returned unchanged when no community overlaps the seeds.
  • seed_ids (list[UUID]) – The entity ids to look for overlapping communities.
  • graph_store (GraphStore) – Where the overlap lookup runs.
  • top_k (int) – The maximum number of communities to add.
  • filters (SearchFilters | None) – Applied to the candidate community node. See community_context for what a scoped filter does and does not match. Community nodes carry no entity label and no document scope of their own, so a document-scoped or property-scoped caller gets no community enrichment at all. This matches a plain search. It is not an error.
  • rrf_k (int) – The reciprocal-rank-fusion constant, from RetrievalSettings.rrf_k.
  • tracer (Tracer | None) – Opens the expansion spans. None opens no recorded span.

Returns:

  • list[SearchResult] – fused with the overlapping communities fused in, or fused
  • list[SearchResult] – itself when there were none.