Core Concepts¶
This page covers the small set of concepts you need to integrate Tuor cleanly: traces, review outcomes, payload shapes, and how reviewed data gets back to your system.
Trace¶
A trace is one model call that can be reviewed by a human. It has three payloads you control:
| Field | Required | Purpose |
|---|---|---|
model_input |
yes | What your model saw: prompt, document, image, ticket, transcript, etc. |
model_output |
yes | What your model produced. |
trace_config |
no | Metadata for traceback: model name, prompt version, run ID, customer/account ID, experiment ID. |
Tuor adds review fields:
| Field | Meaning |
|---|---|
status |
pending, approved, rejected, or corrected. |
corrected_output |
Human-edited output, present after a correction. |
final_output |
The output to trust downstream. It equals model_output when approved, corrected_output when corrected, and null when pending or rejected. |
tags |
Optional labels for routing, filtering, and export cohorts. |
Each JSON payload field is capped at 5 MB and 10 nesting levels.
Review outcomes¶
Every trace starts as pending. Reviewers then choose one of three outcomes:
| Outcome | Meaning | final_output |
|---|---|---|
approved |
The model output is correct as-is. | model_output |
corrected |
A reviewer fixed the output. | corrected_output |
rejected |
The output is not usable. | null |
For most integrations, this is the state machine that matters: send traces while they are pending, then consume approved and corrected traces through webhooks or export.
Payload shapes¶
Project input/output types control how reviewers see each trace. Choose types that match the data your pipeline already produces.
Inputs
Project input_type |
Put this in model_input |
|---|---|
text |
{"content": "...", "system_prompt": "..."} |
pdf |
{"pdf_base64": "...", "filename": "..."} |
image |
{"image_base64": "...", "media_type": "image/png", "filename": "..."} |
Outputs
Project output_type |
Put this in model_output |
|---|---|
key_value |
A flat object such as {"vendor": "Acme", "total": 1250.45}. |
text |
{"content": "long-form text..."}. |
classification |
{"label": "billing_dispute", "alternatives": ["billing_dispute", "technical_support"]}. |
See Reviewer Blueprints for practical recipes.
Getting results back¶
There are three common patterns:
| Pattern | Best for |
|---|---|
trace_config IDs |
Tying every Tuor trace back to your own run, user, ticket, or database row. |
| Webhooks | Reacting as soon as a reviewer approves, rejects, or corrects a trace. |
| JSONL export | Batch evals, dashboards, analytics, training-data jobs, or prompt-improvement workflows. |
Use trace_config aggressively. For example, include internal_run_id, prompt_version_id, and customer_id when you create a trace. Tuor echoes those values in webhooks and exports, so downstream systems do not need a separate mapping table.