Aligning your model

Manually rewriting prompts for every new edge case doesn't scale well. Without a systematic way to evaluate changes, it's hard to know whether a revision improves the task or just fixes the last example you looked at.

Alignment turns that trial and error into a repeatable process. Target decisions where the model is unsure, collect feedback from a larger reasoning model or a human expert, then align the Model against a measured baseline. Improved instructions become a new version of the same Model.

A Model keeps the base model and its instructions together as one versioned decision primitive. Alignment updates its question instructions, not the base model's weights. When a run improves on the starting version, it creates a new repository commit and increments the Model's checkpoint.

1. Collect representative examples

Examples can come from captured live decisions, explicit ingestion, or batch decisions. Each example keeps its input state, current annotation, and decision history.

Start with low-confidence decisions where the model is unsure. Ask a larger reasoning model or a human expert to review them and provide the expected answer and reasoning. Include repeated mistakes and unclear policy boundaries too. You do not need to label everything; focus feedback where the model needs it most.

2. Add ground truth

Annotate an example with answers keyed by question ID:

• noul questions use a boolean.
• choice questions use one configured option key.
• score questions use the zero-based index into the question's criteria.

Add concise groundReasoning when the correct answer depends on a policy or rubric distinction. The first annotation assigns a stable train or test split; later updates preserve it.

Use PATCH /v1/models/{modelId}/examples/{exampleId}/annotation to add or update the annotation.

3. Start an alignment

Ensure every question has string instructions before aligning. Unlike inference, alignment does not accept omitted, null, or other JSON instructions. Structured criteria descriptions are supported.

Call POST /v1/models/{modelId}/alignments with an Idempotency-Key header and:

• the branch to update;
• its exact current commit SHA;
• a maximum metric-call budget;
• optional reflection settings.

The exact source commit prevents an alignment from overwriting a branch that changed after you prepared the request. If it advanced, the API returns a conflict and reports the current head.

4. Evaluate the result

Poll the returned alignment URL until its status is completed, failed, or cancelled. Progress reports the current stage, scores, candidate count, and metric-call usage when available.

An improving run:

1. commits optimized instructions and the alignment artifact;
2. increments the Model checkpoint;
3. records validation metrics; and
4. starts a batch decision for all examples at the new commit.

If the candidate does not beat the starting instructions, the run completes without changing the Model.

Feedback guidelines

• Label genuine disagreements, not only obvious failures.
• Keep ground truth consistent across reviewers.
• Explain the policy distinction, not how to rewrite the prompt.
• Pin decisions and alignments to exact commits when comparing checkpoints.
• Re-run representative examples after important schema or rubric changes.