Alignment with the SDK

Alignment improves a model from its annotated examples. A job starts from an exact model commit and finishes with a new commit when it finds an improvement.

Configure the model

Load a model with annotated examples, then save the configuration you want to align:

from modaic import Modaic

modaic = Modaic()
model = modaic.models.get(workspace="acme", model="support-priority")

configured = modaic.models.update(
    model.id,
    questions={
        "priority": {
            "type": "choice",
            "instructions": "Choose the support priority.",
            "criteria": {
                "low": "No financial or time-sensitive impact.",
                "normal": "Routine customer issue.",
                "high": "Financial impact or an urgent blocker.",
            },
        }
    },
    message="Prepare priority alignment",
)

if configured.commit is None:
    raise RuntimeError("The model configuration did not change.")

Start and wait for alignment

Use model.jobs.alignments to create and list jobs for this model. Methods that take a job ID, such as wait, get, logs, and cancel, remain on modaic.alignments. With AsyncModaic, await each call.

alignment = model.jobs.alignments.create(
    branch=configured.commit.branch,
    source_commit_sha=configured.commit.commit_sha,
    idempotency_key="support-alignment-2026-09-22",
    reflection_minibatch_size=8,
    seed=42,
)

finished = modaic.alignments.wait(alignment.id, timeout=900.0, progress=True)
print(finished.status, finished.result_commit_sha)

The metric-call budget is optional. When maxMetricCalls is omitted, as above, the API sizes it to the validation split at launch, which is the recommended default. Pass maxMetricCalls in TypeScript or max_metric_calls in Python only to override that sizing.

Set progress: true in TypeScript or progress=True in Python to show the current stage and metric calls against the reported budget. Python uses tqdm and supports the same option with AsyncModaic; TypeScript renders to stderr. Output is silent by default.

The bar measures budget usage, not overall job completion. Alignment can finish before using the full budget. If counts are unavailable, the display shows the stage without a percentage. Updates follow the polling interval; a timeout stops waiting without cancelling the job.

Inspect logs or cancel

current = modaic.alignments.get(alignment.id)
logs = modaic.alignments.logs(alignment.id)
modaic.alignments.cancel(alignment.id)

See the Alignment API reference for the complete wire contract.