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:

• list[CandidateGroup] – Matching candidate groups.

Raises:

• ValueError – If limit or skip is negative.