Skip to main content
Version: latest

agrag.candidates.review.list_candidates

list_candidates(graph_store:GraphStore, query:CandidateQuery | None = None, *, limit:int = 100, skip:int = 0, schema:GraphSchema | None = None, include_covered:bool = False) -> list[CandidateGroup]

List candidate groups, ordered and paged by aggregate sightings.

When a schema is supplied, covered pending candidates are hidden unless include_covered is true.

Parameters:

  • graph_store (GraphStore) – Store used to read candidate groups.
  • query (CandidateQuery | None) – Optional filters for kind, label, state, and sighting count.
  • limit (int) – Maximum number of groups to return.
  • skip (int) – Number of groups to skip.
  • schema (GraphSchema | None) – Schema used to identify already-covered candidates.
  • include_covered (bool) – Whether to retain candidates covered by the schema.

Returns:

Raises:

  • ValueError – If limit or skip is negative.