Skip to main content

agrag.ingestion.merge.compute_merge

compute_merge(*, existing_entities:list[Entity], mentions:list[ExtractedEntity], schema:GraphSchema, rules:PropertyRules | None = None, description_settings:Any | None = None, description_client:Any | None = None, job_id:UUID | str | None = None, tracer:Tracer | None = None) -> tuple[MergePlan, list[Any]]

Compute how existing_entities and mentions combine into one Entity.

No storage is touched. Zero existing entities produces a brand-new Entity. One produces an updated copy folding in the mentions. Two or more picks a canonical entity for the survivor identity. The others contribute property values and accepted merge-key aliases.

Parameters:

  • existing_entities (list[Entity]) – Already-persisted entities this call reconciles.
  • mentions (list[ExtractedEntity]) – Fresh ExtractedEntity mentions to fold in.
  • schema (GraphSchema) – Used to look up the entity type's declared properties for the canonical-id schema-completeness check.
  • rules (PropertyRules | None) – Per-property conflict resolution. Defaults to keep_first. The name is always a single string: under merge_all it takes the canonical entity's name, or the first mention's when none exists.
  • description_settings (Any | None) – LLM settings for description summarization.
  • description_client (Any | None) – Injected LLM client for tests.
  • job_id (UUID | str | None) – The Cutover Job this merge runs under. A brand-new entity derives its id from (job_id, merge_key) instead of uuid4, so replaying the job after a crash reproduces the same id. None keeps today's random-id behavior for callers outside a job.
  • tracer (Tracer | None) – Passed to description summarization.

Returns:

  • tuple[MergePlan, list[Any]] – The computed MergePlan and any description-LLM failures.

Raises:

  • ValueError – existing_entities and mentions are both empty, or their labels disagree.