Using models

A Model is a versioned decision primitive: a base model and its instructions, managed as one artifact. Questions, instructions, and criteria define the task. You version, evaluate, and improve the combination together.

Use a Model to decide which tickets need escalation, whether content meets your policy, or how well an agent completed a task.

Beyond manual prompt engineering

Manual prompt engineering doesn't scale well. It often becomes an unsystematic loop of tweaking wording, checking a few outputs, and trying again. A change that fixes one example can break another, and spot checks don't show whether the prompt is better across the cases that matter.

Modaic makes improvement 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, so you can track what changed and how it performed.

What a model contains

• Root model — the base model that evaluates incoming state.
• Questions — named decision tasks with optional instructions and a fixed answer shape.
• Checkpoint — the alignment iteration, reset when the root model or questions change.
• Metrics — optional accuracy and calibration measurements for a checkpoint.
• Capture policy — the fraction of live decisions saved as examples for review and alignment.

Models live in private repositories. The repository path, such as acme/support-triage, is the identifier you pass to the Decision API. Model- scoped resource routes use the repository's UUID as modelId.

Use GET /v1/models to list supported base models and the repositories accessible to your token.

Decision question types

Question IDs become keys in the decision response. Keep IDs stable so stored ground truth and metrics continue to refer to the same task.

An empty question ID ("") is valid. Choice criteria have no minimum option count, and score rubrics accept one or more levels. See the decision reference for the full question shapes and structured criteria examples.

Create and configure a model

1. Create the repository

   Call POST /v1/models with an owner and slug. The response id is the model's modelId.

2. Set the model and questions

   Call PATCH /v1/models/{modelId} to set the root model and typed questions on a branch.

3. Run decisions

   Call POST /v1/decision with the repository path. Pin revision to a commit SHA when you need reproducible behavior.

Live decisions and capture

Repository-model decisions can save their state and answers as an example and decision record. The response tells you whether capture occurred and, when it did, returns example_id and decision_id.

Set capture: false on an individual request to skip recording it. A model can also define capture.sampleRate from 0 to 1 to sample production traffic.

Captured examples create the feedback loop: review a decision, add ground truth, then align the model to compile that feedback into a new checkpoint.