Skip to main content

agrag.ingestion.resolve.candidate_source.persisted_candidate_indices

persisted_candidate_indices(mentions:list[ExtractedEntity], entities:list[Entity], *, source:GraphCandidateSource, error_policy:ErrorPolicy, fallback_limit:int = 128) -> tuple[dict[int, list[int]], dict[tuple[int, int], float], list[StageFailure]]

Return ANN candidate indices, with a bounded exhaustive fallback.

The fallback only applies when no indexed candidates are available. It keeps first-time and small-graph consolidation deterministic without returning to an unbounded pairwise scan for established graphs.

Returns:

  • dict[int, list[int]] – Mention index to its candidate entity indices, plus each compared
  • dict[tuple[int, int], float] – pair's real embedding cosine similarity keyed by (min, max)
  • list[StageFailure] – index order (matching how Resolver.resolve builds its own pair
  • tuple[dict[int, list[int]], dict[tuple[int, int], float], list[StageFailure]] – keys), plus one StageFailure per mention whose candidate read
  • tuple[dict[int, list[int]], dict[tuple[int, int], float], list[StageFailure]] – failed. The exhaustive-fallback branch reports no scores, so its
  • tuple[dict[int, list[int]], dict[tuple[int, int], float], list[StageFailure]] – similarity map is empty. A mention whose read failed neither starts
  • tuple[dict[int, list[int]], dict[tuple[int, int], float], list[StageFailure]] – nor joins a comparison, so it is not resolved in this call.

Raises:

  • Exception – A candidate read failed and error_policy is RAISE.