Skip to main content
Version: latest

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.

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. Their displayed counts reflect repeated sightings within each run, not the number of times a person reviewed a candidate.

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.

Ordinary retrieval excludes candidates. The optional search_unreviewed_candidates agent tool searches their text without embeddings. It is off by default, marks results as unreviewed, and cannot cite them as evidence. Scoped agents never receive the tool because candidate search cannot enforce their scope.