Skip to content

Review in the viewer (S4)

The review screen turns the read-only evidence viewer into the place where a person checks, corrects and verifies a document. It lives at /runs/{id} (and /workflows/{workflow}/runs/{id}); everything it does goes through the API below, so a script can review exactly like the screen does.

The effective value

The extraction result of a run (T08) never changes. Every action a reviewer takes appends a review_decision (append-only: UPDATE and DELETE fail in the database) and rewrites the field_override projection. The values of both are sealed with the run's data key (T50): a certified deletion or a ZDR sweep destroys that key, and the history and the review then show the decisions with their values as null and redacted: true (docs/security/encryption.md). What the screen, the verification and the later consumers (T33, T36, T37, T40, T42) read is the effective result: the extraction with the overrides applied.

Action Effective field
none the extracted value; review_state is approved (auto-approved or verified by the pipeline) or needs_review
approve the value it had (a correction stays a correction); reviewed: true
correct the typed value, status: human_override, review_state: corrected; original keeps the extracted value; the evidence is the one the reviewer chose (or none)
mark_absent no value (status: not_found), review_state: absent
reject no value, review_state: rejected

Rows of a table have a stable row_id: r0..rN for the extracted rows and u_<id> for the rows a reviewer adds. Overrides are keyed by the stable path (line_items[r2].amount), so adding or deleting a row never moves another row's decisions. The API accepts both the stable path and the positional one (line_items[2].amount names the third row now).

final_result is the snapshot saved when the document is verified (POST /v1/runs/{id}:approve): the effective fields with their review_state, the nested data, the validations recomputed on the effective data and the counters. Its JSON Schema, and those of the decision log and of the two events, are in schemas/review/ (generated from src/extractit/review/contracts.py, checked by make contracts). Fixtures: tests/fixtures/review/.

API

Route What it does
GET /v1/runs/{id}/review effective fields, validations, state, counters (?below=), ETag
PATCH /v1/runs/{id}/fields/{path} {action: approve\|correct\|mark_absent\|reject, value?, region?, reason_code?, time_spent_ms?, locale?} with If-Match; answers the field and the recomputed validations
POST /v1/runs/{id}/rows {table_path, index} adds an empty row (201, the whole review)
DELETE /v1/runs/{id}/rows/{path} deletes a row (line_items[2], line_items[r2])
POST /v1/runs/{id}:approve verifies the document; one review.completed and one extraction.corrected per corrected field in the outbox, in the same transaction; idempotent
POST /v1/runs/{id}:reject rejects the document; idempotent
GET /v1/runs/{id}/review/history?path= the decisions on a field, in order
GET /v1/review/next?workflow_id=&after= the next run of the workflow whose review is still open

Mutations need review:act (Reviewer, Admin, Owner; a Viewer reads but every mutation is 403) and If-Match with the review's weak ETag W/"sha256(extraction_id:last_seq)[:16]":

  • missing → 428 precondition-required;
  • stale → 412 etag-mismatch (nothing is written; the body carries the current etag and, for a field, its current state);
  • a value that does not fit the field's type → 422 invalid-field-value with errors[].pointer (#/value, #/region, #/index);
  • approving while a blocking rule fails → 409 blocking-rule-failing, unless acknowledge_blocking: true with a reason;
  • any change to a verified or rejected review → 409 conflict; another tenant's run → 404.

Values are validated and normalized with the normalizers of T07 according to the type of the output contract: 4.594,62 with locale: es-ES is 4594.62. Rules are re-evaluated on every change through the RuleEvaluator port (review/rules_adapter.py imports extractit.rules lazily and runs the deterministic rules of the run's workflow version or one-shot rules; AI and external rules are not re-run inside a 300 ms request).

The region as human evidence

region is {page, bbox | polygon} in page_display_norm_v1 (normalized 0..1 of the displayed page). The server selects the DocIR words whose overlap with the region covers at least 50 % of their area, builds quote and word_range, and passes the value and those words through the grounding verifier (T07) to set verification. Without value the value is read from the words. A region without words keeps the box as evidence unverified and the response carries the warning no_words_in_region; a value the words do not hold is unverified or contradicted with value_not_in_region.

Keyboard

Cmd instead of Ctrl on macOS. Nothing acts while a text field has the focus, except Ctrl/⌘+Enter and Esc. ? shows this table in the app.

Key Action
J / K next / previous field (of the current filter)
Enter approve the field and move to the next pending one
A approve the field
E edit the value (Enter saves, Esc cancels)
D mark the field absent
X reject the field
R pick the region with the keyboard: arrows move over the words, Shift+arrow extends, Enter confirms, Esc cancels
G go to the field's evidence
Ctrl/⌘+Enter verify the document
Shift+Enter verify the document and open the next one
Shift+→ / Shift+← next / previous document
? show the shortcuts
Esc cancel the editor, the region picker or a dialog

With the pointer, Elegir región (or R after the keyboard flow) lets you drag a rectangle over the words of the page.

Filters

filter (pending, the default, or all), below (confidence threshold, 0.80 by default) and unverified live in the URL, so a link reopens the same view; the counters next to them are the ones the API computes (counts in GET .../review).

  • Pendientes: no decision yet, and confidence below the threshold, or a primary evidence whose verification is not verified, or a failed validation citing the field's evidence, or needs_review from the extraction.
  • No verificados: fields no human has decided on.

The marks next to a value are ƒ (derived), ⇢ (taken from metadata) and ⚠ (evidence no verification backs).

Time per field

The client measures the time between selecting a field and deciding on it (performance.now(), capped at 10 minutes per decision) and sends it as time_spent_ms; the review keeps the sum.