agrag.common.data_models.candidate_review.CandidateGroup

Bases: BaseModel

A deduplicated group of candidate nodes in one review state.

Attributes:

• key (str) – Stable key shared by the grouped candidate nodes.
• state (CandidateState) – Current review state.
• count (int) – Total sightings represented by the group.
• ids (list[UUID]) – Candidate node identifiers in the group.
• candidate (CandidateRecord) – Representative candidate record.
• chunk_ids (list[UUID]) – Source chunk identifiers, when available.
• document_count (int) – Number of documents represented by the group.

Functions:

• from_row – Build a group from a candidate-listing result row.

candidate

candidate: CandidateRecord

chunk_ids

chunk_ids: list[UUID] = Field(default_factory=list)

count

count: int

document_count

document_count: int = 0

from_row

from_row(row:Mapping[str, Any]) -> CandidateGroup

Build a group from a candidate-listing result row.

The row may contain a nested candidate record or candidate fields at the top level. Aggregate count and confidence values are applied to the representative record.

Parameters:

• row (Mapping[str, Any]) – Flat graph result row with a key, state, count, and ids.

Returns:

• CandidateGroup – Validated group with UUID identifiers.

Raises:

• KeyError – If a required result field is missing.
• ValueError – If an identifier or candidate field is invalid.

ids

ids: list[UUID]

key

key: str

state

state: CandidateState