> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eigenpal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Human Review

> Pause the run for selective field confirmation or correction, then continue with the reviewed data.

`control.human_review`: Pause the run for selective field confirmation or correction, then continue with the reviewed data.

Use this step after extraction or transformation when a human must confirm or
correct specific fields before the run continues. Place it as a **top-level
sequential step** only — nested placement inside other control containers is
rejected at publish time.

```yaml theme={null}
- name: review-invoice
  type: control.human_review
  with:
    data: '{{ steps.extract.output }}'
    metadataFrom: ai.extract
    instructions: Confirm vendor and total before posting.
    selection:
      mode: confidence
      threshold: medium
      missingConfidence: review
      fields:
        /vendor:
          review: always
        /total:
          threshold: high
    files:
      includeRunInputs: true
```

When `metadataFrom: ai.extract` is set and `data` references the whole extract
output, the step strips the reserved `_grounding` key, derives categorical
confidence (`low`, `medium`, `high`) per field from nested dotted-path
grounding, and reuses the extract schema when `schema` is omitted.

When `data` is exactly `{{ steps.<extract-step>.output }}`, Eigenpal also
snapshots any lineage and ParsedDocument sidecars the extract step produced.
Studio loads them for the review workspace: source PDFs/images beside the
structured output, spatial citation highlights on supported fields, and bbox
overlays when a canonical ParsedDocument is available. Missing or unreadable
sidecars are skipped — review still works from `_grounding` alone. Review
decisions are not yet written back into lineage.

The human review API includes optional `lineage` and `parsedDocument` on task
detail when sidecars resolve; they are API-only context, not workflow output.

**Selection modes:** `confidence` reviews fields below a threshold;
`explicit` reviews paths matched by include/exclude; `all` reviews every scalar
leaf. Thresholds accept numeric `0`–`1` or categorical `low|medium|high`.
Per-path overrides live under `selection.fields` with `review:
always|never|skip` and optional per-field `threshold`.

**Evaluations:** evaluation runs always simulate review and never pause. Assert
routing and simulated edits with `review` fixtures in dataset `meta.json` — see
[Build a dataset](/guides/build-a-dataset).

## Configuration

Configuration goes inside the step's `with:` block.

<ParamField path="data" type="string | record<string, unknown> | array<unknown>" required>
  Structured data or a template expression resolving to an object or array
</ParamField>

<ParamField path="schema" type="record<string, unknown>">
  Optional JSON Schema for validating edits and exposing downstream autocomplete. When omitted with metadataFrom: ai.extract and a direct whole-output data expression, the extract step schema is reused.
</ParamField>

<ParamField path="metadataFrom" type="&#x22;ai.extract&#x22;">
  Producer adapter. `ai.extract` derives field confidence from `_grounding` and strips that reserved key from review data. Grounding is not stripped unless this is set.
</ParamField>

<ParamField path="fieldMetadata" type="record<string, object>" default="{}">
  RFC 6901 pointer map of producer facts (labels, confidence, display). Selection policy belongs under selection.fields; fieldMetadata.review is a legacy alias.
</ParamField>

<ParamField path="selection" type="object" required>
  Field selection policy resolved once when the task is created
</ParamField>

<ParamField path="files" type="object" default="{&#x22;includeRunInputs&#x22;:true,&#x22;attachments&#x22;:[]}">
  Run input files and optional current-run attachments for reviewers

  <Expandable title="files properties">
    <ParamField path="includeRunInputs" type="boolean" default="true">
      Attach every authorized run input file to the review task
    </ParamField>

    <ParamField path="attachments" type="array<string>" default="[]">
      Additional current-run file or artifact template expressions
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="instructions" type="string">
  Free-form guidance shown above the review workspace
</ParamField>

## Output

Returns `unknown`. The complete reviewed data in the same object or array shape as the input.