spans and model_output so that the Tuor review workspace renders intuitively — even for non-technical reviewers.
Spans are provider-neutral, self-describing review units. Keep them in trajectory order and the rendering is automatic.
Reviewer context mapping
Reviewers need to see what your model saw and did alongside what your model produced. Each trace carries its own ordered span trajectory.Messages and text
system, user, and assistant roles. Do not omit an assistant message merely because the same answer also appears in model_output.
Documents and images
Media is a content block with a base64 source inside a message; filenames are optional display metadata.type: "image" and a supported image MIME type. Note the 5 MB per-field cap; downsample or paginate large media before ingest.
Reasoning, tools, and unknown data
- Use
{ "type": "reasoning", "content": [{ "type": "text", "value": "..." }] }for reviewable reasoning; its content accepts the same blocks as every other span, and itsroleis alwaysassistant(filled in for you if omitted). - Use
tool_requestandtool_responsespans; connect them with an optional caller-suppliedcall_id.roleis filled in for you —assistanton a request,systemon a response. Put structured inputs and outputs injsonblocks. - Use
unknownwhen the span itself does not fit a known type, with its raw payload in ajsonblock. Unsupported or malformed content also becomes ajsonblock automatically.
Task-specific payload blueprints
Every output is structured JSON rendered as an editable path form. Nested object leaves appear as dot-path rows, arrays remain editable JSON values, and each row’s control is inferred from the value’s type. Describe a path in the trace’soutput_schema to pin its control: enum renders a label picker, boolean a true/false toggle, and json keeps the value as one editable JSON block instead of expanding it into child rows. The recipes below are all shapes of that one model.
Structured extraction
Best for contracts, invoices, receipts, forms — anything where the model produces structured JSON. The reviewer sees editable field paths where they can correct nested values, add missing paths, or remove spurious ones.output_schema for enum paths inside the structure, such as invoice.status or review.sentiment. Dot paths refer to nested object keys.
Classification / labeled fields
Best for routing, triage, and labeling tasks. The predicted label is just a field inmodel_output; describe it in output_schema as an enum and the reviewer gets a label picker, pre-selected to the model’s choice, with the valid options one click away.
confidence) rides alongside it. Two flags tune the picker:
With the default
open: true, reviewers can always type a value beyond options — leave options empty for a pure freeform label.
Boolean checks and raw JSON fields
For yes/no verdicts and nested payloads you don’t want flattened, pin the control with aboolean or json field type. A boolean path renders as a true/false toggle (and rejects non-boolean values on ingest and correction); a json path keeps its whole value as one editable JSON block rather than exploding into child dot-path rows.
boolean/json types only when you want to lock that choice in.
Generative copy / summarization
Best for long-form text outputs: summaries, copywriting, translations, rewrites. A long string value renders in a wide, resizable text area; when a reviewer edits it, the original value stays visible for reference.Reviewer ergonomics
A few patterns that keep reviewers fast:- Use message text blocks for text-heavy tasks instead of burying the prompt in arbitrary JSON.
- Stamp
modelandprompt_version_idintrace_config. They’re displayed inline in the reviewer’s trace metadata strip and included in exports for traceback. - Keep
model_outputshapes 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, runsgpt-4o, and emits structured JSON with invoice-level fields and line items.
Project config
Configure the webhook URL and secret; the trace itself declares its document content.
Ingest call
- Left pane: the original PDF, scrollable.
- Right pane: editable paths such as
invoice.vendor_name,invoice.total_amount, andline_items. - Metadata:
gpt-4o, prompt versionprm_abc123, run IDrun_01j2abcde. - Actions: approve, reject, or edit the output and submit the correction.
/tuor/invoices endpoint receives a signed review.corrected event; you look up the corresponding row by the event’s trace_id (which you stored at ingest time) and update it with the corrected fields from final_output_after.
That’s the full loop.