> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/workflows/model-stages.md).

# Model stages

A Model stage makes inference part of the same state machine as human work. It must have a versioned contract, mapped outputs, visible failure behavior, and a human-controlled acceptance route.

### Before you make the change

* Define model owner, version, endpoint or runtime, supported modality, input, output, and ontology mapping.
* Prepare a calibration cohort and expected failure cases.
* Define timeout, retry, empty-output, malformed-output, and low-confidence routes.

![Unitlab AI Models catalog](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FISFVz8ybYzJM3OxSHs4v%2Fai-models.png?alt=media\&token=e7c6b0f2-1222-4c1b-8a07-b6d1d55e8a09)

*Treat every public or private model as a versioned production dependency whose mapping and failure behavior are part of workflow design.*

### Understand the product behavior

* **Model → Annotate → Review:** a model proposes labels, an annotator corrects them, and a reviewer verifies the result.
* **Annotate with local assistance → Review:** Magic Touch, prompt detection, Find Similar, or tracking helps the annotator within the task.
* **Model → Review with rejection to annotation:** high-confidence output moves directly to review; rejected work returns to a human correction stage.
* **Annotate → Review → specialist Review:** ambiguous or high-risk cases move to a second Review stage configured for specialists.

### Workflow save and change impact

Workflows are reusable workspace definitions that can be bound to multiple projects. Saving an active graph is therefore not a cosmetic edit. Before applying a change, Unitlab validates reachability, required edges, terminal stages, and the effect on in-flight items.

Important UX rules:

* exactly one Project and one Complete stage;
* Project has no incoming edge and must lead to an entry stage;
* Review has one Approve and one Reject route;
* terminal stages have no outgoing routes;
* every stage is reachable from Project;
* duplicate outgoing action names are rejected;
* a stage holding active items cannot be silently deleted;
* sensitive automated-stage configuration cannot change while occupied without resolving the impact.

When an active workflow change would strand work, Unitlab returns an apply-impact conflict instead of silently moving or losing items.

### Model-stage user experience

Entering a Model stage automatically dispatches the configured model. The item shows Processing while inference runs. Predictions are saved as normal annotation history, then the item follows the Model stage’s default edge to another Model stage, Annotate, Review, or a terminal stage. A failure moves the item to Error so it can be diagnosed rather than disappearing from the workflow.

### Add a model to production routing

{% stepper %}
{% step %}

#### 1. Approve the contract

Document inputs, outputs, classes, geometry, confidence, version, and ownership.
{% endstep %}

{% step %}

#### 2. Map to ontology

Verify every model output has an intentional destination or rejection rule.
{% endstep %}

{% step %}

#### 3. Place the stage

Connect model input, success, human review, failure, and escalation routes.
{% endstep %}

{% step %}

#### 4. Exercise failure modes

Test timeouts, empty output, malformed output, partial success, and unavailable runtime.
{% endstep %}

{% step %}

#### 5. Review corrected output

Measure human correction by source, class, and model version.
{% endstep %}

{% step %}

#### 6. Version change safely

Re-run calibration and workflow impact review for material model or mapping updates.
{% endstep %}
{% endstepper %}

### Decisions that affect production

| Decision                      | Production guidance                                                            |
| ----------------------------- | ------------------------------------------------------------------------------ |
| Pre-label vs autonomous route | Choose according to risk and the required human acceptance gate.               |
| Confidence                    | Use for prioritization or routing only when calibrated on the relevant domain. |
| Retry                         | Inspect remote task state before repeating a mutation.                         |
| Ownership                     | A failed model task must land in a visible queue with a named owner.           |

### Continue the operating flow

* Monitor Batch Queue and task failures.
* Inspect systematic correction cohorts.
* Record model version in release provenance.