Reviewer Blueprints¶

Aligning your reviewers is the single biggest lever for review throughput and accuracy. This page is a set of practical recipes for shaping model_input and model_output so that the Tuor review workspace renders intuitively — even for non-technical reviewers.

Most of these recipes are about putting your data in the keys the review workspace expects. Get the keys right and the rendering is automatic.

Reviewer context mapping¶

Reviewers need to see what your model saw alongside what your model produced. The Tuor review workspace layout is driven by the project's input_type.

Text input (`input_type: "text"`)¶

Use a free-form text input field for any prompt-only model. The review workspace renders these keys, if present:

Key in `model_input`	What it does
`content`	Rendered as the prominent, full-width text block — the main reading panel.
`system_prompt`	Rendered in a collapsible panel above the content, styled to indicate "instructions to the model".

// POST /v1/traces/ — model_input
{
  "system_prompt": "You are a financial assistant. Always return JSON.",
  "content": "Extract the net income from the attached statement..."
}

Any additional keys are still shown (as a structured tree below the main panel) but are not given the prominent layout.

Document input (`input_type: "pdf"`)¶

Reviewers compare the extraction form against the original document side-by-side. Configure the project's input_type to pdf and provide:

Key in `model_input`	What it does
`pdf_base64`	Base64-encoded PDF bytes. Rendered in a scrollable PDF viewer.
`filename`	Optional. Displayed in the viewer chrome.

// POST /v1/traces/ — model_input
{
  "pdf_base64": "JVBERi0xLjQKJ...",
  "filename": "acme-invoice-2026-05-15.pdf"
}

Note the 5 MB per-field cap — for very large PDFs, downsample or paginate before ingest.

Image input (`input_type: "image"`)¶

For image-grounded tasks (receipts, screenshots, ID documents, charts):

Key in `model_input`	What it does
`image_base64`	Base64-encoded image bytes. Rendered in an image viewer.
`media_type`	MIME type (e.g. `image/png`). Used as the `data:` URI type.
`filename`	Optional. Displayed in the viewer chrome.

// POST /v1/traces/ — model_input
{
  "image_base64": "iVBORw0KGgoAAAANS...",
  "media_type": "image/png",
  "filename": "receipt-2026-05-15.png"
}

Task-specific schema blueprints¶

The shape of model_output determines which editor reviewers get. Match your output payload to the project's output_type and the editor is automatic.

Structured extraction (`output_type: "key_value"`)¶

Best for contracts, invoices, receipts, forms — anything where the model produces a flat dictionary of fields. The reviewer sees a clean spreadsheet-style table where they can edit values, add missing keys, or remove spurious ones.

// POST /v1/traces/ — model_output
{
  "vendor_name": "Acme Corp",
  "invoice_date": "2026-05-15",
  "total_amount": 1250.45,
  "tax_id": "12-345678"
}

Keep it flat. Nested objects render as nested tables, which slow reviewers down. If your model produces nested data (e.g. line items), put the per-line-item details in a separate trace, or in trace_config as reference metadata.

Multi-class classification (`output_type: "classification"`)¶

Best for routing, triage, and labeling tasks. The reviewer sees the model's selected label prominently, plus the valid alternatives for quick correction.

Key in `model_output`	What it does
`label`	The model's predicted label. Pre-selected in the dropdown.
`alternatives`	The full set of valid labels (including `label` itself).

// POST /v1/traces/ — model_output
{
  "label": "billing_dispute",
  "alternatives": [
    "billing_dispute",
    "cancellation_request",
    "technical_support",
    "account_settings"
  ]
}

alternatives must be a flat array of strings. If you don't have a closed set of labels, leave alternatives empty and reviewers can type a freeform value.

Generative copy / summarization (`output_type: "text"`)¶

Best for long-form text outputs: summaries, copywriting, translations, rewrites. The reviewer sees an editable text panel with live word and character counts and diff highlighting against the original.

Key in `model_output`	What it does
`content`	The long-form text. Rendered in a wide, vertically-scrolling editor.

// POST /v1/traces/ — model_output
{
  "content": "The customer requested a refund due to a defective software module. The refund was processed successfully under policy guideline A-12."
}

Reviewer ergonomics¶

A few patterns that keep reviewers fast:

Always provide model_input.content for text-heavy tasks. Avoid burying the prompt in a deeply-nested object.
Stamp model and prompt_version_id in trace_config. They're displayed inline in the reviewer's trace metadata strip and are echoed in webhooks for traceback.
Keep model_output shapes stable per project. Reviewers build muscle memory for where each field is. Shape drift across traces in the same project slows them down significantly.
Use tags to specialize trace lists. If you have heterogeneous traffic (e.g. PDFs for finance reviewers, contracts for legal), tag accordingly and have each reviewer filter to their domain.

Putting it all together: a worked example¶

Suppose you're building an invoice extraction pipeline. Each model call ingests a PDF, runs gpt-4o, and emits a flat dictionary of extracted fields.

Project config

Setting	Value
`input_type`	`pdf`
`output_type`	`key_value`
`webhook_url`	`https://hooks.example.com/tuor/invoices`
`webhook_active`	`true`

Ingest call

curl -X POST "https://api.tuor.dev/v1/traces/" \
  -H "X-API-Key: $TUOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_invoices",
    "model_input": {
      "pdf_base64": "JVBERi0xLjQK...",
      "filename": "acme-invoice-2026-05-15.pdf"
    },
    "model_output": {
      "vendor_name": "Acme Corp",
      "invoice_date": "2026-05-15",
      "total_amount": 1250.45,
      "tax_id": "12-345678"
    },
    "trace_config": {
      "model": "gpt-4o",
      "prompt_version_id": "prm_abc123",
      "internal_run_id": "run_01j2abcde"
    }
  }'

Reviewer experience

Left pane: the original PDF, scrollable.
Right pane: a four-row spreadsheet they can edit field-by-field.
Metadata: gpt-4o, prompt version prm_abc123, run ID run_01j2abcde.
Actions: approve, reject, or edit the output and submit the correction.

Webhook on correction

Your /tuor/invoices endpoint receives a signed review.corrected event; you read trace.trace_config.internal_run_id and update the corresponding row in your database with the corrected fields.

That's the full loop.

Reviewer Blueprints¶

Reviewer context mapping¶

Text input (input_type: "text")¶

Document input (input_type: "pdf")¶

Image input (input_type: "image")¶