Skip to main content
Version: 0.0.6

Candidates

Candidates preserve extraction results that do not qualify as trusted graph facts. A result can miss a confidence threshold, fall outside the schema, or refer to an unresolved endpoint. Keeping it separate lets you review useful schema gaps without allowing unreviewed data into ordinary entity search or graph traversal.

An extraction result that misses a threshold or falls outside the schema is saved as a pending candidate. You approve or reject it. Approval returns a schema patch that you apply. Conversion then turns the approved candidate into an entity, a relation, or a property. A rejected candidate stays, so later runs do not create it again.An extraction result that misses a threshold or falls outside the schema is saved as a pending candidate. You approve or reject it. Approval returns a schema patch that you apply. Conversion then turns the approved candidate into an entity, a relation, or a property. A rejected candidate stays, so later runs do not create it again.

Each candidate records its kind, label, confidence, rejection reason, and source chunk. An EVIDENCED_BY edge links it to the source chunk. Relation candidates link to resolved endpoints through SOURCE and TARGET. Property candidates link to their entity through SOURCE. An unresolved endpoint retains its text without an entity link.

Equal candidates in one document run become one record. Its count records the number of sightings in that run, and its confidence is the highest score. The record retains one source chunk. Candidate IDs change when a document is re-extracted. The content key groups equal candidates across runs.

Candidate lists group records by content key and review state. A group's count adds the sighting counts from its records across runs. Review actions do not increase it.

Document changes​

An add or update replaces the document's old pending candidates when its job commits. A failed job leaves its previous candidates unchanged. Deleting a document removes its pending candidates. Approved and rejected candidates remain, and their keys prevent later runs from creating the same candidate again.

Candidates do not expire automatically. A schema change does not remove them. Updating a document replaces its pending candidates with the latest extraction result. When a caller passes a schema to list_candidates, the list hides pending candidates that the schema already covers. Callers can request covered candidates. The coverage check does not change candidate state.

Review and conversion​

Review functions list, approve, reject, and prune candidates. Approval returns a patch that describes required schema changes and names the approved candidate IDs. Pass an output path to write the patch to a file. The review API does not edit the schema file. Apply the patch changes to your schema and raise its version, then open the graph with that schema and convert the approved candidates. Conversion turns entity candidates into entity nodes, relation candidates into edges, and property candidates into entity properties. Converted records stop being candidates.

See Review candidates and grow your schema for the workflow and the Candidates reference for API details.

Candidates stay outside ordinary retrieval. Read them with list_candidates.