Skip to main content

agrag.ingestion.community.embed_communities

embed_communities(communities:list[Community], *, embedder:Embedder, batch_size:int = _DEFAULT_EMBED_BATCH_SIZE, max_concurrency:int = 4, tracer:Tracer | None = None) -> list[StageFailure]

Compute each community's embedding from its report text, in place.

Called after generate_community_reports and before to_node_record(), so the vector is already present on the very first (and only) write a replace cycle makes.

Embedder.embed's contract makes no chunking guarantee (see agrag/embedding/base.py), so at 1M+ entity scale, where a full recompute can produce 100,000+ communities, this batches the embed() calls itself rather than passing every community's text in one call.

A batch embed() failure does not block other batches: it is recorded as one StageFailure per community in that batch, matching the failure-tolerance shape generate_community_reports already uses. Those communities keep embedding=None and still get written by Community.to_node_record(), which omits the embedding property when it is None, rather than being dropped from the graph.

Parameters:

  • communities (list[Community]) – The communities to embed, mutated in place.
  • embedder (Embedder) – Computes one vector per community's embedding_text.
  • batch_size (int) – Communities embedded per embed() call.
  • max_concurrency (int) – Max concurrent embed calls.
  • tracer (Tracer | None) – Opens one span per batch.

Returns:

  • list[StageFailure] – One StageFailure per community whose batch embed() call failed.