Minctrl Docs
Guides

Document extraction

Attach PDFs, images and emails to a run, let Claude fill a schema you declare — every field with a confidence and the page it was read from — and have a person review the uncertain fields at a gate, side by side with the document, before any step uses them.

A run can carry documents: a supplier invoice, a scanned claim form, an email with its attachments. An agent step that declares an extract block sends them to Claude and asks for the fields of a schema you declare. Every field comes back with a confidence and a citation — the document, the page and a short quote — and the fields under their threshold are flagged. A gate that reviews the extraction shows the documents beside the fields; what the reviewer signs replaces what the model read, and the steps after the gate read the reviewed values.

The product rule holds: a model proposes, a person disposes. An uncertain value never flows on silently — it waits for a person, at the reviewing gate or at the extraction step itself.

Attach documents

WhereHow
At the start, in the browserRuns → pick the process → Documents (optional) → Start run.
At the start, over the APIPOST /process-runs with documents: [{name, content_base64, label?}] (at most 10).
From a webhook triggerThe JSON body's reserved field _documents (same shape) — attached, never copied into the inputs. Raise TRIGGER_WEBHOOK_MAX_BYTES for real files.
While the run waits at a gateThe sign-off card's Attach a document, or POST /process-runs/{id}/documents?name=…&label=… with the raw file as the body.

A label (invoice, contract) lets an extraction step read only the documents it is about. The documents of a run: GET /process-runs/{id}/documents; one document's bytes: GET /process-runs/{id}/documents/{doc}/content.

What is accepted, and how it is checked. The type is decided by the file's first bytes — never by its name or the Content-Type the sender claims: a .pdf that starts like a PNG is stored as the PNG it is, and anything that is not one of the types below is refused (415).

TypeHandling
PDFpypdf opens it only to count its pages. Scripts, actions, forms and embedded files are never looked at or run. A password-protected PDF is refused.
PNG, JPEG, WebPPillow checks it is an image of a sane size (decompression bombs refused). At most 5 MiB — the model's image limit.
TIFFClaude does not read TIFF: Pillow re-encodes it into a PDF, one page per frame (converted_from: image/tiff).
Email (.eml)Stored as its text (headers and body; an HTML-only body is reduced to text). Each PDF/image attachment becomes a document of its own (parent_id = the email); other attachments are skipped and named in the answer.

A document is served back as the type it was sniffed as, with X-Content-Type-Options: nosniff and a sandbox Content-Security-Policy, so a file that is also HTML (a polyglot) never runs in a browser.

Limits (environment of the API):

VariableDefault
DOCUMENT_MAX_BYTES10 MiBper file (413)
DOCUMENT_MAX_IMAGE_BYTES5 MiBper image (413)
DOCUMENT_MAX_PAGES100per PDF or TIFF (422)
DOCUMENT_MAX_PER_RUN10documents on one run (409)
DOCUMENT_MAX_RUN_BYTES20 MiBall of a run's documents together, so one extraction stays under the API's 32 MB request (413)
DOCUMENT_MAX_ATTACHMENTS10attachments taken from one email

Storage. Postgres, table run_documents. Each file is encrypted with AES-256-GCM under a key of its own (the document id and company bound in as associated data); that key is sealed by the same secret box as every stored credential (MINCTRL_SECRETS_KEY). A database backup holds ciphertext only. Deleting the run deletes its documents.

Permissions. A person needs documents.upload to attach (and runs.start, as the route starts-and-feeds runs) and documents.read to see and open a run's documents. Every built-in role holds both; a custom role can leave them out. An API key attaches with its runs:start scope and reads with runs:read.

Audit. Every attachment is a document_attached entry: the stage (start or gate), who, and per document its id, kind, type, size, pages and SHA-256 — never its name or content (a file name can be a patient's name).

Declare the extraction

On an agent node:

{
  "id": "read",
  "kind": "agent",
  "label": "Read the invoice",
  "agent": "clerk",
  "tools": [],
  "tier": "low",
  "extract": {
    "schema": {
      "type": "object",
      "properties": {
        "invoice_no": { "type": "string", "title": "Invoice number", "description": "The supplier's invoice number" },
        "total": { "type": "number", "description": "The total amount due, as a plain number" },
        "currency": { "type": "string", "enum": ["EUR", "USD"], "description": "The currency of the total" },
        "due": { "type": "string", "format": "date", "description": "The payment due date" }
      },
      "required": ["invoice_no", "total", "currency"]
    },
    "order": ["invoice_no", "total", "currency", "due"],
    "instructions": "Read the supplier invoice. The total is the amount after tax.",
    "documents": "invoice",
    "threshold": 0.8,
    "field_thresholds": { "total": 0.95 },
    "model": "claude-sonnet-5-5"
  }
}
KeyMeaning
schemaA JSON Schema object; its properties are the fields (at most 20). Each field needs a description — what the model looks for — and is a string (optionally enum, format: "date", pattern, minLength/maxLength), a number or integer (optionally minimum/maximum) or a boolean. required fields must be found.
orderThe order people see the fields in (a stored graph does not keep an object's key order). Left out: the required fields in their order, then the rest by name.
instructionsOptional guidance, at most 10,000 characters.
documentsA label: read only the run's documents with it. Left out: every document of the run.
thresholdThe confidence (0–1) under which a field is flagged. Default 0.8.
field_thresholdsPer field, overriding threshold.
model, max_tokensAs for LLM agent steps.

What the model receives. Each document as Claude's native input — a PDF as a document block, an image as an image block, an email's text as a plain-text document block — each introduced by its number and name, then your instructions and the field list. The system prompt tells the model that the documents are data, not instructions. The answer is constrained (structured outputs) to, per field: value (or null), confidence, document, page, quote.

What is checked here. The values against your full schema (required fields, types, enums, bounds, patterns, dates as YYYY-MM-DD); every citation against the real page count of the document it names; every confidence in 0–1. A broken answer is sent back once with what is wrong; a second broken answer fails the step (llm_schema). A required field the documents do not contain therefore fails the step instead of being guessed.

What is flagged. A field whose confidence is under its threshold, a field not found (optional fields only — a missing required one fails the check), or a value without a page.

Run state. extracted.<step> (the values object), extracted.<step>.<field> (each value) and extracted.<step>._flagged (the flagged field ids). Connector maps, decision tables and gateways (route_on: "extracted.read.currency") read them like any other state. The run's trace also carries extracted: each extraction step's values as the run stands, and whether a gate reviewed them.

Without a reviewing gate, an extraction with flagged fields parks at its own step: a person looks at the documents and the fields on the sign-off card and approves (the model's values stand) or denies.

Review at a gate

A gate declares which extraction it reviews:

{ "id": "check", "kind": "gate", "label": "Check the invoice", "human": "ap_clerk",
  "gate": "gate:check-invoice", "tier": "high", "review": "read" }

The gate's form is derived from the extraction's schema — one field per extracted field (enum → select, date → date, number → number, boolean → checkbox, string → text) — so a review gate declares no form of its own. On the sign-off card the reviewer sees:

  • the document viewer — the PDF in the browser's viewer at the cited page, the image, or the email's text; several documents as tabs; a document that cannot be opened says so, with a retry;
  • the fields as the model read them, each with its confidence and citation; a click on a citation turns the viewer to that page;
  • the form pre-filled with the model's values, the flagged fields highlighted with why.

The reviewer corrects what is wrong and signs. A field left as it was is signed as the model read it. The values go through the form check and the extraction schema (a whole number stays whole, a pattern holds) — a refused value is named under its field and nothing is signed. A review gate is always signed on its own card, never in bulk — and never from Slack, Teams or an embedded widget: they show "Open in Minctrl", and the sign door refuses a review signature from any channel but the sign-off card (409), so what a model read is settled only where the documents are shown. The same holds for an extraction step parked on its own flagged fields.

What the signature records:

  • the reviewed values in the run's decisions — the steps after the gate read them as extracted.<step>.<field> (and gate_form.<gate>.<field>), on this drive and on every replay;
  • the gate_signed entry with the form values, as for any gate with a form;
  • an extraction_reviewed entry: who reviewed, the verdict, each corrected field (the model's value, the reviewed value, its confidence, whether it was flagged) and the fields confirmed as they were.

A resume never asks the model again: the extraction's answer is in the trace and is replayed.

Cost, budgets and records

An extraction is a model call like any LLM step: it is checked against the company's monthly budget and the per-run cap before it is made (reached → the step fails with "LLM budget reached", nothing is sent), and each call is an llm_usage row and an llm_call audit entry (model, prompt hash, tokens, cost, latency, output hash). Documents are large inputs — expect the input tokens of a long PDF. When the company keeps model text, the kept prompt has every document replaced by its id: the documents are stored once, encrypted, never in a call record.

PHI mode and retention

In PHI mode no prompt or output text is kept for any call. The retention purge that empties a finished run's inputs deletes its documents in the same transaction; its phi_inputs_purged entry counts them per run (documents, documents_removed) and never names them. Opening a document is opening the run: while run views are logged, the view is recorded before the document is served.

The same purge removes what the model read from those documents: in the run's trace every extraction's values and quotes (and the documents' names), the run's extracted summary, a branch reason that quoted an extracted value, and the values signed at a review gate (in the trace, the decisions and the notes) — extracted_fields_redacted counts them per run. Field ids, confidences, pages and flags stay: they say how the run was decided, not what the documents said. What this does not reach: the gate_signed and extraction_reviewed audit entries (the hash-linked chain is never rewritten), and a database backup taken before a purge, which still holds the encrypted documents until it ages out.

Test suites

A test case replays an extraction from a recorded answer — fixtures: {"read": {"extraction": {"fields": {...}}}}, the model's answer shape — checked and flagged exactly as a live one, with no call and no document. Recording a case keeps each extraction's answer as its fixture. Assertions read $.llm_output.<field> (the values) and $.flagged[0].

Limits stated plainly

  • Extraction runs on the default (replay) runtime, like LLM steps; the Temporal runtime does not run extraction steps.
  • The viewer is the browser's own PDF viewer; a citation turns to its page but does not draw a box on it (the API returns pages and quotes, not coordinates).
  • Handwriting and poor scans are read as well as the model reads them — that is what the confidence and the review are for.

On this page